@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/workflows/workflow-receipt.js

@@ -0,0 +1,387 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../shared/atomic-json.js";
+import { parseWorkflowChildSummary } from "./workflow-child-summary.js";
+import { HOST_STEP_MAX_COUNT, assertUniqueHostStepIds, parseHostStepNode } from "../runs/shared/host-step-status.js";
+import { assertWorkflowLaneKey, normalizeWorkflowLaneMetadata } from "../runs/shared/lane-metadata.js";
+export const WORKFLOW_RECEIPT_VERSION = 1;
+export const WORKFLOW_RECEIPT_FILE = "workflow-receipt.json";
+const MAX_WORKFLOW_RECEIPT_BYTES = 2 * 1024 * 1024;
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function assertSafeRunId(value, label) {
+  const normalized = value.trim();
+  if (!normalized || path.basename(normalized) !== normalized || normalized === "." || normalized === "..") {
+    throw new Error(`${label} must be an exact workflow run id, not a path or prefix.`);
+  }
+  return normalized;
+}
+function assertKey(value, label) {
+  if (!KEY_PATTERN.test(value))
+    throw new Error(`${label} is invalid.`);
+  return value;
+}
+export function workflowReceiptPath(asyncDirRoot, workflowRunId) {
+  return path.join(asyncDirRoot, assertSafeRunId(workflowRunId, "workflowRunId"), WORKFLOW_RECEIPT_FILE);
+}
+export function buildWorkflowReceipt(input) {
+  const workflowRunId = assertSafeRunId(input.workflowRunId, "workflowRunId");
+  if (input.workflowChildren?.workflowRunId !== undefined && input.workflowChildren.workflowRunId !== workflowRunId)
+    throw new Error("workflowChildren workflowRunId does not match its receipt.");
+  const entries = Object.create(null);
+  for (const child of input.children) {
+    const key = assertKey(child.key, "workflow receipt child key");
+    if (entries[key])
+      throw new Error(`Workflow receipt has duplicate child key '${key}'.`);
+    const lane = normalizeWorkflowLaneMetadata(child.lane, `workflow receipt child '${key}'.lane`);
+    assertWorkflowLaneKey(lane, key, `workflow receipt child '${key}'.lane`);
+    const runIds = [...new Set((child.continuation?.runIds ?? (child.runId ? [child.runId] : [])).filter((runId) => typeof runId === "string" && runId.trim()).map((runId) => runId.trim()))];
+    const latestRunId = runIds.at(-1);
+    const resumability = child.resumability ?? { state: "not-resumable", reason: child.runId ? "resumability was not recorded" : "child produced no run id" };
+    if (resumability.state === "resumable" && !latestRunId)
+      throw new Error(`Workflow receipt child '${key}' is resumable but has no retained run id.`);
+    const base = {
+      key,
+      ...lane ? { lane } : {},
+      ...child.terminalOutcome ? { terminalOutcome: child.terminalOutcome } : {},
+      ...child.agent ? { agent: child.agent } : {},
+      ...child.requestedContext ? { requestedContext: child.requestedContext } : {},
+      ...child.resolvedContext ? { resolvedContext: child.resolvedContext } : {},
+      ...child.outputReference ? { outputReference: child.outputReference } : {},
+      ...child.recovery ? { acceptanceRecovery: child.recovery } : {},
+      ...child.externalAdapter ? { externalAdapter: child.externalAdapter } : {},
+      continuation: { runIds }
+    };
+    entries[key] = resumability.state === "resumable" ? { ...base, latestRunId, resumability } : { ...base, ...latestRunId ? { latestRunId } : {}, resumability };
+  }
+  if (input.hostSteps && input.hostSteps.length > HOST_STEP_MAX_COUNT)
+    throw new Error(`Workflow receipt has more than ${HOST_STEP_MAX_COUNT} host steps.`);
+  const hostSteps = input.hostSteps?.map((hostStep, index) => parseHostStepNode(hostStep, `workflow receipt hostSteps[${index}]`));
+  if (hostSteps)
+    assertUniqueHostStepIds(hostSteps, "workflow receipt");
+  return { version: WORKFLOW_RECEIPT_VERSION, workflowRunId, state: input.state, createdAt: input.createdAt ?? Date.now(), entries, ...hostSteps?.length ? { hostSteps } : {}, ...input.workflowChildren ? { workflowChildren: input.workflowChildren } : {}, ...input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {} };
+}
+export function writeWorkflowReceipt(asyncDir, receipt) {
+  const receiptPath = path.join(asyncDir, WORKFLOW_RECEIPT_FILE);
+  writePrivateAtomicJson(receiptPath, receipt);
+  return receiptPath;
+}
+function readWorkflowReceiptFile(receiptPath) {
+  let fd;
+  try {
+    fd = fs.openSync(receiptPath, "r");
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile())
+      throw new Error("workflow receipt is not a regular file.");
+    if (stat.size > MAX_WORKFLOW_RECEIPT_BYTES)
+      throw new Error(`workflow receipt exceeds the ${MAX_WORKFLOW_RECEIPT_BYTES}-byte limit.`);
+    const buffer = Buffer.allocUnsafe(stat.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const bytesRead = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+      if (bytesRead <= 0)
+        throw new Error("workflow receipt ended before its declared size.");
+      offset += bytesRead;
+    }
+    return JSON.parse(buffer.toString("utf-8"));
+  } finally {
+    if (fd !== undefined)
+      fs.closeSync(fd);
+  }
+}
+const EXTERNAL_CLI_CAPABILITIES = {
+  stop: true,
+  steer: false,
+  resume: false,
+  structuredOutput: false,
+  toolEvents: false,
+  supervisor: "unsupported",
+  forkContext: false,
+  extensionBindings: false
+};
+function parseExternalCliReceiptMetadata(value, key, source) {
+  if (value === undefined)
+    return;
+  const label = `Invalid workflow receipt '${source}': entry '${key}' externalAdapter`;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  const metadata = value;
+  const unknownMetadata = Object.keys(metadata).filter((field) => !["adapter", "capabilities", "safety", "outputArtifacts", "handoff", "supervisor", "nonResumableReason"].includes(field));
+  if (unknownMetadata.length > 0)
+    throw new Error(`${label} has unsupported fields: ${unknownMetadata.join(", ")}.`);
+  const adapter = metadata.adapter;
+  if (!adapter || typeof adapter !== "object" || Array.isArray(adapter))
+    throw new Error(`${label}.adapter must be an object.`);
+  const adapterRecord = adapter;
+  const unknownAdapter = Object.keys(adapterRecord).filter((field) => !["id", "version", "executionMode"].includes(field));
+  if (unknownAdapter.length > 0)
+    throw new Error(`${label}.adapter has unsupported fields: ${unknownAdapter.join(", ")}.`);
+  if (adapterRecord.id !== "external-cli" && adapterRecord.id !== "codex-exec" && adapterRecord.id !== "codex-exec-writer" && adapterRecord.id !== "claude-code" && adapterRecord.id !== "claude-code-writer" && adapterRecord.id !== "cursor-agent" && adapterRecord.id !== "cursor-agent-writer" && adapterRecord.id !== "grok-build" || adapterRecord.version !== 1 || adapterRecord.executionMode !== (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer" || adapterRecord.id === "grok-build" ? "one-shot-prompt-file" : "one-shot-stdin"))
+    throw new Error(`${label}.adapter is invalid.`);
+  const capabilities = metadata.capabilities;
+  if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities))
+    throw new Error(`${label}.capabilities must be an object.`);
+  const capabilityRecord = capabilities;
+  const unknownCapabilities = Object.keys(capabilityRecord).filter((field) => !(field in EXTERNAL_CLI_CAPABILITIES));
+  if (unknownCapabilities.length > 0)
+    throw new Error(`${label}.capabilities has unsupported fields: ${unknownCapabilities.join(", ")}.`);
+  for (const [capability, expected] of Object.entries(EXTERNAL_CLI_CAPABILITIES)) {
+    if (capabilityRecord[capability] !== expected)
+      throw new Error(`${label}.capabilities.${capability} is invalid.`);
+  }
+  const safety = metadata.safety;
+  if (adapterRecord.id === "codex-exec") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !["sandbox", "approvalPolicy", "ephemeral"].includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    if (safetyRecord.sandbox !== "read-only" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (adapterRecord.id === "codex-exec-writer") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "sandbox", "approvalPolicy", "ephemeral"].includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    if (safetyRecord.access !== "workspace-write" || safetyRecord.sandbox !== "workspace-write" || safetyRecord.approvalPolicy !== "never" || safetyRecord.ephemeral !== true)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (adapterRecord.id === "claude-code") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const legacy = safetyRecord.authentication === undefined;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !(legacy ? ["permissionMode", "tools", "mcp", "settingSources", "sessionPersistence"] : ["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"]).includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    if (legacy) {
+      if (safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "none" || safetyRecord.sessionPersistence !== false)
+        throw new Error(`${label}.safety is invalid.`);
+    } else if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "none" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (adapterRecord.id === "claude-code-writer") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "mcp", "settingSources", "userSettingsTrust", "sessionPersistence"].includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    if (safetyRecord.access !== "workspace-write" || safetyRecord.authentication !== "existing-cli-required" || safetyRecord.permissionMode !== "acceptEdits" || safetyRecord.tools !== "Read,Write,Edit,Glob,Grep" || safetyRecord.mcp !== "empty-strict" || safetyRecord.settingSources !== "user" || safetyRecord.userSettingsTrust !== "required" || safetyRecord.sessionPersistence !== false)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (adapterRecord.id === "cursor-agent" || adapterRecord.id === "cursor-agent-writer") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "mode", "sandbox", "workspaceTrust", "sessionReuse"].includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    const writer = adapterRecord.id === "cursor-agent-writer";
+    if (safetyRecord.access !== (writer ? "workspace-write" : "read-only") || safetyRecord.authentication !== "cursor-api-key-or-existing-login" || safetyRecord.mode !== (writer ? "print" : "ask") || safetyRecord.sandbox !== "enabled" || safetyRecord.workspaceTrust !== "existing-required" || safetyRecord.sessionReuse !== false)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (adapterRecord.id === "grok-build") {
+    if (!safety || typeof safety !== "object" || Array.isArray(safety))
+      throw new Error(`${label}.safety is missing.`);
+    const safetyRecord = safety;
+    const unknownSafety = Object.keys(safetyRecord).filter((field) => !["access", "authentication", "permissionMode", "tools", "deniedTools", "sandbox", "webSearch", "subagents", "config", "updates", "sessionPersistence"].includes(field));
+    if (unknownSafety.length > 0)
+      throw new Error(`${label}.safety has unsupported fields: ${unknownSafety.join(", ")}.`);
+    if (safetyRecord.access !== "read-only" || safetyRecord.authentication !== "xai-api-key-required" || safetyRecord.permissionMode !== "plan" || safetyRecord.tools !== "read_file,grep,list_dir" || safetyRecord.deniedTools !== "run_terminal_cmd,search_replace,Agent,Bash,Edit,Write,MCPTool" || safetyRecord.sandbox !== "read-only" || safetyRecord.webSearch !== false || safetyRecord.subagents !== false || safetyRecord.config !== "temporary-home" || safetyRecord.updates !== "disabled" || safetyRecord.sessionPersistence !== false)
+      throw new Error(`${label}.safety is invalid.`);
+  } else if (safety !== undefined)
+    throw new Error(`${label}.safety is invalid for the generic adapter.`);
+  const handoff = metadata.handoff;
+  if (!handoff || typeof handoff !== "object" || Array.isArray(handoff))
+    throw new Error(`${label}.handoff must be an object.`);
+  const handoffRecord = handoff;
+  const unknownHandoff = Object.keys(handoffRecord).filter((field) => field !== "mode");
+  if (unknownHandoff.length > 0)
+    throw new Error(`${label}.handoff has unsupported fields: ${unknownHandoff.join(", ")}.`);
+  if (handoffRecord.mode !== "fresh")
+    throw new Error(`${label}.handoff is invalid.`);
+  const supervisor = metadata.supervisor;
+  if (!supervisor || typeof supervisor !== "object" || Array.isArray(supervisor))
+    throw new Error(`${label}.supervisor must be an object.`);
+  const supervisorRecord = supervisor;
+  const unknownSupervisor = Object.keys(supervisorRecord).filter((field) => !["mode", "reason"].includes(field));
+  if (unknownSupervisor.length > 0)
+    throw new Error(`${label}.supervisor has unsupported fields: ${unknownSupervisor.join(", ")}.`);
+  if (supervisorRecord.mode !== "unsupported" || typeof supervisorRecord.reason !== "string" || !supervisorRecord.reason.trim())
+    throw new Error(`${label}.supervisor is invalid.`);
+  if (typeof metadata.nonResumableReason !== "string" || !metadata.nonResumableReason.trim())
+    throw new Error(`${label}.nonResumableReason is missing.`);
+  const outputArtifacts = metadata.outputArtifacts;
+  if (outputArtifacts !== undefined) {
+    if (!outputArtifacts || typeof outputArtifacts !== "object" || Array.isArray(outputArtifacts))
+      throw new Error(`${label}.outputArtifacts must be an object.`);
+    const unknownArtifacts = Object.keys(outputArtifacts).filter((field) => !["stdoutPath", "stderrPath", "finalOutputPath"].includes(field));
+    if (unknownArtifacts.length > 0)
+      throw new Error(`${label}.outputArtifacts has unsupported fields: ${unknownArtifacts.join(", ")}.`);
+    for (const field of ["stdoutPath", "stderrPath", "finalOutputPath"]) {
+      const artifactPath = outputArtifacts[field];
+      if (artifactPath !== undefined && (typeof artifactPath !== "string" || !artifactPath.trim()))
+        throw new Error(`${label}.outputArtifacts.${field} must be a non-empty string.`);
+    }
+  }
+  return value;
+}
+function parseTerminalOutcome(value, label) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  const outcome = value;
+  if (outcome.state !== "partial" || outcome.reason !== "budget_exhausted" && outcome.reason !== "timeout")
+    throw new Error(`${label} is invalid.`);
+  return { state: "partial", reason: outcome.reason };
+}
+function parseAcceptanceRecoveryMetadata(value, label) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  const recovery = value;
+  if (recovery.status !== "available-for-review" || recovery.reason !== "acceptance-metadata-rejected")
+    throw new Error(`${label} is invalid.`);
+  if (typeof recovery.reportPath !== "string" || !recovery.reportPath.trim() || typeof recovery.reportHash !== "string" || !/^[a-f0-9]{64}$/u.test(recovery.reportHash))
+    throw new Error(`${label} is invalid.`);
+  return {
+    status: "available-for-review",
+    reason: "acceptance-metadata-rejected",
+    reportPath: recovery.reportPath,
+    reportHash: recovery.reportHash
+  };
+}
+function parseEntry(value, key, source) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' must be an object.`);
+  const entry = value;
+  if (entry.key !== key)
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' has a mismatched key.`);
+  const latestRunId = entry.latestRunId;
+  if (latestRunId !== undefined && (typeof latestRunId !== "string" || !latestRunId.trim()))
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' latestRunId must be non-empty.`);
+  const continuation = entry.continuation;
+  if (!continuation || typeof continuation !== "object" || Array.isArray(continuation) || !Array.isArray(continuation.runIds)) {
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' continuation is missing.`);
+  }
+  const runIds = continuation.runIds;
+  if (runIds.some((runId) => typeof runId !== "string" || !runId.trim()))
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' continuation contains an invalid run id.`);
+  if (latestRunId !== undefined && runIds.at(-1) !== latestRunId)
+    throw new Error(`Workflow receipt '${source}' entry '${key}' is stale: latestRunId does not match its continuation lineage.`);
+  const resumability = entry.resumability;
+  if (!resumability || typeof resumability !== "object" || Array.isArray(resumability))
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumability is missing.`);
+  const state = resumability.state;
+  if (state !== "resumable" && state !== "not-resumable")
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumability state is invalid.`);
+  const reason = resumability.reason;
+  if (state === "resumable" && latestRunId === undefined)
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' resumable entry has no retained run id.`);
+  if (state === "not-resumable" && (typeof reason !== "string" || !reason.trim()))
+    throw new Error(`Invalid workflow receipt '${source}': entry '${key}' non-resumable reason is missing.`);
+  const terminalOutcome = parseTerminalOutcome(entry.terminalOutcome, `Invalid workflow receipt '${source}': entry '${key}' terminalOutcome`);
+  const acceptanceRecovery = parseAcceptanceRecoveryMetadata(entry.acceptanceRecovery, `Invalid workflow receipt '${source}': entry '${key}' acceptanceRecovery`);
+  parseExternalCliReceiptMetadata(entry.externalAdapter, key, source);
+  const lane = normalizeWorkflowLaneMetadata(entry.lane, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
+  assertWorkflowLaneKey(lane, key, `Invalid workflow receipt '${source}': entry '${key}'.lane`);
+  return { ...value, ...lane ? { lane } : {}, ...terminalOutcome ? { terminalOutcome } : {}, ...acceptanceRecovery ? { acceptanceRecovery } : {} };
+}
+function parseWorkflowResolution(value, source) {
+  if (value === undefined)
+    return;
+  if (value !== "settled-awaiting-resume" && value !== "failed-child" && value !== "interrupted-child")
+    throw new Error(`Invalid workflow receipt '${source}': workflowResolution is invalid.`);
+  return value;
+}
+function parseRecovery(value, workflowRunId, entries, source) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value))
+    throw new Error(`Invalid workflow receipt '${source}': recovery must be an array.`);
+  return value.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] must be an object.`);
+    const action = item;
+    const key = action.key;
+    const resume = action.resume;
+    if (typeof key !== "string" || !entries[key] || action.call !== "runs.run" || action.taskRequired !== true || !resume || typeof resume !== "object" || Array.isArray(resume))
+      throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] is invalid.`);
+    const reference = resume;
+    if (reference.workflowRunId !== workflowRunId || reference.key !== key || reference.latest !== true || entries[key].resumability.state !== "resumable")
+      throw new Error(`Invalid workflow receipt '${source}': recovery[${index}] does not identify a resumable entry.`);
+    return { key, call: "runs.run", resume: { workflowRunId, key, latest: true }, taskRequired: true };
+  });
+}
+export function readWorkflowReceipt(asyncDirRoot, workflowRunId) {
+  const receiptPath = workflowReceiptPath(asyncDirRoot, workflowRunId);
+  let value;
+  try {
+    value = readWorkflowReceiptFile(receiptPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      const workflowDir = path.dirname(receiptPath);
+      if (fs.existsSync(path.join(workflowDir, "status.json")) || fs.existsSync(path.join(workflowDir, "events.jsonl"))) {
+        throw new Error(`Workflow receipt '${workflowRunId}' is not available because the workflow may still be active or terminal receipt writing failed. Use direct child run IDs from status/events for direct resume after the normal retained-child checks.`);
+      }
+      throw new Error(`Workflow receipt '${workflowRunId}' was not found.`);
+    }
+    throw new Error(`Workflow receipt '${workflowRunId}' could not be read: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid workflow receipt '${receiptPath}': expected an object.`);
+  const receipt = value;
+  if (receipt.version !== WORKFLOW_RECEIPT_VERSION)
+    throw new Error(`Invalid workflow receipt '${receiptPath}': unsupported version.`);
+  if (receipt.workflowRunId !== workflowRunId)
+    throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowRunId does not match.`);
+  if (receipt.state !== "complete" && receipt.state !== "failed" && receipt.state !== "paused" && receipt.state !== "stopped") {
+    throw new Error(`Workflow receipt '${receiptPath}' is stale: workflow is not terminal.`);
+  }
+  if (typeof receipt.createdAt !== "number" || !Number.isFinite(receipt.createdAt))
+    throw new Error(`Invalid workflow receipt '${receiptPath}': createdAt is invalid.`);
+  if (!receipt.entries || typeof receipt.entries !== "object" || Array.isArray(receipt.entries))
+    throw new Error(`Invalid workflow receipt '${receiptPath}': entries must be an object.`);
+  const entries = Object.create(null);
+  for (const [key, entry] of Object.entries(receipt.entries))
+    entries[assertKey(key, "workflow receipt key")] = parseEntry(entry, key, receiptPath);
+  const workflowChildren = parseWorkflowChildSummary(receipt.workflowChildren);
+  if (workflowChildren && workflowChildren.workflowRunId !== workflowRunId)
+    throw new Error(`Workflow receipt '${receiptPath}' is stale: workflowChildren.workflowRunId does not match.`);
+  let hostSteps;
+  if (receipt.hostSteps !== undefined) {
+    if (!Array.isArray(receipt.hostSteps))
+      throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps must be an array.`);
+    if (receipt.hostSteps.length > HOST_STEP_MAX_COUNT)
+      throw new Error(`Invalid workflow receipt '${receiptPath}': hostSteps exceeds ${HOST_STEP_MAX_COUNT} entries.`);
+    hostSteps = receipt.hostSteps.map((hostStep, index) => parseHostStepNode(hostStep, `${receiptPath} hostSteps[${index}]`));
+    assertUniqueHostStepIds(hostSteps, receiptPath);
+  }
+  const workflowResolution = parseWorkflowResolution(receipt.workflowResolution, receiptPath);
+  const terminalOutcome = parseTerminalOutcome(receipt.terminalOutcome, `Invalid workflow receipt '${receiptPath}': terminalOutcome`);
+  const recovery = parseRecovery(receipt.recovery, workflowRunId, entries, receiptPath);
+  return { version: 1, workflowRunId, state: receipt.state, createdAt: receipt.createdAt, entries, ...hostSteps?.length ? { hostSteps } : {}, ...workflowChildren ? { workflowChildren } : {}, ...workflowResolution ? { workflowResolution } : {}, ...terminalOutcome ? { terminalOutcome } : {}, ...recovery ? { recovery } : {} };
+}
+export function resolveWorkflowReceiptResumeEntry(input) {
+  if (input.reference.latest !== true)
+    throw new Error("Keyed workflow receipt resume requires latest: true.");
+  const key = assertKey(input.reference.key, "keyed resume key");
+  const receipt = readWorkflowReceipt(input.asyncDirRoot, input.reference.workflowRunId.trim());
+  const entry = receipt.entries[key];
+  if (!entry)
+    throw new Error(`Workflow receipt '${receipt.workflowRunId}' has no child key '${key}'.`);
+  assertResumableEntry(entry, receipt.workflowRunId, key);
+  input.assertResumable?.(entry.latestRunId);
+  return entry;
+}
+function assertResumableEntry(entry, workflowRunId, key) {
+  if (entry.resumability.state !== "resumable")
+    throw new Error(`Workflow receipt '${workflowRunId}' child '${key}' is not resumable: ${entry.resumability.reason}.`);
+  if (!entry.latestRunId)
+    throw new Error(`Workflow receipt '${workflowRunId}' child '${key}' has no retained run id.`);
+}
+export function resolveWorkflowReceiptResume(input) {
+  const entry = resolveWorkflowReceiptResumeEntry(input);
+  return entry.latestRunId;
+}

package/extensions/dm-subagents/src/workflows/workflow-settlement.js

@@ -0,0 +1,189 @@
+import { workflowChildSummary } from "./workflow-child-summary.js";
+export const UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION = "unsupported-continuation: detached workflow child settled, but JavaScript workflow continuation was not persisted. Resume the workflow explicitly instead of treating the completed child as top-level workflow completion.";
+export const INTERRUPTED_DETACHED_CHILD = "Interrupted. Waiting for explicit next action.";
+export const EVIDENCE_PERSISTENCE_FAILED = "evidence-persistence-failed";
+function cloneWorkflowStatus(status) {
+  return {
+    ...status,
+    steps: status.steps?.map((step) => ({ ...step })),
+    workflow: status.workflow ? { ...status.workflow, trace: [...status.workflow.trace ?? []] } : status.workflow
+  };
+}
+function workflowState(status) {
+  return status.state === "complete" ? "completed" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed";
+}
+function withWorkflowChildren(status) {
+  return {
+    ...status,
+    workflowChildren: workflowChildSummary({
+      parentToolCallId: status.toolCallId ?? status.runId,
+      workflowRunId: status.runId,
+      workflowState: workflowState(status),
+      inventoryComplete: true,
+      trace: status.workflow?.trace,
+      steps: status.steps
+    })
+  };
+}
+export function findWorkflowSettlementStep(status, childRunId, workflowKey, sessionFile) {
+  const exact = status.steps?.find((candidate) => candidate.runId === childRunId);
+  if (exact || !workflowKey || !sessionFile)
+    return exact;
+  const candidates = status.steps?.filter((candidate) => candidate.runId === undefined && candidate.workflowKey === workflowKey && candidate.sessionFile === sessionFile) ?? [];
+  return candidates.length === 1 ? candidates[0] : undefined;
+}
+export function promoteSettledPausedWorkflow(status, now = Date.now()) {
+  if (status.mode !== "workflow" || status.state !== "paused")
+    return;
+  const next = cloneWorkflowStatus(status);
+  const stillOpen = next.steps?.some((candidate) => candidate.status === "running" || candidate.status === "paused" && candidate.activityState === "needs_attention") === true;
+  if (stillOpen || !next.steps?.length)
+    return;
+  const failed = next.steps.some((candidate) => candidate.status === "failed");
+  next.lastUpdate = now;
+  next.state = "failed";
+  next.endedAt = now;
+  delete next.activityState;
+  if (!failed)
+    next.error = UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION;
+  return withWorkflowChildren(next);
+}
+export function applyDetachedChildSettlement(status, input) {
+  if (status.mode !== "workflow" || status.state !== "paused")
+    return;
+  const next = cloneWorkflowStatus(status);
+  const step = findWorkflowSettlementStep(next, input.childRunId, input.workflowKey, input.result.sessionFile);
+  if (!step)
+    return;
+  step.runId ??= input.childRunId;
+  const succeeded = input.result.exitCode === 0 && !input.result.error && !input.result.interrupted;
+  const failedSiblingError = next.steps?.find((candidate) => {
+    const candidateStep = candidate;
+    return candidateStep !== step && candidateStep.status === "failed" && !candidateStep.interrupted && candidateStep.error;
+  })?.error;
+  const interruptedChildError = next.steps?.find((candidate) => {
+    const candidateStep = candidate;
+    return candidateStep.status === "failed" && candidateStep.interrupted && candidateStep.error;
+  })?.error;
+  const now = input.now ?? Date.now();
+  step.status = succeeded ? "completed" : "failed";
+  step.endedAt = now;
+  delete step.activityState;
+  delete step.currentTool;
+  delete step.currentToolStartedAt;
+  if (input.result.sessionFile)
+    step.sessionFile = input.result.sessionFile;
+  if (input.result.sessionName)
+    step.sessionName = input.result.sessionName;
+  if (succeeded) {
+    delete step.error;
+    delete step.interrupted;
+  } else if (input.result.interrupted || input.result.stopped) {
+    step.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+    step.interrupted = true;
+    if (input.result.stopped)
+      step.stopped = true;
+  } else {
+    delete step.interrupted;
+    delete step.stopped;
+    if (input.result.error)
+      step.error = input.result.error;
+  }
+  next.lastUpdate = now;
+  const promoted = promoteSettledPausedWorkflow(next, now);
+  if (promoted?.state === "failed" && failedSiblingError)
+    promoted.error = failedSiblingError;
+  else if (promoted?.state === "failed" && (input.result.interrupted || input.result.stopped))
+    promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+  else if (promoted?.state === "failed" && input.result.error)
+    promoted.error = input.result.error;
+  else if (promoted?.state === "failed" && interruptedChildError)
+    promoted.error = interruptedChildError;
+  return withWorkflowChildren(promoted ?? next);
+}
+export function classifyWorkflowSettlement(status, interrupted = false) {
+  if (status.state !== "complete" && status.state !== "failed")
+    return;
+  if (status.steps?.some((step) => {
+    const candidate = step;
+    return candidate.status === "failed" && !candidate.interrupted;
+  }))
+    return "failed-child";
+  if (interrupted || status.steps?.some((step) => {
+    const candidate = step;
+    return candidate.status === "stopped" || candidate.stopped || candidate.interrupted || candidate.error === INTERRUPTED_DETACHED_CHILD;
+  }))
+    return "interrupted-child";
+  return "settled-awaiting-resume";
+}
+export function workflowRecoveryActions(receipt) {
+  if (!receipt)
+    return [];
+  return Object.values(receipt.entries).flatMap((entry) => entry.resumability.state === "resumable" ? [{ key: entry.key, call: "runs.run", resume: { workflowRunId: receipt.workflowRunId, key: entry.key, latest: true }, taskRequired: true }] : []);
+}
+export function workflowTerminalOutcomeForResult(result) {
+  if (result.timedOut)
+    return { state: "partial", reason: "timeout" };
+  if (result.turnBudgetExceeded || result.toolBudgetBlocked)
+    return { state: "partial", reason: "budget_exhausted" };
+  return;
+}
+export function workflowOutputPathMappingSummary(children) {
+  const mappings = children.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const child = entry;
+    return child.outputPathMapping ? [`'${child.workflowKey ?? "child"}': requested ${child.outputPathMapping.requestedPath} -> saved ${child.outputPathMapping.savedPath}`] : [];
+  });
+  return mappings.length > 0 ? ` Output path mappings: ${mappings.join("; ")}.` : "";
+}
+export function planWorkflowSettlement(input) {
+  const now = input.now ?? Date.now();
+  let status = withWorkflowChildren(cloneWorkflowStatus(input.status));
+  let summary = input.summary;
+  let receipt = input.receipt;
+  let resolution = input.resolution;
+  if (input.receiptPersistenceError) {
+    const diagnostic = `${EVIDENCE_PERSISTENCE_FAILED}: ${input.receiptPersistenceError}`;
+    status = withWorkflowChildren({ ...status, state: "failed", error: diagnostic, activityState: undefined, endedAt: now, lastUpdate: now });
+    summary = `${diagnostic} Available child evidence was preserved, but workflow completion was not accepted.`;
+    receipt = undefined;
+    if (!resolution)
+      resolution = classifyWorkflowSettlement(status);
+  }
+  const recovery = workflowRecoveryActions(receipt);
+  if (receipt) {
+    receipt = {
+      ...receipt,
+      state: status.state === "complete" ? "complete" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed",
+      workflowChildren: status.workflowChildren,
+      ...resolution ? { workflowResolution: resolution, recovery } : {}
+    };
+  }
+  const publicResult = {
+    ...input.baseResult,
+    success: status.state === "complete",
+    state: status.state,
+    summary,
+    error: status.state === "complete" ? undefined : status.error ?? summary,
+    stopped: status.stopped ? true : undefined,
+    activityState: status.activityState,
+    workflowChildren: status.workflowChildren,
+    results: input.children,
+    ...input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {},
+    ...resolution ? { workflowResolution: resolution, recovery } : {},
+    ...receipt && input.receiptPath ? { workflowReceipt: { path: input.receiptPath, receipt } } : {},
+    timestamp: now
+  };
+  const terminal = status.state === "complete" || status.state === "failed" || status.state === "partial" || status.state === "stopped";
+  const completionEvent = terminal ? {
+    type: "subagent.workflow.completed",
+    state: status.state,
+    ...resolution ? { workflowResolution: resolution } : {},
+    ...input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {},
+    ...status.error ? { error: status.error } : {},
+    ...status.activityState ? { activityState: status.activityState } : {},
+    ...input.eventMetadata
+  } : undefined;
+  return { status, publicResult, receipt, recovery, completionEvent };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckmind/dm-windows-x64",
-  "version": "0.61.4",
+  "version": "0.61.9",
   "description": "DuckMind (dm) binary payload for windows x64",
   "license": "MIT",
   "os": [
@@ -27,11 +27,12 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "acorn": "8.18.0",
     "jiti": "2.7.0",
     "typebox": "^1.1.34",
-    "@ff-labs/fff-node": "*",
-    "@sinclair/typebox": "^0.34.48",
+    "yaml": "2.8.3",
     "@mozilla/readability": "^0.6.0",
+    "@sinclair/typebox": "^0.34.48",
     "jsdom": "^29.1.1",
     "pdf-parse": "^2.4.5",
     "turndown": "^7.1.2"

package/extensions/dm-fff/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "dm-fff",
-  "version": "0.6.0",
-  "description": "DM extension: FFF-powered fuzzy file and content search",
-  "type": "module",
-  "license": "MIT",
-  "keywords": [
-    "duckmind",
-    "dm",
-    "fff",
-    "search",
-    "grep",
-    "fuzzy-search",
-    "ai-agent"
-  ],
-  "dm": {
-    "extensions": [
-      "./src/index.js"
-    ]
-  }
-}