looply-cli 0.5.1 → 0.5.3

package/win/appcontainer.ps1

@@ -358,6 +358,39 @@ public static class LooplyAc {
 
   [DllImport("kernel32.dll", SetLastError=true)] static extern uint ResumeThread(IntPtr h);
   static void ResumeThreadSafe(IntPtr h) { ResumeThread(h); }
+
+  [DllImport("kernel32.dll", SetLastError=true, CharSet=CharSet.Unicode)] static extern bool DefineDosDevice(uint flags, string name, string target);
+  [DllImport("kernel32.dll", SetLastError=true, CharSet=CharSet.Unicode)] static extern uint QueryDosDevice(string name, StringBuilder buf, int max);
+
+  const uint DDD_RAW_TARGET_PATH = 0x1, DDD_REMOVE_DEFINITION = 0x2, DDD_EXACT_MATCH_ON_REMOVE = 0x4, DDD_NO_BROADCAST_SYSTEM = 0x8;
+
+  /** The CURRENT target of a DOS device name such as `Q:`, or null when it names nothing. */
+  public static string DeviceTarget(string name) {
+    StringBuilder sb = new StringBuilder(4096);
+    // The buffer holds a null-separated list, newest first; the builder stops
+    // at the first null, which is the definition in force.
+    return QueryDosDevice(name, sb, sb.Capacity) == 0 ? null : sb.ToString();
+  }
+
+  /**
+   * Map `name` to `rawTarget` (`\??\C:\path`), and prove it is OUR definition
+   * that is in force. DefineDosDevice does not refuse a name already in use —
+   * it stacks a new definition on top — so a name someone else took between
+   * the caller's check and this call is detected here and given back.
+   *
+   * No broadcast: Explorer is not told, so no drive appears in its windows.
+   */
+  public static bool MapDrive(string name, string rawTarget) {
+    if (!DefineDosDevice(DDD_RAW_TARGET_PATH | DDD_NO_BROADCAST_SYSTEM, name, rawTarget)) return false;
+    if (DeviceTarget(name) == rawTarget) return true;
+    UnmapDrive(name, rawTarget);
+    return false;
+  }
+
+  /** Remove exactly this definition — never one stacked above or below it. */
+  public static bool UnmapDrive(string name, string rawTarget) {
+    return DefineDosDevice(DDD_RAW_TARGET_PATH | DDD_REMOVE_DEFINITION | DDD_EXACT_MATCH_ON_REMOVE | DDD_NO_BROADCAST_SYSTEM, name, rawTarget);
+  }
 }
 '@
 
@@ -485,9 +518,69 @@ if ($req.network -eq 'internet-client') {
   $caps = @('S-1-15-3-1', 'S-1-15-3-3')
 }
 $stdinPath = if ($req.stdinPath) { [string]$req.stdinPath } else { '' }
-$runErr = [LooplyAc]::Run($req.executable, $req.commandLine, $req.cwd, [string[]]$envPairs,
-                          $req.stdoutPath, $req.stderrPath, $stdinPath, [uint32]$req.timeoutMs, [string[]]$caps,
-                          [ref]$exitCode, [ref]$timedOut)
+
+# --- drive root --------------------------------------------------------------
+# A container cannot list the directories ABOVE its grant — C:\, C:\Users, the
+# profile — and esbuild's resolver (native Go, so no preload reaches it) lists
+# every ancestor from the drive root down and aborts on "Access is denied" on
+# Windows, where its "treat EACCES as empty" check does not match. That stops
+# Vite, and with it Vitest, before a single test runs (measured on Tabsy).
+#
+# So the step runs from a DRIVE LETTER mapped to the project: the walk's root is
+# then the project itself, which the container can read. A drive letter is a
+# NAME, not a grant — every access still lands on the real files and is decided
+# by their ACLs, so the container reaches nothing it could not reach before.
+#
+# The letter is claimed through a ledger file created exclusively, so two
+# helpers never stack on one letter; it is removed in `finally`, by exact
+# match; and a mapping whose helper died is removed by the next helper to start.
+# Any failure here runs the step from its real path, exactly as before.
+$cwd = [string]$req.cwd
+$drive = $null; $driveTarget = $null; $driveClaim = $null
+if ($req.driveRoot -and $req.driveLedger -and (Test-Path -LiteralPath $req.driveRoot -PathType Container)) {
+  try {
+    $root = ([string]$req.driveRoot).TrimEnd('\')
+    New-Item -ItemType Directory -Force -Path $req.driveLedger | Out-Null
+    foreach ($f in @(Get-ChildItem -LiteralPath $req.driveLedger -Filter '*.drive' -File)) {
+      $parts = ([IO.File]::ReadAllText($f.FullName)) -split '\|', 2
+      if ($parts.Count -ne 2) { continue }
+      if (Get-Process -Id ([int]$parts[0]) -ErrorAction SilentlyContinue) { continue }
+      [LooplyAc]::UnmapDrive(($f.BaseName + ':'), $parts[1]) | Out-Null
+      Remove-Item -LiteralPath $f.FullName -Force -ErrorAction SilentlyContinue
+    }
+    foreach ($l in [char[]]'ZYXWVUTSRQPONMLKJIHGFED') {
+      $name = "${l}:"
+      if ([LooplyAc]::DeviceTarget($name)) { continue }
+      $claimPath = Join-Path $req.driveLedger "$l.drive"
+      try { $claim = [IO.File]::Open($claimPath, 'CreateNew', 'Write') } catch { continue }
+      $target = '\??\' + $root
+      $bytes = [Text.Encoding]::UTF8.GetBytes("$PID|$target")
+      $claim.Write($bytes, 0, $bytes.Length); $claim.Close()
+      if ([LooplyAc]::MapDrive($name, $target)) { $drive = $name; $driveTarget = $target; $driveClaim = $claimPath; break }
+      Remove-Item -LiteralPath $claimPath -Force -ErrorAction SilentlyContinue
+    }
+  } catch {
+    if ($drive) { [LooplyAc]::UnmapDrive($drive, $driveTarget) | Out-Null; Remove-Item -LiteralPath $driveClaim -Force -ErrorAction SilentlyContinue }
+    $drive = $null
+  }
+  if ($drive) {
+    $rest = $null
+    if ($cwd.Equals($root, [StringComparison]::OrdinalIgnoreCase)) { $rest = '' }
+    elseif ($cwd.StartsWith($root + '\', [StringComparison]::OrdinalIgnoreCase)) { $rest = $cwd.Substring($root.Length + 1) }
+    if ($rest -ne $null) { $cwd = $drive + '\' + $rest }
+  }
+}
+
+try {
+  $runErr = [LooplyAc]::Run($req.executable, $req.commandLine, $cwd, [string[]]$envPairs,
+                            $req.stdoutPath, $req.stderrPath, $stdinPath, [uint32]$req.timeoutMs, [string[]]$caps,
+                            [ref]$exitCode, [ref]$timedOut)
+} finally {
+  if ($drive) {
+    [LooplyAc]::UnmapDrive($drive, $driveTarget) | Out-Null
+    Remove-Item -LiteralPath $driveClaim -Force -ErrorAction SilentlyContinue
+  }
+}
 if ($runErr) {
   # The environment count travels with the failure: CreateProcess answers 203
   # (ERROR_ENVVAR_NOT_FOUND) for an EMPTY block as readily as a malformed one,
@@ -496,5 +589,5 @@ if ($runErr) {
   exit 0
 }
 
-Write-Result @{ ok = $true; stage = 'ran'; sid = $sidStr; exitCode = [int]$exitCode; timedOut = $timedOut }
+Write-Result @{ ok = $true; stage = 'ran'; sid = $sidStr; exitCode = [int]$exitCode; timedOut = $timedOut; drive = $drive }
 exit 0

package/win/contained-node.cjs

@@ -0,0 +1,530 @@
+'use strict';
+/*
+    WHAT NODE NEEDS TO WORK INSIDE A WINDOWS APPCONTAINER, AND CANNOT DO ITSELF.
+
+    Loaded into every Node process a contained gate or agent starts, through
+    `NODE_OPTIONS=--require` (see `contained-node.ts`). It changes nothing about
+    what the container may reach — it is plain JavaScript running with the
+    container's own token, so it can do nothing the project's code could not do
+    itself. It exists so the project's code does not HANG or FAIL on two
+    properties of the boundary that were measured, not assumed:
+
+    1. PIPED CHILD PROCESSES. libuv implements piped stdio as a named pipe
+       called `\\?\pipe\uv\<ptr>-<pid>`, and an AppContainer may not create a
+       pipe outside its own `\\.\pipe\LOCAL\` namespace. libuv reads the
+       resulting ERROR_ACCESS_DENIED as a name COLLISION and retries with the
+       next name, for ever — so `spawn(…, {stdio:'pipe'})` never returns and
+       the process spins. That is why esbuild (a Go binary driven over its
+       stdin/stdout) hung, and with it Vite and Vitest.
+
+       The repair keeps the API and moves the pipe: each piped slot gets a pipe
+       under `\\.\pipe\LOCAL\`, which the container IS allowed to create; the
+       child is handed the client end as an inherited handle (which has always
+       worked), and the parent reads and writes the server end through a stream
+       with the same surface `child.stdout` always had. `spawnSync` and the
+       `exec*Sync` family go through temporary files instead — a synchronous
+       call cannot wait for an asynchronous accept.
+
+       `fork()`'s IPC channel cannot be moved: its pipe is created inside
+       libuv and set up by Node internals no preload can reach. So it FAILS
+       FAST, naming the cause, instead of hanging until the gate's timeout —
+       a test runner then needs its worker-thread pool (`vitest --pool=threads`,
+       jest `--runInBand` or `workerThreads`).
+
+    2. REALPATH. `fs.realpathSync.native` fails with EPERM on EVERY path — it
+       maps the final path back to a drive letter, which a container is not
+       allowed to ask — and the JavaScript `fs.realpath` walks up to `lstat C:\`,
+       which the container cannot read either. Jest and Vite both call it at
+       startup. On EPERM/EACCES only, the path is resolved again component by
+       component, following the links the container CAN see and taking the
+       ancestors it cannot see as they are. Any other error is unchanged.
+
+    Installed only when `LOOPLY_CONTAINED_NODE=1`, so requiring the file to test
+    it changes nothing.
+*/
+
+const BS = String.fromCharCode(92);
+const LOCAL_PIPE_PREFIX = BS + BS + '.' + BS + 'pipe' + BS + 'LOCAL' + BS + 'looply-';
+
+const IPC_REFUSAL =
+  'child_process IPC (fork, or stdio "ipc") cannot work inside the Looply Windows sandbox: ' +
+  'Node creates its IPC pipe where an AppContainer may not, and would hang for ever. ' +
+  'Use a worker-thread pool instead (vitest --pool=threads; jest --runInBand or workerThreads).';
+
+/* ─────────────────────────────────────────────────────────── realpath ── */
+
+/**
+ * A realpath that tolerates ancestors it may not read.
+ *
+ * Walks the absolute path one component at a time. A component the container
+ * cannot `lstat` is taken as it is (it is an ancestor above the grant, and the
+ * container could not follow a link there anyway); a component it CAN see is
+ * followed if it is a link. A component that does not exist throws ENOENT, as
+ * realpath does.
+ */
+function lenientRealpath(fs, path, p) {
+  // The root as the platform spells it — `C:\`, or `\\server\share\` — and
+  // the components below it.
+  const split = (abs) => {
+    const root = path.parse(abs).root;
+    return [root, abs.slice(root.length).split(/[\\/]+/)];
+  };
+  let [current, pending] = split(path.resolve(p));
+  let links = 0;
+  while (pending.length > 0) {
+    const part = pending.shift();
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      current = path.dirname(current);
+      continue;
+    }
+    const next = path.join(current, part);
+    let st = null;
+    try {
+      st = fs.lstatSync(next);
+    } catch (e) {
+      if (!e || (e.code !== 'EPERM' && e.code !== 'EACCES')) throw e;
+    }
+    if (st !== null && st.isSymbolicLink()) {
+      if (++links > 40) {
+        const err = new Error(`ELOOP: too many symbolic links encountered, realpath '${p}'`);
+        err.code = 'ELOOP';
+        throw err;
+      }
+      const [root, parts] = split(path.resolve(current, fs.readlinkSync(next)));
+      current = root;
+      pending = parts.concat(pending);
+      continue;
+    }
+    current = next;
+  }
+  return current;
+}
+
+function denied(e) {
+  return !!e && (e.code === 'EPERM' || e.code === 'EACCES');
+}
+
+function toPathString(p) {
+  if (typeof p === 'string') return p;
+  if (Buffer.isBuffer(p)) return p.toString('utf8');
+  if (p instanceof URL) return require('url').fileURLToPath(p);
+  return String(p);
+}
+
+function encode(result, options) {
+  const enc = typeof options === 'string' ? options : options && options.encoding;
+  return enc === 'buffer' ? Buffer.from(result, 'utf8') : result;
+}
+
+function installRealpath(fs, path) {
+  const lenient = (p, options) => encode(lenientRealpath(fs, path, toPathString(p)), options);
+
+  const wrapSync = (orig) =>
+    function realpathSync(p, options) {
+      try {
+        return orig.call(fs, p, options);
+      } catch (e) {
+        if (!denied(e)) throw e;
+        return lenient(p, options);
+      }
+    };
+  const wrapCallback = (orig) =>
+    function realpath(p, options, callback) {
+      if (typeof options === 'function') {
+        callback = options;
+        options = undefined;
+      }
+      orig.call(fs, p, options, (e, resolved) => {
+        if (!denied(e)) return callback(e, resolved);
+        let out;
+        try {
+          out = lenient(p, options);
+        } catch (e2) {
+          return callback(e2);
+        }
+        callback(null, out);
+      });
+    };
+
+  const sync = wrapSync(fs.realpathSync);
+  sync.native = wrapSync(fs.realpathSync.native);
+  fs.realpathSync = sync;
+  const cb = wrapCallback(fs.realpath);
+  cb.native = wrapCallback(fs.realpath.native);
+  fs.realpath = cb;
+
+  const origPromise = fs.promises.realpath;
+  fs.promises.realpath = async function realpath(p, options) {
+    try {
+      return await origPromise.call(fs.promises, p, options);
+    } catch (e) {
+      if (!denied(e)) throw e;
+      return lenient(p, options);
+    }
+  };
+}
+
+/* ───────────────────────────────────────────────────── piped children ── */
+
+/** Every piped slot normalised the way Node normalises it. */
+function normaliseStdio(stdio) {
+  if (stdio === undefined || stdio === null) stdio = 'pipe';
+  if (typeof stdio === 'string') return [stdio, stdio, stdio];
+  if (!Array.isArray(stdio)) return null; // Node will throw its own error for this
+  const out = stdio.slice();
+  for (let i = 0; i < out.length; i += 1) {
+    if (out[i] === undefined || out[i] === null) out[i] = i < 3 ? 'pipe' : 'ignore';
+  }
+  return out;
+}
+
+const isPipe = (s) => s === 'pipe' || s === 'overlapped';
+
+/**
+ * A pipe pair under `\\.\pipe\LOCAL\`: the child's end as a file descriptor,
+ * opened NOW, and the parent's end as a stream that is wired the moment the
+ * server accepts it — on the next turn of the loop.
+ *
+ * The server must stay open until it has accepted: closing it first closes the
+ * pending instance the child is connected to, and the child's first write fails
+ * with EPIPE.
+ */
+function pipePair(deps, end) {
+  const { fs, net, crypto } = deps;
+  const name = LOCAL_PIPE_PREFIX + process.pid + '-' + crypto.randomBytes(8).toString('hex');
+  const server = net.createServer();
+  server.on('error', (e) => end.destroy(e));
+  server.once('connection', (socket) => {
+    server.close();
+    end._attach(socket);
+  });
+  // Binding a pipe server is synchronous; only the accept is not.
+  server.listen(name);
+  // Never keep a process alive on its own: the child is already connected, so
+  // the accept completes on the next loop turn whenever anything else runs.
+  server.unref();
+  let fd;
+  try {
+    fd = fs.openSync(name, 'r+');
+  } catch (e) {
+    server.close();
+    throw e;
+  }
+  return fd;
+}
+
+function makePipeEnd(Duplex) {
+  /**
+   * The parent's end of one piped slot.
+   *
+   * A Duplex over a socket that does not exist yet: writes queue until it does,
+   * reads are pushed as they arrive and pause the socket when nobody is reading.
+   * `ref`/`unref` are kept and applied, because esbuild unrefs its service's
+   * stdio so a process using it can exit.
+   */
+  return class PipeEnd extends Duplex {
+    constructor(options) {
+      super(options);
+      this._socket = null;
+      this._queued = [];
+      this._finalCallback = null;
+      this._refed = true;
+    }
+
+    _attach(socket) {
+      if (this.destroyed) {
+        socket.destroy();
+        return;
+      }
+      this._socket = socket;
+      if (!this._refed) socket.unref();
+      socket.on('data', (chunk) => {
+        if (!this.push(chunk)) socket.pause();
+      });
+      socket.on('end', () => this.push(null));
+      socket.on('error', (e) => this.destroy(e));
+      for (const [chunk, encoding, callback] of this._queued) socket.write(chunk, encoding, callback);
+      this._queued = [];
+      if (this._finalCallback !== null) {
+        const callback = this._finalCallback;
+        this._finalCallback = null;
+        this._finish(callback);
+      }
+    }
+
+    _read() {
+      if (this._socket !== null) this._socket.resume();
+    }
+
+    _write(chunk, encoding, callback) {
+      if (this._socket !== null) this._socket.write(chunk, encoding, callback);
+      else this._queued.push([chunk, encoding, callback]);
+    }
+
+    _final(callback) {
+      if (this._socket !== null) this._finish(callback);
+      else this._finalCallback = callback;
+    }
+
+    /** A named pipe has no half-close: the child sees EOF when the handle closes. */
+    _finish(callback) {
+      const socket = this._socket;
+      socket.end(() => {
+        socket.destroy();
+        callback();
+      });
+    }
+
+    _destroy(error, callback) {
+      if (this._socket !== null) this._socket.destroy();
+      for (const [, , cb] of this._queued) cb(error || new Error('stream destroyed'));
+      this._queued = [];
+      callback(error);
+    }
+
+    ref() {
+      this._refed = true;
+      if (this._socket !== null) this._socket.ref();
+      return this;
+    }
+
+    unref() {
+      this._refed = false;
+      if (this._socket !== null) this._socket.unref();
+      return this;
+    }
+  };
+}
+
+function installSpawn(deps) {
+  const { cp, fs } = deps;
+  const PipeEnd = makePipeEnd(require('stream').Duplex);
+  const original = cp.ChildProcess.prototype.spawn;
+
+  cp.ChildProcess.prototype.spawn = function spawn(options) {
+    const stdio = options && typeof options === 'object' ? normaliseStdio(options.stdio) : null;
+    if (stdio === null) return original.call(this, options);
+    if (stdio.includes('ipc')) {
+      const err = new Error(IPC_REFUSAL);
+      err.code = 'ERR_LOOPLY_CONTAINED_IPC';
+      throw err;
+    }
+    if (!stdio.some(isPipe)) return original.call(this, options);
+
+    const ends = [];
+    const fds = [];
+    try {
+      for (let i = 0; i < stdio.length; i += 1) {
+        if (!isPipe(stdio[i])) continue;
+        // Node's own shape: stdin is written, every other slot is read.
+        const end = new PipeEnd(i === 0 ? { readable: false } : { writable: false });
+        const fd = pipePair(deps, end);
+        ends.push([i, end]);
+        fds.push(fd);
+        stdio[i] = fd;
+      }
+    } catch (e) {
+      for (const fd of fds) fs.closeSync(fd);
+      for (const [, end] of ends) end.destroy();
+      throw e;
+    }
+
+    let result;
+    try {
+      result = original.call(this, Object.assign({}, options, { stdio }));
+    } finally {
+      // The child holds its own copies now. Ours must go, or the parent keeps
+      // the pipe open and never sees the child's EOF.
+      for (const fd of fds) fs.closeSync(fd);
+    }
+
+    const spawned = typeof this.pid === 'number' && this.pid !== 0;
+    for (const [i, end] of ends) {
+      if (!spawned) {
+        end.destroy();
+        continue;
+      }
+      this.stdio[i] = end;
+      if (i === 0) this.stdin = end;
+      if (i === 1) this.stdout = end;
+      if (i === 2) this.stderr = end;
+      if (i > 0) {
+        // Node waits for every READ slot to close before 'close', so the last
+        // of a child's output is never lost to an early 'close'. Same here,
+        // through the same counters its own `maybeClose` uses.
+        this._closesNeeded += 1;
+        end.on('close', () => {
+          this._closesGot += 1;
+          if (this._closesGot === this._closesNeeded) this.emit('close', this.exitCode, this.signalCode);
+        });
+      }
+    }
+    return result;
+  };
+}
+
+/* ─────────────────────────────────────────────────── synchronous calls ── */
+
+function installSync(deps) {
+  const { cp, fs, path, os, crypto } = deps;
+  const originalSpawnSync = cp.spawnSync;
+  const DEFAULT_MAX_BUFFER = 1024 * 1024;
+
+  function spawnSync(file, args, options) {
+    if (!Array.isArray(args)) {
+      options = args;
+      args = [];
+    }
+    options = Object.assign({}, options);
+    const stdio = normaliseStdio(options.stdio);
+    if (stdio === null) return originalSpawnSync(file, args, options);
+    if (stdio.includes('ipc')) {
+      const err = new Error(IPC_REFUSAL);
+      err.code = 'ERR_LOOPLY_CONTAINED_IPC';
+      throw err;
+    }
+    if (!stdio.some(isPipe)) return originalSpawnSync(file, args, options);
+
+    const box = fs.mkdtempSync(path.join(os.tmpdir(), 'looply-sync-'));
+    const opened = [];
+    const outputs = [];
+    try {
+      for (let i = 0; i < stdio.length; i += 1) {
+        if (!isPipe(stdio[i])) continue;
+        const file_ = path.join(box, String(i) + '-' + crypto.randomBytes(4).toString('hex'));
+        if (i === 0) {
+          const input = options.input;
+          const bytes =
+            input === undefined || input === null
+              ? Buffer.alloc(0)
+              : typeof input === 'string'
+                ? Buffer.from(input, options.encoding && options.encoding !== 'buffer' ? options.encoding : 'utf8')
+                : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+          fs.writeFileSync(file_, bytes);
+          const fd = fs.openSync(file_, 'r');
+          opened.push(fd);
+          stdio[i] = fd;
+        } else {
+          const fd = fs.openSync(file_, 'w');
+          opened.push(fd);
+          outputs.push([i, file_]);
+          stdio[i] = fd;
+        }
+      }
+      delete options.input;
+      const ret = originalSpawnSync(file, args, Object.assign(options, { stdio }));
+      for (const fd of opened.splice(0)) fs.closeSync(fd);
+
+      const maxBuffer = options.maxBuffer === undefined ? DEFAULT_MAX_BUFFER : options.maxBuffer;
+      const encoding = options.encoding && options.encoding !== 'buffer' ? options.encoding : null;
+      const output = Array.isArray(ret.output) ? ret.output.slice() : new Array(stdio.length).fill(null);
+      for (const [i, file_] of outputs) {
+        let bytes = fs.readFileSync(file_);
+        if (Number.isFinite(maxBuffer) && bytes.length > maxBuffer) {
+          bytes = bytes.subarray(0, maxBuffer);
+          if (!ret.error) {
+            const err = new Error(`spawnSync ${file} ENOBUFS`);
+            err.code = 'ENOBUFS';
+            err.errno = -4060;
+            err.syscall = `spawnSync ${file}`;
+            err.path = file;
+            err.spawnargs = args;
+            ret.error = err;
+          }
+        }
+        output[i] = encoding === null ? bytes : bytes.toString(encoding);
+      }
+      ret.output = output;
+      ret.stdout = output[1] === undefined ? null : output[1];
+      ret.stderr = output[2] === undefined ? null : output[2];
+      return ret;
+    } finally {
+      for (const fd of opened) fs.closeSync(fd);
+      try {
+        fs.rmSync(box, { recursive: true, force: true });
+      } catch {
+        /* a temp directory is not this call's verdict */
+      }
+    }
+  }
+
+  /** Node's own `checkExecSyncError`, which is not exported. */
+  function execSyncError(ret, command) {
+    if (ret.error) return Object.assign(ret.error, ret);
+    if (ret.status !== 0) {
+      let message = 'Command failed: ' + command;
+      if (ret.stderr && ret.stderr.length > 0) message += '\n' + ret.stderr.toString();
+      return Object.assign(new Error(message), ret);
+    }
+    return null;
+  }
+
+  function execFileSync(file, args, options) {
+    if (!Array.isArray(args)) {
+      options = args;
+      args = [];
+    }
+    options = Object.assign({}, options);
+    const inheritStderr = !options.stdio;
+    const ret = spawnSync(file, args, options);
+    if (inheritStderr && ret.stderr) process.stderr.write(ret.stderr);
+    const err = execSyncError(ret, [options.argv0 || file].concat(args).join(' '));
+    if (err) throw err;
+    return ret.stdout;
+  }
+
+  function execSync(command, options) {
+    options = Object.assign({}, options);
+    options.shell = typeof options.shell === 'string' ? options.shell : true;
+    const inheritStderr = !options.stdio;
+    const ret = spawnSync(command, [], options);
+    if (inheritStderr && ret.stderr) process.stderr.write(ret.stderr);
+    const err = execSyncError(ret, command);
+    if (err) throw err;
+    return ret.stdout;
+  }
+
+  cp.spawnSync = spawnSync;
+  cp.execFileSync = execFileSync;
+  cp.execSync = execSync;
+}
+
+/* ───────────────────────────────────────────────────────────── install ── */
+
+function install() {
+  if (process.platform !== 'win32') return false;
+  if (global.__looplyContainedNode) return false;
+  global.__looplyContainedNode = true;
+  const deps = {
+    cp: require('child_process'),
+    fs: require('fs'),
+    net: require('net'),
+    os: require('os'),
+    path: require('path'),
+    crypto: require('crypto'),
+  };
+  /*
+   * Windows REWRITES `TEMP`/`TMP` for an AppContainer process, to
+   * `<LOCALAPPDATA>\Packages\<container>\AC\Temp` — whatever the environment
+   * block said — and nothing creates that directory, so `os.tmpdir()` names a
+   * path that is not there and every temp file fails with ENOENT (measured).
+   * It is under the contained root's granted `local`, so it can be made.
+   */
+  try {
+    deps.fs.mkdirSync(deps.os.tmpdir(), { recursive: true });
+  } catch {
+    /* a temp directory we cannot make is a failure for whoever needs it */
+  }
+  installRealpath(deps.fs, deps.path);
+  installSpawn(deps);
+  installSync(deps);
+  // ESM `import { spawn } from 'node:child_process'` reads a snapshot of the
+  // CommonJS exports; refresh it so both module systems see the same functions.
+  require('module').syncBuiltinESMExports();
+  return true;
+}
+
+module.exports = { install, lenientRealpath, normaliseStdio, IPC_REFUSAL, LOCAL_PIPE_PREFIX };
+
+if (process.env.LOOPLY_CONTAINED_NODE === '1') install();