@duckmind/dm-linux-x64 0.65.5 → 0.65.6

package/extensions/dm-subagents/src/runs/shared/external-cli-preflight.js

@@ -3,7 +3,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
 const MAX_PROBE_TIMEOUT_MS = 5000;
+const MAX_REMOTE_PROBE_TIMEOUT_MS = 15000;
 const MAX_CACHE_ENTRIES = 64;
+const MAX_AVAILABILITY_REASON_LENGTH = 256;
 const cache = new Map;
 const lookup = new Map;
 function resolveBinary(command, env) {
@@ -26,6 +28,15 @@ function resolveBinary(command, env) {
   }
   throw new Error(`External CLI binary '${command}' was not found on PATH.`);
 }
+export function resolveExternalCliBinaryAvailability(command, env) {
+  try {
+    resolveBinary(command, env);
+    return { available: true };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { available: false, unavailableReason: reason.slice(0, MAX_AVAILABILITY_REASON_LENGTH) };
+  }
+}
 function probeWithTimeout(binaryPath, args, env, label, timeoutMs, cwd) {
   const result = spawnSync(binaryPath, [...args], {
     cwd,
@@ -50,7 +61,7 @@ function narrowPositiveInteger(value, ceiling, label) {
   return value;
 }
 function specKey(spec) {
-  return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+  return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs, spec.remote === true]);
 }
 export function preflightExternalCli(command, spec, env, cwd) {
   const binaryPath = resolveBinary(command, env);
@@ -58,7 +69,8 @@ export function preflightExternalCli(command, spec, env, cwd) {
   const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
   const cachedKey = lookup.get(lookupKey);
   const cached = cachedKey ? cache.get(cachedKey) : undefined;
-  const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+  const ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
+  const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "probeTimeoutMs");
   const base = cached ?? {
     binaryPath,
     binaryMtimeMs,

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

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { finished } from "node:stream/promises";
 import { createOwnedProcessTreeController } from "../background/owned-process-tree.js";
 import { omitExtensionBindingsEnv } from "./extension-bindings.js";
+import { omitGitRoutingEnv } from "./git-environment.js";
 import {
   invalidateExternalCliPreflight,
   preflightExternalCli
@@ -47,7 +48,7 @@ function narrowLimit(value, ceiling, label) {
 }
 function externalEnvironment(allowlist, values) {
   if (!allowlist)
-    return omitExtensionBindingsEnv(process.env);
+    return omitGitRoutingEnv(omitExtensionBindingsEnv(process.env));
   const allowed = new Set(allowlist);
   const env = {};
   for (const key of allowed) {
@@ -366,10 +367,7 @@ export function runExternalCli(input) {
       input.registerTimeout?.(undefined);
       input.registerStop?.(undefined);
       (async () => {
-        if (termination)
-          await termination;
-        else if (processTree)
-          await processTree.finishAfterWriterClose();
+        const treeProof = termination ? await termination : processTree ? await processTree.finishAfterWriterClose() : undefined;
         const endedAt = Date.now();
         const externalProcess = {
           ...initialProcess,
@@ -385,12 +383,13 @@ export function runExternalCli(input) {
         input.onProcess?.(externalProcess);
         const stderr = stderrTail.text().trim();
         const parserFailure = parserError?.message ?? (parserTerminal?.state === "failed" ? parserTerminal.error ?? "External CLI parser reported terminal failure." : undefined);
-        const error = stopped ? input.stopMessage ?? "Subagent stopped by user." : timedOut ? input.timeoutMessage ?? "Subagent timed out." : spawnError?.message ?? parserFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
+        const treeFailure = process.platform !== "win32" && treeProof?.state === "unknown" ? `Process-tree cleanup failed: ${treeProof.reason}.` : undefined;
+        const error = stopped ? input.stopMessage ?? "Subagent stopped by user." : timedOut ? input.timeoutMessage ?? "Subagent timed out." : spawnError?.message ?? parserFailure ?? treeFailure ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
         if (error && input.preflight && !parserError)
           invalidateExternalCliPreflight(input.command, input.preflight, classifyInvalidation(error));
         const result = {
           output: (!parserError && parserTerminal?.state === "completed" ? parserTerminal.output ?? "" : stdoutTail.text()).trim(),
-          exitCode: timedOut || stopped || spawnError || parserFailure ? 1 : exitCode,
+          exitCode: timedOut || stopped || spawnError || parserFailure || treeFailure ? 1 : exitCode,
           ...error ? { error } : {},
           ...timedOut ? { timedOut: true } : {},
           ...stopped ? { stopped: true } : {},

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

@@ -3,6 +3,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.js";
+import { readStatus } from "../../shared/utils.js";
+import { isActiveAsyncState } from "../background/active-run-index.js";
 import {
   ExternalJobProviderError,
   getExternalJobProvider,
@@ -13,6 +15,7 @@ export const EXTERNAL_JOB_BRIDGE_REQUEST_DIR = "external-job-requests";
 const EXTERNAL_JOB_BRIDGE_RESPONSE_DIR = "external-job-responses";
 const DEFAULT_OPERATION_TIMEOUT_MS = 120000;
 const POLL_INTERVAL_MS = 50;
+const CHILD_BRIDGE_SWEEP_INTERVAL_MS = 1000;
 const MAX_REQUESTS_PER_SWEEP = 100;
 const inFlight = new Set;
 function requestDir(asyncDir) {
@@ -251,6 +254,63 @@ function readClaimHandle(provider, claimDir) {
     return;
   }
 }
+export function externalJobBridgeEligibility(steps) {
+  if (!Array.isArray(steps))
+    return "unknown";
+  for (const step of steps) {
+    const runner = step?.runner;
+    if (runner === undefined)
+      continue;
+    if (!runner || typeof runner !== "object" || Array.isArray(runner))
+      return "unknown";
+    const runnerType = runner.type;
+    if (typeof runnerType !== "string")
+      return "unknown";
+    if (runnerType === "external-job")
+      return "required";
+    if (runnerType !== "dm" && runnerType !== "external-cli")
+      return "unknown";
+  }
+  return "not-required";
+}
+export function createChildExternalJobBridgeSweeper() {
+  const runs = new Map;
+  let timer;
+  const sweep = () => {
+    for (const [runId, asyncDir] of runs) {
+      try {
+        const status = readStatus(asyncDir);
+        if (externalJobBridgeEligibility(status?.steps) !== "not-required")
+          serviceExternalJobBridgeRequests(asyncDir);
+        if (status && !isActiveAsyncState(status.state))
+          runs.delete(runId);
+      } catch (error) {
+        console.error(`Failed to service external-job bridge requests for '${asyncDir}':`, error);
+      }
+    }
+    if (runs.size === 0 && timer) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+    return runs.size;
+  };
+  return {
+    track(runId, asyncDir) {
+      runs.set(runId, asyncDir);
+      if (timer)
+        return;
+      timer = setInterval(sweep, CHILD_BRIDGE_SWEEP_INTERVAL_MS);
+      timer.unref?.();
+    },
+    sweep,
+    dispose() {
+      runs.clear();
+      if (timer)
+        clearInterval(timer);
+      timer = undefined;
+    }
+  };
+}
 export function serviceExternalJobBridgeRequests(asyncDir) {
   let files;
   try {

package/extensions/dm-subagents/src/runs/shared/git-environment.js

@@ -0,0 +1,25 @@
+const GIT_ROUTING_VARIABLES = new Set([
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_COMMON_DIR",
+  "GIT_CONFIG",
+  "GIT_CONFIG_COUNT",
+  "GIT_CONFIG_PARAMETERS",
+  "GIT_DIR",
+  "GIT_GRAFT_FILE",
+  "GIT_IMPLICIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_NAMESPACE",
+  "GIT_NO_REPLACE_OBJECTS",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_PREFIX",
+  "GIT_REPLACE_REF_BASE",
+  "GIT_SHALLOW_FILE",
+  "GIT_WORK_TREE"
+]);
+function isGitRoutingVariable(name) {
+  const upper = name.toUpperCase();
+  return GIT_ROUTING_VARIABLES.has(upper) || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(upper);
+}
+export function omitGitRoutingEnv(env) {
+  return Object.fromEntries(Object.entries(env).filter(([name]) => !isGitRoutingVariable(name)));
+}

package/extensions/dm-subagents/src/runs/shared/herdr-connection.js

@@ -0,0 +1,341 @@
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+const MAX_DISCOVERY_BYTES = 256 * 1024;
+const MAX_RPC_BYTES = 4 * 1024 * 1024;
+const SUBSCRIPTION_ACK_TIMEOUT_MS = 15000;
+export const HERDR_REMOTE_PATH = "$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export const HERDR_SSH_BASE = ["-T", "-o", "BatchMode=yes", "-o", "NumberOfPasswordPrompts=0", "-o", "StrictHostKeyChecking=yes", "-o", "ConnectTimeout=10", "-o", "ConnectionAttempts=1", "-o", "ForwardAgent=no", "-o", "ExitOnForwardFailure=yes", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=4", "-o", "SendEnv=-*", "-o", "SetEnv=DM_SUBAGENTS_SSH_GUARD="];
+export function hardenedSshEnv(source = process.env) {
+  return { PATH: process.platform === "win32" ? source.PATH : "/usr/bin:/bin:/usr/sbin:/sbin", ...source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}, ...source.WINDIR ? { WINDIR: source.WINDIR } : {} };
+}
+export function herdrSshArgs(source = process.env) {
+  return [...HERDR_SSH_BASE, ...source.SSH_AUTH_SOCK ? ["-o", `IdentityAgent=${source.SSH_AUTH_SOCK}`] : []];
+}
+
+export class HerdrRpcError extends Error {
+  code;
+  requestId;
+  constructor(message, requestId, code) {
+    super(message);
+    this.name = "HerdrRpcError";
+    this.requestId = requestId;
+    this.code = code;
+  }
+}
+
+export class HerdrTransportError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "HerdrTransportError";
+  }
+}
+export function decodeHerdrJsonLine(line) {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+  } catch {
+    throw new Error("Herdr emitted malformed JSON or UTF-8.");
+  }
+}
+export function shellQuoteRemote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function remoteShellCommand(script, args = []) {
+  return `sh -c ${shellQuoteRemote(`PATH="${HERDR_REMOTE_PATH}"; export PATH; ${script}`)} sh${args.map((arg) => ` ${shellQuoteRemote(arg)}`).join("")}`;
+}
+function canonicalHerdrSession(session) {
+  return session && session !== "default" ? session : null;
+}
+function sshEnvCommand(session, command) {
+  const selected = canonicalHerdrSession(session), assignment = selected ? ` HERDR_SESSION=${shellQuoteRemote(selected)}` : "";
+  return `/usr/bin/env -u HERDR_SOCKET_PATH -u HERDR_SESSION${assignment} ${remoteShellCommand(command)}`;
+}
+export function runHerdrRemoteCommand(machine, command, options = {}) {
+  return spawnSync(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { encoding: "utf8", env: hardenedSshEnv(options.env), timeout: options.timeout ?? 15000, maxBuffer: options.maxBuffer ?? MAX_DISCOVERY_BYTES, windowsHide: true });
+}
+export function runHerdrRemoteCommandAsync(machine, command, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { env: hardenedSshEnv(options.env), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    const stdout = [], stderr = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES;
+    let stdoutBytes = 0, stderrBytes = 0, error, settled = false, escalation;
+    const finish = (status, spawnError = error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      if (escalation)
+        clearTimeout(escalation);
+      resolve({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), ...spawnError ? { error: spawnError } : {} });
+    };
+    const terminate = () => {
+      child.kill("SIGTERM");
+      escalation ??= setTimeout(() => {
+        if (!settled) {
+          child.kill("SIGKILL");
+          finish(child.exitCode ?? null);
+        }
+      }, 1000);
+      escalation.unref?.();
+    };
+    const collect = (target, stream) => (chunk) => {
+      const bytes = stream === "stdout" ? stdoutBytes += chunk.byteLength : stderrBytes += chunk.byteLength;
+      if (bytes > maxBuffer) {
+        error ??= new Error(`${stream} maxBuffer length exceeded`);
+        terminate();
+      } else
+        target.push(chunk);
+    };
+    child.stdout.on("data", collect(stdout, "stdout"));
+    child.stderr.on("data", collect(stderr, "stderr"));
+    child.once("error", (spawnError) => finish(null, spawnError));
+    child.once("close", (status) => finish(status));
+    const timer = setTimeout(terminate, options.timeout ?? 15000);
+    timer.unref?.();
+  });
+}
+export function parseHerdrEndpoint(value, expectedSession) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("Remote Herdr endpoint discovery returned malformed JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("Remote Herdr endpoint discovery returned no endpoint.");
+  const p = parsed;
+  if (typeof p.socket !== "string" || !path.posix.isAbsolute(p.socket) || typeof p.version !== "string" || typeof p.protocol !== "number")
+    throw new Error("Remote Herdr endpoint discovery returned incomplete identity.");
+  const session = canonicalHerdrSession(typeof p.session === "string" ? p.session : null), expected = canonicalHerdrSession(expectedSession);
+  if (expected !== session)
+    throw new Error(`Remote Herdr session identity mismatch: expected ${expected ?? "default"}, received ${session ?? "default"}.`);
+  if (p.running !== true || p.compatible !== true || p.endpoint_compatible === false)
+    throw new Error("The selected remote Herdr session is stopped or incompatible.");
+  return { socket: p.socket, session, version: p.version, protocol: p.protocol, compatible: true, running: true };
+}
+export async function discoverHerdrEndpoint(machine, options = {}) {
+  const discovery = 'herdr_path=$(command -v herdr) || exit 127; case "$herdr_path" in /*/herdr) ;; *) exit 126;; esac; exec "$herdr_path" status server --json';
+  const result = await runHerdrRemoteCommandAsync(machine, sshEnvCommand(machine.session, discovery), { ...options, timeout: 15000, maxBuffer: MAX_DISCOVERY_BYTES });
+  if (result.error)
+    throw new Error(`Remote Herdr discovery failed: ${result.error.message}`);
+  if (result.status !== 0)
+    throw new Error(`Remote Herdr discovery failed with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
+  return parseHerdrEndpoint(result.stdout, machine.session);
+}
+
+export class SocketRpcClient {
+  #socketPath;
+  #subscriptionAckTimeoutMs;
+  #next = 0;
+  constructor(socketPath, subscriptionAckTimeoutMs = SUBSCRIPTION_ACK_TIMEOUT_MS) {
+    this.#socketPath = socketPath;
+    this.#subscriptionAckTimeoutMs = subscriptionAckTimeoutMs;
+  }
+  call(method, params = {}, timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+      const socket = net.createConnection(this.#socketPath);
+      let bytes = 0;
+      let data = Buffer.alloc(0);
+      let finished = false;
+      const id = String(++this.#next);
+      const timer = setTimeout(() => finish(new HerdrTransportError(`Herdr RPC '${method}' timed out.`)), timeoutMs);
+      timer.unref?.();
+      const finish = (error, value) => {
+        if (finished)
+          return;
+        finished = true;
+        clearTimeout(timer);
+        socket.destroy();
+        error ? reject(error) : resolve(value);
+      };
+      socket.on("connect", () => socket.write(`${JSON.stringify({ id, method, params })}
+`));
+      socket.on("data", (chunk) => {
+        bytes += chunk.byteLength;
+        if (bytes > MAX_RPC_BYTES) {
+          finish(new Error("Herdr RPC response exceeded its byte bound."));
+          return;
+        }
+        data = Buffer.concat([data, chunk]);
+        const newline = data.indexOf(10);
+        if (newline < 0)
+          return;
+        let frame;
+        try {
+          frame = decodeHerdrJsonLine(data.subarray(0, newline));
+        } catch {
+          finish(new Error("Herdr RPC returned malformed JSON or UTF-8."));
+          return;
+        }
+        const record = frame;
+        if (record.id !== id) {
+          finish(new Error("Herdr RPC response identity mismatch."));
+          return;
+        }
+        if (record.error)
+          finish(new HerdrRpcError(String(record.error.message ?? "Herdr RPC failed."), id, typeof record.error.code === "string" ? record.error.code : undefined));
+        else
+          finish(undefined, record.result);
+      });
+      socket.on("error", (error) => finish(new HerdrTransportError(error.message, { cause: error })));
+      socket.on("close", () => finish(new HerdrTransportError(`Herdr RPC '${method}' ended before a response.`)));
+    });
+  }
+  async subscribe(subscriptions, listener, onDisconnect) {
+    const socket = net.createConnection(this.#socketPath);
+    const id = String(++this.#next);
+    let buffer = Buffer.alloc(0), bytes = 0, acknowledged = false, intentional = false, notified = false, settled = false;
+    let resolveAck, rejectAck;
+    const acknowledgement = new Promise((resolve, reject) => {
+      resolveAck = resolve;
+      rejectAck = reject;
+    });
+    const failHandshake = (error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      rejectAck(error);
+    };
+    const disconnect = (error) => {
+      if (intentional || notified)
+        return;
+      notified = true;
+      if (!acknowledged)
+        failHandshake(error);
+      else
+        onDisconnect?.(error);
+    };
+    const timer = setTimeout(() => failHandshake(new Error("Herdr subscription acknowledgement timed out.")), this.#subscriptionAckTimeoutMs);
+    timer.unref?.();
+    socket.on("data", (chunk) => {
+      bytes += chunk.byteLength;
+      if (bytes > (acknowledged ? MAX_RPC_BYTES * 32 : MAX_RPC_BYTES)) {
+        disconnect(new Error("Herdr subscription exceeded its byte bound."));
+        socket.destroy();
+        return;
+      }
+      buffer = Buffer.concat([buffer, chunk]);
+      for (;; ) {
+        const i = buffer.indexOf(10);
+        if (i < 0)
+          break;
+        const line = buffer.subarray(0, i);
+        buffer = buffer.subarray(i + 1);
+        let value;
+        try {
+          value = decodeHerdrJsonLine(line);
+        } catch {
+          disconnect(new Error("Herdr subscription emitted malformed JSON or UTF-8."));
+          socket.destroy();
+          return;
+        }
+        const record = value;
+        if (!acknowledged) {
+          if (record.id === id) {
+            if (record.error) {
+              failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), id, typeof record.error.code === "string" ? record.error.code : undefined));
+              return;
+            }
+            if (record.result?.type !== "subscription_started") {
+              failHandshake(new Error("Herdr subscription returned an invalid acknowledgement."));
+              return;
+            }
+            acknowledged = true;
+            settled = true;
+            clearTimeout(timer);
+            resolveAck();
+            continue;
+          }
+          if (record.id === "" && record.error && record.error.code === "invalid_request") {
+            failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription request was invalid."), "", "invalid_request"));
+            return;
+          }
+          failHandshake(new Error("Herdr subscription emitted an event before acknowledgement."));
+          return;
+        }
+        if (record.error) {
+          disconnect(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), typeof record.id === "string" ? record.id : "", typeof record.error.code === "string" ? record.error.code : undefined));
+          socket.destroy();
+          return;
+        }
+        listener(value);
+      }
+    });
+    socket.on("error", (error) => disconnect(error));
+    socket.on("close", () => disconnect(new Error("Herdr subscription connection was lost.")));
+    socket.on("connect", () => socket.write(`${JSON.stringify({ id, method: "events.subscribe", params: { subscriptions } })}
+`));
+    await acknowledgement;
+    return () => {
+      intentional = true;
+      clearTimeout(timer);
+      socket.destroy();
+    };
+  }
+}
+async function waitForSocket(socketPath, child) {
+  for (let attempt = 0;attempt < 100; attempt++) {
+    if (child.exitCode !== null)
+      throw new Error(`SSH StreamLocal forwarding exited with code ${child.exitCode}.`);
+    try {
+      const stat = fs.lstatSync(socketPath);
+      if (stat.isSocket()) {
+        fs.chmodSync(socketPath, 384);
+        return;
+      }
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("SSH StreamLocal forwarding did not create its local socket.");
+}
+async function terminateChild(child) {
+  const wait = (ms) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise((resolve) => child.once("exit", () => resolve())), new Promise((resolve) => setTimeout(resolve, ms))]);
+  if (child.exitCode === null && child.signalCode === null)
+    child.kill("SIGTERM");
+  await wait(1000);
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill("SIGKILL");
+    await wait(1000);
+  }
+}
+export async function connectHerdrMachine(machine, options = {}) {
+  if (process.platform === "win32")
+    throw new Error("Pane-native Herdr placement requires OpenSSH StreamLocal forwarding and is not supported on Windows.");
+  const endpoint = await discoverHerdrEndpoint(machine, options);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dm-subagents-herdr-"));
+  fs.chmodSync(dir, 448);
+  const children = new Set;
+  const forward = async (remotePath, name) => {
+    if (!path.posix.isAbsolute(remotePath))
+      throw new Error("Remote socket path must be absolute.");
+    const local = path.join(dir, `${name}.sock`);
+    const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), "-N", "-o", "StreamLocalBindUnlink=yes", "-L", `${local}:${remotePath}`, machine.target], { env: hardenedSshEnv(options.env), stdio: "ignore", windowsHide: true });
+    children.add(child);
+    const stop = async () => {
+      await terminateChild(child);
+      children.delete(child);
+      try {
+        fs.rmSync(local, { force: true });
+      } catch {}
+    };
+    try {
+      await waitForSocket(local, child);
+    } catch (error) {
+      await stop();
+      throw error;
+    }
+    return { socketPath: local, close: stop };
+  };
+  const primary = await forward(endpoint.socket, "herdr").catch((error) => {
+    fs.rmSync(dir, { recursive: true, force: true });
+    throw error;
+  });
+  return { endpoint, socketPath: primary.socketPath, client: new SocketRpcClient(primary.socketPath), forwardRemoteSocket: forward, close: async () => {
+    await Promise.all([...children].map(terminateChild));
+    children.clear();
+    fs.rmSync(dir, { recursive: true, force: true });
+  } };
+}

package/extensions/dm-subagents/src/runs/shared/herdr-dm-protocol.js

@@ -0,0 +1,60 @@
+import * as path from "node:path";
+export const HERDR_PI_PROTOCOL = 1;
+export const HERDR_PI_MAX_FRAME_BYTES = 1024 * 1024;
+export const HERDR_PI_MODE_ENV = "DM_SUBAGENTS_HERDR_BRIDGE";
+export const HERDR_PI_RUN_ENV = "DM_SUBAGENTS_HERDR_RUN_ID";
+export const HERDR_PI_RUNTIME_DIR_ENV = "DM_SUBAGENTS_HERDR_RUNTIME_DIR";
+const SAFE_ID = /^[A-Za-z0-9_-]{8,96}$/u;
+export function validateHerdrPiRunId(value) {
+  if (typeof value !== "string" || !SAFE_ID.test(value))
+    throw new Error("Herdr DM bridge run identity is invalid.");
+  return value;
+}
+export function herdrPiRuntimeRoot(agentDir) {
+  return path.join(agentDir, "dm-subagents", "herdr-runs");
+}
+export function herdrPiRunDir(agentDir, runId) {
+  return path.join(herdrPiRuntimeRoot(agentDir), validateHerdrPiRunId(runId));
+}
+export function encodeHerdrPiFrame(frame) {
+  const data = Buffer.from(`${JSON.stringify(frame)}
+`, "utf8");
+  if (data.byteLength > HERDR_PI_MAX_FRAME_BYTES)
+    throw new Error(`Herdr DM frame exceeds ${HERDR_PI_MAX_FRAME_BYTES} bytes.`);
+  return data;
+}
+
+export class HerdrPiFrameDecoder {
+  #buffer = Buffer.alloc(0);
+  push(chunk) {
+    this.#buffer = Buffer.concat([this.#buffer, chunk]);
+    if (this.#buffer.byteLength > HERDR_PI_MAX_FRAME_BYTES)
+      throw new Error(`Herdr DM frame exceeds ${HERDR_PI_MAX_FRAME_BYTES} bytes.`);
+    const frames = [];
+    for (;; ) {
+      const newline = this.#buffer.indexOf(10);
+      if (newline < 0)
+        break;
+      const line = this.#buffer.subarray(0, newline);
+      this.#buffer = this.#buffer.subarray(newline + 1);
+      let value;
+      try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+      } catch {
+        throw new Error("Herdr DM bridge emitted malformed JSON or UTF-8.");
+      }
+      if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Herdr DM bridge frame must be an object.");
+      const frame = value;
+      if (frame.protocol !== HERDR_PI_PROTOCOL || typeof frame.type !== "string")
+        throw new Error("Herdr DM bridge protocol mismatch.");
+      validateHerdrPiRunId(frame.runId);
+      frames.push(frame);
+    }
+    return frames;
+  }
+  end() {
+    if (this.#buffer.byteLength)
+      throw new Error("Herdr DM bridge ended with a partial frame.");
+  }
+}