intentdna 1.9.0 → 1.9.3

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

@@ -0,0 +1,788 @@
+import { createHash } from "node:crypto";
+/**
+ * Dependency-free Windows supervisor. The native keeper owns the Job Object;
+ * this process owns durable CAS transitions and the authenticated named pipe.
+ */
+export const LOCAL_WINDOWS_EXECUTION_SUPERVISOR_SOURCE = String.raw `"use strict";
+const { spawn } = 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 RECORD_SCHEMA = "intentdna.local_execution_record.v1";
+const CONTROL_SCHEMA = "intentdna.local_execution_control.v1";
+const FACT_SCHEMA = "intentdna.windows_job_keeper_fact.v1";
+const KEEPER_MAGIC = "IDNA_WINDOWS_JOB_KEEPER_V1";
+const recordPath = process.argv[2];
+if (!recordPath) process.exit(64);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isErrno = (error, code) => error && error.code === code;
+const renameWait = new Int32Array(new SharedArrayBuffer(4));
+const canonical = (value) => {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+  return "{" + Object.keys(value).sort().map((key) => JSON.stringify(key) + ":" + canonical(value[key])).join(",") + "}";
+};
+
+function replaceFile(temporary, target) {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      fs.renameSync(temporary, target);
+      return;
+    } catch (error) {
+      const retryable = ["EACCES", "EBUSY", "EPERM"].some((code) => isErrno(error, code));
+      if (!retryable || attempt >= 9) {
+        try { fs.unlinkSync(temporary); } catch {}
+        throw error;
+      }
+      Atomics.wait(renameWait, 0, 0, 25 * (attempt + 1));
+    }
+  }
+}
+
+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, canonical(value) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  replaceFile(temporary, target);
+  try {
+    const directoryFd = fs.openSync(directory, "r");
+    try { fs.fsyncSync(directoryFd); } finally { fs.closeSync(directoryFd); }
+  } catch (error) {
+    if (!isErrno(error, "EPERM") && !isErrno(error, "EACCES") && !isErrno(error, "EISDIR") && !isErrno(error, "EINVAL") && !isErrno(error, "ENOTSUP")) throw error;
+  }
+}
+
+function readRecord() {
+  return JSON.parse(fs.readFileSync(recordPath, "utf8"));
+}
+
+function syncDirectory(target) {
+  try {
+    const descriptor = fs.openSync(target, "r");
+    try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+  } catch (error) {
+    if (!isErrno(error, "EPERM") && !isErrno(error, "EACCES") && !isErrno(error, "EISDIR")
+      && !isErrno(error, "EINVAL") && !isErrno(error, "ENOTSUP")) throw error;
+  }
+}
+
+function readLockOwner(target) {
+  try {
+    const value = JSON.parse(fs.readFileSync(target, "utf8"));
+    return exactKeys(value, ["schema_version", "pid", "process_birth_id", "generation", "acquired_at"])
+      && value.schema_version === "intentdna.execution_lock_owner.v1"
+      && positivePid(value.pid)
+      && 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
+      ? value
+      : null;
+  } catch { return null; }
+}
+
+function lockOwnersEqual(left, right) {
+  return left !== null && canonical(left) === canonical(right);
+}
+
+function lockOwnerDigest(owner) {
+  return createHash("sha256").update(canonical(owner), "utf8").digest("hex");
+}
+
+async function withRecordLock(operation) {
+  const lockPath = recordPath + ".lock";
+  const ownerPath = path.join(lockPath, "owner.json");
+  const owner = {
+    schema_version: "intentdna.execution_lock_owner.v1",
+    pid: process.pid,
+    process_birth_id: "node-time-origin-ms:" + String(Math.floor(performance.timeOrigin)),
+    generation: randomUUID(),
+    acquired_at: Date.now(),
+  };
+  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, canonical(owner) + "\n", "utf8");
+        fs.fsyncSync(descriptor);
+      } finally { fs.closeSync(descriptor); }
+      try {
+        const candidateDescriptor = fs.openSync(candidatePath, "r");
+        try { fs.fsyncSync(candidateDescriptor); } finally { fs.closeSync(candidateDescriptor); }
+      } catch (error) {
+        if (!isErrno(error, "EPERM") && !isErrno(error, "EACCES") && !isErrno(error, "EISDIR")
+          && !isErrno(error, "EINVAL") && !isErrno(error, "ENOTSUP")) throw error;
+      }
+      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;
+      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 exactKeys(value, keys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function positivePid(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
+function filetime(value) {
+  return typeof value === "string" && /^[1-9][0-9]*$/.test(value);
+}
+
+function digest(value) {
+  return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+
+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(),
+  };
+}
+
+function parseFact(line) {
+  const value = JSON.parse(line);
+  if (!value || value.schema_version !== FACT_SCHEMA || typeof value.kind !== "string") {
+    throw new Error("keeper emitted a fact with an invalid schema");
+  }
+  if (value.kind === "contained_ready") {
+    if (!exactKeys(value, ["schema_version", "kind", "job_identifier", "keeper_pid", "keeper_creation_filetime", "root_pid", "root_creation_filetime"])
+      || !digest(value.job_identifier) || !positivePid(value.keeper_pid)
+      || !filetime(value.keeper_creation_filetime) || !positivePid(value.root_pid)
+      || !filetime(value.root_creation_filetime)) {
+      throw new Error("keeper emitted invalid containment identity");
+    }
+    return value;
+  }
+  if (value.kind === "released") {
+    if (!exactKeys(value, ["schema_version", "kind", "root_pid"]) || !positivePid(value.root_pid)) {
+      throw new Error("keeper emitted invalid release evidence");
+    }
+    return value;
+  }
+  if (value.kind === "completed") {
+    if (!exactKeys(value, ["schema_version", "kind", "reason", "root_exit_observed", "root_exit_code", "windows_signal", "active_processes", "process_tree_drained"])
+      || !["root_exit", "terminate", "parent_eof", "protocol_error", "drain_timeout", "output_limit"].includes(value.reason)
+      || typeof value.root_exit_observed !== "boolean"
+      || !Number.isSafeInteger(value.root_exit_code) || value.root_exit_code < 0 || value.root_exit_code > 0xffffffff
+      || value.windows_signal !== null || value.active_processes !== 0
+      || value.process_tree_drained !== true) {
+      throw new Error("keeper emitted invalid completion evidence");
+    }
+    return value;
+  }
+  throw new Error("keeper emitted an unknown fact kind");
+}
+
+function hex(value) {
+  if (typeof value !== "string" || value.includes("\0")) throw new Error("keeper configuration contains NUL");
+  return Buffer.from(value, "utf8").toString("hex");
+}
+
+function encodeConfig(config) {
+  const lines = [
+    KEEPER_MAGIC,
+    "exe:" + hex(config.executable),
+    "cwd:" + hex(config.cwd),
+    "stdin:" + hex(config.stdin_path || ""),
+    "stdout:" + hex(config.stdout_path),
+    "stderr:" + hex(config.stderr_path),
+    "max_output_bytes:" + String(config.max_output_bytes),
+  ];
+  if (config.command_line !== null) {
+    lines.push("mode:verbatim", "command:" + hex(config.command_line));
+  } else {
+    lines.push("mode:argv", "argc:" + String(config.args.length));
+    for (const argument of config.args) lines.push("arg:" + hex(argument));
+  }
+  const environment = Object.entries(config.env).sort(([left], [right]) => {
+    const folded = left.toLowerCase().localeCompare(right.toLowerCase(), "en");
+    return folded === 0 ? left.localeCompare(right, "en") : folded;
+  });
+  const seen = new Set();
+  lines.push("envc:" + String(environment.length));
+  for (const [key, value] of environment) {
+    if (key.length === 0 || key.includes("=") || key.includes("\0") || value.includes("\0")) {
+      throw new Error("keeper environment contains an invalid entry");
+    }
+    const folded = key.toLowerCase();
+    if (seen.has(folded)) throw new Error("keeper environment contains duplicate case-insensitive keys");
+    seen.add(folded);
+    lines.push("env:" + hex(key + "=" + value));
+  }
+  lines.push(
+    "natural_drain_grace_ms:" + String(config.natural_drain_grace_ms),
+    "forced_drain_grace_ms:" + String(config.forced_drain_grace_ms),
+    "end",
+  );
+  const encoded = lines.join("\n") + "\n";
+  if (Buffer.byteLength(encoded, "utf8") > 8 * 1024 * 1024) throw new Error("keeper configuration exceeds the protocol limit");
+  return encoded;
+}
+
+async function main() {
+  let configurationText = "";
+  for await (const chunk of process.stdin) configurationText += chunk;
+  const config = JSON.parse(configurationText);
+  const prepared = readRecord();
+  if (prepared.schema_version !== RECORD_SCHEMA || prepared.phase !== "launching"
+    || prepared.execution_instance_id !== config.execution_instance_id
+    || prepared.challenge !== config.challenge
+    || prepared.backend.kind !== "windows_job"
+    || prepared.backend.containment_nonce !== config.containment_nonce
+    || prepared.backend.helper_path !== config.helper_path
+    || prepared.backend.helper_digest !== config.helper_digest
+    || prepared.supervisor.socket_path !== config.control_endpoint) {
+    throw new Error("prepared execution record does not match Windows supervisor configuration");
+  }
+  if (!path.win32.isAbsolute(config.helper_path) || !path.win32.isAbsolute(config.executable)
+    || !path.win32.isAbsolute(config.cwd) || !path.win32.isAbsolute(config.stdout_path)
+    || !path.win32.isAbsolute(config.stderr_path)
+    || (config.stdin_path !== null && !path.win32.isAbsolute(config.stdin_path))
+    || !Array.isArray(config.args) || config.args.length > 4096
+    || config.args.some((value) => typeof value !== "string" || value.includes("\0"))
+    || config.env === null || typeof config.env !== "object" || Array.isArray(config.env)
+    || !Number.isSafeInteger(config.natural_drain_grace_ms)
+    || config.natural_drain_grace_ms < 0 || config.natural_drain_grace_ms > 300000
+    || !Number.isSafeInteger(config.forced_drain_grace_ms)
+    || config.forced_drain_grace_ms < 0 || config.forced_drain_grace_ms > 300000
+    || !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("Windows supervisor configuration is invalid");
+  }
+
+  function validateHelper() {
+    const helperMetadata = fs.lstatSync(config.helper_path);
+    if (!helperMetadata.isFile() || helperMetadata.isSymbolicLink()) throw new Error("Windows Job keeper is not a trusted regular file");
+    const helperDigest = "sha256:" + createHash("sha256").update(fs.readFileSync(config.helper_path)).digest("hex");
+    if (helperDigest !== config.helper_digest) throw new Error("Windows Job keeper changed after preflight");
+  }
+
+  let helper = null;
+  let helperFacts = "";
+  let helperErrors = "";
+  let stopFact = null;
+  let rawCompletion = null;
+  let pendingCompletionFact = null;
+  let provider = null;
+  let released = false;
+  let releaseSent = false;
+  let terminateSent = false;
+  let supervisorReadyAt = null;
+  let uncertaintyObserved = null;
+  let timeout = null;
+  let completionSettled = false;
+  let completionResolve;
+  const completion = new Promise((resolve) => { completionResolve = resolve; });
+
+  function settleCompletion(value) {
+    if (completionSettled) return;
+    completionSettled = true;
+    completionResolve(value);
+  }
+
+  async function persist(patch) {
+    return withRecordLock(async () => {
+      const current = readRecord();
+      if (current.execution_instance_id !== config.execution_instance_id
+        || current.challenge !== config.challenge
+        || current.backend.kind !== "windows_job"
+        || current.backend.containment_nonce !== config.containment_nonce) {
+        throw new Error("execution record identity changed");
+      }
+      if (current.phase === "never_launched") throw new Error("execution was durably attested as never launched");
+      if (current.phase === "unsupported") return current;
+      if (["raw_completed", "normalized_completed", "receipted"].includes(current.phase)) {
+        return current;
+      }
+      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;
+    });
+  }
+
+  function stopHelperAfterUncertainty() {
+    try {
+      if (!helper || !helper.stdin || helper.stdin.destroyed) return;
+      if (released) {
+        if (!terminateSent) {
+          terminateSent = true;
+          helper.stdin.end("terminate\n");
+        }
+      } else {
+        helper.stdin.end();
+      }
+    } catch {}
+  }
+
+  async function commitUnsupported(error) {
+    stopHelperAfterUncertainty();
+    await withRecordLock(async () => {
+      const current = readRecord();
+      if (["never_launched", "raw_completed", "normalized_completed", "receipted", "unsupported"].includes(current.phase)) return;
+      atomicWrite(recordPath, {
+        ...current,
+        phase: "unsupported",
+        supervisor_error: error instanceof Error ? error.message : String(error),
+        revision: current.revision + 1,
+        updated_at: new Date().toISOString(),
+      });
+    });
+    settleCompletion(null);
+  }
+
+  let eventQueue = Promise.resolve();
+  function enqueue(operation) {
+    const task = eventQueue.then(async () => {
+      if (uncertaintyObserved !== null) throw uncertaintyObserved;
+      return operation();
+    });
+    eventQueue = task.then(
+      () => undefined,
+      async (error) => {
+        if (error && error.control_conflict === true) return;
+        if (uncertaintyObserved === null) {
+          uncertaintyObserved = error instanceof Error ? error : new Error(String(error));
+        }
+        try { await commitUnsupported(uncertaintyObserved); }
+        catch { stopHelperAfterUncertainty(); settleCompletion(null); }
+      },
+    );
+    return task;
+  }
+
+  function enqueueObserved(operation) {
+    void enqueue(operation).catch(() => undefined);
+  }
+
+  function controlConflict(message) {
+    const error = new Error(message);
+    error.control_conflict = true;
+    return error;
+  }
+
+  function sendTerminateIfReleased() {
+    if (stopFact === null || !released || terminateSent) return;
+    if (!helper || !helper.stdin || helper.stdin.destroyed) {
+      throw new Error("Windows Job keeper control channel is unavailable after release");
+    }
+    terminateSent = true;
+    helper.stdin.write("terminate\n");
+  }
+
+  function canonicalStopMode(outcome) {
+    if (!outcome || outcome.kind !== "worker_process" || !outcome.process) return null;
+    if (outcome.status === "failed" && outcome.process.kind === "timeout"
+      && exactKeys(outcome.process, ["kind", "exit_code", "signal", "timeout_ms"])
+      && outcome.process.exit_code === null && outcome.process.signal === null
+      && Number.isSafeInteger(outcome.process.timeout_ms) && outcome.process.timeout_ms > 0) {
+      return { kind: "timeout", reason: null };
+    }
+    if (outcome.status === "cancelled" && outcome.process.kind === "cancelled"
+      && exactKeys(outcome.process, ["kind", "exit_code", "signal", "reason"])
+      && outcome.process.exit_code === null && outcome.process.signal === null
+      && (outcome.process.reason === null || typeof outcome.process.reason === "string")) {
+      return { kind: "cancellation", reason: outcome.process.reason };
+    }
+    return null;
+  }
+
+  function completionResult(fact) {
+    const canonicalMode = stopFact && stopFact.kind === "canonical_stop"
+      ? canonicalStopMode(stopFact.requested_outcome)
+      : null;
+    const timeoutStop = stopFact && (stopFact.kind === "timeout" || canonicalMode && canonicalMode.kind === "timeout");
+    const cancelledStop = stopFact && (stopFact.kind === "local_cancel" || canonicalMode && canonicalMode.kind === "cancellation");
+    const outputStop = stopFact && stopFact.kind === "output_limit";
+    return {
+      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,
+      status: fact.root_exit_observed && !timeoutStop && !cancelledStop && !outputStop ? fact.root_exit_code : null,
+      signal: null,
+      timed_out: Boolean(timeoutStop),
+      cancelled: Boolean(cancelledStop),
+      cancellation_reason: cancelledStop
+        ? (canonicalMode ? canonicalMode.reason : stopFact.reason || null)
+        : null,
+      process_limit_exceeded: false,
+      output_limit_exceeded: Boolean(outputStop),
+      termination_reason: timeoutStop ? "timeout" : cancelledStop ? "cancellation" : outputStop ? "output_limit" : null,
+      process_id: provider.root_pid,
+      process_tree_drained: true,
+      completed_at: new Date().toISOString(),
+      error: null,
+      windows_job_completion: fact,
+    };
+  }
+
+  async function finish(fact) {
+    if (rawCompletion !== null) throw new Error("keeper emitted duplicate completion evidence");
+    if (provider === null || !released) throw new Error("keeper completed before durable release evidence");
+    if (fact.reason === "parent_eof" || fact.reason === "protocol_error") {
+      throw new Error("keeper completion reported control-channel uncertainty: " + fact.reason);
+    }
+    if (fact.reason === "output_limit" && stopFact === null) {
+      stopFact = { kind: "output_limit", reason: "output_limit" };
+    }
+    if (stopFact === null) {
+      if (!["root_exit", "drain_timeout"].includes(fact.reason) || !fact.root_exit_observed) {
+        throw new Error("keeper completion does not prove an unstopped root exit");
+      }
+    } else if (stopFact.kind === "output_limit" ? fact.reason !== "output_limit" : fact.reason !== "terminate") {
+      throw new Error("keeper completion does not match the durable stop fact");
+    }
+    const candidate = completionResult(fact);
+    const next = await persist({ phase: "raw_completed", raw_completion: candidate, stop_fact: stopFact });
+    if (next.phase === "unsupported") throw new Error("execution became unsupported before completion commit");
+    if (next.phase !== "raw_completed" || canonical(next.raw_completion) !== canonical(candidate)) {
+      throw new Error("raw completion lost durable transition ownership");
+    }
+    rawCompletion = candidate;
+    settleCompletion(rawCompletion);
+  }
+
+  async function registerStop(kind, detail) {
+    if (rawCompletion !== null || pendingCompletionFact !== null) {
+      throw controlConflict("execution already completed before the stop request");
+    }
+    if (stopFact !== null) {
+      const same = stopFact.kind === kind && (kind !== "canonical_stop" || (
+        stopFact.stop_idempotency_key === detail.stop_idempotency_key
+        && canonical(stopFact.requested_outcome) === canonical(detail.requested_outcome)
+      ));
+      if (!same) throw controlConflict("execution already has a different terminal fact");
+      return;
+    }
+    if (kind === "canonical_stop" && canonicalStopMode(detail.requested_outcome) === null) {
+      throw controlConflict("canonical stop outcome is unsupported by Windows execution");
+    }
+    stopFact = kind === "canonical_stop"
+      ? {
+          kind,
+          stop_idempotency_key: detail.stop_idempotency_key,
+          requested_at: detail.requested_at,
+          requested_outcome: detail.requested_outcome,
+        }
+      : { kind, reason: detail.reason || null };
+    const next = await persist({ stop_fact: stopFact });
+    if (next.phase !== "running" || canonical(next.stop_fact) !== canonical(stopFact)) {
+      stopFact = null;
+      throw controlConflict("execution completion won before the stop request");
+    }
+    sendTerminateIfReleased();
+  }
+
+  async function handleFact(line) {
+    const fact = parseFact(line);
+    if (fact.kind === "contained_ready") {
+      if (provider !== null || helper === null || fact.keeper_pid !== helper.pid) {
+        throw new Error("keeper containment identity conflicts with launched helper");
+      }
+      provider = {
+        pid: fact.root_pid,
+        keeper_pid: fact.keeper_pid,
+        keeper_creation_filetime: fact.keeper_creation_filetime,
+        root_pid: fact.root_pid,
+        root_creation_filetime: fact.root_creation_filetime,
+        job_identifier: fact.job_identifier,
+        containment_nonce: config.containment_nonce,
+        contained_at: new Date().toISOString(),
+        released_at: null,
+      };
+      const next = await persist({ provider });
+      if (canonical(next.provider) !== canonical(provider)) throw new Error("containment identity was not durably committed");
+      if (!helper.stdin || helper.stdin.destroyed) throw new Error("Windows Job keeper release channel is unavailable");
+      releaseSent = true;
+      helper.stdin.write("release\n");
+      return;
+    }
+    if (fact.kind === "released") {
+      if (provider === null || !releaseSent || released || fact.root_pid !== provider.root_pid) {
+        throw new Error("keeper release identity conflicts with containment evidence");
+      }
+      provider = { ...provider, released_at: new Date().toISOString() };
+      const next = await persist({ provider });
+      if (canonical(next.provider) !== canonical(provider)) throw new Error("release identity was not durably committed");
+      released = true;
+      sendTerminateIfReleased();
+      return;
+    }
+    if (pendingCompletionFact !== null) throw new Error("keeper emitted duplicate completion evidence");
+    if (provider === null || !released) throw new Error("keeper completed before durable release evidence");
+    pendingCompletionFact = fact;
+  }
+
+  let startupReadyResolve;
+  const startupReady = new Promise((resolve) => { startupReadyResolve = resolve; });
+  const activeControls = new Set();
+  function respond(socket, value) {
+    return new Promise((resolve) => {
+      if (socket.destroyed) {
+        resolve();
+        return;
+      }
+      socket.once("close", resolve);
+      socket.end(JSON.stringify(value) + "\n");
+    });
+  }
+  const server = net.createServer({ allowHalfOpen: true }, (socket) => {
+    let resolveControl;
+    const control = new Promise((resolve) => { resolveControl = resolve; });
+    socket.once("close", resolveControl);
+    socket.on("error", () => undefined);
+    socket.setEncoding("utf8");
+    let text = "";
+    socket.on("data", (chunk) => {
+      if (handled) {
+        socket.destroy(new Error("execution control request has trailing bytes"));
+        return;
+      }
+      text += chunk;
+      if (Buffer.byteLength(text, "utf8") > 1024 * 1024) {
+        socket.destroy(new Error("control request too large"));
+        return;
+      }
+      handleRequest();
+    });
+    let handled = false;
+    function handleRequest() {
+      if (handled) return;
+      const newline = text.indexOf("\n");
+      if (newline < 0) return;
+      handled = true;
+      const requestText = text.slice(0, newline);
+      if (text.slice(newline + 1).length !== 0) {
+        socket.destroy(new Error("execution control request has trailing bytes"));
+        return;
+      }
+      void (async () => {
+        const request = JSON.parse(requestText);
+        const unauthenticated = request.schema_version !== CONTROL_SCHEMA
+          || request.execution_instance_id !== config.execution_instance_id
+          || request.challenge !== config.challenge
+          || request.containment_nonce !== config.containment_nonce;
+        if (unauthenticated) {
+          throw new Error("unauthenticated execution control request");
+        }
+        const expectedKeys = request.action === "probe"
+          ? ["schema_version", "execution_instance_id", "challenge", "containment_nonce", "action"]
+          : request.action === "stop" && request.requested_outcome
+            ? ["schema_version", "execution_instance_id", "challenge", "containment_nonce", "action", "stop_idempotency_key", "requested_at", "requested_outcome"]
+            : request.action === "stop"
+              ? ["schema_version", "execution_instance_id", "challenge", "containment_nonce", "action", "reason"]
+              : [];
+        if (expectedKeys.length === 0 || !exactKeys(request, expectedKeys)) {
+          throw new Error("execution control request has an invalid schema");
+        }
+        if (request.action === "stop" && request.requested_outcome
+          && (!digest(request.stop_idempotency_key)
+            || typeof request.requested_at !== "string"
+            || !Number.isFinite(Date.parse(request.requested_at))
+            || new Date(Date.parse(request.requested_at)).toISOString() !== request.requested_at
+            || canonicalStopMode(request.requested_outcome) === null)) {
+          throw new Error("canonical stop request is invalid");
+        }
+        if (request.action === "stop" && !request.requested_outcome
+          && request.reason !== null && typeof request.reason !== "string") {
+          throw new Error("local cancellation request is invalid");
+        }
+        await startupReady;
+        if (request.action === "probe") {
+          const identity = await enqueue(async () => {
+            const current = readRecord();
+            return {
+              record_revision: current.revision,
+              execution_instance_id: config.execution_instance_id,
+              supervisor_pid: process.pid,
+              supervisor_ready_at: supervisorReadyAt,
+              containment_nonce: config.containment_nonce,
+              backend: prepared.backend,
+              provider,
+            };
+          });
+          await respond(socket, { ok: true, identity });
+          return;
+        }
+        await enqueue(() => request.requested_outcome
+          ? registerStop("canonical_stop", request)
+          : registerStop("local_cancel", request));
+        const result = await completion;
+        if (result === null) throw new Error("Windows execution became unsupported while stopping");
+        await respond(socket, { ok: true, raw_completion: result });
+      })()
+        .catch((error) => respond(socket, { ok: false, error: error.message }));
+    }
+    socket.on("end", () => {
+      if (!handled) void respond(socket, { ok: false, error: "execution control request was incomplete" });
+    });
+    activeControls.add(control);
+    void control.finally(() => activeControls.delete(control));
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen({ path: config.control_endpoint, readableAll: false, writableAll: false }, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  supervisorReadyAt = new Date().toISOString();
+  await persist({
+    phase: "running",
+    supervisor: { ...prepared.supervisor, pid: process.pid, ready_at: supervisorReadyAt },
+  });
+  startupReadyResolve();
+
+  try {
+    if (config.stdin_path !== null) {
+      fs.writeFileSync(config.stdin_path, config.stdin, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    }
+    const encodedConfig = encodeConfig(config);
+    validateHelper();
+    helper = spawn(config.helper_path, [], {
+      detached: false,
+      windowsHide: true,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    helper.stdout.setEncoding("utf8");
+    helper.stderr.setEncoding("utf8");
+    helper.stderr.on("data", (chunk) => {
+      helperErrors += chunk;
+      if (Buffer.byteLength(helperErrors, "utf8") > 1024 * 1024) helperErrors = helperErrors.slice(-1024 * 1024);
+    });
+    helper.stdout.on("data", (chunk) => {
+      helperFacts += chunk;
+      if (Buffer.byteLength(helperFacts, "utf8") > 1024 * 1024) {
+        enqueueObserved(() => { throw new Error("keeper fact stream exceeded the protocol limit"); });
+        return;
+      }
+      for (;;) {
+        const newline = helperFacts.indexOf("\n");
+        if (newline < 0) break;
+        const line = helperFacts.slice(0, newline);
+        helperFacts = helperFacts.slice(newline + 1);
+        if (line.length === 0) continue;
+        enqueueObserved(() => handleFact(line));
+      }
+    });
+    helper.once("error", (error) => { enqueueObserved(() => { throw error; }); });
+    helper.once("close", (status) => {
+      enqueueObserved(() => {
+        if (helperFacts.length !== 0) throw new Error("Windows Job keeper ended with a partial fact");
+        if (helperErrors.trim().length !== 0) {
+          throw new Error("Windows Job keeper reported an error: " + helperErrors.trim());
+        }
+        if (status !== 0) {
+          throw new Error("Windows Job keeper exited without success" + (status === null ? "" : " (exit " + status + ")"));
+        }
+        if (pendingCompletionFact === null) throw new Error("Windows Job keeper exited without trusted completion evidence");
+        return finish(pendingCompletionFact);
+      });
+    });
+    helper.stdin.on("error", (error) => {
+      enqueueObserved(() => {
+        if (rawCompletion === null) throw error;
+      });
+    });
+    helper.stdin.write(encodedConfig);
+    if (config.timeout_ms !== null) {
+      timeout = setTimeout(() => {
+        enqueueObserved(() => registerStop("timeout", { reason: "timeout" }));
+      }, config.timeout_ms);
+    }
+    await completion;
+  } catch (error) {
+    await enqueue(() => { throw error; }).catch(() => undefined);
+    await completion;
+  } finally {
+    if (timeout !== null) clearTimeout(timeout);
+    await new Promise((resolve) => server.close(resolve));
+    await Promise.allSettled([...activeControls]);
+    if (config.stdin_path !== null) {
+      try { fs.unlinkSync(config.stdin_path); } catch {}
+    }
+  }
+}
+
+main().catch((error) => {
+  void withRecordLock(async () => {
+    const current = readRecord();
+    if (["never_launched", "raw_completed", "normalized_completed", "receipted", "unsupported"].includes(current.phase)) return;
+    atomicWrite(recordPath, {
+      ...current,
+      phase: "unsupported",
+      supervisor_error: error.message,
+      revision: current.revision + 1,
+      updated_at: new Date().toISOString(),
+    });
+  }).catch(() => {}).finally(() => process.exit(1));
+});
+`;
+export const LOCAL_WINDOWS_EXECUTION_SUPERVISOR_DIGEST = `sha256:${createHash("sha256")
+    .update(LOCAL_WINDOWS_EXECUTION_SUPERVISOR_SOURCE, "utf8")
+    .digest("hex")}`;