@code-yeongyu/senpi 2026.10.18 → 2026.10.19

package/dist/modes/rpc/host-ensure-liveness.js

@@ -8,7 +8,7 @@ import { HostEnsureRefusedError } from "./host-decision.js";
 import { probeSocketReachable } from "./host-probe.js";
 import { hostChildAlive, hostLoopStalled, stallRefusalWindowMs } from "./host-stalled-evidence.js";
 import { loopLagErrorMs } from "./loop-lag-threshold.js";
-import { statSocketIdentity } from "./socket-ownership.js";
+import { socketEntryListenerState, statSocketIdentity } from "./socket-ownership.js";
 /**
  * IS-5: a generation nothing can reach whose loop is measurably stalled is still serving its sessions, so
  * it is neither stopped nor stranded beside a new generation: no signal, no successor, registration intact.
@@ -47,4 +47,21 @@ export async function publicEndpointAccepts(socket) {
         return true;
     return probeSocketReachable(socket, FOREIGN_ENDPOINT_PROBE_TIMEOUT_MS);
 }
+/**
+ * Whether something stands behind a public path that no registration names: the gate before an
+ * ensure would start a host there. Unlike `publicEndpointAccepts` it also counts a listener that
+ * refuses only because its backlog is full (`socketEntryListenerState`), because a start there
+ * could only lose the bind; the registered paths keep `publicEndpointAccepts`, whose "not
+ * accepting" leads to the stall check (IS-5).
+ */
+export async function unregisteredEndpointHeld(socket) {
+    if (process.platform === "win32" || socket.startsWith("\0"))
+        return false;
+    const entry = await statSocketIdentity(socket).then((identity) => (identity === undefined ? "absent" : "present"), () => "unknown");
+    if (entry === "absent")
+        return false;
+    if (entry === "unknown")
+        return true;
+    return (await socketEntryListenerState(socket)).verdict === "live";
+}
 //# sourceMappingURL=host-ensure-liveness.js.map

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

@@ -26,6 +26,8 @@ export interface EnsureHostOptions {
     readonly stoppingTimeoutMs?: number;
     readonly _test?: {
         readonly readinessTimeoutMs?: number;
+        /** How long the existing-host probe waits for get_protocol_info; tests shorten it. */
+        readonly existingHostProbeTimeoutMs?: number;
         readonly stopTimeoutMs?: number;
         readonly spawn?: {
             readonly command: string;

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

@@ -7,7 +7,7 @@ import { clearHostRegistration, readHostRegistration, writtenByThisProcess, } fr
 import { claimHostOwner } from "./host-daemon-state.js";
 import { decideHostAction, HostEnsureRefusedError } from "./host-decision.js";
 import { ensureClient } from "./host-ensure-client.js";
-import { publicEndpointAccepts, refuseIfStalled } from "./host-ensure-liveness.js";
+import { publicEndpointAccepts, refuseIfStalled, unregisteredEndpointHeld } from "./host-ensure-liveness.js";
 import { hostEnsureLockOptions, hostEnsureLockTarget } from "./host-ensure-lock.js";
 import { appendStderr, DEFAULT_READINESS_TIMEOUT_MS, DEFAULT_STOP_TIMEOUT_MS, startHost } from "./host-ensure-start.js";
 import { delay, ensureSender, matchesPidFileOrUnknown, resolvePidFileOwnership, STOP_WAIT_BUDGET_MS, stopManagedHost, } from "./host-ensure-stop.js";
@@ -82,7 +82,7 @@ async function ensureHostLocked(paths, socket, options, stopDeadline = Date.now(
         (await hostChildAlive(generationPaths(paths, registered.instanceId))))
         throw new HostEnsureRefusedError(socket, "host_stalled", undefined);
     // A reusable host is held from the connection that proved it compatible, never re-probed later.
-    const held = await holdProtocolInfo(socket, EXISTING_HOST_PROBE_TIMEOUT_MS);
+    const held = await holdProtocolInfo(socket, testOptions?.existingHostProbeTimeoutMs ?? EXISTING_HOST_PROBE_TIMEOUT_MS);
     const protocol = held?.info;
     if (protocol?.lifecycle === "stopping") {
         held?.hold.release();
@@ -184,6 +184,12 @@ async function ensureHostLocked(paths, socket, options, stopDeadline = Date.now(
         throw new HostEnsureRefusedError(socket, "legacy_host", protocol, legacyRefusal);
     if (stranded !== undefined)
         return startHost(paths, socket, options, stranded.generation + 1);
+    // Something no registration names still ACCEPTS at the public path and did not answer the probe.
+    // A start can only lose the bind ("address already in use") and exit without a reason, and the
+    // holder is not ours to remove (I1): refuse with the reason instead. A stale entry nobody listens
+    // behind reads as free here, so the start below still replaces it.
+    if (await unregisteredEndpointHeld(socket))
+        throw new HostEnsureRefusedError(socket, "endpoint_occupied", protocol, "no host registration names this socket and its listener did not answer get_protocol_info");
     if (registeredHere)
         await clearHostRegistration(paths);
     return startHost(paths, socket, options);

package/dist/modes/rpc/host-lifecycle-proxy.d.ts

@@ -1,7 +1,7 @@
 import { type Server } from "node:net";
 import type { HostAdmission } from "./host-admission.ts";
 import type { ClientOccupancy } from "./host-client-occupancy.ts";
-import { type SocketFileIdentity } from "./socket-ownership.ts";
+import { type ListenerState, type SocketFileIdentity } from "./socket-ownership.ts";
 export interface PublicProxyOptions {
     readonly internalSocket: string;
     readonly internalSecret?: Buffer;
@@ -32,7 +32,14 @@ export declare function adoptPublicSocket(bindSocket: string, publicSocket: stri
  */
 export declare function ensurePublicSocketSecret(publicSocket: string): Promise<Buffer>;
 export declare function waitForListener(socketPath: string, timeoutMs: number, secret?: Uint8Array): Promise<void>;
-export declare function prepareSocketPath(socketPath: string): Promise<void>;
+/** Test-only seams for `prepareSocketPath`'s stale-entry check. */
+export interface PrepareSocketPathHooks {
+    /** Runs after the entry was probed dead and before it is unlinked. */
+    readonly afterStaleProbe?: () => Promise<void>;
+    /** Replaces the listener probe, so a test can pin each verdict. */
+    readonly listenerState?: (socketPath: string) => Promise<ListenerState>;
+}
+export declare function prepareSocketPath(socketPath: string, hooks?: PrepareSocketPathHooks): Promise<void>;
 export declare function listen(server: Server, socketPath: string, secret?: Uint8Array): Promise<void>;
 export declare function closeServer(server: Server): Promise<void>;
 //# sourceMappingURL=host-lifecycle-proxy.d.ts.map

package/dist/modes/rpc/host-lifecycle-proxy.js

@@ -3,11 +3,11 @@
  * adoption of the public name, and the readiness probes of the private hop. Split out of
  * `host-lifecycle.ts`, which keeps the supervisor's orchestration (senpi#2566).
  */
-import { access, chmod, mkdir, rename, unlink } from "node:fs/promises";
+import { chmod, mkdir, rename, stat, unlink } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { dirname } from "node:path";
 import { proxyWithAdmission } from "./host-admission-proxy.js";
-import { MAX_SOCKET_PATH_BYTES, statSocketIdentity } from "./socket-ownership.js";
+import { MAX_SOCKET_PATH_BYTES, socketEntryListenerState, statSocketIdentity, } from "./socket-ownership.js";
 import { authenticateSocket, ensureSocketSecret, resolveSocketTransportAddress, sendSocketHandshake, socketSecretPath, } from "./socket-transport.js";
 export function createPublicProxy(options) {
     const { internalSocket, internalSecret, publicSecret, clients } = options;
@@ -100,8 +100,20 @@ function canConnect(socketPath, secret) {
         socket.once("error", () => settle(false));
     });
 }
-export async function prepareSocketPath(socketPath) {
-    if (process.platform === "win32")
+async function stampOf(socketPath) {
+    try {
+        const entry = await stat(socketPath, { bigint: true });
+        return { dev: entry.dev, ino: entry.ino, ctimeNs: entry.ctimeNs, socket: entry.isSocket() };
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+}
+const sameStamp = (a, b) => a.dev === b.dev && a.ino === b.ino && a.ctimeNs === b.ctimeNs;
+export async function prepareSocketPath(socketPath, hooks = {}) {
+    if (process.platform === "win32" || socketPath.startsWith("\0"))
         return;
     // A path the kernel would truncate binds a DIFFERENT endpoint than the one every client was
     // told about, and the failure surfaces much later as "the host does not answer". Refuse here.
@@ -109,17 +121,33 @@ export async function prepareSocketPath(socketPath) {
         throw new Error(`${socketPath}: socket path is ${Buffer.byteLength(socketPath)} bytes, over the ${MAX_SOCKET_PATH_BYTES}-byte limit.`);
     }
     await mkdir(dirname(socketPath), { recursive: true, mode: 0o700 });
+    const probed = await stampOf(socketPath);
+    if (probed === undefined)
+        return;
+    const inUse = (evidence) => new Error(`${socketPath}: address already in use by a live server (${evidence}).`);
+    // Linux refuses a connect to a regular file too; never remove what is not a socket.
+    if (!probed.socket)
+        throw inUse("the entry is not a socket");
+    const state = await (hooks.listenerState ?? socketEntryListenerState)(socketPath);
+    if (state.verdict === "gone")
+        return;
+    if (state.verdict === "live")
+        throw inUse(state.evidence);
+    await hooks.afterStaleProbe?.();
+    // Something may have replaced the entry since the probe; unlink only the entry probed dead.
+    const current = await stampOf(socketPath);
+    if (current === undefined)
+        return;
+    if (!sameStamp(probed, current))
+        throw inUse("the entry changed after it was probed");
     try {
-        await access(socketPath);
+        await unlink(socketPath);
     }
     catch (cause) {
         if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
             return;
         throw cause;
     }
-    if (await canConnect(socketPath))
-        throw new Error(`${socketPath}: address already in use by a live server.`);
-    await unlink(socketPath);
 }
 export function listen(server, socketPath, secret) {
     return new Promise((resolve, reject) => {

package/dist/modes/rpc/host-observe-request.js

@@ -31,6 +31,7 @@ const OBSERVING_COMMANDS = new Set([
     "subscribe_sessions",
     "unsubscribe_sessions",
     "get_effect_status",
+    "get_pending_inputs",
     "get_subscription_limits",
 ]);
 export function isObservingRequest(line) {

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

@@ -1,5 +1,5 @@
-import { access, chmod, mkdir, unlink } from "node:fs/promises";
-import { createConnection, createServer } from "node:net";
+import { chmod } from "node:fs/promises";
+import { createServer } from "node:net";
 import { basename, dirname, join } from "node:path";
 import { envValue } from "../../core/brand.js";
 import { HostMcpRegistry } from "../../core/extensions/builtin/mcp/host-registry.js";
@@ -16,6 +16,7 @@ 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 { 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";
@@ -539,34 +540,6 @@ function resolveSocketPath(value, agentDir) {
 function formatSocketAddress(socketPath) {
     return socketPath.startsWith("\0") ? `unix://@${socketPath.slice(1)}` : `unix://${socketPath}`;
 }
-async function prepareSocketPath(socketPath) {
-    if (process.platform === "win32" || socketPath.startsWith("\0"))
-        return;
-    await mkdir(dirname(socketPath), { recursive: true, mode: 0o700 });
-    try {
-        await access(socketPath);
-    }
-    catch (cause) {
-        if (isNodeErrorCode(cause, "ENOENT"))
-            return;
-        throw cause;
-    }
-    if (await probeSocket(socketPath))
-        throw new Error(`${socketPath}: address already in use by a live server.`);
-    await unlink(socketPath);
-}
-function probeSocket(socketPath) {
-    return new Promise((resolve) => {
-        const socket = createConnection(resolveSocketTransportAddress(socketPath, process.platform));
-        const settle = (live) => {
-            socket.destroy();
-            resolve(live);
-        };
-        socket.once("connect", () => settle(true));
-        socket.once("error", () => settle(false));
-        socket.setTimeout(1_000, () => settle(false));
-    });
-}
 function listen(server, socketPath, secret) {
     return new Promise((resolve, reject) => {
         server.once("error", reject);
@@ -595,9 +568,6 @@ function closeServer(server) {
 function hostLog(message) {
     process.stderr.write(`senpi rpc host: ${message}\n`);
 }
-function isNodeErrorCode(cause, code) {
-    return cause instanceof Error && "code" in cause && cause.code === code;
-}
 function registerShutdownSignals(shutdown) {
     for (const signal of process.platform === "win32" ? ["SIGTERM"] : ["SIGTERM", "SIGHUP"]) {
         process.on(signal, () => {

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

@@ -86,6 +86,11 @@ export type RpcEffectStatusAnswer = Extract<RpcResponse, {
     command: "get_effect_status";
     success: true;
 }>["data"];
+/** `get_pending_inputs`: pending inputs in durable custody, and an outcome for each known id. */
+export type RpcPendingInputsAnswer = Extract<RpcResponse, {
+    command: "get_pending_inputs";
+    success: true;
+}>["data"];
 export declare class RpcClientOpenInFlightError extends Error {
     readonly code: "open_session_in_flight";
     constructor();
@@ -251,6 +256,11 @@ export declare class RpcClient {
     getEffectStatus(effectId: string, options?: {
         readonly sessionPath?: string;
     }): Promise<RpcEffectStatusAnswer>;
+    /**
+     * The pending inputs in durable custody (queued, sending, failed) and an explicit outcome for each id in
+     * `knownClientMessageIds` (at most 64), consistent through `throughCursor`.
+     */
+    getPendingInputs(knownClientMessageIds?: readonly string[]): Promise<RpcPendingInputsAnswer>;
     /** Abort with host refusals and transport loss surfaced to machine callers. */
     abortStrict(): Promise<void>;
     abortCompaction(): Promise<void>;

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

@@ -480,6 +480,17 @@ export class RpcClient {
         };
         return this.getData(await this.send(command, options.sessionPath === undefined));
     }
+    /**
+     * The pending inputs in durable custody (queued, sending, failed) and an explicit outcome for each id in
+     * `knownClientMessageIds` (at most 64), consistent through `throughCursor`.
+     */
+    async getPendingInputs(knownClientMessageIds) {
+        const command = {
+            type: "get_pending_inputs",
+            ...(knownClientMessageIds === undefined ? {} : { knownClientMessageIds: [...knownClientMessageIds] }),
+        };
+        return this.getData(await this.send(command));
+    }
     /** Abort with host refusals and transport loss surfaced to machine callers. */
     async abortStrict() {
         this.getData(await this.send({ type: "abort" }));

package/dist/modes/rpc/rpc-input-validation.js

@@ -119,6 +119,14 @@ export function rpcCommandPayloadError(command) {
         !(typeof value.effectId === "string" && value.effectId.length > 0 && value.effectId.length <= 256)) {
         return "effectId must be a non-empty string of at most 256 characters.";
     }
+    if (value.type === "get_pending_inputs" && value.knownClientMessageIds !== undefined) {
+        const ids = value.knownClientMessageIds;
+        if (!Array.isArray(ids) ||
+            ids.length > 64 ||
+            !ids.every((id) => typeof id === "string" && id.length > 0 && id.length <= 256)) {
+            return "knownClientMessageIds must be an array of at most 64 non-empty strings of at most 256 characters.";
+        }
+    }
     if (value.type === "get_effect_status" && value.sessionPath !== undefined && typeof value.sessionPath !== "string") {
         return "sessionPath must be a string.";
     }

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

@@ -19,6 +19,7 @@ import type { EngineOrdinal } from "../../core/engine-build-identity.ts";
 import type { ServiceTier } from "../../core/extensions/builtin/service-tier.ts";
 import type { ContextUsage, SessionControlAdmission, SessionKind } from "../../core/extensions/types.ts";
 import type { ResolvedMessagePath } from "../../core/message-path-resolution.ts";
+import type { PendingInputSnapshot, PendingInputUpdate } from "../../core/pending-input-session.ts";
 import type { SessionEntry, SessionMessageEntry, SessionTreeNode, UsageTotals } from "../../core/session-manager.ts";
 import type { SourceInfo } from "../../core/source-info.ts";
 import type { ApiKeyVerification } from "../../core/verify-api-key.ts";
@@ -165,6 +166,16 @@ type RpcSessionCommand = {
     type: "get_effect_status";
     effectId: string;
     sessionPath?: string;
+}
+/**
+ * The pending inputs in durable custody (queued, sending, failed) and an explicit outcome for each listed id,
+ * consistent through `throughCursor` (senpi#3549). Subscribe to `pending_input_update` first, then apply this
+ * snapshot and only updates after its cursor. At most 64 ids.
+ */
+ | {
+    id?: string;
+    type: "get_pending_inputs";
+    knownClientMessageIds?: string[];
 } | {
     id?: string;
     type: "set_model";
@@ -689,7 +700,10 @@ export type RpcCommand = (RpcSessionCommand & {
      */
     type: "release_session";
     sessionId: string;
-    reason: "takeover";
+    /** `move` seals the file for a move to another device (`moveId` required); writes are refused here after. */
+    reason: "takeover" | "move";
+    moveId?: string;
+    target?: string;
     interrupt?: boolean;
     force?: boolean;
 } | {
@@ -1202,6 +1216,12 @@ export type RpcResponse = {
         found: false;
         searched: "complete";
     };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_pending_inputs";
+    success: true;
+    data: PendingInputSnapshot;
 } | {
     id?: string;
     type: "response";
@@ -1824,6 +1844,10 @@ export interface RpcHighReasoningWarningEvent {
     provider: string;
     thinkingLevel: ThinkingLevel;
 }
+/** A pending input in durable custody changed; `changes` are complete projections, in cursor order. */
+export type RpcPendingInputUpdateEvent = {
+    type: "pending_input_update";
+} & PendingInputUpdate;
 /** Emitted after explicit skill tokens are expanded for a user-authored request. */
 export interface RpcSkillInvocationEvent {
     type: "skill_invocation";

package/dist/modes/rpc/session-command-activity.js

@@ -2,6 +2,7 @@
 const observations = new Set([
     "get_state",
     "get_effect_status",
+    "get_pending_inputs",
     "get_messages",
     "get_entries",
     "get_tree",

package/dist/modes/rpc/session-control-actions-data.js

@@ -6,15 +6,24 @@
 import { modelSupportsAssistantPrefill } from "@earendil-works/pi-ai";
 import { getSupportedThinkingLevels } from "../../core/thinking-levels.js";
 export async function availableModelsData(session) {
-    const models = await session.modelRegistry.modelRuntime.getAvailable();
+    const registry = session.modelRegistry;
+    const models = await registry.modelRuntime.getAvailable();
     return {
-        models: models.map((model) => ({
-            ...model,
-            supportedThinkingLevels: getSupportedThinkingLevels(model),
-            supportsAssistantPrefill: modelSupportsAssistantPrefill(model, {
-                thinkingEnabled: session.thinkingLevel !== "off",
-            }),
-        })),
+        models: models.map((model) => {
+            // A models.json or extension definition can declare the priority pairing without putting it on
+            // the Model object; clients must see the values the session itself acts on (#3666).
+            const serviceTier = registry.getServiceTier(model);
+            const upstreamModelId = registry.getUpstreamModelId(model);
+            return {
+                ...model,
+                ...(serviceTier === undefined ? {} : { serviceTier }),
+                ...(upstreamModelId === undefined ? {} : { upstreamModelId }),
+                supportedThinkingLevels: getSupportedThinkingLevels(model),
+                supportsAssistantPrefill: modelSupportsAssistantPrefill(model, {
+                    thinkingEnabled: session.thinkingLevel !== "off",
+                }),
+            };
+        }),
     };
 }
 /** The refusal of a level the active model cannot run; callers match this text. */

package/dist/modes/rpc/session-held.js

@@ -9,6 +9,7 @@ import { RpcSessionRegistryError } from "./session-registry-types.js";
 const READ_ONLY_OR_CONTROL = new Set([
     "get_state",
     "get_effect_status",
+    "get_pending_inputs",
     "get_steering_messages",
     "get_follow_up_messages",
     "get_available_models",

package/dist/modes/rpc/session-release.js

@@ -1,3 +1,4 @@
+import { SessionMovedAwayError } from "../../core/session-move/ownership.js";
 import { isHandoffBusy } from "./handoff-activity.js";
 import { RPC_ERROR_ATTACHED, RPC_ERROR_HOST_DRAINING, RPC_ERROR_INVALID_RELEASE_REASON, RPC_ERROR_RELEASE_FAILED, RPC_ERROR_RELEASE_UNSUPPORTED, RPC_ERROR_SESSION_BUSY, RPC_ERROR_SESSION_CLOSING, RPC_ERROR_TURN_ACTIVE, } from "./rpc-types.js";
 import { abortAndSettle, NOTHING_DROPPED, takeQueuedInput, } from "./session-release-interrupt.js";
@@ -8,7 +9,8 @@ export const RELEASED_ADMISSION_CLOSED = "release_session handed this session to
 /** `errorData.hint` of a refusal whose `busy` names `queued`: only an interrupt hands that input back. */
 export const RELEASE_QUEUED_HINT = "queued user input is still owed a turn; release with interrupt: true to take it out and receive it in dropped.user_messages";
 export async function releaseSession(port, command) {
-    if (command.reason !== "takeover")
+    const validMove = command.reason === "move" && typeof command.moveId === "string" && command.moveId !== "";
+    if (command.reason !== "takeover" && !validMove)
         return refusal(command.id, RPC_ERROR_INVALID_RELEASE_REASON);
     if (port.draining())
         return refusal(command.id, RPC_ERROR_HOST_DRAINING);
@@ -30,6 +32,8 @@ export async function releaseSession(port, command) {
             admission.close(RELEASED_ADMISSION_CLOSED);
             dropped = takeQueuedInput(first.session);
             await abortAndSettle(port, command.sessionId, first.session);
+            // What the clear retired is on disk before `session_released` seals the file (senpi#3549).
+            await first.session.whenQueueClearRecorded();
         }
         // A never-written session gets its file here, before the final check: its `session_released` entry
         // must reach disk, and a header write that fails is this release's failure, never a stray rejection.
@@ -41,6 +45,10 @@ export async function releaseSession(port, command) {
         return answer;
     }
     catch (cause) {
+        if (cause instanceof SessionMovedAwayError) {
+            answer = refusal(command.id, cause.code, { detail: cause.message });
+            return answer;
+        }
         answer = refusal(command.id, RPC_ERROR_RELEASE_FAILED, {
             detail: cause instanceof Error ? cause.message : String(cause),
             ...(interrupted ? { interrupted: true, dropped } : {}),
@@ -78,6 +86,13 @@ async function claimAndRelease(port, command, interrupted, dropped) {
         // On disk or not at all: a failed write leaves no entry a later append could chain onto.
         ready.session.sessionManager.appendCustomEntry(SESSION_RELEASED_ENTRY_TYPE, {
             reason: command.reason,
+            ...(command.reason === "move"
+                ? {
+                    move_id: command.moveId,
+                    target: command.target ?? "",
+                    session_id: ready.session.sessionManager.getSessionId(),
+                }
+                : {}),
             interrupted,
             attachments: ready.attachments,
             host_instance: port.hostInstance ?? null,

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

@@ -26,6 +26,23 @@ export declare const MAX_SOCKET_PATH_BYTES = 103;
  * public path: that path belongs to the running host until the successor is proven to work.
  */
 export declare function generationBindPath(publicSocket: string, generation: number): string;
+/**
+ * What one failed connect says about the process behind a socket entry. Only a refusal can mean
+ * "nobody": on Linux a full backlog answers EAGAIN, so ECONNREFUSED is proof of absence there,
+ * but macOS (and the BSDs) refuse a live listener whose backlog is full, so a refusal there needs
+ * a second witness. ENOENT means the entry is gone; every other error is a live owner (I1).
+ */
+export type ConnectVerdict = "live" | "dead" | "gone" | "confirm-holder";
+export declare function classifyConnectError(code: string | undefined, platform: NodeJS.Platform): ConnectVerdict;
+/** Whether any process holds the entry open: pids from `lsof -t`, none, or unknown. */
+export type SocketHolders = (socketPath: string) => Promise<readonly number[] | undefined>;
+export declare const lsofSocketHolders: SocketHolders;
+/** Whether a live process stands behind a socket entry, and the evidence for the answer. */
+export interface ListenerState {
+    readonly verdict: "live" | "dead" | "gone";
+    readonly evidence: string;
+}
+export declare function socketEntryListenerState(socketPath: string, platform?: NodeJS.Platform, holders?: SocketHolders): Promise<ListenerState>;
 /** Reads the current identity of a socket path entry; `undefined` once absent. */
 export declare function statSocketIdentity(socketPath: string): Promise<SocketFileIdentity | undefined>;
 /**

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

@@ -10,8 +10,11 @@
  * capture the bound entry's filesystem identity (dev + ino) at listen time and
  * unlink only while the path still stat-matches that identity.
  */
+import { execFile } from "node:child_process";
 import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
 import { dirname } from "node:path";
+import { resolveSocketTransportAddress } from "./socket-transport.js";
 /**
  * Name of the sidecar, inside the lifecycle supervisor's private scratch
  * directory, that records which public socket entry that supervisor bound. The
@@ -38,6 +41,55 @@ export function generationBindPath(publicSocket, generation) {
 function sameSocketIdentity(a, b) {
     return a.dev === b.dev && a.ino === b.ino;
 }
+export function classifyConnectError(code, platform) {
+    if (code === "ENOENT")
+        return "gone";
+    if (code === "ECONNREFUSED")
+        return platform === "linux" ? "dead" : "confirm-holder";
+    return "live";
+}
+const HOLDER_PROBE_TIMEOUT_MS = 5_000;
+export const lsofSocketHolders = (socketPath) => new Promise((resolve) => {
+    execFile("lsof", ["-t", "--", socketPath], { timeout: HOLDER_PROBE_TIMEOUT_MS }, (error, stdout) => {
+        const pids = String(stdout)
+            .split(/\s+/)
+            .filter((part) => /^\d+$/.test(part))
+            .map(Number);
+        if (pids.length > 0)
+            return resolve(pids);
+        // lsof exits 1 with no output when nothing holds the file; anything else proves nothing.
+        const exitCode = error === null ? undefined : Reflect.get(error, "code");
+        resolve(error === null || exitCode === 1 ? [] : undefined);
+    });
+});
+const CONNECT_PROBE_TIMEOUT_MS = 2_000;
+/** One connect to the entry: `connected`, or the error code it failed with (`timeout` when it hung). */
+function connectOnce(socketPath) {
+    return new Promise((resolve) => {
+        const socket = createConnection(resolveSocketTransportAddress(socketPath, process.platform));
+        const settle = (value) => {
+            socket.destroy();
+            resolve(value);
+        };
+        socket.setTimeout(CONNECT_PROBE_TIMEOUT_MS, () => settle({ code: "timeout" }));
+        socket.once("connect", () => settle({ connected: true }));
+        socket.once("error", (cause) => settle({ code: cause.code }));
+    });
+}
+export async function socketEntryListenerState(socketPath, platform = process.platform, holders = lsofSocketHolders) {
+    const attempt = await connectOnce(socketPath);
+    if ("connected" in attempt)
+        return { verdict: "live", evidence: "accepting connections" };
+    const verdict = classifyConnectError(attempt.code, platform);
+    if (verdict !== "confirm-holder")
+        return { verdict, evidence: `connect ${attempt.code ?? "failed"}` };
+    const pids = await holders(socketPath);
+    if (pids === undefined)
+        return { verdict: "live", evidence: "connect ECONNREFUSED, holders unknown" };
+    if (pids.length > 0)
+        return { verdict: "live", evidence: `connect ECONNREFUSED, held open by pid ${pids.join(",")}` };
+    return { verdict: "dead", evidence: "connect ECONNREFUSED, held by nobody" };
+}
 /** Reads the current identity of a socket path entry; `undefined` once absent. */
 export async function statSocketIdentity(socketPath) {
     try {

package/dist/modes/rpc/tool-child/admission.d.ts

@@ -0,0 +1,42 @@
+import { type ToolChildMessageOf } from "./protocol.ts";
+/**
+ * The one host-call capacity both sides enforce: `HOST_CALL_ACTIVE` running plus `HOST_CALL_WAITING` queued (264).
+ * The child admits against it before sending, the server admits against it on receipt; there is no second constant.
+ */
+export declare function hostCallCapacity(): number;
+export type HostCallRefusalCode = "host_call_capacity" | "host_call_duplicate";
+export type HostCallDecision = {
+    state: "active";
+} | {
+    state: "waiting";
+} | {
+    state: "refused";
+    frame: ToolChildMessageOf<"host_call_refused">;
+};
+/** Lossless host-call admission: a call is running, queued FIFO, or refused with a frame naming its `callId`. */
+export declare class HostCallAdmission {
+    #private;
+    get active(): number;
+    get waiting(): number;
+    submit(callId: string): HostCallDecision;
+    /** Ends a call (or withdraws a queued one) and returns the call promoted into the freed active slot, if any. */
+    settle(callId: string): string | undefined;
+}
+export type JobRefusalCode = "tool_child_jobs_full" | "tool_child_nested_full" | "tool_child_parent_unknown" | "tool_child_job_duplicate";
+export type JobDecision = {
+    admitted: true;
+} | {
+    admitted: false;
+    frame: ToolChildMessageOf<"job_refused">;
+};
+/**
+ * Per-child job budget. Ordinary jobs are capped at `TOOL_CHILD_LIMITS.jobs`. A nested job (started on behalf of a
+ * running job, e.g. a tool an eval cell calls) is admitted past that cap, so a full child cannot deadlock its own
+ * callers; nested jobs arrive through host calls and are bounded by `hostCallCapacity()`.
+ */
+export declare class JobAdmission {
+    #private;
+    admit(jobId: string, parentJobId?: string): JobDecision;
+    finish(jobId: string): void;
+}
+//# sourceMappingURL=admission.d.ts.map