@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/shared/external-job-runner.js

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExternalJobProviderError } from "../../api/external-job-provider.js";
+import { requestExternalJobOperation } from "./external-job-bridge.js";
+const STATUS_POLL_INTERVAL_MS = 1000;
+export function externalJobPromptDigest(prompt) {
+  return createHash("sha256").update(prompt).digest("hex");
+}
+export function externalJobStableJson(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(externalJobStableJson).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${externalJobStableJson(record[key])}`).join(",")}}`;
+}
+export function externalJobFollowUpRequestDigest(input) {
+  return createHash("sha256").update(externalJobStableJson({ provider: input.provider, parentProviderJobId: input.parentProviderJobId, promptDigest: input.promptDigest, options: input.options })).digest("hex");
+}
+export function externalJobFollowUpRequestId(requestDigest) {
+  return `follow-up-${requestDigest.slice(0, 48)}`;
+}
+export function externalJobFollowUpRunId(requestDigest) {
+  const hex = requestDigest.padEnd(32, "0").slice(0, 32).split("");
+  hex[12] = "4";
+  hex[16] = (Number.parseInt(hex[16], 16) & 3 | 8).toString(16);
+  const value = hex.join("");
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function terminal(state) {
+  return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
+}
+function formatError(error, provider) {
+  const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
+  return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function malformedStatus(statusPath) {
+  return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
+}
+function parseExternalJobStatus(value, statusPath) {
+  if (!isRecord(value))
+    throw malformedStatus(statusPath);
+  const provider = value.provider;
+  const promptDigest = value.promptDigest;
+  const state = value.state;
+  if (typeof provider !== "string" || provider.length === 0)
+    throw malformedStatus(statusPath);
+  if (typeof promptDigest !== "string" || promptDigest.length === 0)
+    throw malformedStatus(statusPath);
+  if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked")
+    throw malformedStatus(statusPath);
+  if (value.options !== undefined && !isRecord(value.options))
+    throw malformedStatus(statusPath);
+  const providerJobId = value.providerJobId;
+  const handleUrl = value.handleUrl;
+  const conversationUrl = value.conversationUrl;
+  const resultArtifactPath = value.resultArtifactPath;
+  const failureCode = value.failureCode;
+  const failureMessage = value.failureMessage;
+  const blockingJobId = value.blockingJobId;
+  const startedAt = value.startedAt;
+  const updatedAt = value.updatedAt;
+  if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0))
+    throw malformedStatus(statusPath);
+  if (handleUrl !== undefined && typeof handleUrl !== "string")
+    throw malformedStatus(statusPath);
+  if (conversationUrl !== undefined && typeof conversationUrl !== "string")
+    throw malformedStatus(statusPath);
+  if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string")
+    throw malformedStatus(statusPath);
+  if (failureCode !== undefined && typeof failureCode !== "string")
+    throw malformedStatus(statusPath);
+  if (failureMessage !== undefined && typeof failureMessage !== "string")
+    throw malformedStatus(statusPath);
+  if (blockingJobId !== undefined && typeof blockingJobId !== "string")
+    throw malformedStatus(statusPath);
+  const operation = value.operation;
+  const sourceRunId = value.sourceRunId;
+  const sourceStepIndex = value.sourceStepIndex;
+  const parentProviderJobId = value.parentProviderJobId;
+  const requestId = value.requestId;
+  const requestDigest = value.requestDigest;
+  if (operation !== undefined && operation !== "start" && operation !== "follow-up")
+    throw malformedStatus(statusPath);
+  if (sourceRunId !== undefined && (typeof sourceRunId !== "string" || sourceRunId.length === 0))
+    throw malformedStatus(statusPath);
+  if (sourceStepIndex !== undefined && (typeof sourceStepIndex !== "number" || !Number.isInteger(sourceStepIndex) || sourceStepIndex < 0))
+    throw malformedStatus(statusPath);
+  if (parentProviderJobId !== undefined && (typeof parentProviderJobId !== "string" || parentProviderJobId.length === 0))
+    throw malformedStatus(statusPath);
+  if (requestId !== undefined && (typeof requestId !== "string" || requestId.length === 0))
+    throw malformedStatus(statusPath);
+  if (requestDigest !== undefined && (typeof requestDigest !== "string" || requestDigest.length === 0))
+    throw malformedStatus(statusPath);
+  if (startedAt !== undefined && typeof startedAt !== "number")
+    throw malformedStatus(statusPath);
+  if (updatedAt !== undefined && typeof updatedAt !== "number")
+    throw malformedStatus(statusPath);
+  return {
+    provider,
+    promptDigest,
+    ...operation ? { operation } : {},
+    ...sourceRunId ? { sourceRunId } : {},
+    ...sourceStepIndex !== undefined ? { sourceStepIndex } : {},
+    ...parentProviderJobId ? { parentProviderJobId } : {},
+    ...requestId ? { requestId } : {},
+    ...requestDigest ? { requestDigest } : {},
+    options: value.options ?? {},
+    state,
+    ...providerJobId ? { providerJobId } : {},
+    ...handleUrl ? { handleUrl } : {},
+    ...conversationUrl ? { conversationUrl } : {},
+    ...resultArtifactPath ? { resultArtifactPath } : {},
+    ...failureCode ? { failureCode } : {},
+    ...failureMessage ? { failureMessage } : {},
+    ...blockingJobId ? { blockingJobId } : {},
+    ...startedAt !== undefined ? { startedAt } : {},
+    ...updatedAt !== undefined ? { updatedAt } : {}
+  };
+}
+function readExistingExternalJob(asyncDir, stepIndex) {
+  const statusPath = path.join(asyncDir, "status.json");
+  let raw;
+  try {
+    raw = fs.readFileSync(statusPath, "utf-8");
+  } catch (error) {
+    if (isNotFound(error))
+      return;
+    throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.steps))
+    throw malformedStatus(statusPath);
+  const step = parsed.steps[stepIndex];
+  if (step === undefined || !isRecord(step))
+    throw malformedStatus(statusPath);
+  if (step.externalJob === undefined)
+    return;
+  return parseExternalJobStatus(step.externalJob, statusPath);
+}
+function externalJobLineage(followUp, previous) {
+  return {
+    operation: followUp ? "follow-up" : previous?.operation,
+    ...followUp ? {
+      sourceRunId: followUp.sourceRunId,
+      sourceStepIndex: followUp.sourceStepIndex,
+      parentProviderJobId: followUp.parentProviderJobId,
+      requestId: followUp.requestId,
+      requestDigest: followUp.requestDigest
+    } : {
+      ...previous?.sourceRunId ? { sourceRunId: previous.sourceRunId } : {},
+      ...previous?.sourceStepIndex !== undefined ? { sourceStepIndex: previous.sourceStepIndex } : {},
+      ...previous?.parentProviderJobId ? { parentProviderJobId: previous.parentProviderJobId } : {},
+      ...previous?.requestId ? { requestId: previous.requestId } : {},
+      ...previous?.requestDigest ? { requestDigest: previous.requestDigest } : {}
+    }
+  };
+}
+function statusFromHandle(input) {
+  return {
+    provider: input.provider,
+    providerJobId: input.handle.providerJobId,
+    promptDigest: input.promptDigest,
+    ...externalJobLineage(input.followUp, input.previous),
+    options: input.options,
+    handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
+    conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
+    resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
+    state: input.handle.state,
+    failureCode: input.handle.failureCode,
+    failureMessage: input.handle.failureMessage,
+    blockingJobId: input.handle.blockingJobId,
+    startedAt: input.previous?.startedAt ?? input.startedAt,
+    updatedAt: Date.now()
+  };
+}
+function failureStatus(input) {
+  return {
+    provider: input.provider,
+    providerJobId: input.previous?.providerJobId,
+    promptDigest: input.promptDigest,
+    ...externalJobLineage(input.followUp, input.previous),
+    options: input.options,
+    handleUrl: input.previous?.handleUrl,
+    conversationUrl: input.previous?.conversationUrl,
+    resultArtifactPath: input.previous?.resultArtifactPath,
+    state: input.blockingJobId ? "blocked" : "failed",
+    failureCode: input.code,
+    failureMessage: input.message,
+    blockingJobId: input.blockingJobId,
+    startedAt: input.previous?.startedAt,
+    updatedAt: Date.now()
+  };
+}
+function resultOutput(result, artifactPath) {
+  if (result.output?.trim())
+    return result.output.trim();
+  if (artifactPath)
+    return `External job finished. Result artifact: ${artifactPath}`;
+  return "External job finished without text output.";
+}
+function blocksStartRedispatch(status, provider, promptDigest) {
+  return status.provider === provider && status.promptDigest === promptDigest && !status.providerJobId && status.failureCode !== "provider-unavailable";
+}
+function sameFollowUpLineage(status, followUp) {
+  if (!followUp)
+    return status.operation !== "follow-up";
+  return status.operation === "follow-up" && status.sourceRunId === followUp.sourceRunId && status.sourceStepIndex === followUp.sourceStepIndex && status.parentProviderJobId === followUp.parentProviderJobId && status.requestId === followUp.requestId && status.requestDigest === followUp.requestDigest;
+}
+export async function runExternalJob(input) {
+  const provider = input.provider;
+  const options = input.options ?? {};
+  const promptDigest = externalJobPromptDigest(input.prompt);
+  const startedAt = Date.now();
+  let timedOut = false;
+  let stopped = false;
+  let current;
+  const timeout = () => {
+    timedOut = true;
+  };
+  const stop = () => {
+    stopped = true;
+  };
+  input.registerTimeout?.(timeout);
+  input.registerStop?.(stop);
+  const publish = (status) => {
+    current = status;
+    input.onExternalJob?.(status);
+  };
+  const localCancellation = () => {
+    if (!timedOut && !stopped)
+      return;
+    const message = stopped ? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.` : input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
+    return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
+  };
+  try {
+    current = readExistingExternalJob(input.asyncDir, input.stepIndex);
+    let handle;
+    if (current?.providerJobId) {
+      if (current.provider !== provider || current.promptDigest !== promptDigest || !sameFollowUpLineage(current, input.followUp)) {
+        const message = `Existing external job '${current.providerJobId}' does not match provider, prompt digest, or follow-up lineage. Refusing to redispatch prompt.`;
+        const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: "recovery-mismatch", message });
+        publish(status);
+        return { output: message, exitCode: 1, error: message, externalJob: status };
+      }
+      handle = await requestExternalJobOperation(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
+    } else {
+      if (current && blocksStartRedispatch(current, provider, promptDigest)) {
+        const message = `External-job ${input.followUp ? "follow-up" : "start"} for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
+        const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: input.followUp ? "dispatch-redispatch-blocked" : "start-redispatch-blocked", message });
+        publish(status);
+        return { output: message, exitCode: 1, error: message, externalJob: status };
+      }
+      publish({ provider, promptDigest, ...input.followUp ? { operation: "follow-up", ...input.followUp } : {}, options, state: "queued", startedAt, updatedAt: Date.now() });
+      if (input.followUp) {
+        handle = await requestExternalJobOperation(input.asyncDir, {
+          operation: "follow-up",
+          provider,
+          followUp: {
+            prompt: input.prompt,
+            promptDigest,
+            cwd: input.cwd,
+            runId: input.runId,
+            stepIndex: input.stepIndex,
+            agent: input.agent,
+            options,
+            ...input.sessionId ? { sessionId: input.sessionId } : {},
+            ...input.followUp
+          }
+        }, undefined, localCancellation);
+      } else {
+        handle = await requestExternalJobOperation(input.asyncDir, {
+          operation: "start",
+          provider,
+          start: {
+            prompt: input.prompt,
+            promptDigest,
+            cwd: input.cwd,
+            runId: input.runId,
+            stepIndex: input.stepIndex,
+            agent: input.agent,
+            options,
+            ...input.sessionId ? { sessionId: input.sessionId } : {}
+          }
+        }, undefined, localCancellation);
+      }
+    }
+    publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, startedAt, previous: current, handle }));
+    while (!terminal(handle.state)) {
+      if (timedOut || stopped) {
+        const message = stopped ? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.` : input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
+        return { output: message, exitCode: 1, error: message, ...timedOut ? { timedOut: true } : {}, ...stopped ? { stopped: true } : {}, externalJob: current };
+      }
+      await sleep(STATUS_POLL_INTERVAL_MS);
+      handle = await requestExternalJobOperation(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
+      publish(statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle }));
+    }
+    const result = await requestExternalJobOperation(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
+    let artifactPath = result.artifactPath;
+    if (!artifactPath && result.output !== undefined) {
+      artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
+      fs.writeFileSync(artifactPath, result.output, "utf-8");
+    }
+    const finalStatus = statusFromHandle({ provider, promptDigest, options, followUp: input.followUp, previous: current, handle: result, resultArtifactPath: artifactPath });
+    publish(finalStatus);
+    const output = resultOutput(result, artifactPath);
+    const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
+    return { output, exitCode: result.state === "completed" ? 0 : 1, ...error ? { error } : {}, externalJob: finalStatus };
+  } catch (error) {
+    const providerError = error instanceof ExternalJobProviderError ? error : new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
+    const message = formatError(providerError, provider);
+    const status = failureStatus({ provider, promptDigest, options, followUp: input.followUp, previous: current, code: providerError.code, message, ...providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {} });
+    publish(status);
+    return { output: message, exitCode: 1, error: message, ...timedOut ? { timedOut: true } : {}, ...stopped ? { stopped: true } : {}, externalJob: status };
+  } finally {
+    input.registerTimeout?.(undefined);
+    input.registerStop?.(undefined);
+  }
+}

package/extensions/dm-subagents/src/runs/shared/fast-mode-extension.js

@@ -0,0 +1,8 @@
+export function rewriteFastModeProviderRequest(event) {
+  if (!event.payload || typeof event.payload !== "object" || Array.isArray(event.payload))
+    return event.payload;
+  return { ...event.payload, service_tier: "priority" };
+}
+export default function registerSubagentFastModeExtension(dm) {
+  dm.on("before_provider_request", rewriteFastModeProviderRequest);
+}

package/extensions/dm-subagents/src/runs/shared/host-step-status.js

@@ -0,0 +1,228 @@
+export const HOST_STEP_MAX_ID_CHARS = 128;
+export const HOST_STEP_MAX_LABEL_CHARS = 80;
+export const HOST_STEP_MAX_ROLE_CHARS = 32;
+export const HOST_STEP_MAX_PROVIDER_CHARS = 64;
+export const HOST_STEP_MAX_REASON_CHARS = 64;
+export const HOST_STEP_MAX_DETAIL_CHARS = 200;
+export const HOST_STEP_MAX_TARGET_CHARS = 128;
+export const HOST_STEP_MAX_REF_CHARS = 128;
+export const HOST_STEP_MAX_REPORT_PATH_CHARS = 240;
+export const HOST_STEP_MAX_COUNT = 32;
+const HOST_STEP_FIELDS = new Set([
+  "version",
+  "kind",
+  "monitorKind",
+  "id",
+  "label",
+  "role",
+  "provider",
+  "state",
+  "verdict",
+  "reasonCode",
+  "detail",
+  "target",
+  "freshness",
+  "reportPath",
+  "exitCode",
+  "updatedAt",
+  "deadlineAt"
+]);
+const FRESHNESS_FIELDS = new Set(["expectedRef", "observedRef", "stale"]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertBoundedString(value, field, maxChars, source, required = false) {
+  if (value === undefined && !required)
+    return;
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`Invalid host step '${source}': ${field} must be a non-empty string.`);
+  if (value.length > maxChars)
+    throw new Error(`Invalid host step '${source}': ${field} exceeds ${maxChars} characters.`);
+  if (/\r|\n/.test(value))
+    throw new Error(`Invalid host step '${source}': ${field} must be single-line.`);
+}
+function assertTimestamp(value, field, source, required = false) {
+  if (value === undefined && !required)
+    return;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    throw new Error(`Invalid host step '${source}': ${field} must be a non-negative safe integer.`);
+}
+function assertFreshness(value, source) {
+  if (!isRecord(value))
+    throw new Error(`Invalid host step '${source}': freshness must be an object.`);
+  const unknownFields = Object.keys(value).filter((field) => !FRESHNESS_FIELDS.has(field));
+  if (unknownFields.length > 0)
+    throw new Error(`Invalid host step '${source}': freshness has unsupported fields: ${unknownFields.join(", ")}.`);
+  assertBoundedString(value.expectedRef, "freshness.expectedRef", HOST_STEP_MAX_REF_CHARS, source, true);
+  assertBoundedString(value.observedRef, "freshness.observedRef", HOST_STEP_MAX_REF_CHARS, source);
+  if (value.stale !== undefined && typeof value.stale !== "boolean")
+    throw new Error(`Invalid host step '${source}': freshness.stale must be a boolean.`);
+}
+export function assertHostStepNode(value, source = "status") {
+  if (!isRecord(value))
+    throw new Error(`Invalid host step '${source}': expected an object.`);
+  const unknownFields = Object.keys(value).filter((field) => !HOST_STEP_FIELDS.has(field));
+  if (unknownFields.length > 0)
+    throw new Error(`Invalid host step '${source}': unsupported fields: ${unknownFields.join(", ")}.`);
+  if (value.version !== 1)
+    throw new Error(`Invalid host step '${source}': version must be 1.`);
+  if (value.kind !== "host-step")
+    throw new Error(`Invalid host step '${source}': kind must be 'host-step'.`);
+  if (value.monitorKind !== "command" && value.monitorKind !== "ci" && value.monitorKind !== "gate")
+    throw new Error(`Invalid host step '${source}': monitorKind must be 'command', 'ci', or 'gate'.`);
+  assertBoundedString(value.id, "id", HOST_STEP_MAX_ID_CHARS, source, true);
+  assertBoundedString(value.label, "label", HOST_STEP_MAX_LABEL_CHARS, source, true);
+  assertBoundedString(value.role, "role", HOST_STEP_MAX_ROLE_CHARS, source);
+  assertBoundedString(value.provider, "provider", HOST_STEP_MAX_PROVIDER_CHARS, source);
+  if (value.state !== "pending" && value.state !== "running" && value.state !== "done" && value.state !== "cancelled" && value.state !== "error") {
+    throw new Error(`Invalid host step '${source}': state is invalid.`);
+  }
+  if (value.verdict !== undefined && value.verdict !== "pass" && value.verdict !== "fail" && value.verdict !== "inconclusive") {
+    throw new Error(`Invalid host step '${source}': verdict is invalid.`);
+  }
+  if (value.state !== "done" && value.verdict !== undefined)
+    throw new Error(`Invalid host step '${source}': verdict is only valid for done state.`);
+  assertBoundedString(value.reasonCode, "reasonCode", HOST_STEP_MAX_REASON_CHARS, source);
+  assertBoundedString(value.detail, "detail", HOST_STEP_MAX_DETAIL_CHARS, source);
+  assertBoundedString(value.target, "target", HOST_STEP_MAX_TARGET_CHARS, source);
+  if (value.freshness !== undefined)
+    assertFreshness(value.freshness, source);
+  if (value.freshness && value.freshness.stale === true && (value.state !== "done" || value.verdict !== "inconclusive")) {
+    throw new Error(`Invalid host step '${source}': stale freshness requires done/inconclusive state.`);
+  }
+  assertBoundedString(value.reportPath, "reportPath", HOST_STEP_MAX_REPORT_PATH_CHARS, source);
+  const reportName = hostStepReportName(value.reportPath);
+  if (value.reportPath !== undefined && (!reportName || reportName === "." || reportName === ".."))
+    throw new Error(`Invalid host step '${source}': reportPath must name a report.`);
+  if (value.exitCode !== undefined && value.exitCode !== null && (typeof value.exitCode !== "number" || !Number.isSafeInteger(value.exitCode) || value.exitCode < 0))
+    throw new Error(`Invalid host step '${source}': exitCode must be a non-negative safe integer or null.`);
+  if (value.monitorKind !== "command" && value.exitCode !== undefined)
+    throw new Error(`Invalid host step '${source}': exitCode is only valid for command steps.`);
+  if ((value.state === "pending" || value.state === "running") && value.exitCode !== undefined)
+    throw new Error(`Invalid host step '${source}': exitCode is only valid after command settlement.`);
+  assertTimestamp(value.updatedAt, "updatedAt", source, true);
+  assertTimestamp(value.deadlineAt, "deadlineAt", source);
+}
+export function parseHostStepNode(value, source = "status") {
+  assertHostStepNode(value, source);
+  return {
+    ...value,
+    ...value.freshness ? { freshness: { ...value.freshness } } : {}
+  };
+}
+export function assertUniqueHostStepIds(hostSteps, source = "status") {
+  const ids = new Set;
+  for (const hostStep of hostSteps) {
+    if (ids.has(hostStep.id))
+      throw new Error(`Invalid host step '${source}': duplicate host step id '${hostStep.id}'.`);
+    ids.add(hostStep.id);
+  }
+}
+export function validHostStepNodes(graph) {
+  const nodes = graph?.nodes ?? [];
+  const nodeIdCounts = new Map;
+  for (const node of nodes)
+    nodeIdCounts.set(node.id, (nodeIdCounts.get(node.id) ?? 0) + 1);
+  const hostSteps = [];
+  for (const [index, node] of nodes.entries()) {
+    if (node.kind !== "host-step")
+      continue;
+    try {
+      const hostStep = parseHostStepNode(node.hostStep, `workflowGraph.nodes[${index}].hostStep`);
+      if (node.id !== hostStep.id || node.label !== hostStep.label)
+        continue;
+      if (nodeIdCounts.get(hostStep.id) !== 1)
+        continue;
+      hostSteps.push(hostStep);
+    } catch {}
+  }
+  return hostSteps.slice(0, HOST_STEP_MAX_COUNT);
+}
+export function assertWorkflowGraphHostSteps(graph, source = "status", expectedRunId) {
+  if (!graph)
+    return;
+  if (expectedRunId !== undefined && graph.runId !== expectedRunId)
+    throw new Error(`Invalid host step '${source}': workflowGraph.runId does not match the status run id.`);
+  const hostStepCount = graph.nodes.filter((node) => node.kind === "host-step").length;
+  if (hostStepCount > HOST_STEP_MAX_COUNT)
+    throw new Error(`Invalid host step '${source}': workflowGraph contains more than ${HOST_STEP_MAX_COUNT} host steps.`);
+  const hostSteps = [];
+  for (const [index, node] of graph.nodes.entries()) {
+    if (node.kind !== "host-step")
+      continue;
+    const hostStep = parseHostStepNode(node.hostStep, `${source}.workflowGraph.nodes[${index}].hostStep`);
+    if (node.id !== hostStep.id)
+      throw new Error(`Invalid host step '${source}': workflowGraph.nodes[${index}].id does not match hostStep.id.`);
+    if (node.label !== hostStep.label)
+      throw new Error(`Invalid host step '${source}': workflowGraph.nodes[${index}].label does not match hostStep.label.`);
+    hostSteps.push(hostStep);
+  }
+  assertUniqueHostStepIds(hostSteps, source);
+  for (const hostStep of hostSteps) {
+    if (graph.nodes.filter((node) => node.id === hostStep.id).length !== 1)
+      throw new Error(`Invalid host step '${source}': workflowGraph id '${hostStep.id}' is not unique.`);
+  }
+}
+export function hostStepWorkflowNode(hostStep) {
+  assertHostStepNode(hostStep, hostStep.id);
+  return {
+    id: hostStep.id,
+    kind: "host-step",
+    label: hostStep.label,
+    status: workflowNodeStatus(hostStep),
+    hostStep: { ...hostStep, ...hostStep.freshness ? { freshness: { ...hostStep.freshness } } : {} }
+  };
+}
+function workflowNodeStatus(hostStep) {
+  if (hostStep.state === "pending")
+    return "pending";
+  if (hostStep.state === "running")
+    return "running";
+  if (hostStep.state === "cancelled")
+    return "stopped";
+  if (hostStep.state === "error")
+    return "failed";
+  if (hostStep.verdict === undefined || hostStep.verdict === "inconclusive")
+    return "partial";
+  return hostStep.verdict === "fail" ? "failed" : "completed";
+}
+export function upsertHostStep(input) {
+  const hostStep = parseHostStepNode(input.hostStep, input.hostStep.id);
+  assertWorkflowGraphHostSteps(input.status.workflowGraph, "host-step", input.status.runId);
+  const graph = input.status.workflowGraph ? {
+    ...input.status.workflowGraph,
+    nodes: [...input.status.workflowGraph.nodes]
+  } : {
+    runId: input.status.runId,
+    mode: input.status.mode,
+    phases: [],
+    nodes: []
+  };
+  const existingIndex = graph.nodes.findIndex((node) => node.id === hostStep.id);
+  const existing = existingIndex >= 0 ? graph.nodes[existingIndex] : undefined;
+  if (existing && existing.kind !== "host-step")
+    throw new Error(`Host step '${hostStep.id}' conflicts with an existing workflow node.`);
+  if (existingIndex < 0 && graph.nodes.filter((candidate) => candidate.kind === "host-step").length >= HOST_STEP_MAX_COUNT) {
+    throw new Error(`Host step limit of ${HOST_STEP_MAX_COUNT} has been reached.`);
+  }
+  const node = hostStepWorkflowNode(hostStep);
+  if (existingIndex >= 0)
+    graph.nodes[existingIndex] = node;
+  else
+    graph.nodes.push(node);
+  const nextStatus = {
+    ...input.status,
+    workflowGraph: graph,
+    lastUpdate: Math.max(input.status.lastUpdate ?? 0, hostStep.updatedAt)
+  };
+  input.persist(nextStatus);
+  return nextStatus;
+}
+export function hostStepVerdictLabel(state, verdict) {
+  return state === "done" ? verdict ?? "inconclusive" : state;
+}
+export function hostStepReportName(reportPath) {
+  if (!reportPath)
+    return;
+  return reportPath.split(/[\\/]/).filter(Boolean).at(-1);
+}

package/extensions/dm-subagents/src/runs/shared/lane-metadata.js

@@ -0,0 +1,104 @@
+export const WORKFLOW_LANE_KEY_MAX_BYTES = 128;
+export const WORKFLOW_LANE_SOURCE_REF_MAX_BYTES = 128;
+export const WORKFLOW_LANE_CLAIM_MAX_BYTES = 160;
+export const WORKFLOW_LANE_CLAIMS_MAX = 20;
+export const WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES = 256;
+export const WORKFLOW_LANE_OUTPUT_PATHS_MAX = 10;
+export const WORKTREE_STATUS_PATH_MAX_BYTES = 4096;
+export const WORKTREE_STATUS_BRANCH_MAX_BYTES = 256;
+const WORKFLOW_LANE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const WORKFLOW_LANE_MODES = new Set(["mutation", "review", "scout", "gate"]);
+function byteLength(value) {
+  return Buffer.byteLength(value, "utf8");
+}
+function boundedNonEmptyString(value, label, maxBytes) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} must be a non-empty string.`);
+  const normalized = value.trim();
+  if (byteLength(normalized) > maxBytes)
+    throw new Error(`${label} exceeds ${maxBytes} UTF-8 bytes.`);
+  if ([...normalized].some((character) => character === `
+` || character === "\r" || character === "\x00"))
+    throw new Error(`${label} must not contain newlines or NUL bytes.`);
+  return normalized;
+}
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new Error(`${label} must be a plain JSON object.`);
+  }
+}
+function assertKnownFields(value, fields, label) {
+  const unknown = Object.keys(value).filter((field) => !fields.includes(field));
+  if (unknown.length > 0)
+    throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+}
+function boundedStringArray(value, label, maxItems, maxBytes) {
+  if (!Array.isArray(value))
+    throw new Error(`${label} must be an array.`);
+  if (value.length > maxItems)
+    throw new Error(`${label} supports at most ${maxItems} entries.`);
+  return value.map((entry, index) => {
+    if (!Object.hasOwn(value, index))
+      throw new Error(`${label} must not contain sparse entries.`);
+    return boundedNonEmptyString(entry, `${label}[${index}]`, maxBytes);
+  });
+}
+export function normalizeWorkflowLaneMetadata(value, label = "lane") {
+  if (value === undefined)
+    return;
+  assertPlainObject(value, label);
+  assertKnownFields(value, ["version", "key", "mode", "sourceRef", "claims", "outputPaths"], label);
+  if (value.version !== 1)
+    throw new Error(`${label}.version must be 1.`);
+  const key = boundedNonEmptyString(value.key, `${label}.key`, WORKFLOW_LANE_KEY_MAX_BYTES);
+  if (!WORKFLOW_LANE_KEY_PATTERN.test(key))
+    throw new Error(`${label}.key is invalid.`);
+  const mode = value.mode;
+  if (mode !== undefined && (typeof mode !== "string" || !WORKFLOW_LANE_MODES.has(mode)))
+    throw new Error(`${label}.mode is invalid.`);
+  const sourceRef = value.sourceRef === undefined ? undefined : boundedNonEmptyString(value.sourceRef, `${label}.sourceRef`, WORKFLOW_LANE_SOURCE_REF_MAX_BYTES);
+  const claims = value.claims === undefined ? undefined : boundedStringArray(value.claims, `${label}.claims`, WORKFLOW_LANE_CLAIMS_MAX, WORKFLOW_LANE_CLAIM_MAX_BYTES);
+  const outputPaths = value.outputPaths === undefined ? undefined : boundedStringArray(value.outputPaths, `${label}.outputPaths`, WORKFLOW_LANE_OUTPUT_PATHS_MAX, WORKFLOW_LANE_OUTPUT_PATH_MAX_BYTES);
+  return {
+    version: 1,
+    key,
+    ...mode !== undefined ? { mode } : {},
+    ...sourceRef !== undefined ? { sourceRef } : {},
+    ...claims !== undefined ? { claims } : {},
+    ...outputPaths !== undefined ? { outputPaths } : {}
+  };
+}
+export function assertWorkflowLaneKey(lane, workflowKey, label = "lane") {
+  if (!lane || workflowKey === undefined)
+    return;
+  if (lane.key !== workflowKey)
+    throw new Error(`${label}.key '${lane.key}' does not match workflow key '${workflowKey}'.`);
+}
+export function normalizeWorktreeStatusReference(value, label = "worktree status reference") {
+  if (value === undefined)
+    return;
+  assertPlainObject(value, label);
+  assertKnownFields(value, ["worktreePath", "branch"], label);
+  return {
+    worktreePath: boundedNonEmptyString(value.worktreePath, `${label}.worktreePath`, WORKTREE_STATUS_PATH_MAX_BYTES),
+    branch: boundedNonEmptyString(value.branch, `${label}.branch`, WORKTREE_STATUS_BRANCH_MAX_BYTES)
+  };
+}
+export function validateAsyncStatusLaneMetadata(status, label = "async status") {
+  const lane = normalizeWorkflowLaneMetadata(status.lane, `${label}.lane`);
+  assertWorkflowLaneKey(lane, status.workflowKey, `${label}.lane`);
+  if (lane)
+    status.lane = lane;
+  for (const [index, step] of (status.steps ?? []).entries()) {
+    const stepLane = normalizeWorkflowLaneMetadata(step.lane, `${label}.steps[${index}].lane`);
+    assertWorkflowLaneKey(stepLane, step.workflowKey, `${label}.steps[${index}].lane`);
+    if (stepLane)
+      step.lane = stepLane;
+    const hasPath = step.worktreePath !== undefined;
+    const hasBranch = step.branch !== undefined;
+    if (hasPath !== hasBranch)
+      throw new Error(`${label}.steps[${index}] must include both worktreePath and branch.`);
+    if (hasPath)
+      normalizeWorktreeStatusReference({ worktreePath: step.worktreePath, branch: step.branch }, `${label}.steps[${index}]`);
+  }
+}