intentdna 1.9.0 → 1.9.3

package/dist/runtime/local-execution-supervisor-script.js

@@ -0,0 +1,793 @@
+import { createHash } from "node:crypto";
+/**
+ * Self-contained CommonJS supervisor written into the private authority root.
+ * Keeping the child runtime dependency-free lets source tests and compiled CLI
+ * builds use the exact same protocol.
+ */
+export const LOCAL_EXECUTION_SUPERVISOR_SOURCE = String.raw `"use strict";
+const { spawn, spawnSync } = require("node:child_process");
+const { createHash, randomUUID } = require("node:crypto");
+const fs = require("node:fs");
+const net = require("node:net");
+const path = require("node:path");
+
+const recordPath = process.argv[2];
+if (!recordPath) process.exit(64);
+let ownedSocketPath = null;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isErrno = (error, code) => error && error.code === code;
+
+function atomicWrite(target, value) {
+  const directory = path.dirname(target);
+  const temporary = path.join(directory, "." + path.basename(target) + ".tmp." + process.pid + "." + randomUUID());
+  const fd = fs.openSync(temporary, "wx", 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(value) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temporary, target);
+  const directoryFd = fs.openSync(directory, "r");
+  try { fs.fsyncSync(directoryFd); } finally { fs.closeSync(directoryFd); }
+}
+
+function readRecord() {
+  return JSON.parse(fs.readFileSync(recordPath, "utf8"));
+}
+
+function syncDirectory(target) {
+  const descriptor = fs.openSync(target, "r");
+  try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+}
+
+function readLockOwner(target) {
+  try {
+    const value = JSON.parse(fs.readFileSync(target, "utf8"));
+    return value && value.schema_version === "intentdna.execution_lock_owner.v1"
+      && Number.isSafeInteger(value.pid) && value.pid > 0
+      && typeof value.process_birth_id === "string" && value.process_birth_id.length > 0
+      && typeof value.generation === "string" && value.generation.length > 0
+      && Number.isSafeInteger(value.acquired_at) && value.acquired_at >= 0
+      && Object.keys(value).sort().join(",") === "acquired_at,generation,pid,process_birth_id,schema_version"
+      ? value
+      : null;
+  } catch { return null; }
+}
+
+function lockOwnersEqual(left, right) {
+  return left !== null
+    && left.schema_version === right.schema_version
+    && left.pid === right.pid
+    && left.process_birth_id === right.process_birth_id
+    && left.generation === right.generation
+    && left.acquired_at === right.acquired_at;
+}
+
+function lockOwnerDigest(owner) {
+  return createHash("sha256").update(JSON.stringify({
+    acquired_at: owner.acquired_at,
+    generation: owner.generation,
+    pid: owner.pid,
+    process_birth_id: owner.process_birth_id,
+    schema_version: owner.schema_version,
+  }), "utf8").digest("hex");
+}
+
+function guardianMain() {
+  const { spawn } = require("node:child_process");
+  const fs = require("node:fs");
+  const config = JSON.parse(Buffer.from(process.argv[process.argv.length - 1], "base64").toString("utf8"));
+  if (config.kill_signal !== "SIGKILL" && config.kill_signal !== "SIGSTOP") {
+    process.on(config.kill_signal, () => {});
+  }
+  const control = require("node:fs").createWriteStream(null, { fd: 3 });
+  const actual = spawn("/bin/sh", [
+    "-c",
+    "gate=$1; shift; while [ ! -f \"$gate\" ]; do sleep 0.01; done; exec \"$@\"",
+    "intentdna-provider-gate",
+    config.gate_path,
+    config.command,
+    ...config.args,
+  ], {
+    cwd: config.cwd,
+    env: config.env,
+    detached: false,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const publish = (value) => control.write(JSON.stringify(value) + "\n");
+  let outputLimited = false;
+  const forward = (stream, descriptor) => {
+    let written = 0;
+    stream.on("data", (chunk) => {
+      if (outputLimited) return;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, config.max_output_bytes - written);
+      if (bytes.byteLength > remaining) {
+        if (remaining > 0) fs.writeSync(descriptor, bytes.subarray(0, remaining));
+        written += remaining;
+        outputLimited = true;
+        publish({ type: "output_limit" });
+        actual.stdout.pause();
+        actual.stderr.pause();
+        return;
+      }
+      if (bytes.byteLength > 0) fs.writeSync(descriptor, bytes);
+      written += bytes.byteLength;
+    });
+  };
+  forward(actual.stdout, 1);
+  forward(actual.stderr, 2);
+  actual.stdin.on("error", () => {});
+  actual.stdin.end(config.stdin === null ? undefined : config.stdin);
+  publish({ type: "ready", pid: actual.pid || null });
+  actual.once("error", (error) => publish({
+    type: "completed",
+    status: null,
+    signal: null,
+    error: { code: error.code || "UNKNOWN", message: error.message },
+  }));
+  actual.once("exit", (status, signal) => publish({ type: "completed", status, signal, error: null }));
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+  let command = "";
+  let released = false;
+  const killOrphanedGroup = () => {
+    if (released) return;
+    try { process.kill(-process.pid, "SIGKILL"); } catch (error) {
+      if (!error || error.code !== "ESRCH") process.exit(1);
+    }
+  };
+  process.stdin.on("data", (chunk) => {
+    command += chunk;
+    if (command.includes("release\n")) {
+      released = true;
+      process.exit(0);
+    }
+  });
+  process.stdin.once("end", killOrphanedGroup);
+  process.stdin.once("close", killOrphanedGroup);
+}
+
+const guardianSource = "(" + guardianMain.toString() + ")()";
+
+async function withRecordLock(operation) {
+  const lockPath = recordPath + ".lock";
+  const ownerPath = path.join(lockPath, "owner.json");
+  const processBirthIdentity = (pid) => {
+    if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+    if (process.platform === "linux") {
+      try {
+        const stat = fs.readFileSync("/proc/" + pid + "/stat", "utf8");
+        const fields = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
+        return fields[19] && /^[0-9]+$/.test(fields[19]) ? "linux-start-ticks:" + fields[19] : null;
+      } catch { return null; }
+    }
+    const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 1000 });
+    const started = result.status === 0 ? result.stdout.trim().replace(/\s+/g, " ") : "";
+    return started === "" ? null : process.platform + "-lstart:" + started;
+  };
+  const owner = {
+    schema_version: "intentdna.execution_lock_owner.v1",
+    pid: process.pid,
+    process_birth_id: processBirthIdentity(process.pid),
+    generation: randomUUID(),
+    acquired_at: Date.now(),
+  };
+  if (owner.process_birth_id === null) throw new Error("cannot establish execution lock owner identity");
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    const candidatePath = lockPath + ".candidate." + process.pid + "." + randomUUID();
+    try {
+      fs.mkdirSync(candidatePath, { mode: 0o700 });
+      const descriptor = fs.openSync(path.join(candidatePath, "owner.json"), "wx", 0o600);
+      try {
+        fs.writeFileSync(descriptor, JSON.stringify(owner) + "\n", "utf8");
+        fs.fsyncSync(descriptor);
+      } finally { fs.closeSync(descriptor); }
+      const candidateDescriptor = fs.openSync(candidatePath, "r");
+      try { fs.fsyncSync(candidateDescriptor); } finally { fs.closeSync(candidateDescriptor); }
+      fs.renameSync(candidatePath, lockPath);
+      syncDirectory(path.dirname(lockPath));
+      break;
+    } catch (error) {
+      if (!isErrno(error, "EEXIST") && !isErrno(error, "ENOTEMPTY")
+        && !(isErrno(error, "EPERM") && fs.existsSync(lockPath))) throw error;
+      const current = readLockOwner(ownerPath);
+      let stale = false;
+      if (current) {
+        let alive = true;
+        try { process.kill(current.pid, 0); } catch (probeError) { alive = probeError.code === "EPERM"; }
+        const actualBirthIdentity = alive ? processBirthIdentity(current.pid) : null;
+        stale = !alive || (actualBirthIdentity !== null && actualBirthIdentity !== current.process_birth_id);
+      }
+      if (stale) {
+        try {
+          const quarantine = lockPath + ".stale." + lockOwnerDigest(current);
+          fs.renameSync(lockPath, quarantine);
+          syncDirectory(path.dirname(lockPath));
+          if (!lockOwnersEqual(readLockOwner(path.join(quarantine, "owner.json")), current)) {
+            throw new Error("execution record lock ownership changed during stale takeover");
+          }
+          continue;
+        } catch (takeoverError) {
+          const quarantine = lockPath + ".stale." + lockOwnerDigest(current);
+          if (!isErrno(takeoverError, "ENOENT")
+            && !isErrno(takeoverError, "EEXIST")
+            && !isErrno(takeoverError, "ENOTEMPTY")
+            && !((isErrno(takeoverError, "EPERM") || isErrno(takeoverError, "EACCES")) && fs.existsSync(quarantine))) {
+            throw takeoverError;
+          }
+        }
+      }
+      if (Date.now() >= deadline) throw new Error("execution record lock is unavailable");
+      await sleep(10);
+    } finally {
+      fs.rmSync(candidatePath, { recursive: true, force: true });
+    }
+  }
+  try {
+    return await operation();
+  } finally {
+    try {
+      const current = readLockOwner(ownerPath);
+      if (lockOwnersEqual(current, owner)) {
+        const released = lockPath + ".released." + lockOwnerDigest(owner) + "." + randomUUID();
+        let retired = true;
+        try { fs.renameSync(lockPath, released); }
+        catch (error) {
+          if (isErrno(error, "ENOENT")) retired = false;
+          else throw error;
+        }
+        if (retired) {
+          syncDirectory(path.dirname(lockPath));
+          if (!lockOwnersEqual(readLockOwner(path.join(released, "owner.json")), owner)) {
+            throw new Error("execution record lock ownership changed during release");
+          }
+          fs.rmSync(released, { recursive: true, force: true });
+          syncDirectory(path.dirname(lockPath));
+        }
+      }
+    } catch (error) {
+      if (!isErrno(error, "ENOENT")) throw error;
+    }
+  }
+}
+
+function processGroupMembers(processId) {
+  const result = spawnSync("ps", ["-axo", "pid=,pgid=,state="], { encoding: "utf8" });
+  if (result.status !== 0) return null;
+  return result.stdout.split("\n").flatMap((line) => {
+    const [pidText, pgidText, state] = line.trim().split(/\s+/);
+    const pid = Number(pidText);
+    const pgid = Number(pgidText);
+    return Number.isSafeInteger(pid) && pgid === processId && state !== "Z" ? [pid] : [];
+  });
+}
+
+function signalProcessGroup(processId, signal) {
+  try { process.kill(-processId, signal); return true; }
+  catch (error) {
+    if (error.code === "ESRCH") return false;
+    throw error;
+  }
+}
+
+async function waitForGuardianExit(guardian, timeoutMs) {
+  if (guardian.exitCode !== null || guardian.signalCode !== null) return true;
+  return new Promise((resolve) => {
+    const exited = () => { clearTimeout(timer); resolve(true); };
+    const timer = setTimeout(() => { guardian.off("exit", exited); resolve(false); }, timeoutMs);
+    guardian.once("exit", exited);
+  });
+}
+
+async function waitForEmptyProcessGroup(processId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let consecutiveEmptyObservations = 0;
+  for (;;) {
+    const members = processGroupMembers(processId);
+    if (members !== null && members.length === 0) {
+      consecutiveEmptyObservations += 1;
+      if (consecutiveEmptyObservations >= 3) return true;
+    } else {
+      consecutiveEmptyObservations = 0;
+    }
+    if (members === null || Date.now() >= deadline) return false;
+    await sleep(10);
+  }
+}
+
+async function forceDrainProcessGroup(processId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let consecutiveEmptyObservations = 0;
+  for (;;) {
+    const members = processGroupMembers(processId);
+    if (members === null) return false;
+    if (members.length === 0) {
+      consecutiveEmptyObservations += 1;
+      if (consecutiveEmptyObservations >= 3) return true;
+    } else {
+      consecutiveEmptyObservations = 0;
+      for (const pid of members) {
+        try { process.kill(pid, "SIGKILL"); }
+        catch (error) { if (error.code !== "ESRCH") throw error; }
+      }
+    }
+    if (Date.now() >= deadline) return false;
+    await sleep(10);
+  }
+}
+
+async function drainProcessGroup(guardian, initialSignal, graceMs) {
+  const processId = guardian && guardian.pid ? guardian.pid : null;
+  if (processId === null) return true;
+  signalProcessGroup(processId, initialSignal);
+  let deadline = Date.now() + graceMs;
+  for (;;) {
+    const members = processGroupMembers(processId);
+    if (members !== null && members.every((pid) => pid === processId)) {
+      guardian.stdin.end("release\n");
+      if (!await waitForGuardianExit(guardian, Math.max(1_000, graceMs))) return false;
+      return waitForEmptyProcessGroup(processId, Math.max(1_000, graceMs));
+    }
+    if (members === null || Date.now() >= deadline) break;
+    await sleep(10);
+  }
+  signalProcessGroup(processId, "SIGKILL");
+  if (!await waitForGuardianExit(guardian, Math.max(1_000, graceMs))) return false;
+  return forceDrainProcessGroup(processId, Math.max(1_000, graceMs));
+}
+
+function signalKnownGroupMembers(processId, signal) {
+  const members = processGroupMembers(processId);
+  if (members === null) return false;
+  for (const pid of members) {
+    try { process.kill(pid, signal); }
+    catch (error) { if (error.code !== "ESRCH") throw error; }
+  }
+  return true;
+}
+
+async function drainExitedProcessGroup(processId, initialSignal, graceMs) {
+  if (processId === null) return true;
+  if (!signalKnownGroupMembers(processId, initialSignal)) return false;
+  let deadline = Date.now() + graceMs;
+  for (;;) {
+    const members = processGroupMembers(processId);
+    if (members !== null && members.length === 0) return true;
+    if (members === null || Date.now() >= deadline) break;
+    await sleep(10);
+  }
+  if (!signalKnownGroupMembers(processId, "SIGKILL")) return false;
+  return forceDrainProcessGroup(processId, Math.max(1_000, graceMs));
+}
+
+async function readConfiguration() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  return JSON.parse(text);
+}
+
+function streamEvidence(target, maxOutputBytes) {
+  const metadata = fs.lstatSync(target, { bigint: true });
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > BigInt(maxOutputBytes)) {
+    throw new Error("provider stream does not satisfy the durable output boundary");
+  }
+  const bytes = fs.readFileSync(target);
+  if (BigInt(bytes.byteLength) !== metadata.size) {
+    throw new Error("provider stream changed while completion evidence was captured");
+  }
+  return {
+    path: target,
+    byte_count: bytes.byteLength,
+    sha256: "sha256:" + createHash("sha256").update(bytes).digest("hex"),
+    device: metadata.dev.toString(),
+    inode: metadata.ino.toString(),
+    birthtime_ns: metadata.birthtimeNs.toString(),
+  };
+}
+
+async function main() {
+  const config = await readConfiguration();
+  const prepared = readRecord();
+  if (
+    prepared.schema_version !== "intentdna.local_execution_record.v1"
+    || prepared.phase !== "launching"
+    || prepared.execution_instance_id !== config.execution_instance_id
+    || prepared.challenge !== config.challenge
+    || prepared.supervisor.socket_path !== config.socket_path
+  ) throw new Error("prepared execution record does not match supervisor configuration");
+  if (!Number.isSafeInteger(config.max_output_bytes) || config.max_output_bytes <= 0
+    || (config.timeout_ms !== null && (!Number.isSafeInteger(config.timeout_ms) || config.timeout_ms <= 0))) {
+    throw new Error("execution supervisor configuration is invalid");
+  }
+
+  try { fs.unlinkSync(config.socket_path); } catch (error) { if (!isErrno(error, "ENOENT")) throw error; }
+  let provider = null;
+  let providerCompletion = null;
+  let stopFact = null;
+  let rawCompletion = null;
+  let completeRaw;
+  let timeout = null;
+  let setupComplete = false;
+  let providerChildPid = null;
+  let stdoutFd = null;
+  let stderrFd = null;
+  const rawCompleted = new Promise((resolve) => { completeRaw = resolve; });
+
+  async function persist(patch) {
+    return withRecordLock(async () => {
+      const current = readRecord();
+      if (current.execution_instance_id !== config.execution_instance_id || current.challenge !== config.challenge) {
+        throw new Error("execution record identity changed");
+      }
+      if (current.phase === "never_launched") throw new Error("execution was durably attested as never launched");
+      const terminal = ["raw_completed", "normalized_completed", "receipted"];
+      if (terminal.includes(current.phase) && patch.phase && patch.phase !== current.phase) {
+        if (patch.phase === "unsupported") return current;
+        throw new Error("terminal execution record cannot transition to " + patch.phase);
+      }
+      if (current.phase === "unsupported" && patch.phase && patch.phase !== "unsupported") {
+        throw new Error("unsupported execution record is terminal");
+      }
+      if (patch.phase === "running" && current.phase !== "launching") {
+        throw new Error("execution no longer owns the durable launch claim");
+      }
+      if (patch.phase === "raw_completed" && current.phase !== "running") {
+        throw new Error("raw completion requires running launch ownership");
+      }
+      const next = { ...current, ...patch, revision: current.revision + 1, updated_at: new Date().toISOString() };
+      atomicWrite(recordPath, next);
+      return next;
+    });
+  }
+
+  async function finishRaw(value, release = true) {
+    if (rawCompletion !== null) return rawCompletion;
+    if (stdoutFd !== null) { fs.closeSync(stdoutFd); stdoutFd = null; }
+    if (stderrFd !== null) { fs.closeSync(stderrFd); stderrFd = null; }
+    rawCompletion = {
+      stdout: streamEvidence(config.stdout_path, config.max_output_bytes),
+      stderr: streamEvidence(config.stderr_path, config.max_output_bytes),
+      max_output_bytes: config.max_output_bytes,
+      timeout_ms: config.timeout_ms,
+      ...value,
+    };
+    await persist({ phase: "raw_completed", raw_completion: rawCompletion, stop_fact: stopFact });
+    if (release) completeRaw(rawCompletion);
+    return rawCompletion;
+  }
+
+  async function failAfterGuardian(error) {
+    if (stopFact !== null) return rawCompletion ?? rawCompleted;
+    const processId = provider && provider.pid ? provider.pid : null;
+    if (config.hold_before_failure_drain_path) {
+      fs.writeFileSync(
+        config.hold_before_failure_drain_path,
+        JSON.stringify({ guardian_pid: processId }) + "\n",
+        { encoding: "utf8", flag: "wx", mode: 0o600 },
+      );
+      while (fs.existsSync(config.hold_before_failure_drain_path)) await sleep(10);
+    }
+    const drained = provider === null
+      ? true
+      : provider.exitCode === null && provider.signalCode === null
+        ? await drainProcessGroup(provider, config.kill_signal, config.cancellation_grace_ms)
+        : await drainExitedProcessGroup(processId, config.kill_signal, config.cancellation_grace_ms);
+    if (!drained) {
+      await persist({ phase: "unsupported", supervisor_error: error.message });
+      completeRaw(null);
+      return null;
+    }
+    return finishRaw({
+      status: null,
+      signal: provider ? provider.signalCode : null,
+      timed_out: false,
+      cancelled: false,
+      cancellation_reason: null,
+      process_limit_exceeded: false,
+      output_limit_exceeded: false,
+      termination_reason: null,
+      process_id: processId,
+      process_tree_drained: true,
+      completed_at: new Date().toISOString(),
+      error: { code: error.code || "UNKNOWN", message: error.message },
+    });
+  }
+
+  async function publishUnsupported(error) {
+    await persist({ phase: "unsupported", supervisor_error: error.message });
+    completeRaw(null);
+  }
+
+  function attachProviderObservers() {
+    let guardianEvents = "";
+    let readySettled = false;
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+      resolveReady = resolve;
+      rejectReady = reject;
+    });
+    const rejectUnready = (error) => {
+      if (readySettled) return;
+      readySettled = true;
+      rejectReady(error);
+    };
+    const handleCompletion = (event) => {
+      if (event.type === "ready") {
+        if (readySettled) throw new Error("provider guardian published duplicate ready evidence");
+        if (!Number.isSafeInteger(event.pid) || event.pid <= 0) {
+          throw new Error("provider guardian published an invalid child identity");
+        }
+        readySettled = true;
+        providerChildPid = event.pid;
+        resolveReady(event.pid);
+        return;
+      }
+      if (event.type === "output_limit") {
+        void terminate("output_limit", { reason: "output_limit" }).catch(publishUnsupported);
+        return;
+      }
+      if (event.type !== "completed" || providerCompletion !== null) return;
+      providerCompletion = event;
+      void (async () => {
+        while (!setupComplete && rawCompletion === null && stopFact === null) await sleep(1);
+        if (rawCompletion !== null || stopFact !== null) return;
+        const processId = provider.pid || null;
+        const drained = await drainProcessGroup(provider, config.kill_signal, config.timeout_grace_ms);
+        if (!drained) throw new Error("provider process group drain was not proven");
+        await finishRaw({
+          status: event.status,
+          signal: event.signal,
+          timed_out: false,
+          cancelled: false,
+          cancellation_reason: null,
+          process_limit_exceeded: false,
+          output_limit_exceeded: false,
+          termination_reason: null,
+          process_id: processId,
+          process_tree_drained: true,
+          completed_at: new Date().toISOString(),
+          error: event.error,
+        });
+      })().catch(publishUnsupported);
+    };
+    provider.stdio[3].setEncoding("utf8");
+    provider.stdio[3].on("data", (chunk) => {
+      guardianEvents += chunk;
+      for (;;) {
+        const newline = guardianEvents.indexOf("\n");
+        if (newline < 0) break;
+        const line = guardianEvents.slice(0, newline);
+        guardianEvents = guardianEvents.slice(newline + 1);
+        try {
+          handleCompletion(JSON.parse(line));
+        } catch (error) {
+          rejectUnready(error);
+          void (async () => {
+            while (!setupComplete && rawCompletion === null && stopFact === null) await sleep(1);
+            if (rawCompletion === null && stopFact === null) await failAfterGuardian(error);
+          })().catch(publishUnsupported);
+        }
+      }
+    });
+    provider.once("error", (error) => {
+      rejectUnready(error);
+      void (async () => {
+        while (!setupComplete && rawCompletion === null && stopFact === null) await sleep(1);
+        if (rawCompletion === null && stopFact === null) await failAfterGuardian(error);
+      })().catch(publishUnsupported);
+    });
+    provider.once("exit", (status, signal) => {
+      rejectUnready(new Error("provider guardian exited before publishing ready evidence"));
+      void (async () => {
+        while (!setupComplete && rawCompletion === null && stopFact === null) await sleep(1);
+        if (rawCompletion !== null || stopFact !== null || providerCompletion !== null) return;
+        const processId = provider.pid || null;
+        const drained = await drainExitedProcessGroup(processId, "SIGKILL", config.timeout_grace_ms);
+        if (!drained) throw new Error("provider guardian exited and residual group drain was not proven");
+        await finishRaw({
+          status,
+          signal,
+          timed_out: false,
+          cancelled: false,
+          cancellation_reason: null,
+          process_limit_exceeded: false,
+          output_limit_exceeded: false,
+          termination_reason: null,
+          process_id: processId,
+          process_tree_drained: true,
+          completed_at: new Date().toISOString(),
+          error: { code: "GUARDIAN_EXIT", message: "provider guardian exited before publishing child completion" },
+        });
+      })().catch(publishUnsupported);
+    });
+    return ready;
+  }
+
+  async function terminate(kind, detail, deferRelease = false) {
+    if (stopFact !== null) {
+      const same = stopFact.kind === kind
+        && (kind !== "canonical_stop" || (
+          stopFact.stop_idempotency_key === detail.stop_idempotency_key
+          && JSON.stringify(stopFact.requested_outcome) === JSON.stringify(detail.requested_outcome)
+        ));
+      if (!same) throw new Error("execution already has a different terminal fact");
+      return rawCompletion ?? rawCompleted;
+    }
+    stopFact = { kind, ...detail };
+    const processId = provider && provider.pid ? provider.pid : null;
+    const drained = provider === null
+      ? true
+      : await drainProcessGroup(provider, config.kill_signal, config.cancellation_grace_ms);
+    if (!drained) throw new Error("provider process group drain was not proven");
+    const canonicalProcess = kind === "canonical_stop" ? detail.requested_outcome.process : null;
+    const canonicalTimeout = canonicalProcess !== null && canonicalProcess.kind === "timeout";
+    const canonicalCancellation = canonicalProcess !== null && canonicalProcess.kind === "cancelled";
+    if (kind === "canonical_stop" && !canonicalTimeout && !canonicalCancellation) {
+      throw new Error("canonical stop outcome is unsupported by the execution supervisor");
+    }
+    const timedOut = kind === "timeout" || canonicalTimeout;
+    const cancelled = kind === "local_cancel" || canonicalCancellation;
+    return finishRaw({
+      status: null,
+      signal: config.kill_signal,
+      timed_out: timedOut,
+      cancelled,
+      cancellation_reason: cancelled
+        ? (canonicalCancellation ? canonicalProcess.reason : detail.reason || null)
+        : null,
+      process_limit_exceeded: kind === "process_limit",
+      output_limit_exceeded: kind === "output_limit",
+      termination_reason: timedOut ? "timeout"
+        : kind === "process_limit" ? "process_limit"
+        : kind === "output_limit" ? "output_limit"
+        : "cancellation",
+      process_id: processId,
+      process_tree_drained: true,
+      completed_at: new Date().toISOString(),
+      error: null,
+    }, !deferRelease);
+  }
+
+  const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+    socket.setEncoding("utf8");
+    let text = "";
+    socket.on("data", (chunk) => {
+      text += chunk;
+      if (text.length > 1024 * 1024) socket.destroy(new Error("control request too large"));
+    });
+    socket.on("end", () => {
+      void (async () => {
+        const request = JSON.parse(text);
+        if (
+          request.schema_version !== "intentdna.local_execution_control.v1"
+          || request.execution_instance_id !== config.execution_instance_id
+          || request.challenge !== config.challenge
+          || request.action !== "stop"
+        ) throw new Error("unauthenticated execution control request");
+        const result = request.requested_outcome
+          ? await terminate("canonical_stop", {
+              stop_idempotency_key: request.stop_idempotency_key,
+              requested_at: request.requested_at,
+              requested_outcome: request.requested_outcome,
+            }, true)
+          : await terminate("local_cancel", { reason: request.reason || null }, true);
+        await new Promise((resolve) => {
+          socket.end(JSON.stringify({ ok: true, raw_completion: result }) + "\n", resolve);
+        });
+        completeRaw(result);
+      })().catch((error) => socket.end(JSON.stringify({ ok: false, error: error.message }) + "\n"));
+    });
+  });
+  stdoutFd = fs.openSync(config.stdout_path, "wx", 0o600);
+  stderrFd = fs.openSync(config.stderr_path, "wx", 0o600);
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(config.socket_path, () => {
+      server.off("error", reject);
+      ownedSocketPath = config.socket_path;
+      resolve();
+    });
+  });
+  fs.chmodSync(config.socket_path, 0o600);
+  if (config.hold_before_running_path) {
+    fs.writeFileSync(
+      config.hold_before_running_path,
+      JSON.stringify({ supervisor_pid: process.pid }) + "\n",
+      { encoding: "utf8", flag: "wx", mode: 0o600 },
+    );
+    while (fs.existsSync(config.hold_before_running_path)) await sleep(10);
+  }
+  await persist({
+    phase: "running",
+    supervisor: { ...prepared.supervisor, pid: process.pid, ready_at: new Date().toISOString() },
+  });
+
+  if (stopFact === null) try {
+    const guardianConfig = Buffer.from(JSON.stringify({
+      gate_path: config.gate_path,
+      command: config.command,
+      args: config.args,
+      cwd: config.cwd,
+      env: config.env,
+      stdin: config.stdin,
+      kill_signal: config.kill_signal,
+      max_output_bytes: config.max_output_bytes,
+    }), "utf8").toString("base64");
+    if (config.inject_guardian_spawn_failure === true) throw new Error("injected guardian spawn failure");
+    provider = spawn(process.execPath, ["-e", guardianSource, guardianConfig], {
+      cwd: config.cwd,
+      env: config.env,
+      detached: true,
+      stdio: ["pipe", stdoutFd, stderrFd, "pipe"],
+      windowsHide: true,
+    });
+    fs.closeSync(stdoutFd);
+    fs.closeSync(stderrFd);
+    stdoutFd = null;
+    stderrFd = null;
+    provider.stdin.on("error", () => {});
+    const providerReady = attachProviderObservers();
+    if (config.timeout_ms !== null) {
+      timeout = setTimeout(() => {
+        void terminate("timeout", { reason: "timeout" }).catch(publishUnsupported);
+      }, config.timeout_ms);
+    }
+    await providerReady;
+    if (config.hold_after_guardian_spawn_path) {
+      fs.writeFileSync(
+        config.hold_after_guardian_spawn_path,
+        JSON.stringify({ guardian_pid: provider.pid || null }) + "\n",
+        { encoding: "utf8", flag: "wx", mode: 0o600 },
+      );
+      while (fs.existsSync(config.hold_after_guardian_spawn_path)) await sleep(10);
+    }
+    if (config.inject_provider_persist_failure === true) throw new Error("injected provider persist failure");
+    await persist({
+      provider: {
+        pid: provider.pid || null,
+        process_group_id: provider.pid || null,
+        child_pid: providerChildPid,
+        launched_at: new Date().toISOString(),
+      },
+    });
+    if (config.auto_release_gate === true && rawCompletion === null && stopFact === null) {
+      if (config.inject_gate_release_failure === true) throw new Error("injected gate release failure");
+      fs.writeFileSync(config.gate_path, "release\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
+    }
+  } catch (error) {
+    await failAfterGuardian(error);
+  } finally {
+    setupComplete = true;
+  }
+
+  if (provider !== null) {
+    await rawCompleted;
+    if (timeout !== null) clearTimeout(timeout);
+  }
+  server.close();
+  try { fs.unlinkSync(config.socket_path); } catch {}
+  ownedSocketPath = null;
+}
+
+main().catch((error) => {
+  void withRecordLock(async () => {
+    const current = readRecord();
+    if (["never_launched", "raw_completed", "normalized_completed", "receipted"].includes(current.phase)) return;
+    atomicWrite(recordPath, { ...current, phase: "unsupported", supervisor_error: error.message, revision: current.revision + 1, updated_at: new Date().toISOString() });
+  }).catch(() => {}).finally(() => {
+    if (ownedSocketPath !== null) {
+      try { fs.unlinkSync(ownedSocketPath); } catch {}
+    }
+    process.exit(1);
+  });
+});
+`;
+export const LOCAL_EXECUTION_SUPERVISOR_DIGEST = `sha256:${createHash("sha256")
+    .update(LOCAL_EXECUTION_SUPERVISOR_SOURCE, "utf8")
+    .digest("hex")}`;