agent-shim 7.14.0 → 8.0.1

package/dist/types/index.d.ts

@@ -664,10 +664,12 @@ interface LayoutPaths {
     readonly categoriesLocalFile: string;
     /** Path to the claude-shim.json marker recording where `agent-shim shim enable` last placed a `claude`-named copy of this executable, and how. */
     readonly claudeShimFile: string;
-    /** Directory holding the headroom daemon's coordination state: state.json, the start lock, and the session registry. */
+    /** Directory holding the headroom daemon's coordination state: the state file, the start lock, the session registry, and the socket directory. */
     readonly headroomDir: string;
-    /** Path to the headroom supervisor's state.json: pids, port, version, allowlist hash, last error. */
+    /** Path to the headroom supervisor's state file: pids, socket path, version, allowlist hash, last error. Its name carries `HEADROOM_STATE_SCHEMA_VERSION`, so a supervisor from a release with another state schema keeps its own file instead of contending for this one. */
     readonly headroomStateFile: string;
+    /** Directory, mode 0700, holding the headroom daemon's unix socket: one `<supervisor-pid>.sock` per supervisor generation. Only its owner can enter it, which is what authenticates the door's hop to the daemon. */
+    readonly headroomSocketDir: string;
     /** Path to the exclusive-create marker guarding "who spawns the supervisor" so concurrent launches start at most one. */
     readonly headroomLockFile: string;
     /** Directory holding one `<launcher-pid>.json` session-registry entry per live launch routed through headroom. */
@@ -684,7 +686,7 @@ interface LayoutPaths {
     readonly frontdoorCaCertFile: string;
     /** Path to the front door's CA private key, mode 0600: whoever can read it can impersonate the door to every routed child. */
     readonly frontdoorCaKeyFile: string;
-    /** Directory of combined CA bundles: a parent environment's own NODE_EXTRA_CA_CERTS file plus the front door's CA, one file per distinct combination, for children that must keep trusting both. */
+    /** Directory of combined CA bundles: a parent environment's own NODE_EXTRA_CA_CERTS (for a routed child) or HEADROOM_CA_BUNDLE (for the headroom daemon) file plus the front door's CA, one file per distinct combination, for processes that must keep trusting both. */
     readonly frontdoorCaBundlesDir: string;
     /** Path to the front door's state.json: its supervisor pid, its port, and the sticky port it last served on. */
     readonly frontdoorStateFile: string;
@@ -1157,8 +1159,8 @@ interface LogPort {
 }
 /** The running headroom daemon one launch routed through, as `HeadroomPort.ensure` reports it. The front door owns the session's routing; this names the daemon the door's headroom hop forwards to, and the project identity headroom scopes memory to. */
 interface HeadroomUp {
-    /** The loopback port the headroom daemon listens on: what the door's headroom hop reads live and `HEADROOM_PROXY_URL` names for anything else that wants the daemon. */
-    readonly port: number;
+    /** The unix socket the headroom daemon serves on, inside the owner-only socket directory: what the door's headroom hop dials. The child never reaches the daemon itself, so this is reported, never exported to its environment. */
+    readonly socketPath: string;
     /** The project identity headroom scopes memory state to: the git repo root of the launch directory, or the directory itself outside a repository. */
     readonly projectId: string;
 }
@@ -1468,7 +1470,7 @@ declare function mintLeaf(ca: CaMaterial, names: readonly string[], now: Readonl
 /** Mints each host's leaf once from the CA and reuses it, because generating a 2048-bit RSA keypair costs noticeable time and nothing about the certificate changes between sessions. */
 declare function createLeafCache(ca: CaMaterial, now: () => Date): (host: string) => LeafCert;
 /**
- * Persistence for the CA: generated once on the machine's first headroom start and reused forever after, because regenerating it would invalidate every child's `NODE_EXTRA_CA_CERTS` pointing at the old file. The real implementation writes the key with mode 0600; injected fakes keep it in memory.
+ * Persistence for the CA: generated once on the machine's first front-door start and reused forever after, because regenerating it would invalidate every child's `NODE_EXTRA_CA_CERTS` pointing at the old file. The real implementation writes the key with mode 0600; injected fakes keep it in memory.
  */
 interface ConnectCertStore {
     /** The persisted CA, or undefined when none exists yet (or only half of it does: a cert without its key can sign nothing, so it counts as absent). */
@@ -1784,21 +1786,39 @@ interface EnsureHeadroomPorts {
 /**
  * Brings the headroom daemon up for this launch, or finds it already running, and registers this launcher pid in its session registry (the fact that keeps the daemon alive and defers drift restarts until this launch is done).
  *
- * The exclusive-create start lock decides which of several concurrent launches spawns the one supervisor: its holder spawns and keeps waiting like everyone else, everyone else waits on state.json, and a lock whose holder has died is removed and retried. Readiness is "state names a live supervisor, a live headroom pid, and a port", which the supervisor only writes after its own `/readyz` probe has passed, so polling state alone never mistakes a bound-but-not-ready port for a usable daemon.
+ * The exclusive-create start lock decides which of several concurrent launches spawns the one supervisor: its holder spawns and keeps waiting like everyone else, everyone else waits on the state file, and a lock whose holder has died is removed and retried. Readiness is "state names a live supervisor, a live headroom pid, and a socket path", which the supervisor only writes after its own `/readyz` probe over that socket has passed, so polling state alone never mistakes a bound-but-not-ready socket for a usable daemon.
  *
- * Throws `HeadroomStartError` (naming the daemon log path and any recorded `lastError`) when the daemon is not up within `HEADROOM_START_TIMEOUT_MS`, or when a live supervisor has recorded a fatal error.
+ * Throws `HeadroomStartError` (naming the daemon log path and any recorded `lastError`) when the daemon is not up within `HEADROOM_START_TIMEOUT_MS`, or when a live supervisor has recorded a fatal error (a platform without unix sockets and a socket directory that fails the owner-only check are recorded this way, so the launch fails with the reason).
  */
 declare function ensureHeadroom(params: {
     readonly paths: LayoutPaths;
     readonly launcherPid: number;
     readonly ports: EnsureHeadroomPorts;
 }): {
-    readonly port: number;
+    readonly socketPath: string;
 };
 
 /** The token-saving settings of the `headroom` config block, without its install and lifecycle fields (`source`, `idleShutdownMinutes`). */
 type HeadroomSettings = Pick<HeadroomGlobalConfig, "mode" | "targetRatio" | "ccr" | "rolloutChannel" | "interceptToolResults" | "readMaturation">;
 
+/** What an `lstat` (which never follows symlinks) reports about one path, narrowed to what authenticating the socket needs. */
+interface SocketPathStat {
+    readonly kind: "dir" | "socket" | "symlink" | "other";
+    /** The owning user id. */
+    readonly uid: number;
+    /** The permission bits, without the file type bits. */
+    readonly mode: number;
+}
+/** The platform facts and the one filesystem call the socket checks need, injected so every refusal is unit-testable without a real socket, directory or second user. */
+interface HeadroomSocketTrustPorts {
+    /** `process.platform` in the real implementation. */
+    readonly platform: string;
+    /** This process's user id. Only called on a platform with unix sockets, which all have POSIX user ids. */
+    readonly currentUid: () => number;
+    /** Stats one path without following symlinks, or returns undefined when nothing is there. */
+    readonly lstat: (target: string) => SocketPathStat | undefined;
+}
+
 /** Everything the supervisor needs to run the daemon, resolved from the global config and the filesystem before it starts. */
 interface HeadroomSupervisorConfig {
     /** The install spec as configured (`headroom.source`), already defaulted. */
@@ -1826,20 +1846,18 @@ interface SupervisorPorts {
      * Zombie-aware liveness, and for a daemon this supervisor spawned, exit-event-backed: the implementation keeps the spawned ChildProcess handle, consumes its exit event (which is also what reaps it), and reports the pid as not running from that moment. A bare signal-0 check is not enough, because a defunct process still answers it.
      */
     readonly isRunning: (pid: number) => boolean;
-    /** Returns a free loopback port. Async because the only reliable way to reserve one is to bind and release a socket. */
-    readonly freePort: () => Promise<number>;
-    /** Whether nothing is currently listening on one specific loopback port: the check that decides whether the sticky `lastPort` can be reused. The same bind-and-release technique `freePort` uses, applied to a number the caller already cares about. */
-    readonly isPortFree: (port: number) => Promise<boolean>;
+    /** The platform facts and owner-only checks the daemon's socket directory is prepared and verified with (see `prepareHeadroomSocket`). */
+    readonly socketTrust: HeadroomSocketTrustPorts;
     /**
-     * Starts `headroom proxy` bound to `port` with the given allowlist, returning its pid. Output goes to the daemon log. The implementation must keep the ChildProcess handle and attach an exit listener (detaching the process is fine; unref'ing a child you still need events from is not, since without the listener nothing reaps it and it lingers as a zombie).
+     * Starts `headroom proxy` serving on the unix socket `socketPath` (and on no TCP port) with the given allowlist, returning its pid. Output goes to the daemon log. The implementation must keep the ChildProcess handle and attach an exit listener (detaching the process is fine; unref'ing a child you still need events from is not, since without the listener nothing reaps it and it lingers as a zombie).
      */
-    readonly spawnHeadroom: (port: number, allowlist: readonly string[], settings: Readonly<HeadroomSettings>) => number;
+    readonly spawnHeadroom: (socketPath: string, allowlist: readonly string[], settings: Readonly<HeadroomSettings>) => number;
     /** Reads the headroom config block as it stands on disk now. The supervisor calls it every tick, so a changed `source` or setting is noticed while the daemon runs and applied by the same quiet-registry restart an allowlist change gets. */
     readonly readConfig: () => HeadroomSupervisorConfig;
     /** Stops a process the supervisor owns, escalating SIGTERM to SIGKILL on a bounded timeout (see `stopSupervisedProcess`). */
     readonly stopProcess: (pid: number) => void;
-    /** True once `GET /readyz` on the port succeeds. */
-    readonly ready: (port: number) => Promise<boolean>;
+    /** True once `GET /readyz` over the unix socket succeeds. */
+    readonly ready: (socketPath: string) => Promise<boolean>;
     /** Runs `uv tool install <spec>`, logging output to the daemon log. Returns ok=false with the error when `uv` is absent or the install fails. */
     readonly install: (spec: string) => {
         readonly ok: boolean;
@@ -2644,7 +2662,7 @@ interface RunDoctorParams {
     readonly run?: RunPort;
     /** `process.platform` in real use; the Keychain check only ever runs when this is `"darwin"`. */
     readonly platform: string;
-    /** The headroom daemon's state.json plus a zombie-aware liveness predicate for the pids it names (a defunct daemon holds no port but still answers signal 0). Omit the raw text when the daemon has never run; that is a pass, not a failure. */
+    /** The headroom daemon's state.json plus a zombie-aware liveness predicate for the pids it names (a defunct daemon serves nothing but still answers signal 0). Omit the raw text when the daemon has never run; that is a pass, not a failure. */
     readonly headroom: {
         readonly state: DoctorFileInput;
         readonly isRunning: (pid: number) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "7.14.0",
+  "version": "8.0.1",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",