@code-yeongyu/senpi 2026.11.10-1 → 2026.11.10-2

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

@@ -24,6 +24,8 @@ export type SessionRuntime = AgentSessionRuntime;
 export type RpcSessionState = "opening" | "open" | "closing" | "quarantined" | "closed";
 export interface RpcSessionEntry {
     state: RpcSessionState;
+    /** Built speculatively: no public identity, attachment, listing, or disk persistence until claimed. */
+    speculative?: boolean;
     runtime?: SessionRuntime;
     worker?: SessionWorkerClient;
     /** The in-process session's ordered acceptance lane, present only while the compact-updates flag is on. */
@@ -116,6 +118,8 @@ export interface RpcSessionRegistryOptions {
 }
 /** Host-side lifecycle policy for one `open_session`, distinct from the session's launch profile. */
 export interface RpcSessionOpenOptions {
+    /** Router-owned park construction; never accepted directly from the wire. */
+    speculative?: boolean;
     /** Refuse unless the registry already owns the path; never prepare or construct a writer. */
     attachOnly?: boolean;
     /** Keep the session alive when its last client disconnects (`open_session.retain_on_disconnect`). */

package/dist/modes/rpc/session-registry.d.ts

@@ -4,6 +4,7 @@ export { frozenProfile, type OpenRpcSession, type RpcSessionEntry, type RpcSessi
 /** Process-local lifecycle owner for multi-session RPC runtimes. */
 export declare class RpcSessionRegistry {
     readonly supportsCompact: (profile?: RpcSessionLaunchProfile) => boolean;
+    readonly supportsParkClaim = true;
     private readonly entries;
     private readonly reservations;
     private readonly pendingClaims;
@@ -20,6 +21,8 @@ export declare class RpcSessionRegistry {
     constructor(options: RpcSessionRegistryOptions);
     /** Number of live entries, including ones still opening or closing. */
     get size(): number;
+    /** Commit the ledger's exclusive claim after its existing runtime has acquired a persistent file. */
+    claimPark(handle: string, retainOnDisconnect: boolean): Promise<OpenRpcSession>;
     /** Daemon-family identities come from the endpoint's claims and generation registry. */
     holderPids(observedStarts?: ReadonlyMap<number, number | undefined>): Promise<readonly number[]>;
     openSession(requested: RpcSessionLaunchProfile, options?: RpcSessionOpenOptions): Promise<OpenRpcSession>;

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

@@ -16,6 +16,7 @@ export class RpcSessionRegistry {
         return this.options.agentDir;
     }
     constructor(options) {
+        this.supportsParkClaim = true;
         this.entries = new Map();
         this.reservations = new Set();
         this.pendingClaims = new Map();
@@ -42,8 +43,10 @@ export class RpcSessionRegistry {
             closeGraceMs: this.closeGraceMs,
             get: (handle) => this.entries.get(handle),
             delete: (handle) => {
+                const speculative = this.entries.get(handle)?.speculative;
                 const deleted = this.entries.delete(handle);
-                this.options.onSizeChange?.(this.entries.size);
+                if (!speculative)
+                    this.options.onSizeChange?.(this.size);
                 return deleted;
             },
             releaseReservation: async (key) => {
@@ -66,7 +69,26 @@ export class RpcSessionRegistry {
     }
     /** Number of live entries, including ones still opening or closing. */
     get size() {
-        return this.entries.size;
+        return [...this.entries.values()].filter((entry) => !entry.speculative).length;
+    }
+    /** Commit the ledger's exclusive claim after its existing runtime has acquired a persistent file. */
+    async claimPark(handle, retainOnDisconnect) {
+        const entry = this.entries.get(handle);
+        if (!entry?.speculative || entry.state !== "open" || !entry.runtime)
+            throw new RpcSessionRegistryError("unknown_session");
+        await entry.runtime.persistSession();
+        // No await between the duplicate decision and publication: an ordinary open may have
+        // reserved this identity while persistence was being enabled.
+        for (const other of this.entries.values())
+            if (!other.speculative && other.durableSessionId === entry.runtime.session.sessionId)
+                throw new RpcSessionRegistryError("session_id_in_use");
+        entry.speculative = false;
+        entry.attachments = 1;
+        entry.retainOnDisconnect = retainOnDisconnect;
+        entry.lastCommandAt = this.now();
+        this.syncRuntimeMetadata();
+        this.options.onSizeChange?.(this.size);
+        return { sessionId: handle, durableSessionId: entry.runtime.session.sessionId, sessionPath: entry.sessionPath };
     }
     /** Daemon-family identities come from the endpoint's claims and generation registry. */
     holderPids(observedStarts) {
@@ -143,7 +165,9 @@ export class RpcSessionRegistry {
     list() {
         this.syncRuntimeMetadata();
         const now = this.now();
-        return [...this.entries].map(([sessionId, entry]) => ({
+        return [...this.entries]
+            .filter(([, entry]) => !entry.speculative)
+            .map(([sessionId, entry]) => ({
             sessionId,
             durableSessionId: entry.durableSessionId,
             sessionPath: entry.sessionPath,

package/dist/modes/rpc/session-router-close.js

@@ -208,6 +208,7 @@ export async function dispose(host) {
     stopSweep(host);
     if (host.drainTimer !== undefined)
         clearInterval(host.drainTimer);
+    await host.parks.stop();
     if (host.admissions)
         await host.admissions.dispose();
     await Promise.all([...host.bindings.entries()].map(async ([sessionId, binding]) => {

package/dist/modes/rpc/session-router-context.d.ts

@@ -6,7 +6,9 @@ import type { SessionEventWriter } from "./session-event-writer.ts";
 import type { RpcSessionRegistry } from "./session-registry.ts";
 import { SessionAttachOrder } from "./session-attach-order.ts";
 import type { RpcHostSessionDefaults, RpcSessionIdlePolicy } from "./session-router-types.ts";
+import { HostParkLedger } from "./host-park-ledger.ts";
 export declare class RouterContext {
+    readonly parks: HostParkLedger;
     readonly admissions: CompactAdmissions | undefined;
     readonly bindings: Map<string, RpcSessionBinding>;
     readonly stopLimitBroadcast: () => void;
@@ -18,7 +20,7 @@ export declare class RouterContext {
     readonly opensByConnection: Map<string, Set<Promise<void>>>;
     /** Connections whose socket has already been detached. */
     readonly releasedConnections: Set<string>;
-    readonly registry: Pick<RpcSessionRegistry, "openSession" | "peek" | "getForCommand" | "beginClose" | "close" | "closeMarked" | "list" | "size" | "warm" | "closeGraceMs"> & Partial<Pick<RpcSessionRegistry, "supportsCompact" | "holderPids" | "attachSession" | "agentDir">>;
+    readonly registry: Pick<RpcSessionRegistry, "openSession" | "peek" | "getForCommand" | "beginClose" | "close" | "closeMarked" | "list" | "size" | "warm" | "closeGraceMs"> & Partial<Pick<RpcSessionRegistry, "supportsCompact" | "supportsParkClaim" | "claimPark" | "holderPids" | "attachSession" | "agentDir">>;
     readonly writer: SessionEventWriter;
     readonly defaults: RpcHostSessionDefaults;
     readonly createBinding: typeof createRpcSessionBinding;
@@ -59,6 +61,6 @@ export declare class RouterContext {
         readonly mainHeapBytes: () => number;
         readonly kernels: () => readonly RpcHostKernelMemory[];
     } | undefined;
-    constructor(registry: Pick<RpcSessionRegistry, "openSession" | "peek" | "getForCommand" | "beginClose" | "close" | "closeMarked" | "list" | "size" | "warm" | "closeGraceMs"> & Partial<Pick<RpcSessionRegistry, "supportsCompact" | "holderPids" | "attachSession" | "agentDir">>, writer: SessionEventWriter, defaults: RpcHostSessionDefaults, createBinding?: typeof createRpcSessionBinding, connectionOptions?: Parameters<typeof createRpcSessionBinding>[4], idle?: RpcSessionIdlePolicy);
+    constructor(registry: Pick<RpcSessionRegistry, "openSession" | "peek" | "getForCommand" | "beginClose" | "close" | "closeMarked" | "list" | "size" | "warm" | "closeGraceMs"> & Partial<Pick<RpcSessionRegistry, "supportsCompact" | "supportsParkClaim" | "claimPark" | "holderPids" | "attachSession" | "agentDir">>, writer: SessionEventWriter, defaults: RpcHostSessionDefaults, createBinding?: typeof createRpcSessionBinding, connectionOptions?: Parameters<typeof createRpcSessionBinding>[4], idle?: RpcSessionIdlePolicy);
 }
 //# sourceMappingURL=session-router-context.d.ts.map

package/dist/modes/rpc/session-router-context.js

@@ -12,8 +12,11 @@ import { routingIdOf } from "./session-router-errors.js";
 import { sweepIdleSessions } from "./session-router-occupancy.js";
 import { followRetainedRecord } from "./session-router-residency.js";
 import { registryStatusSource } from "./session-status-source.js";
+import { HostParkLedger } from "./host-park-ledger.js";
+import { closePark } from "./session-router-park.js";
 export class RouterContext {
     constructor(registry, writer, defaults, createBinding = createRpcSessionBinding, connectionOptions = {}, idle) {
+        this.parks = new HostParkLedger((opened) => closePark(this, opened));
         this.admissions = compactUpdatesEnabled()
             ? new CompactAdmissions(ADMISSION_LIMITS, (socketEpoch, admissionId) => this.writer.routesAdmission(socketEpoch, admissionId))
             : undefined;

package/dist/modes/rpc/session-router-host-reads.js

@@ -14,6 +14,7 @@ import { sessionMemory } from "./session-router-observation.js";
 export function answerProtocolInfo(host, command) {
     const hostCapabilities = multiSessionHostCapabilities({
         warm: host.registry.warm !== undefined,
+        parkClaim: host.registry.supportsParkClaim === true,
         toolRuntime: host.defaults.toolRuntime ?? "in-process",
         negotiated: host.connectionOptions?.capabilities ?? [],
         mcpPresenters: host.writer.mcpPresenters !== undefined,

package/dist/modes/rpc/session-router-occupancy.js

@@ -12,6 +12,15 @@ const DRAIN_SWEEP_MS = 50;
  */
 export function beginDrain(host) {
     host.draining = true;
+    void host.parks
+        .stop()
+        .catch((cause) => {
+        process.stderr.write(`senpi rpc park close failed during drain: ${String(cause)}\n`);
+    })
+        .then(() => sweepDrain(host))
+        .catch((cause) => {
+        process.stderr.write(`senpi rpc drain sweep failed after park close: ${String(cause)}\n`);
+    });
     stopSweep(host);
     // Armed BEFORE the first pass, so a pass that fails is retried instead of ending the drain
     // (senpi#2285). Unref'd: a draining host must never be the reason the event loop stays open.
@@ -35,7 +44,7 @@ export function sweepDrain(host) {
         parkForHandoff(host, sessionId, "session_dir_removed");
     for (const sessionId of verdicts.park)
         parkForHandoff(host, sessionId, "handoff_parked");
-    if (host.registry.size > 0 || host.handoffParks > 0 || host.finalizations.size > 0)
+    if (host.registry.size > 0 || host.parks.size > 0 || host.handoffParks > 0 || host.finalizations.size > 0)
         return;
     if (host.drainTimer !== undefined) {
         clearInterval(host.drainTimer);

package/dist/modes/rpc/session-router-open-result.d.ts

@@ -0,0 +1,12 @@
+import type { OpenRpcSession, RpcSessionEntry } from "./session-registry.ts";
+import type { RouterContext } from "./session-router-context.ts";
+/** A dropped opener waits until its open or claim has either transferred or released ownership. */
+export declare function holdOpenConnection(host: RouterContext, owner: string): () => void;
+/** One ownership transition for both a freshly built open and a claimed speculative open. */
+export declare function ownOpen(host: RouterContext, opened: OpenRpcSession, owner: string | undefined, compact?: boolean): void;
+export declare function publishOpen(host: RouterContext, opened: OpenRpcSession, entry: RpcSessionEntry): void;
+export declare function replyOpen(host: RouterContext, opened: OpenRpcSession, entry: RpcSessionEntry, command: {
+    readonly type: "open_session" | "claim_session";
+    readonly id?: string;
+}, reply?: boolean): void;
+//# sourceMappingURL=session-router-open-result.d.ts.map

package/dist/modes/rpc/session-router-open-result.js

@@ -0,0 +1,63 @@
+import { openReplyPermissionMode } from "../../core/permission-mode.js";
+import { buildRpcSessionState } from "./connection-handler.js";
+/** A dropped opener waits until its open or claim has either transferred or released ownership. */
+export function holdOpenConnection(host, owner) {
+    const barrier = Promise.withResolvers();
+    const opens = host.opensByConnection.get(owner) ?? new Set();
+    opens.add(barrier.promise);
+    host.opensByConnection.set(owner, opens);
+    return () => {
+        barrier.resolve();
+        opens.delete(barrier.promise);
+        if (opens.size === 0)
+            host.opensByConnection.delete(owner);
+    };
+}
+/** One ownership transition for both a freshly built open and a claimed speculative open. */
+export function ownOpen(host, opened, owner, compact = false) {
+    if (owner === undefined)
+        return;
+    if (!host.writer.hasRegisteredConnectionCapabilities(owner))
+        host.writer.setConnectionCapabilities(owner, host.pendingCapabilities.get(owner) ?? host.connectionOptions?.capabilities ?? []);
+    host.writer.attachConnectionToSession(owner, opened.sessionId, compact);
+    const owned = host.sessionsByConnection.get(owner) ?? new Map();
+    owned.set(opened.sessionId, (owned.get(opened.sessionId) ?? 0) + 1);
+    host.sessionsByConnection.set(owner, owned);
+    host.attachOrder.attached(opened.sessionId, owner);
+}
+export function publishOpen(host, opened, entry) {
+    if (opened.attached)
+        host.writer.status.publish(opened.sessionId, "attach", "client");
+    else {
+        host.writer.publishSessionOpened({
+            type: "session_opened",
+            sessionId: opened.sessionId,
+            durableSessionId: opened.durableSessionId,
+            ...(opened.sessionPath !== undefined ? { sessionPath: opened.sessionPath } : {}),
+            kind: entry.kind,
+            cwd: entry.cwd,
+            context: entry.context,
+        });
+        host.writer.status.publish(opened.sessionId, "open", "client");
+    }
+}
+export function replyOpen(host, opened, entry, command, reply = true) {
+    const state = entry.worker?.snapshot?.state ?? (entry.runtime ? buildRpcSessionState(entry.runtime.session) : undefined);
+    if (!state)
+        throw new Error("Session state was not created");
+    if (reply)
+        host.writer.enqueue(opened.sessionId, {
+            id: command.id,
+            type: "response",
+            command: command.type,
+            success: true,
+            data: {
+                sessionId: opened.sessionId,
+                state,
+                ...openReplyPermissionMode(state),
+                ...(opened.attached ? { attached: true } : {}),
+                ...(host.defaults.sessionPresence ? { presence: host.defaults.sessionPresence.view(state.sessionId) } : {}),
+            },
+        });
+}
+//# sourceMappingURL=session-router-open-result.js.map

package/dist/modes/rpc/session-router-open.d.ts

@@ -1,6 +1,7 @@
 import { type OpenAcceptance } from "./compact-open-admission.ts";
 import type { HandoverParkedEntry } from "./host-handover-parked.ts";
 import type { RpcCommand, RpcResponse } from "./rpc-types.ts";
+import type { OpenRpcSession } from "./session-registry.ts";
 import type { RouterContext } from "./session-router-context.ts";
 export declare function openWithBarrier(host: RouterContext, command: Extract<RpcCommand, {
     type: "open_session";
@@ -19,5 +20,7 @@ export declare function open(host: RouterContext, command: Extract<RpcCommand, {
     readonly signal?: AbortSignal;
     readonly defaults?: boolean;
     readonly contextOverlay?: HandoverParkedEntry["contextOverlay"];
+    /** An invisible speculative open, published only when its ledger hands it to a caller. */
+    readonly park?: (opened: OpenRpcSession) => void;
 }): Promise<RpcResponse | undefined>;
 //# sourceMappingURL=session-router-open.d.ts.map

package/dist/modes/rpc/session-router-open.js

@@ -1,7 +1,5 @@
-import { buildRpcSessionState } from "./connection-handler.js";
 import { compactUpdatesEnabled } from "../../core/engine-socket-flag.js";
 import { startOpenTimer } from "../../core/open-timing.js";
-import { openReplyPermissionMode } from "../../core/permission-mode.js";
 import { compactOpen } from "./compact-open-admission.js";
 import { CompactAdmissionError } from "./compact-admission-error.js";
 import { runAdmissionProducer } from "./compact-admission-producer.js";
@@ -12,6 +10,8 @@ import { close } from "./session-router-close.js";
 import { code, detail, error } from "./session-router-errors.js";
 import { sweepDrain } from "./session-router-occupancy.js";
 import { invalidSpawnedBy, validatedOpenProfile } from "./session-router-open-profile.js";
+import { holdOpenConnection, ownOpen, publishOpen, replyOpen } from "./session-router-open-result.js";
+import { closePark } from "./session-router-park.js";
 import { relocationConnection } from "./session-router-relocation.js";
 import { syncRetainedRecord } from "./session-router-residency.js";
 import { liveToolMediaScope, toolMediaPersister } from "./tool-media-store.js";
@@ -24,18 +24,12 @@ function openPhysicalWithBarrier(host, command, accept, signal) {
     const owner = host.writer.currentConnection();
     if (owner === undefined)
         return open(host, command);
-    let resolveBarrier;
-    const barrier = new Promise((resolve) => {
-        resolveBarrier = resolve;
-    });
-    const opens = host.opensByConnection.get(owner) ?? new Set();
     // Every open already accepted anywhere on this host, not just on this connection: the
     // in-process runtime serves them on ONE loop, so the wait this caller faces is the total.
     let inFlight = 0;
     for (const pending of host.opensByConnection.values())
         inFlight += pending.size;
-    opens.add(barrier);
-    host.opensByConnection.set(owner, opens);
+    const releaseBarrier = holdOpenConnection(host, owner);
     // Before the open reaches the loop: a client that later hits its deadline can then say
     // where it was queued instead of reporting a bare timeout (senpi#1844).
     if (command.id !== undefined)
@@ -49,12 +43,7 @@ function openPhysicalWithBarrier(host, command, accept, signal) {
     // A late open's physical session is released by its admission (the accept/rollback path, 4272-admission-
     // abandonment), so the late response itself owns nothing to release here.
     const opened = signal === undefined ? start() : runAdmissionProducer(signal, start, async () => { });
-    return opened.finally(() => {
-        resolveBarrier();
-        opens.delete(barrier);
-        if (opens.size === 0)
-            host.opensByConnection.delete(owner);
-    });
+    return opened.finally(releaseBarrier);
 }
 /**
  * The successor's reopen of a handoff-parked session: the same open as an `open_session`, with no
@@ -87,6 +76,7 @@ export async function open(host, command, owner, options) {
         {
             retainOnDisconnect: command.retain_on_disconnect === true,
             attachOnly: command.expectedHostInstance !== undefined,
+            ...(options?.park ? { speculative: true } : {}),
         });
         timer.mark("registry_open");
         options?.signal?.throwIfAborted();
@@ -119,22 +109,11 @@ export async function open(host, command, owner, options) {
             host.writer.registerAcceptance(openedSession.sessionId, lane);
         if (options?.accept)
             await options.accept(openedSession);
-        if (owner !== undefined) {
-            if (!host.writer.hasRegisteredConnectionCapabilities(owner))
-                host.writer.setConnectionCapabilities(owner, host.pendingCapabilities.get(owner) ?? host.connectionOptions?.capabilities ?? []);
-            host.writer.attachConnectionToSession(owner, openedSession.sessionId, options?.accept !== undefined);
-        }
-        // A client that dies without close_session (terminal closed, SIGKILL, dropped
-        // SSH) still holds this handle's attachment and its path reservation. Remember
-        // which connection owns it so releaseConnection() can close exactly that.
-        if (owner !== undefined) {
-            const owned = host.sessionsByConnection.get(owner) ?? new Map();
-            owned.set(openedSession.sessionId, (owned.get(openedSession.sessionId) ?? 0) + 1);
-            host.sessionsByConnection.set(owner, owned);
-            host.attachOrder.attached(openedSession.sessionId, owner);
-        }
+        ownOpen(host, openedSession, owner, options?.accept !== undefined);
         if (!host.bindings.has(openedSession.sessionId)) {
-            host.bindings.set(openedSession.sessionId, await host.createBinding(openedSession.sessionId, entry, host.writer, () => void close(host, { type: "close_session", sessionId: openedSession.sessionId }), {
+            host.bindings.set(openedSession.sessionId, await host.createBinding(openedSession.sessionId, entry, host.writer, () => void (entry.speculative
+                ? closePark(host, openedSession)
+                : close(host, { type: "close_session", sessionId: openedSession.sessionId })), {
                 ...host.connectionOptions,
                 capabilities: owner !== undefined
                     ? (host.pendingCapabilities.get(owner) ?? host.connectionOptions?.capabilities ?? [])
@@ -181,20 +160,11 @@ export async function open(host, command, owner, options) {
                 });
         }
         options?.signal?.throwIfAborted();
-        if (opened.attached)
-            host.writer.status.publish(openedSession.sessionId, "attach", "client");
-        else {
-            host.writer.publishSessionOpened({
-                type: "session_opened",
-                sessionId: openedSession.sessionId,
-                durableSessionId: openedSession.durableSessionId,
-                ...(openedSession.sessionPath !== undefined ? { sessionPath: openedSession.sessionPath } : {}),
-                kind: entry.kind,
-                cwd: entry.cwd,
-                context: entry.context,
-            });
-            host.writer.status.publish(openedSession.sessionId, "open", "client");
+        if (options?.park) {
+            options.park(openedSession);
+            return undefined;
         }
+        publishOpen(host, openedSession, entry);
         if (!options?.accept && !host.draining && owner !== undefined && host.releasedConnections.has(owner)) {
             releaseOwnerAttachment(host, owner, openedSession.sessionId);
             await releaseOwnedSession(host, openedSession.sessionId);
@@ -205,26 +175,8 @@ export async function open(host, command, owner, options) {
         if (options?.accept) {
             return undefined;
         }
-        const replyState = entry.worker?.snapshot?.state ?? (entry.runtime ? buildRpcSessionState(entry.runtime.session) : undefined);
-        if (!replyState)
-            throw new Error("Session state was not created");
         timer.mark("reply");
-        if (options?.reply !== false)
-            host.writer.enqueue(opened.sessionId, {
-                id: command.id,
-                type: "response",
-                command: "open_session",
-                success: true,
-                data: {
-                    sessionId: opened.sessionId,
-                    state: replyState,
-                    ...openReplyPermissionMode(replyState),
-                    ...(opened.attached ? { attached: true } : {}),
-                    ...(host.defaults.sessionPresence
-                        ? { presence: host.defaults.sessionPresence.view(replyState.sessionId) }
-                        : {}),
-                },
-            });
+        replyOpen(host, opened, entry, command, options?.reply !== false);
         return undefined;
     }
     catch (cause) {
@@ -233,7 +185,7 @@ export async function open(host, command, owner, options) {
             // rollback, and only while the registry still holds the live entry, so only that
             // rollback owes its subscribers the terminal record; an attach rollback, or one whose
             // entry is already gone, never announced the session in the first place (#3198 review, L1).
-            if (!opened.attached && !options?.signal?.aborted) {
+            if (!options?.park && !opened.attached && !options?.signal?.aborted) {
                 const entry = host.registry.peek(opened.sessionId);
                 if (entry?.runtime !== undefined || entry?.worker !== undefined)
                     host.writer.sealRolledBackOpen(opened.sessionId, entry.sessionPath);

package/dist/modes/rpc/session-router-park.d.ts

@@ -0,0 +1,15 @@
+import type { RpcCommand, RpcResponse } from "./rpc-types.ts";
+import type { OpenRpcSession } from "./session-registry.ts";
+import type { RouterContext } from "./session-router-context.ts";
+type ParkCommand = Extract<RpcCommand, {
+    type: "park_session";
+}>;
+type ClaimCommand = Extract<RpcCommand, {
+    type: "claim_session";
+}>;
+/** Quiet teardown: speculation never owes a public terminal record or a handover park. */
+export declare function closePark(host: RouterContext, opened: OpenRpcSession): Promise<void>;
+export declare function parkSession(host: RouterContext, command: ParkCommand): Promise<RpcResponse>;
+export declare function claimSession(host: RouterContext, command: ClaimCommand): Promise<RpcResponse | undefined>;
+export {};
+//# sourceMappingURL=session-router-park.d.ts.map

package/dist/modes/rpc/session-router-park.js

@@ -0,0 +1,176 @@
+import { runWithProviderScope } from "@earendil-works/pi-ai/node/provider-scope";
+import { withoutOpenTiming } from "../../core/open-timing.js";
+import { outsideCommand } from "./command-authority.js";
+import { runSetThinkingLevel } from "./effect-commands.js";
+import { runSetModel } from "./handlers-model.js";
+import { runSetPermissionPreset } from "./permission-preset-command.js";
+import { applyAttachedProfile } from "./session-registry-attach.js";
+import { releaseOwnedSession, releaseOwnerAttachment } from "./session-router-attachments.js";
+import { finalizeClose, tryClaimClose } from "./session-router-close.js";
+import { code, error } from "./session-router-errors.js";
+import { open } from "./session-router-open.js";
+import { validatedOpenProfile } from "./session-router-open-profile.js";
+import { holdOpenConnection, ownOpen, publishOpen, replyOpen } from "./session-router-open-result.js";
+import { syncRetainedRecord } from "./session-router-residency.js";
+function profileKey(profile) {
+    return JSON.stringify([
+        profile.cwd,
+        profile.sessionKind ?? "interactive",
+        Object.entries(profile.sessionContext ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+    ]);
+}
+/** Same open, host-context merge, kind, media and binding; no owner and no publication. */
+async function buildPark(host, command) {
+    let opened;
+    const response = await outsideCommand(() => host.writer.connectionContext.outside(() => withoutOpenTiming(() => open(host, { ...command, type: "open_session" }, undefined, {
+        reply: false,
+        park: (result) => {
+            opened = result;
+        },
+    }))));
+    if (response && !response.success)
+        throw new Error(response.error);
+    if (!opened)
+        throw new Error("park_open_failed");
+    return opened;
+}
+/** Quiet teardown: speculation never owes a public terminal record or a handover park. */
+export async function closePark(host, opened) {
+    const claim = tryClaimClose(host, opened.sessionId, { drainAttachments: true });
+    if (claim?.finalizer)
+        await finalizeClose(host, opened.sessionId, host.bindings.get(opened.sessionId));
+    else
+        await host.finalizations.get(opened.sessionId)?.promise;
+    host.writer.forgetSession(opened.sessionId);
+}
+export async function parkSession(host, command) {
+    if (!host.registry.supportsParkClaim)
+        return error(command.id, command.type, "park_claim_unsupported");
+    if (host.draining || host.drainExitRequested)
+        return error(command.id, command.type, "host_draining");
+    const profile = validatedOpenProfile(host, { ...command, type: "open_session" });
+    if ("type" in profile)
+        return { ...profile, command: command.type };
+    try {
+        const state = await host.parks.park(profileKey(profile), () => buildPark(host, command));
+        if (host.draining || host.drainExitRequested)
+            return error(command.id, command.type, "host_draining");
+        return { id: command.id, type: "response", command: command.type, success: true, data: { state } };
+    }
+    catch (cause) {
+        return error(command.id, command.type, code(cause));
+    }
+}
+export function claimSession(host, command) {
+    const owner = host.writer.currentConnection();
+    const release = owner === undefined ? undefined : holdOpenConnection(host, owner);
+    return claimReady(host, command, owner).finally(release);
+}
+async function claimReady(host, command, owner) {
+    if (!host.registry.supportsParkClaim || !host.registry.claimPark)
+        return error(command.id, command.type, "park_claim_unsupported");
+    if (host.draining || host.drainExitRequested)
+        return error(command.id, command.type, "host_draining");
+    const miss = () => ({
+        id: command.id,
+        type: "response",
+        command: "claim_session",
+        success: true,
+        data: { claimed: false },
+    });
+    // These require construction or a distinct admission contract. A miss leaves the park untouched.
+    if (command.sessionPath !== undefined ||
+        command.durableSessionId !== undefined ||
+        command.expectedHostInstance !== undefined ||
+        command.admissionId !== undefined ||
+        command.attended === false ||
+        command.retry !== undefined ||
+        (command.provider !== undefined) !== (command.modelId !== undefined) ||
+        command.spawnedBy !== undefined ||
+        command.env !== undefined ||
+        command.auto_title !== undefined ||
+        command.retryFallback !== undefined ||
+        (owner !== undefined && host.writer.compactSelection(owner)?.selected))
+        return miss();
+    const profile = validatedOpenProfile(host, { ...command, type: "open_session" });
+    if ("type" in profile)
+        return { ...profile, command: command.type };
+    const key = profileKey(profile);
+    const opened = host.parks.take(key);
+    if (!opened)
+        return miss();
+    let success = false;
+    try {
+        const entry = host.registry.peek(opened.sessionId);
+        if (entry?.state !== "open" || !entry.runtime)
+            return miss();
+        const runtime = entry.runtime;
+        const ctx = { session: runtime.session, sessionId: opened.sessionId, by: { connectionId: owner ?? "host" } };
+        await runWithProviderScope(entry.scope, async () => {
+            const responses = [];
+            if (command.provider !== undefined && command.modelId !== undefined)
+                responses.push(await runSetModel(ctx, {
+                    type: "set_model",
+                    provider: command.provider,
+                    modelId: command.modelId,
+                    scope: "session",
+                }));
+            if (command.thinkingLevel !== undefined)
+                responses.push(await runSetThinkingLevel(ctx, {
+                    type: "set_thinking_level",
+                    level: command.thinkingLevel,
+                    scope: "turn",
+                }));
+            if (command.permissionPreset !== undefined)
+                responses.push(runSetPermissionPreset(runtime, {
+                    type: "set_permission_preset",
+                    permissionPreset: command.permissionPreset,
+                }));
+            const refused = responses.find((response) => !response.success);
+            if (refused && !refused.success)
+                throw new Error(refused.error);
+            applyAttachedProfile(entry, { ...profile, permissionPreset: undefined, permissionPresetSource: undefined });
+            if (runtime.launchProfile)
+                entry.profile = runtime.launchProfile;
+        });
+        if (host.draining || host.drainExitRequested || (owner !== undefined && host.releasedConnections.has(owner)))
+            return miss();
+        const claimed = await host.registry.claimPark(opened.sessionId, command.retain_on_disconnect === true);
+        if (host.draining || host.drainExitRequested)
+            return miss();
+        entry.acceptance?.applyTranscript(runtime.session.sessionManager.drainTranscript());
+        ownOpen(host, claimed, owner);
+        host.bindings
+            .get(claimed.sessionId)
+            ?.setClientCapabilities?.((owner === undefined ? undefined : host.pendingCapabilities.get(owner)) ??
+            host.connectionOptions?.capabilities ??
+            []);
+        publishOpen(host, claimed, entry);
+        await syncRetainedRecord(host, claimed.sessionId, undefined);
+        replyOpen(host, claimed, entry, command);
+        success = true;
+        if (owner !== undefined && host.releasedConnections.has(owner)) {
+            releaseOwnerAttachment(host, owner, claimed.sessionId);
+            await releaseOwnedSession(host, claimed.sessionId);
+        }
+        return undefined;
+    }
+    catch (cause) {
+        return error(command.id, command.type, code(cause));
+    }
+    finally {
+        if (!success)
+            await closePark(host, opened);
+        host.parks.finish(key);
+        if (success) {
+            const replacement = {
+                type: "park_session",
+                cwd: command.cwd,
+                kind: command.kind,
+                context: command.context,
+            };
+            host.parks.replace(key, () => buildPark(host, replacement));
+        }
+    }
+}
+//# sourceMappingURL=session-router-park.js.map

package/dist/modes/rpc/session-router-routing.d.ts

@@ -7,7 +7,7 @@ import type { RouterContext } from "./session-router-context.ts";
  */
 export declare function handle(host: RouterContext, command: RpcCommand): Promise<RpcResponse | undefined>;
 export declare function dispatch(host: RouterContext, command: Exclude<RpcCommand, {
-    type: "warm";
+    type: "warm" | "park_session";
 }>): Promise<RpcResponse | undefined>;
 /** Any attached connection may patch; a host with no per-connection identity (stdio) owns every session. */
 export declare function setSessionContext(host: RouterContext, command: Extract<RpcCommand, {

package/dist/modes/rpc/session-router-routing.js

@@ -24,6 +24,7 @@ import { answerListSessions, answerProtocolInfo, answerSubscriptionLimits } from
 import { acknowledgePrompt, otherRequestsSettled } from "./session-router-observation.js";
 import { sweepDrain } from "./session-router-occupancy.js";
 import { openWithBarrier } from "./session-router-open.js";
+import { claimSession, parkSession } from "./session-router-park.js";
 import { syncRetainedRecord } from "./session-router-residency.js";
 import { answerSetSessionContext, answerSubscribeSessions, answerUnsubscribeSessions, notAttachedRefusal, } from "./session-status-commands.js";
 import { unloadSession } from "./session-unload.js";
@@ -42,6 +43,10 @@ export function handle(host, command) {
     return ownership ? Promise.resolve(ownership) : admitted(host, command);
 }
 function admitted(host, command) {
+    if ("sessionId" in command && command.sessionId !== undefined && host.registry.peek(command.sessionId)?.speculative)
+        return Promise.resolve(error(command.id, command.type, "unknown_session"));
+    if (command.type === "park_session")
+        return parkSession(host, command);
     const refusal = attachmentGate(host, command) ?? compactAdmissionGate(host, command);
     if (refusal)
         return Promise.resolve(refusal);
@@ -117,6 +122,8 @@ export async function dispatch(host, command) {
         return detachConnection(command, host.writer.currentConnection(), (id) => releaseConnection(host, id));
     if (command.type === "open_session")
         return openWithBarrier(host, command);
+    if (command.type === "claim_session")
+        return claimSession(host, command);
     if (command.type === "attach_session")
         return attachSession(host, command);
     if (command.type === "release_attachment")