@metamynd/agentsafe-signer 0.13.0

package/service-installer.mjs

@@ -0,0 +1,244 @@
+// service-installer.mjs — generates the OS service unit files from
+// docs/design/agent-key-custody-local-signer-daemon-plan.md's "OS service unit templates"
+// section. Deliberately writes files ONLY to a local output directory the caller specifies —
+// never to a real system location (~/.config/systemd/user, /etc/systemd/system,
+// ~/Library/LaunchAgents, the Windows service registry) and never invokes systemctl/launchctl/
+// sc.exe itself. It prints the exact command an operator runs to actually install the result;
+// running that command is always a separate, deliberate, human step. See README.md "Status" for
+// why: registering a real system service is a genuine system modification, out of scope for what
+// this module does on its own.
+import path from 'node:path';
+
+/** Deterministic, filesystem-safe short id for a logical identity (agentDid/serviceDid/name). */
+function shortId(identity) {
+  // Not crypto-sensitive — just needs to be stable and safe in a unit filename/pipe name.
+  let h = 0;
+  for (let i = 0; i < identity.length; i++) h = (Math.imul(h, 31) + identity.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+/** The node that will actually exist at ExecStart= time. `/usr/bin/node` was the old default and
+ *  is absent on any host using nvm/asdf/volta (verified: the real host this was first installed on
+ *  had node only under ~/.nvm), which systemd reports as a bare 203/EXEC with no explanation of
+ *  which binary was missing. process.execPath is the interpreter running the generator — a far
+ *  better default, and still overridable via the nodePath option. */
+function defaultNodePath() {
+  return process.execPath || '/usr/bin/node';
+}
+
+function assertTier(tier) {
+  if (tier !== 1 && tier !== 2) throw new Error(`tier must be 1 or 2, got ${tier}`);
+}
+
+// --- Linux: systemd, socket-activated -------------------------------------------------------
+
+/**
+ * @param {{identity:string, tier:1|2, nodePath?:string, daemonPath:string, role?:'agent'|'service', cliPath?:string}} opts
+ * @returns {{socketUnit:string, serviceUnit:string, id:string, enableCommand:string}}
+ */
+export function generateSystemdUnits({ identity, tier, nodePath = defaultNodePath(), daemonPath, role = 'agent', cliPath }) {
+  assertTier(tier);
+  if (!identity || !daemonPath) throw new Error('generateSystemdUnits requires { identity, daemonPath }');
+  const id = shortId(identity);
+
+  const socketUnit = [
+    `# agentsafe-signer@.socket (instance: ${id})`,
+    '[Unit]',
+    `Description=AgentSafe local signer socket for identity ${id}`,
+    '',
+    '[Socket]',
+    'ListenStream=%t/agentsafe/signer-%i.sock',
+    'SocketMode=0600',
+    'DirectoryMode=0700',
+    'RemoveOnStop=true',
+    '',
+    '[Install]',
+    'WantedBy=sockets.target',
+    '',
+  ].join('\n');
+
+  // Tier 1: %h-relative ExecStart (the real logged-in user's own home) is correct here because
+  // Tier 1 runs AS that user — see the design doc's own note on why Tier 2 cannot reuse this.
+  // ONLY for a relative daemonPath, though: `%h/` + an ABSOLUTE path produced a doubled,
+  // non-existent path (`/home/u` + `/home/u/...` -> `/home/u/home/u/...`), and the CLI's own
+  // documented example passes an absolute one. Verified by installing and starting the unit on a
+  // real systemd host, where the failure was visible in the ExecStart= line systemd reported back.
+  // ExecStart runs cli.mjs, not daemon.mjs. daemon.mjs is a library module with no argv handling
+  // at all: `node daemon.mjs` loads it, returns 0 and serves nothing, so a unit pointing there
+  // starts and instantly "succeeds" while never listening. Found by installing and starting the
+  // unit on a real systemd host. cli.mjs ships alongside daemon.mjs in this package's own `files`
+  // list, so deriving it from the same directory is stable, and `cliPath` overrides it outright.
+  if (role !== 'agent' && role !== 'service') throw new Error(`role must be 'agent' or 'service', got ${role}`);
+  const resolvedCliPath = cliPath ?? daemonPath.replace(/daemon\.mjs$/, 'cli.mjs');
+  const isAbsolutePath = resolvedCliPath.startsWith('/');
+  const cliInvocationPath = tier === 1 && !isAbsolutePath ? `%h/${resolvedCliPath.replace(/^\.?\//, '')}` : resolvedCliPath;
+  // %S is systemd's own state-directory root, so this lines up with StateDirectory= below rather
+  // than hard-coding a path that has to be kept in sync with it by hand.
+  const invocation = `${nodePath} ${cliInvocationPath} start --state-dir %S/agentsafe/%i --role ${role} --identity %i`;
+  // No setpriv wrapper. An earlier pass wrapped this in `setpriv --dumpable 0 --` to deny ptrace
+  // via PR_SET_DUMPABLE=0. That option does not exist: util-linux's setpriv has no --dumpable flag
+  // (checked on util-linux 2.39.3 / Ubuntu 24.04 LTS — the string is absent from the binary
+  // entirely), so the generated unit failed at exec with "setpriv: unrecognized option
+  // '--dumpable'" and the service never started at all, making every other directive here moot.
+  // Found by actually installing and starting the unit on a real systemd host; the previous
+  // service-installer.smoke.mjs assertion passed because it only matched the generated TEXT.
+  // Tier 1's ptrace posture is therefore what the design doc's threat model already says it is —
+  // T3 "partial", resting on the host's own kernel.yama.ptrace_scope — and Tier 2's dedicated
+  // DynamicUser UID remains the directive that actually mitigates T3. LimitCORE=0 below is
+  // unaffected and still covers the core-dump half declaratively.
+  const execStart = invocation;
+
+  const serviceLines = [
+    `# agentsafe-signer@.service (instance: ${id}, Tier ${tier})`,
+    '[Unit]',
+    `Description=AgentSafe local signer daemon for identity ${id}`,
+    'Requires=agentsafe-signer@%i.socket',
+    '',
+    '[Service]',
+    // Type=exec, not notify. Nothing in this package sends sd_notify READY=1, and systemd fails a
+    // Type=notify service with `Result: protocol` when the notification never arrives — even
+    // though node is healthy and listening. Observed on a real host. Type=exec still waits for a
+    // successful execve() before considering the unit started, which is the strongest readiness
+    // guarantee available without implementing the sd_notify protocol (a real feature, tracked as
+    // an open gap in README.md rather than smuggled into this generator).
+    'Type=exec',
+    `ExecStart=${execStart}`,
+    'StateDirectory=agentsafe/%i',
+    'NoNewPrivileges=true',
+    'ProtectSystem=strict',
+    'ProtectHome=read-only',
+    'PrivateTmp=true',
+    'PrivateDevices=true',
+    'PrivateNetwork=true',
+    'ProtectKernelTunables=true',
+    'ProtectKernelModules=true',
+    'ProtectKernelLogs=true',
+    'ProtectControlGroups=true',
+    'ProtectClock=true',
+    'ProtectHostname=true',
+    'RestrictNamespaces=true',
+    'RestrictRealtime=true',
+    'RestrictSUIDSGID=true',
+    'LockPersonality=true',
+    // NOT MemoryDenyWriteExecute=true. V8 is a JIT: it needs W->X memory transitions, and this
+    // directive makes mprotect(PROT_EXEC) fail with ENOMEM inside v8::base::OS::SetPermissions
+    // during Isolate init, so node dies with SIGTRAP ("Check failed: 12 == errno") before running
+    // a single line of daemon code. Observed on a real systemd host, not inferred — the service
+    // failed with Result: core-dump until this was removed. No Node service can set it.
+    'CapabilityBoundingSet=',
+    'AmbientCapabilities=',
+    'UMask=0077',
+    'LimitCORE=0',
+    'SystemCallFilter=@system-service',
+    'SystemCallErrorNumber=EPERM',
+    'SystemCallArchitectures=native',
+  ];
+  // Tier 2 only: a dedicated dynamic UID makes RemoveIPC safe (see the design doc's own
+  // reasoning for why it's unsafe at Tier 1, where the daemon shares the agent's UID).
+  if (tier === 2) serviceLines.push('DynamicUser=true', 'RemoveIPC=true');
+  serviceLines.push('', '[Install]', 'WantedBy=default.target', '');
+
+  const enableCommand =
+    tier === 1
+      ? `systemctl --user daemon-reload && systemctl --user enable --now agentsafe-signer@${id}.socket`
+      : `sudo systemctl daemon-reload && sudo systemctl enable --now agentsafe-signer@${id}.socket`;
+
+  return { socketUnit, serviceUnit: serviceLines.join('\n'), id, enableCommand };
+}
+
+// --- macOS: launchd, socket-activated --------------------------------------------------------
+
+/**
+ * @param {{identity:string, tier:1|2, nodePath?:string, daemonPath:string, socketDir:string}} opts
+ */
+export function generateLaunchdPlist({ identity, tier, nodePath = '/usr/local/bin/node', daemonPath, socketDir }) {
+  assertTier(tier);
+  if (!identity || !daemonPath || !socketDir) throw new Error('generateLaunchdPlist requires { identity, daemonPath, socketDir }');
+  const id = shortId(identity);
+  const label = `ai.metamynd.agentsafe-signer.${id}`;
+  const socketPath = path.posix.join(socketDir, `signer-${id}.sock`);
+
+  // launchd's plist has no LimitCORE-equivalent key at all (unlike systemd), and `ulimit` is a
+  // shell builtin, not a real binary — so, unlike setpriv above, this genuinely needs a shell
+  // hop. `sh -c 'ulimit -c 0; exec "$@"' sh <node> <daemon> --identity <id>` sets $0='sh' (unused,
+  // just a placeholder) and the rest as $1.. via "$@", then `exec` replaces the shell with node —
+  // a true exec chain, not a forked supervisor, same as setpriv's own execve() above.
+  //
+  // Disclosed, not fixed: macOS has no ptrace-deny equivalent reachable this way at all —
+  // PT_DENY_ATTACH must be called BY the target process itself via a syscall, which needs a
+  // native addon or FFI to reach from here, the same architectural limitation secure-memory.mjs's
+  // own header discloses for mlock(). Only RLIMIT_CORE is closed on macOS by this generator.
+  const plist = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    `  <key>Label</key><string>${label}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    '    <string>/bin/sh</string>',
+    '    <string>-c</string>',
+    '    <string>ulimit -c 0; exec "$@"</string>',
+    '    <string>sh</string>',
+    `    <string>${nodePath}</string>`,
+    `    <string>${daemonPath}</string>`,
+    '    <string>--identity</string>',
+    `    <string>${id}</string>`,
+    '  </array>',
+    '  <key>Sockets</key>',
+    '  <dict>',
+    '    <key>Listener</key>',
+    '    <dict>',
+    `      <key>SockPathName</key><string>${socketPath}</string>`,
+    '      <key>SockPathMode</key><integer>384</integer>',
+    '    </dict>',
+    '  </dict>',
+    '  <key>RunAtLoad</key><false/>',
+    '  <key>KeepAlive</key><false/>',
+    '  <key>ProcessType</key><string>Background</string>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+
+  const plistFileName = `${label}.plist`;
+  const enableCommand =
+    tier === 1
+      ? `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${plistFileName}`
+      : `# Tier 2 on macOS is a sandbox-exec Seatbelt profile layered on top of this same LaunchAgent, ` +
+        `not a separate plist mechanism — see README.md "Status" for what's not yet generated here.\n` +
+        `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${plistFileName}`;
+
+  return { plist, plistFileName, id, enableCommand };
+}
+
+// --- Windows: a service under a Virtual Service Account, named pipe transport ---------------
+
+/**
+ * Returns the exact sc.exe argv this would run — never runs it. Tier 1 has no natural analog on
+ * Windows (services are inherently system-level there), so this always targets Tier 2's Virtual
+ * Service Account, matching the design doc's own "Tier 2 by default here, not Tier 1" call.
+ * @param {{identity:string, nodePath?:string, daemonPath:string}} opts
+ */
+export function generateWindowsService({ identity, nodePath = 'node.exe', daemonPath }) {
+  if (!identity || !daemonPath) throw new Error('generateWindowsService requires { identity, daemonPath }');
+  const id = shortId(identity);
+  const serviceName = `AgentSafeSigner-${id}`;
+  const virtualAccount = `NT SERVICE\\${serviceName}`;
+  const binPath = `"${nodePath}" "${daemonPath}" --identity ${id}`;
+
+  const createArgv = ['sc.exe', 'create', serviceName, `binPath=${binPath}`, 'start=auto', `obj=${virtualAccount}`, 'password='];
+  const startArgv = ['sc.exe', 'start', serviceName];
+
+  return {
+    serviceName,
+    virtualAccount,
+    createArgv,
+    startArgv,
+    enableCommand: `${createArgv.map(quoteIfNeeded).join(' ')}\n${startArgv.join(' ')}`,
+  };
+}
+
+function quoteIfNeeded(arg) {
+  return /\s/.test(arg) && !arg.includes('"') ? `"${arg}"` : arg;
+}

package/windows-secure-pipe.mjs

@@ -0,0 +1,367 @@
+// windows-secure-pipe.mjs — a real, ACL-restricted named pipe on Windows, closing the gap the
+// design doc originally flagged as blocked ("Node's net module has no API for a custom named-pipe
+// ACL... needs a native addon"). That was wrong: the same technique already used for DPAPI
+// (kek-backends.mjs) — shelling out to .NET via PowerShell, no native module — works here too.
+//
+// .NET's System.IO.Pipes.NamedPipeServerStream accepts a real PipeSecurity at construction, which
+// Node's own net module has no equivalent for. So the pipe itself is created and owned by a small
+// PowerShell/.NET relay process, restricted to the current Windows user, and Node talks to it
+// over the relay's own stdin/stdout — a normal child-process pipe, nothing exotic. Once a client
+// connects to the real named pipe, bytes flow: external caller <-> restricted named pipe (ACL
+// enforced by Windows/.NET) <-> relay process <-> stdin/stdout <-> this module <-> daemon.mjs's
+// existing protocol handling, unchanged.
+//
+// The signing socket needs to keep accepting new connections indefinitely, so a POOL of relay
+// processes is kept warm (each an independent NamedPipeServerStream instance sharing the same
+// pipe name — the normal Windows pattern for a multi-instance named pipe server); whichever one a
+// client connects to gets replaced immediately so the pool stays full. The admin socket is a
+// single, non-replenished instance that self-closes after one connection or its own timeout,
+// matching its existing one-shot design on Linux/macOS.
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+// How long a single relay attempt may take to construct its pipe and report ACL_RULE_COUNT
+// before it's treated as stuck and killed so a fresh attempt can be made. Verified empirically
+// (not hypothesized): under concurrent load — several relay processes constructing a
+// NamedPipeServerStream with a custom PipeSecurity at nearly the same instant, even for
+// DIFFERENT pipe names — one occasionally hangs indefinitely inside the .NET constructor call
+// itself, never printing so much as ACL_RULE_COUNT and never exiting on its own. Without a bound
+// here, that hang was unrecoverable and propagated all the way up to daemon.startSigningServer/
+// startAdminServer's own callers, which had no way to detect or retry it either.
+const SPAWN_TIMEOUT_MS = 1500;
+// Bounds createSecurePipeOnce's retries specifically (the pool already retries indefinitely as
+// part of its own "always on" design — see spawnOne's own comment) so a persistently broken
+// environment fails loudly after a bounded number of attempts instead of retrying forever. A
+// shorter SPAWN_TIMEOUT_MS with more attempts (rather than a longer timeout with fewer) recovers
+// faster from the common case — the observed contention tends to clear within one or two
+// retries — while keeping a similar worst-case total bound.
+const MAX_SPAWN_ATTEMPTS = 8;
+
+function relayScript(pipeName, maxInstances) {
+  return [
+    'Add-Type -AssemblyName System.Core',
+    "$ErrorActionPreference = 'Stop'",
+    'try {',
+    '  $currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User',
+    '  $security = New-Object System.IO.Pipes.PipeSecurity',
+    // FullControl, not ReadWrite — verified empirically (not assumed) that a multi-instance named
+    // pipe with an explicit PipeSecurity granting only ReadWrite fails EVERY instance after the
+    // first with "Access to the path is denied": creating an additional instance of an existing
+    // pipe needs rights beyond plain read/write, which a ReadWrite-only ACL does not grant even to
+    // the same identity that holds it. FullControl still restricts the pipe to exactly this one
+    // identity — the security property this exists for — it only changes what THAT identity may
+    // do with its own pipe, not who else can reach it.
+    '  $rule = New-Object System.IO.Pipes.PipeAccessRule($currentUser, [System.IO.Pipes.PipeAccessRights]::FullControl, [System.Security.AccessControl.AccessControlType]::Allow)',
+    '  $security.AddAccessRule($rule)',
+    // PipeOptions.Asynchronous, not None — the two CopyToAsync loops below run concurrently in
+    // opposite directions on this SAME handle (client->relay and relay->client). A handle opened
+    // without FILE_FLAG_OVERLAPPED (PipeOptions.None) only supports one outstanding I/O operation
+    // at a time; a concurrent Read and Write on it races and faults one of the two Tasks, which
+    // WaitAny treats as "completed" and immediately Disposes the pipe — truncating whichever
+    // direction was still in flight. Verified empirically: with None, a response written to this
+    // relay's stdin after a client request never reached the client at all.
+    `  $pipe = New-Object System.IO.Pipes.NamedPipeServerStream("${pipeName}", [System.IO.Pipes.PipeDirection]::InOut, ${maxInstances}, [System.IO.Pipes.PipeTransmissionMode]::Byte, [System.IO.Pipes.PipeOptions]::Asynchronous, 65536, 65536, $security)`,
+    '  $ruleCount = $pipe.GetAccessControl().GetAccessRules($true,$true,[System.Security.Principal.NTAccount]).Count',
+    '  [Console]::Error.WriteLine("ACL_RULE_COUNT:$ruleCount")',
+    '  [Console]::Error.WriteLine("READY")',
+    '  $pipe.WaitForConnection()',
+    '  [Console]::Error.WriteLine("CONNECTED")',
+    '  $stdin = [Console]::OpenStandardInput()',
+    '  $stdout = [Console]::OpenStandardOutput()',
+    '  $t1 = $pipe.CopyToAsync($stdout)',
+    '  $t2 = $stdin.CopyToAsync($pipe)',
+    '  [System.Threading.Tasks.Task]::WaitAny(@($t1, $t2)) | Out-Null',
+    '  $pipe.Dispose()',
+    '  [Console]::Error.WriteLine("CLOSED")',
+    '} catch {',
+    '  [Console]::Error.WriteLine("RELAY_ERROR:" + $_.Exception.Message)',
+    '  exit 1',
+    '}',
+  ].join('\n');
+}
+
+function spawnRelay(pipeName, maxInstances) {
+  return spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', relayScript(pipeName, maxInstances)], {
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/** Minimal net.Socket-shaped adapter over a relay child process's own stdio. */
+function socketAdapter(child) {
+  return {
+    on: (event, cb) => child.stdout.on(event, cb),
+    once: (event, cb) => child.stdout.once(event, cb),
+    write: (data) => child.stdin.write(data),
+    destroy: () => {
+      try {
+        child.kill();
+      } catch {
+        /* already exited */
+      }
+    },
+  };
+}
+
+function watchRelayStderr(child, { onAclVerified, onConnected } = {}) {
+  let buf = '';
+  child.stderr.on('data', (chunk) => {
+    buf += chunk.toString('utf8');
+    let idx;
+    while ((idx = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (line.startsWith('ACL_RULE_COUNT:')) onAclVerified?.(Number(line.split(':')[1]));
+      else if (line === 'CONNECTED') onConnected?.();
+      else if (line.startsWith('RELAY_ERROR:')) console.error(`[windows-secure-pipe] relay error: ${line.slice('RELAY_ERROR:'.length)}`);
+    }
+  });
+}
+
+/**
+ * Keeps `poolSize` relay instances warm on `pipeName`, calling `onConnection(socketLike)` once
+ * per accepted client and immediately spawning a replacement to keep the pool full. Shaped like a
+ * `net.Server` (`.close()`, emits `'close'`, `'aclVerified'` fires once per spawned instance —
+ * independent of whether it ever receives a connection — as the real test hook proving every
+ * instance, not just a lucky one, is actually restricted).
+ */
+export function createSecurePipePool(pipeName, onConnection, { poolSize = 4 } = {}) {
+  const emitter = new EventEmitter();
+  let stopped = false;
+  const children = new Set();
+  emitter.closed = false; // see createSecurePipeOnce's own comment on this — same synchronous escape hatch
+
+  // Ongoing replenishment after a successful start retries indefinitely on purpose (the pool's
+  // whole "always on" design — a transient failure refilling one consumed slot should just keep
+  // trying). But a pool that has NEVER once succeeded needs a bound: observed directly, not
+  // hypothesized — a persistent (not transient) construction failure can keep every attempt
+  // failing after its own SPAWN_TIMEOUT_MS, in a tight spawn->timeout->exit->respawn cycle, for
+  // 15+ minutes straight with zero signal to the caller that anything is wrong (daemon.mjs's
+  // startServer just awaits 'aclVerified' forever). STARTUP_FAILURE_LIMIT bounds only the
+  // "never even once succeeded" case; a pool that already started stays resilient indefinitely.
+  let everSucceeded = false;
+  let consecutiveFailures = 0;
+  const STARTUP_FAILURE_LIMIT = 20; // ~20 * SPAWN_TIMEOUT_MS worst case before giving up on a first-ever start
+
+  /**
+   * Resolves once THIS instance's own pipe object is constructed (its ACL confirmed) — not once
+   * it has a client. Creating several NamedPipeServerStream instances of the SAME pipe name
+   * concurrently races on Windows (observed directly: "Access to the path is denied" from the
+   * SECOND+ instance's constructor when several are spawned at once); waiting for each one to
+   * finish constructing before starting the next avoids the race entirely.
+   *
+   * Replenishment happens on the relay's own EXIT, not on `onConnected` — a connected instance
+   * still holds its slot against `poolSize` for as long as it's actively relaying (Windows only
+   * frees the slot once that instance's pipe object is disposed). Replenishing immediately on
+   * connect, before that slot is actually free, briefly asks for `poolSize + 1` live instances at
+   * once and fails with "All pipe instances are busy" — observed directly, not a hypothetical.
+   */
+  function spawnOne() {
+    if (stopped) return Promise.resolve();
+    return new Promise((resolve) => {
+      const child = spawnRelay(pipeName, poolSize);
+      children.add(child);
+      let resolved = false;
+      let acked = false;
+      // See SPAWN_TIMEOUT_MS's own comment: a relay can hang indefinitely inside the .NET pipe
+      // constructor under concurrent load without this — killing it here just triggers the SAME
+      // 'exit' handler below that any other exit does, so replenishment/retry falls out for free.
+      const spawnTimer = setTimeout(() => {
+        if (!acked) {
+          try {
+            child.kill();
+          } catch {
+            /* already exited */
+          }
+        }
+      }, SPAWN_TIMEOUT_MS);
+      watchRelayStderr(child, {
+        onAclVerified: (n) => {
+          acked = true;
+          everSucceeded = true;
+          consecutiveFailures = 0;
+          clearTimeout(spawnTimer);
+          emitter.emit('aclVerified', n);
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        },
+        onConnected: () => onConnection(socketAdapter(child)),
+      });
+      child.on('exit', () => {
+        clearTimeout(spawnTimer);
+        children.delete(child);
+        if (!acked && !everSucceeded) {
+          consecutiveFailures++;
+          if (consecutiveFailures >= STARTUP_FAILURE_LIMIT) {
+            // Never once succeeded, after a generous bounded number of attempts — stop retrying
+            // and tell the caller, instead of cycling forever with no way for anyone to notice.
+            stopped = true;
+            emitter.closed = true;
+            emitter.emit('close', new Error(`createSecurePipePool: gave up after ${consecutiveFailures} consecutive failed attempts — the pipe never became ready even once`));
+            if (!resolved) {
+              resolved = true;
+              resolve();
+            }
+            return;
+          }
+        }
+        if (!stopped) spawnOne(); // this slot just freed for real — replenish now, not earlier
+        if (!resolved) {
+          resolved = true;
+          resolve(); // don't hang the startup chain on a relay that failed before ever reporting ready
+        }
+      });
+      child.on('error', () => {
+        clearTimeout(spawnTimer);
+        children.delete(child);
+      });
+    });
+  }
+
+  (async () => {
+    for (let i = 0; i < poolSize; i++) {
+      if (stopped) break;
+      await spawnOne(); // sequential on purpose — see spawnOne's own comment
+    }
+  })();
+
+  // Same discipline as createSecurePipeOnce below: 'close' means every instance's pipe handle is
+  // actually gone (all children have genuinely exited), not just "kill() was requested" — a caller
+  // restarting a daemon on the same logical path right after `.close()` needs the OS to have
+  // already released the old pipe name.
+  emitter.close = () => {
+    if (stopped) return;
+    stopped = true;
+    if (children.size === 0) {
+      emitter.closed = true;
+      emitter.emit('close');
+      return;
+    }
+    let remaining = children.size;
+    for (const c of children) {
+      c.once('exit', () => {
+        remaining--;
+        if (remaining === 0) {
+          emitter.closed = true;
+          emitter.emit('close');
+        }
+      });
+      c.kill();
+    }
+  };
+  return emitter;
+}
+
+/**
+ * A single, non-replenished instance for the admin socket: closes after one connection is fully
+ * handled (the caller calls `.close()` itself, same as the existing Linux/macOS admin server) or
+ * after `timeoutMs` with no connection at all. Same `net.Server`-shaped interface as the pool.
+ */
+export function createSecurePipeOnce(pipeName, onConnection, { timeoutMs = 60_000 } = {}) {
+  const emitter = new EventEmitter();
+  let closed = false; // true once emitter.close() has been called, OR a terminal finish/fail happened
+  let everReady = false; // true once 'aclVerified' has fired at least once, across any attempt
+  let child = null;
+  let attempts = 0;
+  const timer = setTimeout(() => emitter.close(), timeoutMs);
+  emitter.closed = false; // readable synchronously by a caller that only gets `emitter` AFTER it
+  // already closed (see daemon.mjs's startAdminServer) — a 'close' listener attached after the
+  // event already fired would never see it; this lets that caller check directly instead.
+
+  // 'close' must mean the pipe is GENUINELY gone, not merely "kill() was called" — a caller (e.g.
+  // daemon.mjs's startAdminServer, which resolves its own promise off this event) uses it as the
+  // signal that the admin socket is safe to consider unreachable. child.kill() only requests
+  // termination; the relay process (and its held pipe handle) can still exist for a few more
+  // milliseconds until Windows actually tears it down. Verified empirically: without waiting for
+  // the child's own 'exit', a client connecting immediately after `.close()` could still reach the
+  // pipe.
+  function finish() {
+    clearTimeout(timer);
+    emitter.closed = true;
+    emitter.emit('close');
+  }
+
+  // Emitted (with an Error) only when every attempt exhausted MAX_SPAWN_ATTEMPTS without the pipe
+  // EVER becoming ready even once — daemon.mjs's startServer listens for this so a persistently
+  // broken environment REJECTS the caller's promise instead of hanging it forever, which nothing
+  // did before this existed (there was no failure path at all if the pipe simply never came up).
+  // A pipe that WAS ready at least once (everReady) and later closes (e.g. its own overall
+  // timeoutMs elapsed with no client ever connecting — the normal, expected admin-socket
+  // lifecycle) is NOT a failure and goes through finish() instead, even on its very last attempt.
+  function fail(err) {
+    clearTimeout(timer);
+    emitter.closed = true;
+    emitter.emit('close', err);
+  }
+
+  function spawnAttempt() {
+    attempts++;
+    child = spawnRelay(pipeName, 1);
+    let acked = false;
+    // See SPAWN_TIMEOUT_MS's own comment: without this, a relay stuck inside the .NET pipe
+    // constructor under concurrent load hangs forever with no signal at all.
+    const spawnTimer = setTimeout(() => {
+      if (!acked) {
+        try {
+          child.kill();
+        } catch {
+          /* already exited */
+        }
+      }
+    }, SPAWN_TIMEOUT_MS);
+
+    watchRelayStderr(child, {
+      onAclVerified: (n) => {
+        acked = true;
+        everReady = true;
+        clearTimeout(spawnTimer);
+        emitter.emit('aclVerified', n);
+      },
+      onConnected: () => onConnection(socketAdapter(child)),
+    });
+
+    const onExit = () => {
+      clearTimeout(spawnTimer);
+      if (closed) {
+        // A deliberate emitter.close() call caused this exit (its own overall timeoutMs elapsing
+        // counts as deliberate too, per the timer above) — this IS the genuine-exit signal that
+        // call was waiting for, whether or not this particular attempt ever got ready.
+        finish();
+        return;
+      }
+      if (acked) {
+        // Served its purpose (handled its one connection, or the relay script completed on its
+        // own) — not a construction failure, so no retry, just the normal close.
+        closed = true;
+        finish();
+        return;
+      }
+      // This attempt never became ready — either crashed immediately or was killed by the spawn
+      // timeout above. Retry a bounded number of times before giving up for good.
+      if (attempts < MAX_SPAWN_ATTEMPTS) {
+        spawnAttempt();
+        return;
+      }
+      closed = true;
+      fail(new Error(`createSecurePipeOnce: gave up after ${attempts} attempts — the pipe never became ready`));
+    };
+    child.on('exit', onExit);
+    child.on('error', onExit);
+  }
+
+  spawnAttempt();
+
+  emitter.close = () => {
+    if (closed) return;
+    closed = true;
+    try {
+      child.kill();
+    } catch {
+      finish(); // already exited before we could kill it — nothing left to wait for
+    }
+  };
+
+  return emitter;
+}