@code-yeongyu/senpi 2026.10.24-2 → 2026.10.24-4

package/dist/modes/rpc/host-watchdog.js

@@ -16,7 +16,7 @@
 import { rmSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { Socket } from "node:net";
-import { envValue } from "../../core/brand.js";
+import { brandEnvNames, envValue } from "../../core/brand.js";
 import { recordHostCrash } from "./host-crash-record.js";
 import { HOST_DAEMON_DIR_ENV } from "./host-daemon-paths.js";
 import { HOST_INSTANCE_ID_ENV } from "./host-identity-env.js";
@@ -71,24 +71,49 @@ export function readHostWatchdogConfig(env = process.env) {
     };
 }
 /** Same configuration, resolved through the brand-aware env prefixes. */
-export function readHostWatchdogConfigFromBrandEnv() {
+export function readHostWatchdogConfigFromBrandEnv(env = process.env) {
     // The lifecycle supervisor intentionally uses the canonical SENPI_RPC_HOST_*
     // names when spawning a child. envValue() resolves branded aliases for normal
     // launches, but must not hide the canonical variables from the supervisor
     // handoff or the lifetime binding is silently disabled.
     return readHostWatchdogConfig({
-        [HOST_WATCH_FD_ENV]: process.env[HOST_WATCH_FD_ENV] ?? envValue("RPC_HOST_WATCH_FD"),
-        [HOST_WATCH_PPID_ENV]: process.env[HOST_WATCH_PPID_ENV] ?? envValue("RPC_HOST_WATCH_PPID"),
-        [HOST_WATCH_PSTART_ENV]: process.env[HOST_WATCH_PSTART_ENV] ?? envValue("RPC_HOST_WATCH_PSTART"),
-        [HOST_WATCH_PSTART_TICKS_ENV]: process.env[HOST_WATCH_PSTART_TICKS_ENV] ?? envValue("RPC_HOST_WATCH_PSTART_TICKS"),
-        [HOST_WATCH_LIFETIME_FIFO_ENV]: process.env[HOST_WATCH_LIFETIME_FIFO_ENV] ?? envValue("RPC_HOST_LIFETIME_FIFO"),
-        [HOST_SCRATCH_DIR_ENV]: process.env[HOST_SCRATCH_DIR_ENV] ?? envValue("RPC_HOST_SCRATCH_DIR"),
-        [HOST_PUBLIC_SOCKET_ENV]: process.env[HOST_PUBLIC_SOCKET_ENV] ?? envValue("RPC_HOST_PUBLIC_SOCKET"),
-        [HOST_CLEANUP_PATHS_ENV]: process.env[HOST_CLEANUP_PATHS_ENV] ?? envValue("RPC_HOST_CLEANUP_PATHS"),
-        [HOST_DAEMON_DIR_ENV]: process.env[HOST_DAEMON_DIR_ENV],
-        [HOST_INSTANCE_ID_ENV]: process.env[HOST_INSTANCE_ID_ENV],
+        [HOST_WATCH_FD_ENV]: env[HOST_WATCH_FD_ENV] ?? envValue("RPC_HOST_WATCH_FD", env),
+        [HOST_WATCH_PPID_ENV]: env[HOST_WATCH_PPID_ENV] ?? envValue("RPC_HOST_WATCH_PPID", env),
+        [HOST_WATCH_PSTART_ENV]: env[HOST_WATCH_PSTART_ENV] ?? envValue("RPC_HOST_WATCH_PSTART", env),
+        [HOST_WATCH_PSTART_TICKS_ENV]: env[HOST_WATCH_PSTART_TICKS_ENV] ?? envValue("RPC_HOST_WATCH_PSTART_TICKS", env),
+        [HOST_WATCH_LIFETIME_FIFO_ENV]: env[HOST_WATCH_LIFETIME_FIFO_ENV] ?? envValue("RPC_HOST_LIFETIME_FIFO", env),
+        [HOST_SCRATCH_DIR_ENV]: env[HOST_SCRATCH_DIR_ENV] ?? envValue("RPC_HOST_SCRATCH_DIR", env),
+        [HOST_PUBLIC_SOCKET_ENV]: env[HOST_PUBLIC_SOCKET_ENV] ?? envValue("RPC_HOST_PUBLIC_SOCKET", env),
+        [HOST_CLEANUP_PATHS_ENV]: env[HOST_CLEANUP_PATHS_ENV] ?? envValue("RPC_HOST_CLEANUP_PATHS", env),
+        [HOST_DAEMON_DIR_ENV]: env[HOST_DAEMON_DIR_ENV],
+        [HOST_INSTANCE_ID_ENV]: env[HOST_INSTANCE_ID_ENV],
     });
 }
+const WATCH_ENV_SUFFIXES = [
+    "RPC_HOST_WATCH_FD",
+    "RPC_HOST_WATCH_PPID",
+    "RPC_HOST_WATCH_PSTART",
+    "RPC_HOST_WATCH_PSTART_TICKS",
+    "RPC_HOST_LIFETIME_FIFO",
+    "RPC_HOST_SCRATCH_DIR",
+    "RPC_HOST_PUBLIC_SOCKET",
+    "RPC_HOST_CLEANUP_PATHS",
+];
+/**
+ * Reads the supervisor binding once and removes it from `env` (senpi#3815 review L4), so no tool, shell or nested host
+ * this host starts inherits a binding to a supervisor that is not its own. The generation identity (instance id,
+ * daemon dir) stays: sessions use it to name the host they run in.
+ */
+export function consumeHostWatchdogEnv(env = process.env) {
+    const config = readHostWatchdogConfigFromBrandEnv(env);
+    scrubHostWatchdogEnv(env);
+    return config;
+}
+export function scrubHostWatchdogEnv(env = process.env) {
+    for (const suffix of WATCH_ENV_SUFFIXES)
+        for (const name of [`SENPI_${suffix}`, ...brandEnvNames(suffix)])
+            delete env[name];
+}
 /**
  * Arms the configured watchdog. `onSupervisorGone` receives the reason and is
  * expected to perform the host's normal clean shutdown; the scratch directory

package/dist/modes/rpc/internal-channel.js

@@ -1,14 +1,14 @@
-import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { createInternalRecordStream } from "./internal-record-stream.js";
 import { MAX_RPC_LINE_CHARACTERS } from "./jsonl.js";
-const HEX = /^[0-9a-f]{64}$/;
+import { RPC_AUTH_HEX, rpcAuthProof, rpcProofMatches } from "./rpc-auth-proof.js";
+const INTERNAL_LAUNCH_ID = "internal";
+/** One HMAC and constant-time comparison for both endpoints (wire contract v1.1); the hop's launch id is "internal". */
 function proof(key, label, first, second) {
-    return createHmac("sha256", key).update(`${label}\ninternal\n${first}\n${second}`).digest("hex");
+    return rpcAuthProof(key, label, INTERNAL_LAUNCH_ID, first, second);
 }
 function matches(actual, expected) {
-    return (typeof actual === "string" &&
-        HEX.test(actual) &&
-        timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex")));
+    return rpcProofMatches(expected, actual);
 }
 function object(value) {
     if (!isObject(value))
@@ -19,7 +19,7 @@ function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function nonce(value) {
-    if (typeof value !== "string" || !HEX.test(value))
+    if (typeof value !== "string" || !RPC_AUTH_HEX.test(value))
         throw new Error("auth_failed");
     return value;
 }
@@ -117,15 +117,15 @@ export function connectInternalConnection(socket, key, options = {}) {
         const serverNonce = nonce(auth.server_nonce);
         if (response.id !== "internal-protocol" ||
             response.success !== true ||
-            auth.launch_id !== "internal" ||
-            !matches(auth.server_proof, proof(key, "senpi-rpc-server", clientNonce, serverNonce)))
+            auth.launch_id !== INTERNAL_LAUNCH_ID ||
+            !matches(auth.server_proof, proof(key, "server", clientNonce, serverNonce)))
             throw new Error("host_identity_unproven");
         const [result] = await Promise.all([
             read(),
             send({
                 id: "internal-auth",
                 type: "authenticate",
-                client_proof: proof(key, "senpi-rpc-client", serverNonce, clientNonce),
+                client_proof: proof(key, "client", serverNonce, clientNonce),
             }),
         ]);
         if (result.id !== "internal-auth" || result.command !== "authenticate" || result.success !== true)
@@ -150,7 +150,7 @@ export function acceptInternalConnection(socket, key, protocol = {}) {
         };
         const first = await read();
         const offered = isObject(first.auth) ? first.auth.client_nonce : undefined;
-        if (first.type !== "get_protocol_info" || typeof offered !== "string" || !HEX.test(offered))
+        if (first.type !== "get_protocol_info" || typeof offered !== "string" || !RPC_AUTH_HEX.test(offered))
             return refuse(first);
         const clientNonce = offered;
         const serverNonce = randomBytes(32).toString("hex");
@@ -165,16 +165,16 @@ export function acceptInternalConnection(socket, key, protocol = {}) {
                     ...protocol,
                     capabilities: [...(Array.isArray(protocol.capabilities) ? protocol.capabilities : []), "socket_auth"],
                     auth: {
-                        launch_id: "internal",
+                        launch_id: INTERNAL_LAUNCH_ID,
                         server_nonce: serverNonce,
-                        server_proof: proof(key, "senpi-rpc-server", clientNonce, serverNonce),
+                        server_proof: proof(key, "server", clientNonce, serverNonce),
                     },
                 },
             }),
         ]);
         if (frame.type !== "authenticate")
             return refuse(frame);
-        const valid = matches(frame.client_proof, proof(key, "senpi-rpc-client", serverNonce, clientNonce));
+        const valid = matches(frame.client_proof, proof(key, "client", serverNonce, clientNonce));
         await send({
             id: frame.id,
             type: "response",

package/dist/modes/rpc/multi-session-host.js

@@ -1,4 +1,3 @@
-import { chmod } from "node:fs/promises";
 import { createServer } from "node:net";
 import { basename, dirname, join } from "node:path";
 import { envValue } from "../../core/brand.js";
@@ -16,14 +15,14 @@ import { reopenHandoverParkedSessions } from "./host-handover-reopen.js";
 import { performIdleHandover } from "./host-handover-wire.js";
 import { EXPECTED_RUNTIME_BUILD_ID_ENV } from "./host-idle-handover.js";
 import { RPC_CLOSE_GRACE_MS_ENV, resolveHostIdlePolicy } from "./host-idle-policy.js";
-import { internalHostTransport } from "./host-internal-transport.js";
+import { hostWatchdogBinding, internalHostTransport } from "./host-internal-transport.js";
 import { parseIdleExitMs } from "./host-lifecycle.js";
 import { prepareSocketPath } from "./host-lifecycle-proxy.js";
 import { createZeroSessionTrim, startHostObservers } from "./host-observers.js";
 import { runAsHostGenerationProcess } from "./host-process-role.js";
 import { createEndpointReservations } from "./host-reservations.js";
 import { hostChildDrainRequestFile, watchDrainRequest } from "./host-stop-intent.js";
-import { armHostWatchdog, readHostWatchdogConfigFromBrandEnv } from "./host-watchdog.js";
+import { armHostWatchdog } from "./host-watchdog.js";
 import { attachJsonlLineReader, MAX_RPC_LINE_CHARACTERS } from "./jsonl.js";
 import { hostGeneration, hostInstanceId, protocolIdentity } from "./protocol-identity.js";
 import { rpcCommandShapeError } from "./rpc-input-validation.js";
@@ -32,9 +31,10 @@ import { SessionCommandRouter } from "./session-command-router.js";
 import { SessionEventWriter } from "./session-event-writer.js";
 import { canonicalSessionPath } from "./session-path-key.js";
 import { RpcSessionRegistry, RpcSessionRegistryError } from "./session-registry.js";
-import { PUBLIC_SOCKET_IDENTITY_FILE, readSocketIdentityFile, shieldSocketDuringClose, socketEntryReplaced, statSocketIdentity, unlinkOwnedSocket, waitForSocketIdentityFile, } from "./socket-ownership.js";
+import { PUBLIC_SOCKET_IDENTITY_FILE, readSocketIdentityFile, shieldSocketDuringClose, socketEntryReplaced, unlinkOwnedSocket, waitForSocketIdentityFile, } from "./socket-ownership.js";
+import { formatSocketAddress, listen, resolveSocketPath } from "./host-socket-bind.js";
 import { socketSink } from "./socket-sink.js";
-import { ensureSocketSecret, resolveSocketTransportAddress, SOCKET_SECRET_FILE_ENV, socketSecretPath, } from "./socket-transport.js";
+import { ensureSocketSecret, SOCKET_SECRET_FILE_ENV, socketSecretPath } from "./socket-transport.js";
 import { WorkerSessionRegistry } from "./worker-session-registry.js";
 export { DEFAULT_HOST_EMPTY_EXIT_MS, DEFAULT_SESSION_IDLE_EVICTION_MS, RPC_HOST_EMPTY_EXIT_MS_ENV, RPC_SESSION_IDLE_EVICTION_MS_ENV, resolveHostIdlePolicy, } from "./host-idle-policy.js";
 /** Win32 named-pipe close can leave libuv's server callback pending after handles are destroyed. */
@@ -239,7 +239,7 @@ async function runSocketHost(options, socketPath) {
         ...(canHandOver && {
             endpoint: {
                 agentDir: options.agentDir,
-                socket: readHostWatchdogConfigFromBrandEnv()?.publicSocket ?? socketPath,
+                socket: hostWatchdogBinding()?.publicSocket ?? socketPath,
             },
             handover: {
                 identity: () => ({
@@ -249,7 +249,7 @@ async function runSocketHost(options, socketPath) {
                 }),
                 perform: (request) => performIdleHandover({
                     request,
-                    socket: readHostWatchdogConfigFromBrandEnv()?.publicSocket ?? socketPath,
+                    socket: hostWatchdogBinding()?.publicSocket ?? socketPath,
                     agentDir: options.agentDir,
                 }),
                 log: hostLog,
@@ -273,7 +273,12 @@ async function runSocketHost(options, socketPath) {
     const secret = process.platform === "win32"
         ? await ensureSocketSecret(process.env[SOCKET_SECRET_FILE_ENV] ?? socketSecretPath(socketPath))
         : undefined;
-    const { watchdogConfig, admit } = internalHostTransport(readHostWatchdogConfigFromBrandEnv(), secret);
+    const transport = internalHostTransport(hostWatchdogBinding(), secret, {
+        agentDir: options.agentDir,
+        socket: socketPath,
+        log: hostLog,
+    });
+    const { watchdogConfig, admit } = transport;
     // This host's OWN copy of the crash-path cleanup list. A drain empties it: once a successor
     // generation is registered, the daemon state files under those paths describe the successor,
     // and a crash of this (already replaced) host must not take them with it.
@@ -393,6 +398,7 @@ async function runSocketHost(options, socketPath) {
                 await watchdogCleanup;
         }
         finally {
+            await transport.dispose();
             // Explicitly terminate after every shutdown trigger. Windows named-pipe
             // handles are not fully controllable from JS, and an unresolved cleanup
             // must not leave this daemon or its public endpoint alive.
@@ -464,6 +470,8 @@ async function runSocketHost(options, socketPath) {
         setImmediate(killTrackedDetachedChildren);
     });
     boundIdentity = await listen(server, socketPath, secret);
+    // A key record that cannot be published safely ends this host: held connections are refused, never served keyless.
+    await transport.publish(() => shutdown(1));
     if (supervisorPublicOwnerFile) {
         // The supervisor publishes its public-socket token after this internal
         // listener is ready, so a short bounded wait keeps the lifecycles in step
@@ -513,7 +521,7 @@ function errorMessage(cause) {
  * (abstract sockets, a supervised win32 host, whose supervisor publishes none).
  */
 function hostSessionContext(socketPath) {
-    const supervised = readHostWatchdogConfigFromBrandEnv();
+    const supervised = hostWatchdogBinding();
     const endpoint = supervised === undefined ? socketPath : supervised.publicSocket;
     if (endpoint === undefined || endpoint.startsWith("\0"))
         return { host_instance: hostInstanceId() };
@@ -532,47 +540,11 @@ function listenSocketPath(options) {
  * socket or every generation hashes a different directory (senpi#3282). Bare hosts bind the path.
  */
 function publicEndpointSocket(options) {
-    const supervised = readHostWatchdogConfigFromBrandEnv();
+    const supervised = hostWatchdogBinding();
     if (supervised !== undefined)
         return supervised.publicSocket;
     return listenSocketPath(options);
 }
-function resolveSocketPath(value, agentDir) {
-    if (value === "unix://")
-        return join(agentDir, "rpc", "rpc.sock");
-    if (value.startsWith("unix://")) {
-        const path = value.slice("unix://".length);
-        if (path.length === 0)
-            return join(agentDir, "rpc", "rpc.sock");
-        if (path.startsWith("@") && process.platform === "linux")
-            return `\0${path.slice(1)}`;
-        return path;
-    }
-    return value;
-}
-function formatSocketAddress(socketPath) {
-    return socketPath.startsWith("\0") ? `unix://@${socketPath.slice(1)}` : `unix://${socketPath}`;
-}
-function listen(server, socketPath, secret) {
-    return new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(resolveSocketTransportAddress(socketPath, process.platform, secret), async () => {
-            server.off("error", reject);
-            try {
-                if (process.platform !== "win32" && !socketPath.startsWith("\0")) {
-                    await chmod(socketPath, 0o600);
-                    // Record which filesystem entry THIS listener created; shutdown
-                    // removes the path only while this identity still matches.
-                    return resolve(await statSocketIdentity(socketPath));
-                }
-                resolve(undefined);
-            }
-            catch (cause) {
-                reject(cause);
-            }
-        });
-    });
-}
 function closeServer(server) {
     return new Promise((resolve, reject) => {
         server.close((cause) => (cause ? reject(cause) : resolve()));

package/dist/modes/rpc/rpc-auth-client.d.ts

@@ -0,0 +1,13 @@
+import { type Socket } from "node:net";
+export interface RpcKeyOptions {
+    /** Credential lookup only; never selects the session's configuration profile. */
+    readonly keyRoot?: string;
+}
+export declare function withRpcKeyRoot<T>(root: string, operation: () => T): T;
+export declare function rpcKeyRoot(options?: RpcKeyOptions, defaultRoot?: string): string;
+/** A fresh connection per attempt, including the single refresh after a host's auth_failed. */
+export declare function connectAuthenticatedRpcSocket(path: string, first?: Readonly<Record<string, unknown>>, options?: RpcKeyOptions, timeoutMs?: number): Promise<{
+    readonly socket: Socket;
+    readonly protocol: Readonly<Record<string, unknown>>;
+}>;
+//# sourceMappingURL=rpc-auth-client.d.ts.map

package/dist/modes/rpc/rpc-auth-client.js

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { createConnection } from "node:net";
+import { getAgentDir } from "../../config.js";
+import { ORIGIN_HOST_INSTANCE_FIELD, originHostInstance } from "./host-observe-request.js";
+import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
+import { authRecord, RPC_AUTH_HEX, RPC_LAUNCH_ID, RpcEndpointAuthError, rpcAuthProof, rpcProofMatches, } from "./rpc-auth-proof.js";
+import { readRpcKeyRecord } from "./rpc-public-key.js";
+import { SOCKET_HANDSHAKE_TIMEOUT_MS } from "./socket-transport.js";
+const keyRoots = new AsyncLocalStorage();
+export function withRpcKeyRoot(root, operation) {
+    return keyRoots.run(root, operation);
+}
+export function rpcKeyRoot(options = {}, defaultRoot) {
+    return options.keyRoot ?? keyRoots.getStore() ?? process.env.SENPI_RPC_KEY_ROOT ?? defaultRoot ?? getAgentDir();
+}
+/** A fresh connection per attempt, including the single refresh after a host's auth_failed. */
+export async function connectAuthenticatedRpcSocket(path, first = {
+    type: "get_protocol_info",
+    id: "rpc-auth-protocol",
+    observe: true,
+    [ORIGIN_HOST_INSTANCE_FIELD]: originHostInstance(),
+}, options = {}, timeoutMs = SOCKET_HANDSHAKE_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0;; attempt++) {
+        const socket = createConnection(path);
+        // A failed attempt is destroyed below; an error its queued write reports later (Bun does, for a missing
+        // socket) must not surface as an uncaught event. The listener goes once the socket is handed over.
+        let earlyError;
+        const ignoreLateError = (error) => {
+            earlyError ??= error;
+        };
+        socket.on("error", ignoreLateError);
+        let connected = false;
+        socket.once("connect", () => {
+            connected = true;
+        });
+        // Install error/close handlers before any write, including connect failures.
+        try {
+            const protocol = await authenticate(socket, path, first, rpcKeyRoot(options), Math.max(1, deadline - Date.now()));
+            socket.off("error", ignoreLateError);
+            return { socket, protocol };
+        }
+        catch (cause) {
+            socket.destroy();
+            if (attempt === 0 && cause instanceof RpcEndpointAuthError && cause.code === "auth_failed")
+                continue;
+            // The socket's own failure (ENOENT, ECONNREFUSED) is how callers tell an unreachable endpoint apart.
+            const failure = !(cause instanceof RpcEndpointAuthError) && earlyError !== undefined ? earlyError : cause;
+            if (failure instanceof Error)
+                Object.assign(failure, { rpcSocketConnected: connected });
+            throw failure;
+        }
+    }
+}
+async function authenticate(socket, path, first, root, timeoutMs) {
+    let pending;
+    const reject = (error) => pending?.reject(error);
+    // The socket's own error (ENOENT, ECONNREFUSED) is what callers classify an unreachable endpoint by; a close
+    // that a runtime reports before it is answered a turn later, so the error wins when there is one.
+    let socketError;
+    const onClose = () => setImmediate(() => reject(socketError ?? new Error(`RPC socket closed during authentication: ${path}`)));
+    const onError = (error) => {
+        socketError ??= error;
+        reject(error);
+    };
+    socket.on("error", onError);
+    socket.on("close", onClose);
+    const detach = attachJsonlLineReader(socket, (line) => {
+        let response;
+        try {
+            response = authRecord(JSON.parse(line));
+        }
+        catch {
+            return;
+        }
+        // Matched by id alone, as the plain probe always did: a host's broadcast records never carry a request id.
+        if (response === undefined || pending === undefined || response.id !== pending.id)
+            return;
+        if (response.success === true)
+            pending?.resolve(response);
+        else {
+            const code = response.errorCode;
+            reject(code === "auth_failed" || code === "auth_required"
+                ? new RpcEndpointAuthError(code, `${path}; set SENPI_RPC_KEY_ROOT to the host's agent dir (${root})`)
+                : new Error(`RPC authentication probe refused on ${path}: ${String(response.error)}`));
+        }
+    }, { maxLineLength: 1024 * 1024, onOversizedLine: () => socket.destroy() });
+    const exchange = (request) => new Promise((resolve, reject) => {
+        if (socket.destroyed) {
+            // Bun destroys a socket whose connect failed before it emits the error; wait a turn for it.
+            setImmediate(() => reject(socketError ?? new Error(`RPC socket closed during authentication: ${path}`)));
+            return;
+        }
+        pending = { id: request.id, resolve, reject };
+        // net.Socket queues this write until connect, preserving the caller's own first frame.
+        socket.write(serializeJsonLine(request));
+    });
+    const timer = setTimeout(() => {
+        reject(new Error(`RPC authentication timed out on ${path}`));
+        socket.destroy();
+    }, timeoutMs);
+    try {
+        const nonce = randomBytes(32).toString("hex");
+        const response = await exchange({ ...first, auth: { client_nonce: nonce } });
+        const data = authRecord(response.data);
+        if (data?.auth === undefined)
+            return response;
+        const auth = authRecord(data.auth);
+        if (typeof auth?.launch_id !== "string" ||
+            !RPC_LAUNCH_ID.test(auth.launch_id) ||
+            typeof auth.server_nonce !== "string" ||
+            !RPC_AUTH_HEX.test(auth.server_nonce))
+            throw new RpcEndpointAuthError("host_identity_unproven", path);
+        const record = await readRpcKeyRecord(root, auth.launch_id);
+        if (socket.destroyed)
+            throw new Error(`RPC authentication timed out on ${path}`);
+        if (record === undefined) {
+            process.stderr.write(`senpi rpc client: no key record for launch ${auth.launch_id} under ${root}; continuing unauthenticated (refused from the next release; set SENPI_RPC_KEY_ROOT to the host's agent dir)\n`);
+            return response;
+        }
+        // readRpcKeyRecord validates this field at the file boundary.
+        if (typeof record.key !== "string")
+            throw new RpcEndpointAuthError("unsafe_key_record", root);
+        const key = Buffer.from(record.key, "hex");
+        if (!rpcProofMatches(rpcAuthProof(key, "server", auth.launch_id, nonce, auth.server_nonce), auth.server_proof))
+            throw new RpcEndpointAuthError("host_identity_unproven", path);
+        await exchange({
+            id: "rpc-authenticate",
+            type: "authenticate",
+            client_proof: rpcAuthProof(key, "client", auth.launch_id, auth.server_nonce, nonce),
+        });
+        return response;
+    }
+    finally {
+        clearTimeout(timer);
+        detach();
+        socket.off("error", onError);
+        socket.off("close", onClose);
+    }
+}
+//# sourceMappingURL=rpc-auth-client.js.map

package/dist/modes/rpc/rpc-auth-proof.d.ts

@@ -0,0 +1,12 @@
+export declare const RPC_AUTH_CAPABILITY = "socket_auth";
+export declare const RPC_AUTH_HEX: RegExp;
+export declare const RPC_LAUNCH_ID: RegExp;
+export declare function rpcAuthProof(key: Uint8Array, label: "server" | "client", ...parts: readonly string[]): string;
+export declare function rpcProofMatches(expected: string, received: unknown): boolean;
+export type RpcEndpointAuthErrorCode = "unsafe_key_record" | "host_identity_unproven" | "key_publication_failed" | "auth_required" | "auth_failed";
+export declare class RpcEndpointAuthError extends Error {
+    readonly code: RpcEndpointAuthErrorCode;
+    constructor(code: RpcEndpointAuthErrorCode, detail: string, options?: ErrorOptions);
+}
+export declare function authRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
+//# sourceMappingURL=rpc-auth-proof.d.ts.map

package/dist/modes/rpc/rpc-auth-proof.js

@@ -0,0 +1,27 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const RPC_AUTH_CAPABILITY = "socket_auth";
+export const RPC_AUTH_HEX = /^[a-f0-9]{64}$/;
+export const RPC_LAUNCH_ID = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+export function rpcAuthProof(key, label, ...parts) {
+    return createHmac("sha256", key)
+        .update([`senpi-rpc-${label}`, ...parts].join("\n"), "utf8")
+        .digest("hex");
+}
+export function rpcProofMatches(expected, received) {
+    return (typeof received === "string" &&
+        RPC_AUTH_HEX.test(received) &&
+        timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(received, "hex")));
+}
+export class RpcEndpointAuthError extends Error {
+    constructor(code, detail, options) {
+        super(`${code}: ${detail}`, options);
+        this.code = code;
+        this.name = "RpcEndpointAuthError";
+    }
+}
+export function authRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+//# sourceMappingURL=rpc-auth-proof.js.map

package/dist/modes/rpc/rpc-client-socket.d.ts

@@ -0,0 +1,5 @@
+import { type Socket } from "node:net";
+import { type RpcKeyOptions } from "./rpc-auth-client.ts";
+/** Public POSIX authentication and the unchanged TUI/Windows raw-secret connection path. */
+export declare function connectRpcClientSocket(path: string, options: RpcKeyOptions): Promise<Socket>;
+//# sourceMappingURL=rpc-client-socket.d.ts.map

package/dist/modes/rpc/rpc-client-socket.js

@@ -0,0 +1,30 @@
+import { createConnection } from "node:net";
+import { connectAuthenticatedRpcSocket } from "./rpc-auth-client.js";
+import { readSocketSecret, resolveSocketTransportAddress, sendSocketHandshake, socketSecretPath, } from "./socket-transport.js";
+import { socketNeedsHandshake } from "./tui-socket.js";
+/** Public POSIX authentication and the unchanged TUI/Windows raw-secret connection path. */
+export async function connectRpcClientSocket(path, options) {
+    if (!socketNeedsHandshake(path))
+        return (await connectAuthenticatedRpcSocket(path, undefined, options)).socket;
+    const secret = await readSocketSecret(socketSecretPath(path));
+    const socket = createConnection(resolveSocketTransportAddress(path, process.platform, secret));
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            socket.off("connect", onConnect);
+            socket.off("error", onError);
+        };
+        const onConnect = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        socket.once("connect", onConnect);
+        socket.once("error", onError);
+    });
+    sendSocketHandshake(socket, secret);
+    return socket;
+}
+//# sourceMappingURL=rpc-client-socket.js.map

package/dist/modes/rpc/rpc-client.d.ts

@@ -27,6 +27,8 @@ import type { EditAssistantMessageResult, EditUserMessageResult, RpcAccountFailo
 export interface RpcClientOptions {
     /** Connect to an existing multi-session Unix socket instead of spawning a child. */
     socketPath?: string;
+    /** Endpoint credential lookup only; does not change the client's configuration profile. */
+    keyRoot?: string;
     /** Called once when an established transport disconnects. */
     onDisconnect?: (error: RpcTransportGoneError) => void;
     /** Path to the CLI entry point (default: searches for dist/cli.js) */

package/dist/modes/rpc/rpc-client.js

@@ -4,7 +4,6 @@
  * Spawns the agent in RPC mode and provides a typed API for all operations.
  */
 import { spawn } from "node:child_process";
-import { createConnection } from "node:net";
 import { clientMessageIdentity } from "../../core/client-message-identity.js";
 import { MissingSessionCwdError } from "../../core/session-cwd.js";
 import { unknownCommandErrorFromWire } from "../../core/unknown-command.js";
@@ -21,10 +20,9 @@ export class RpcCommandError extends Error {
     }
 }
 import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
+import { connectRpcClientSocket } from "./rpc-client-socket.js";
 import { armRequestDeadline, OPEN_AFTER_QUEUED_DEADLINE_MS, openStalledMessage, PROMPT_ACK_MAX_WAIT_MS, PROMPT_AFTER_QUEUED_DEADLINE_MS, PROMPT_COMPACTION_DEADLINE_MS, promptStalledMessage, REQUEST_DEADLINE_MS, RpcRequestTimeoutError, requestDeadlineMs, } from "./rpc-request-deadline.js";
 import { RPC_ERROR_SESSION_NOT_ATTACHED, RPC_ERROR_UNKNOWN_COMMAND } from "./rpc-types.js";
-import { readSocketSecret, resolveSocketTransportAddress, sendSocketHandshake, socketSecretPath, } from "./socket-transport.js";
-import { socketNeedsHandshake } from "./tui-socket.js";
 function isProviderAccountEvent(event) {
     return event.type === "auth_accounts_changed" || event.type === "account_failover";
 }
@@ -244,28 +242,8 @@ export class RpcClient {
         this.pendingRequests.clear();
     }
     async startSocket(path) {
-        const secret = socketNeedsHandshake(path) ? await readSocketSecret(socketSecretPath(path)) : undefined;
-        const socket = createConnection(resolveSocketTransportAddress(path, process.platform, secret));
+        const socket = await connectRpcClientSocket(path, this.options);
         this.socket = socket;
-        await new Promise((resolve, reject) => {
-            const onConnect = () => {
-                cleanup();
-                resolve();
-            };
-            const onError = (error) => {
-                cleanup();
-                this.socket = null;
-                reject(error);
-            };
-            const cleanup = () => {
-                socket.off("connect", onConnect);
-                socket.off("error", onError);
-            };
-            socket.once("connect", onConnect);
-            socket.once("error", onError);
-        });
-        if (secret)
-            sendSocketHandshake(socket, secret);
         this.stopReadingStdout = attachJsonlLineReader(socket, (line) => this.handleLine(line));
         socket.once("close", () => {
             if (this.socket !== socket)

package/dist/modes/rpc/rpc-host-command-types.d.ts

@@ -14,6 +14,10 @@ export type RpcCommand = RpcAttachmentCommand | (RpcSessionCommand & {
 }) | {
     id?: string;
     type: "get_protocol_info";
+    /** Public POSIX endpoint challenge (wire contract v1.1); ignored by hosts that predate authentication. */
+    auth?: {
+        readonly client_nonce: string;
+    };
     /** An observing read: this connection never counts as host activity (docs/rpc.md, idle exit). */
     observe?: boolean;
 } | {

package/dist/modes/rpc/rpc-protocol-info-types.d.ts

@@ -34,6 +34,12 @@ export interface RpcProtocolIdentity {
     readonly agentDir: string;
 }
 export interface RpcProtocolInfo extends RpcProtocolIdentity {
+    /** Present only on a public POSIX endpoint's answer to a challenge (wire contract v1.1). */
+    readonly auth?: {
+        readonly launch_id: string;
+        readonly server_nonce: string;
+        readonly server_proof: string;
+    };
     /** Supervised socket hosts expose admission state independently of child responsiveness. */
     readonly lifecycle?: "ready" | "stopping";
     readonly protocolVersion: 1;

package/dist/modes/rpc/rpc-public-auth.d.ts

@@ -0,0 +1,41 @@
+import type { Socket } from "node:net";
+import { Duplex, PassThrough } from "node:stream";
+import type { RpcPublicEndpoint } from "./rpc-public-key.ts";
+/** Filters public input before it can reach either the proxy or the bare host's router. */
+export declare class PublicRpcConnection {
+    readonly input: PassThrough;
+    private readonly raw;
+    private readonly timer;
+    private bytes;
+    private active;
+    private failed;
+    private first;
+    private challenge;
+    private protocolPending;
+    /**
+     * The admitted connection as one duplex for a router that reads and writes a single stream: it reads only
+     * frames this filter released and writes through `response()`, so the challenge answer gains its proof.
+     */
+    get stream(): Duplex;
+    private view;
+    private readonly socket;
+    private readonly endpoint;
+    /** Enforcement: refuse an unauthenticated client. Off by default for one release of logged grace. */
+    private readonly requireToken;
+    constructor(socket: Socket, endpoint: RpcPublicEndpoint, requireToken?: boolean);
+    private duplex;
+    private line;
+    private forward;
+    private grace;
+    /** Every pre-auth drop says why on stderr, by reason code only: never a frame, a nonce or key material. */
+    private logDrop;
+    private drop;
+    private refuse;
+    /**
+     * Writer/proxy batches contain whole JSONL records; ordinary authenticated bytes stay untouched. Before
+     * admission only the challenge answer leaves an enforcing host; a grace host keeps delivering records (the
+     * lifecycle broadcasts a passive legacy observer relies on).
+     */
+    response(chunk: string): string;
+}
+//# sourceMappingURL=rpc-public-auth.d.ts.map