dsh-plugin-wsl-env 0.9.0 → 0.10.0

package/lib/native-agent.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Host-side plumbing for the optional native in-distro agent (ADR 0002).
+ *
+ * The shell agent is the shipped peer. This module is the opt-in path that
+ * lets the host run the spike/native binary instead, for the session runtime
+ * only:
+ *
+ *   1. read the binary from a host path (`DSH_WSL_AGENT_NATIVE`);
+ *   2. sha256 it and refuse an architecture the binary was not built for;
+ *   3. stream it into `~/.cache/dsh-wsl/agent/<sha>/dsh-wsl-agent` inside the
+ *      distro, chmod 0755, and verify the distro-side digest;
+ *   4. hand the resulting Linux path to the session-runtime factory.
+ *
+ * The binary is never executed from `/mnt/c` (DrvFs is often `noexec`), and a
+ * failed copy falls back to the shell agent — this module never throws to the
+ * command path.
+ *
+ * This is a TypeScript source built to `lib/native-agent.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/native-agent
+ */
+/** The host environment variable naming the native binary to opt in. */
+export declare const NATIVE_AGENT_ENV = "DSH_WSL_AGENT_NATIVE";
+/**
+ * The in-distro copy/verify script. The digest is embedded so `sh` needs no
+ * second argument and the cache path is derived from the content; stdout is
+ * the final Linux path the session runtime should execute.
+ *
+ * @param digest - lowercase hex sha256 of the binary.
+ * @returns the `sh -c` body (binary on stdin).
+ */
+export declare function nativeCacheScript(digest: string): string;
+/** The injectable edges. */
+export interface NativeBackendOptions {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro. */
+    distro: string;
+    /**
+     * The host path override (the development variable); empty resolves the
+     * packaged binary for the distro's architecture.
+     */
+    source: string;
+    /** The plugin package root; tests and non-standard layouts substitute it. */
+    packageRoot?: string;
+    /** Read the binary (tests substitute). */
+    readSource?: (path: string) => Promise<Buffer>;
+    /** Run a host command and return stdout (tests substitute). */
+    run?: (argv: string[]) => Promise<string>;
+    /** Copy the binary and return the Linux path (tests substitute). */
+    copy?: (script: string, binary: Buffer) => Promise<string>;
+}
+/** A prepared native binary: its in-distro path and the sha256 of its bytes. */
+export interface NativeBackendResult {
+    /** The Linux path the session runtime spawns. */
+    path: string;
+    /** Lowercase hex sha256; the agent's HELLO digest must match it. */
+    digest: string;
+}
+/**
+ * Copy the binary into the distro and verify it. The result is cached per
+ * `(wslPath, distro, source)`; a failure is cached as `undefined` for this
+ * process (the caller falls back to the shell agent).
+ *
+ * @param options - the transport, distro, source and injectables.
+ * @returns the Linux binary path and digest, or undefined when unusable.
+ */
+export declare function ensureNativeBackend({ wslPath, distro, source, packageRoot, readSource, run, copy, }: NativeBackendOptions): Promise<NativeBackendResult | undefined>;
+/**
+ * Forget the cache; tests only.
+ */
+export declare function clearNativeBackendCache(): void;
+/**
+ * Stream the binary to the distro on stdin, run the copy/verify script and
+ * return its stdout (the cache path).
+ *
+ * Exported for its regression check; the copy path is injectable in
+ * {@link ensureNativeBackend}.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the distro.
+ * @param script - the copy/verify script.
+ * @param binary - the binary bytes.
+ * @returns the Linux path printed by the script.
+ */
+export declare function copyBinary(wslPath: string, distro: string, script: string, binary: Buffer): Promise<string>;
+/** The session runtime's agent backend, from `wsl-shell.agentBackend`. */
+export type AgentBackend = "auto" | "native" | "shell";
+/**
+ * Record the selected backend. The session runtime is shared by the shell and
+ * filesystem providers, so this one process-wide value is what both read when
+ * they prepare their runtime; it is set from the `wsl-shell` config.
+ *
+ * @param mode - the selected backend.
+ */
+export declare function configureAgentBackend(mode: AgentBackend): void;
+/** @returns the configured backend (for diagnostics and tests). */
+export declare function configuredAgentBackend(): AgentBackend;
+/**
+ * Select the native binary for a distro when the backend allows it.
+ *
+ * - `shell`: clear any native entry and use the shipped shell agent.
+ * - `auto`: use the native binary when a source exists and copy/verify
+ *   succeeds; otherwise stay on the shell agent.
+ * - `native`: same preparation, but a missing source or a failed preparation
+ *   throws a remedy instead of silently falling back.
+ *
+ * The source is the development override `DSH_WSL_AGENT_NATIVE`; the packaged
+ * per-arch binary will be added by the packaging task and preferred over it.
+ *
+ * @param options - the transport, distro, setter and injectable prepare step.
+ */
+export declare function ensureNativeSessionAgent({ wslPath, distro, setNative, ensure, }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The resolved distro. */
+    distro: string;
+    /** Store (or clear, with an empty path) the distro's native entrypoint. */
+    setNative: (distro: string, path: string, digest: string) => void;
+    /** Prepare the binary; tests substitute. */
+    ensure?: (options: NativeBackendOptions) => Promise<NativeBackendResult | undefined>;
+}): Promise<void>;

package/lib/native-agent.js

@@ -0,0 +1,198 @@
+/**
+ * Host-side plumbing for the optional native in-distro agent (ADR 0002).
+ *
+ * The shell agent is the shipped peer. This module is the opt-in path that
+ * lets the host run the spike/native binary instead, for the session runtime
+ * only:
+ *
+ *   1. read the binary from a host path (`DSH_WSL_AGENT_NATIVE`);
+ *   2. sha256 it and refuse an architecture the binary was not built for;
+ *   3. stream it into `~/.cache/dsh-wsl/agent/<sha>/dsh-wsl-agent` inside the
+ *      distro, chmod 0755, and verify the distro-side digest;
+ *   4. hand the resulting Linux path to the session-runtime factory.
+ *
+ * The binary is never executed from `/mnt/c` (DrvFs is often `noexec`), and a
+ * failed copy falls back to the shell agent — this module never throws to the
+ * command path.
+ *
+ * This is a TypeScript source built to `lib/native-agent.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/native-agent
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pinnedWindowsEnv } from "./agent.js";
+import { runCapture } from "./wsl.js";
+/** The host environment variable naming the native binary to opt in. */
+export const NATIVE_AGENT_ENV = "DSH_WSL_AGENT_NATIVE";
+/** Distro `uname -m` values mapped to the packaged directory names. */
+const ARCHS = new Map([
+    ["x86_64", "x86_64"],
+    ["amd64", "x86_64"],
+    ["aarch64", "aarch64"],
+    ["arm64", "aarch64"],
+]);
+/** The plugin package root: `lib/native-agent.js` -> `<root>`. */
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+/**
+ * The in-distro copy/verify script. The digest is embedded so `sh` needs no
+ * second argument and the cache path is derived from the content; stdout is
+ * the final Linux path the session runtime should execute.
+ *
+ * @param digest - lowercase hex sha256 of the binary.
+ * @returns the `sh -c` body (binary on stdin).
+ */
+export function nativeCacheScript(digest) {
+    return [
+        "set -e",
+        "umask 077",
+        `dir="$HOME/.cache/dsh-wsl/agent/${digest}"`,
+        'target="$dir/dsh-wsl-agent"',
+        // A live session already runs this exact binary; rewriting it would fail
+        // with ETXTBSY. A valid cache is the same verified artifact, so reuse it.
+        `if [ -x "$target" ] && [ "$(sha256sum "$target" | cut -d' ' -f1)" = "${digest}" ]; then printf '%s' "$target"; exit 0; fi`,
+        'mkdir -p "$dir"',
+        'cat > "$target"',
+        'chmod 0755 "$target"',
+        "got=$(sha256sum \"$target\" | cut -d' ' -f1)",
+        `[ "$got" = "${digest}" ] || { echo digest-mismatch >&2; exit 1; }`,
+        '"$target" </dev/null >/dev/null 2>&1 || { echo cannot-execute >&2; exit 1; }',
+        'printf "%s" "$target"',
+    ].join("\n");
+}
+/**
+ * Copy the binary into the distro and verify it. The result is cached per
+ * `(wslPath, distro, source)`; a failure is cached as `undefined` for this
+ * process (the caller falls back to the shell agent).
+ *
+ * @param options - the transport, distro, source and injectables.
+ * @returns the Linux binary path and digest, or undefined when unusable.
+ */
+export async function ensureNativeBackend({ wslPath, distro, source, packageRoot = PACKAGE_ROOT, readSource = readFile, run = (argv) => runCapture(argv), copy, }) {
+    const key = `${wslPath}\u0000${distro}\u0000${source}\u0000${packageRoot}`;
+    const cached = NATIVE_CACHE.get(key);
+    if (cached !== undefined)
+        return cached;
+    const pending = (async () => {
+        const arch = (await run([wslPath, "-d", distro, "--exec", "uname", "-m"])).trim();
+        const normalized = ARCHS.get(arch);
+        if (normalized === undefined)
+            return undefined;
+        const hostPath = source.length > 0 ? source : join(packageRoot, "agent", "native", `linux-${normalized}`, "dsh-wsl-agent");
+        const binary = await readSource(hostPath);
+        const digest = createHash("sha256").update(binary).digest("hex");
+        const install = copy ?? ((script, bytes) => copyBinary(wslPath, distro, script, bytes));
+        const path = await install(nativeCacheScript(digest), binary);
+        return path.length > 0 ? { path, digest } : undefined;
+    })().catch(() => undefined);
+    NATIVE_CACHE.set(key, pending);
+    return pending;
+}
+/** The per-process cache; a failure is remembered as undefined. */
+const NATIVE_CACHE = new Map();
+/**
+ * Forget the cache; tests only.
+ */
+export function clearNativeBackendCache() {
+    NATIVE_CACHE.clear();
+}
+/**
+ * Stream the binary to the distro on stdin, run the copy/verify script and
+ * return its stdout (the cache path).
+ *
+ * Exported for its regression check; the copy path is injectable in
+ * {@link ensureNativeBackend}.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the distro.
+ * @param script - the copy/verify script.
+ * @param binary - the binary bytes.
+ * @returns the Linux path printed by the script.
+ */
+export function copyBinary(wslPath, distro, script, binary) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(wslPath, ["-d", distro, "--exec", "sh", "-c", script, "sh"], {
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            env: pinnedWindowsEnv(process.env),
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve(stdout.trim());
+            else
+                reject(new Error(stderr.trim() || `native agent copy exited with ${code}`));
+        });
+        // The script prints the cached path and exits WITHOUT reading stdin when
+        // the in-distro digest already matches. On Windows, finishing the binary
+        // write against that closed pipe surfaces as `write EOF` on stdin, and an
+        // unhandled stream error would take down the host process. The exit code
+        // and stdout above already decide the result, so absorb the write error.
+        child.stdin?.on("error", () => { });
+        try {
+            child.stdin?.end(binary);
+        }
+        catch {
+            // A pipe that is already gone is the same warm-cache case.
+        }
+    });
+}
+/** The process-wide mode; the shell executor's constructor owns it. */
+let backend = "auto";
+/**
+ * Record the selected backend. The session runtime is shared by the shell and
+ * filesystem providers, so this one process-wide value is what both read when
+ * they prepare their runtime; it is set from the `wsl-shell` config.
+ *
+ * @param mode - the selected backend.
+ */
+export function configureAgentBackend(mode) {
+    backend = mode;
+}
+/** @returns the configured backend (for diagnostics and tests). */
+export function configuredAgentBackend() {
+    return backend;
+}
+/**
+ * Select the native binary for a distro when the backend allows it.
+ *
+ * - `shell`: clear any native entry and use the shipped shell agent.
+ * - `auto`: use the native binary when a source exists and copy/verify
+ *   succeeds; otherwise stay on the shell agent.
+ * - `native`: same preparation, but a missing source or a failed preparation
+ *   throws a remedy instead of silently falling back.
+ *
+ * The source is the development override `DSH_WSL_AGENT_NATIVE`; the packaged
+ * per-arch binary will be added by the packaging task and preferred over it.
+ *
+ * @param options - the transport, distro, setter and injectable prepare step.
+ */
+export async function ensureNativeSessionAgent({ wslPath, distro, setNative, ensure = ensureNativeBackend, }) {
+    if (backend === "shell") {
+        setNative(distro, "", "");
+        return;
+    }
+    const result = await ensure({ wslPath, distro, source: process.env[NATIVE_AGENT_ENV] ?? "" });
+    if (result === undefined) {
+        if (backend === "native") {
+            throw new Error(`agentBackend: "native" could not prepare a native binary: the packaged binary for this architecture is missing or failed the copy/digest/execute check, and ${NATIVE_AGENT_ENV} is unset or unusable; set a valid ${NATIVE_AGENT_ENV}, or use "auto"/"shell".`);
+        }
+        return;
+    }
+    setNative(distro, result.path, result.digest);
+}

package/lib/ports.d.ts

@@ -38,7 +38,18 @@ export declare function procNetScript(): string;
  *
  * @param runner - the {@link WslAgent}-like runner.
  * @param timeoutMs - the exec budget.
- * @returns listening ports, ascending; [] on any failure — a snapshot is a
- *   convenience, never an error the session should see.
+ * @returns listening ports, ascending; undefined when the scan could not
+ *   answer (agent out, non-zero exit), so a caller can keep the last snapshot.
+ */
+export declare function scanListeningPorts(runner: AgentExecRunner, timeoutMs?: number): Promise<number[] | undefined>;
+/**
+ * Snapshot the distro's listening ports, collapsing a failed scan to an empty
+ * list. New callers that must distinguish "none listening" from "the scan
+ * failed" should use {@linkcode scanListeningPorts}; this wrapper exists for
+ * the probe/test shape that only needs the list.
+ *
+ * @param runner - the agent-like runner.
+ * @param timeoutMs - the exec budget.
+ * @returns listening ports, ascending; [] on a failed scan.
  */
 export declare function listeningPorts(runner: AgentExecRunner, timeoutMs?: number): Promise<number[]>;

package/lib/ports.js

@@ -55,17 +55,30 @@ export function procNetScript() {
  *
  * @param runner - the {@link WslAgent}-like runner.
  * @param timeoutMs - the exec budget.
- * @returns listening ports, ascending; [] on any failure — a snapshot is a
- *   convenience, never an error the session should see.
+ * @returns listening ports, ascending; undefined when the scan could not
+ *   answer (agent out, non-zero exit), so a caller can keep the last snapshot.
  */
-export async function listeningPorts(runner, timeoutMs = 10000) {
+export async function scanListeningPorts(runner, timeoutMs = 10000) {
     try {
         const result = await runner.exec({ cwd: "/", argv: ["sh", "-c", procNetScript(), "ports"], timeoutMs });
         if (result.exitCode !== 0)
-            return [];
+            return undefined;
         return parseListeningPorts(result.stdout.toString("utf8"));
     }
     catch {
-        return [];
+        return undefined;
     }
 }
+/**
+ * Snapshot the distro's listening ports, collapsing a failed scan to an empty
+ * list. New callers that must distinguish "none listening" from "the scan
+ * failed" should use {@linkcode scanListeningPorts}; this wrapper exists for
+ * the probe/test shape that only needs the list.
+ *
+ * @param runner - the agent-like runner.
+ * @param timeoutMs - the exec budget.
+ * @returns listening ports, ascending; [] on a failed scan.
+ */
+export async function listeningPorts(runner, timeoutMs = 10000) {
+    return (await scanListeningPorts(runner, timeoutMs)) ?? [];
+}

package/lib/preflight.js

@@ -25,8 +25,9 @@
  */
 import z from "@deepseek-ai/schemastery";
 import { isWslUnc } from "./paths.js";
-import { defaultDistro } from "./wsl.js";
+import { defaultDistro, runCapture } from "./wsl.js";
 import { bwrapFailure, bwrapUsable, missingBwrapRemedy } from "./sandbox-core.js";
+import { sessionScopeSweepScript } from "./session-scope.js";
 export const name = "wsl-preflight";
 export const Config = z.object({
     /** Distro to preflight; empty means this machine's default distro. */
@@ -36,6 +37,25 @@ export const Config = z.object({
     /** Whether the session-start sandbox preflight runs at all. */
     sandbox: z.boolean().default(true),
 });
+/** Distros whose stale-scope sweep has already run in this process. */
+const sweptDistros = new Set();
+/**
+ * Stop `dsh-wsl-*.scope` units a crashed app left behind. A scope is stale
+ * when its cgroup has no `wsl-agent.sh`; a live agent means another session
+ * still owns it. Advisory: a failed spawn re-arms the distro for the next
+ * session, and the once-per-distro cache keeps the cost off the normal path.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the resolved distro.
+ */
+const sweepStaleScopes = (wslPath, distro) => {
+    if (sweptDistros.has(distro))
+        return;
+    sweptDistros.add(distro);
+    void runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", sessionScopeSweepScript()]).catch(() => {
+        sweptDistros.delete(distro);
+    });
+};
 /**
  * Mount the preflight service.
  *
@@ -73,6 +93,9 @@ export async function apply(ctx, config = {}) {
         // bwrapUsable answers false on a failed probe — it never rejects — so
         // nothing here can throw except a broken context, which is the caller's
         // bug, not the session's.
+        // Clean up what a hard crash left behind before this session creates its
+        // runtime; a live agent in another session's cgroup makes its scope safe.
+        sweepStaleScopes(wslPath, distro);
         const usable = await bwrapUsable({ wslPath, distro });
         if (usable) {
             ctx.logger?.debug?.(`wsl-preflight: bwrap is usable inside distro "${distro}"`);

package/lib/session-runtime.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The session-scoped runtime registry (ADR 0001).
+ *
+ * One long-lived agent per `(distro, workspaceRoot, policy)`, shared by the
+ * providers that need it and refcounted: the first `acquire` spawns the agent
+ * inside a systemd user scope, the last `release` closes the agent and stops
+ * the scope (the cgroup then reaps any background dev server a command left
+ * behind). The agent runs with no idle close — its lifetime is the session's —
+ * but an explicit client lease still catches a wedged host.
+ *
+ * The confinement here is the agent's own bwrap mount profile, WITHOUT a PID
+ * namespace: commands are the agent's children, so a background process
+ * survives the command, `/tmp` is the distro's real `/tmp` under
+ * `workspace-write`, and `ps` sees the session. `danger-full-access` gets the
+ * scope but no mounts.
+ *
+ * Nothing in this module touches `wsl.exe` by default except through the
+ * injectable factories; `test/session-runtime.test.mjs` drives the refcount,
+ * the prefix composition and the stop ordering without systemd.
+ *
+ * This is a TypeScript source built to `lib/session-runtime.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/session-runtime
+ */
+import { WslAgent } from "./agent.js";
+/**
+ * Run the session runtime's preflight through an injected host runner and map
+ * the answer to a refusal. Shared by the shell executor and the filesystem
+ * provider, so both gate the runtime on the same four requirements.
+ *
+ * @param options - the transport, distro and runner.
+ * @returns the remedy-bearing refusal, or null when the platform is usable.
+ */
+export declare function probeSessionRuntime({ wslPath, distro, run }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro name. */
+    distro: string;
+    /** The host runner; throws when the probe could not run. */
+    run: (argv: string[]) => Promise<string>;
+}): Promise<string | null>;
+/** One request for a session runtime. */
+export interface SessionRuntimeRequest {
+    /** The distro the runtime lives in. */
+    distro: string;
+    /** The `wsl.exe` path; defaults to `wsl.exe`. */
+    wslPath?: string;
+    /** The session workspace root, in any coordinate system. */
+    workspaceRoot: string;
+    /** The resolved file-effect mode (`read-only`, `workspace-write`, `danger-full-access`). */
+    mode: string;
+    /** Shadow `/mnt` in the runtime's mount profile. */
+    maskWindowsDrive?: boolean;
+    /** The agent's client lease; 0 disables. */
+    leaseMs?: number;
+}
+/** One live runtime and its refcount. */
+export interface SessionRuntimeEntry {
+    /** The registry key (`distro`, workspace, mode, mask). */
+    key: string;
+    /** The systemd user unit name. */
+    unit: string;
+    /** The resident agent. */
+    agent: WslAgent;
+    /** The distro, for the stop command. */
+    distro: string;
+    /** The `wsl.exe` path, for the stop command. */
+    wslPath: string;
+    /** How many providers hold the runtime. */
+    refs: number;
+}
+/** The injectable edges, so the registry is testable without systemd. */
+export interface SessionRuntimeOptions {
+    /** Create the agent; tests substitute a fake. */
+    spawnAgent?: (options: {
+        /** The distro. */
+        distro: string;
+        /** The `wsl.exe` path. */
+        wslPath: string;
+        /** The scope + mount prefix. */
+        argvPrefix: string[];
+        /** No idle close: the runtime lives for the session. */
+        idleMs: number;
+        /** The explicit client lease. */
+        leaseMs: number;
+        /** The prefix has no PID namespace, so USR1 can reach the agent. */
+        signalable: boolean;
+    }) => WslAgent;
+    /** Stop the scope; tests record it. */
+    stopScope?: (options: {
+        wslPath: string;
+        distro: string;
+        unit: string;
+    }) => void;
+    /** The unique token in the unit name; tests pin it. */
+    token?: () => string;
+}
+/**
+ * Set (or clear) the native binary the session runtime should spawn for one
+ * distro. The host calls this after the copy/verify step; an empty path
+ * clears it and restores the shell agent.
+ *
+ * @param distro - the distro.
+ * @param path - the Linux binary path, or empty to clear.
+ * @param digest - the binary's sha256, which the HELLO must present.
+ */
+export declare function setSessionNativeAgent(distro: string, path: string, digest?: string): void;
+/**
+ * The refcounted registry. One instance lives for the process; providers share
+ * it so the shell and filesystem sides address the same runtime for a session.
+ */
+export declare class SessionRuntimes {
+    /** The live runtimes, by key. */
+    private readonly runtimes;
+    /** The agent factory. */
+    private readonly spawnAgent;
+    /** The scope stopper. */
+    private readonly stopScope;
+    /** The unit-token generator. */
+    private readonly token;
+    /**
+     * @param options - the injectable edges; production passes none.
+     */
+    constructor(options?: SessionRuntimeOptions);
+    /**
+     * The key a request addresses: distro, workspace, mode and mask. A policy
+     * change is a different runtime, because the mount profile is fixed for the
+     * agent's lifetime.
+     *
+     * @param request - the runtime request.
+     * @returns the registry key.
+     */
+    static key(request: Pick<SessionRuntimeRequest, "distro" | "workspaceRoot" | "mode" | "maskWindowsDrive">): string;
+    /**
+     * Acquire the runtime for one key, creating it on first use.
+     *
+     * @param request - the runtime request.
+     * @returns the live entry; the caller holds one reference.
+     */
+    acquire(request: SessionRuntimeRequest): SessionRuntimeEntry;
+    /**
+     * Release one reference. The last release closes the agent and stops the
+     * scope, in that order: the agent's exit ends the protocol, the stop reaps
+     * whatever the session left running.
+     *
+     * @param key - the entry's key.
+     * @returns resolved once the last holder's teardown finished.
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Release every runtime, for a host shutdown or a test. Sequential on
+     * purpose: concurrent closes would race the shared agent's state.
+     *
+     * @returns resolved once every runtime is torn down.
+     */
+    disposeAll(): Promise<void>;
+}
+/** The process-wide registry the providers will share. */
+export declare const sessionRuntimes: SessionRuntimes;