@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/acpx-engine/run-site-sandbox.test.js

@@ -0,0 +1,275 @@
+// Tests for the sandbox run site (Phase 19).
+//
+// The sandbox site owns staging, the staging lease, both bridges, the launch-
+// environment contribution, and sync-back. These tests drive the site in
+// isolation with fakes: they pin the ledger registrations, the bridge overlap and
+// the callback-environment sequencing point, the staged-files reuse (which still
+// creates the runtime), the synchronous plan, and Amendment B — no run-scoped
+// contribution or bridge token escapes into the ledger or the reuse payload.
+import { describe, expect, it } from "vitest";
+import { createSandboxRunSite, } from "./run-site-sandbox.js";
+function makeStagedRuntime(id) {
+    return {
+        runtimeRootDir: `/remote/${id}/.paperclip-runtime/acpx`,
+        additionalSourceDirs: {},
+        additionalSourceFailures: [],
+    };
+}
+function makeLedger() {
+    const registered = [];
+    const ledger = {
+        register(registration) {
+            registered.push(registration);
+        },
+        seal() {
+            throw new Error("seal is not exercised by these unit tests");
+        },
+        takeForSettlement() {
+            throw new Error("takeForSettlement is not exercised by these unit tests");
+        },
+    };
+    return { ledger, registered };
+}
+function makeContext(sessionKey) {
+    return { sessionKey };
+}
+/** Build a site over injectable fakes. Every option has a sensible default. */
+function makeSite(overrides = {}) {
+    const { ledger, registered } = makeLedger();
+    const env = { BASE: "1" };
+    const stagedRuntimes = new Map();
+    const stagingLocks = new Map();
+    const freshStaged = makeStagedRuntime("fresh");
+    const bridgeCalls = [];
+    const options = {
+        ledger,
+        stagedRuntimes,
+        stagingLocks,
+        now: () => 1000,
+        idleMs: 60_000,
+        sessionCwd: "/remote/workspace",
+        spawnCwd: "/host/workspace",
+        target: { kind: "remote" },
+        env,
+        isCompatibleResume: false,
+        stage: async () => freshStaged,
+        seedManagedHome: async (stage) => {
+            const stagedRuntime = await stage([]);
+            // Repoint a managed-home env var, so the site captures the delta.
+            env.CODEX_HOME = "/remote/home";
+            return {
+                stagedRuntime,
+                teardown: async () => ({ ok: true }),
+                dispose: async () => { },
+            };
+        },
+        disposeFreshStagedRuntime: async () => { },
+        measureStageStep: (run) => run(),
+        publishStagedProjectHints: () => { },
+        onReuseLog: async () => { },
+        startPaperclipBridge: async () => {
+            bridgeCalls.push("paperclip:start");
+            return { env: { PAPERCLIP_API_KEY: "run-token" }, stop: async () => { } };
+        },
+        startProcessSessionBridge: async ({ launchEnv }) => {
+            bridgeCalls.push("process-session:start");
+            await launchEnv();
+            return { agentCommand: null, stop: async () => { } };
+        },
+        measureBridgeStep: (_step, run) => run(),
+        finalizeLaunchEnv: (contributions) => {
+            const merged = { ...env };
+            for (const contribution of contributions)
+                Object.assign(merged, contribution.env);
+            return merged;
+        },
+        onPaperclipBridgeLog: async () => { },
+        stopBridges: async () => { },
+        ...overrides,
+    };
+    const site = createSandboxRunSite(options);
+    return { site, ledger, registered, env, stagedRuntimes, stagingLocks, freshStaged, bridgeCalls, options };
+}
+/** A minimal `ReadyRunResources` that resolves a single staged runtime. */
+function makeReady(stagedRuntime) {
+    const staged = { stagedRuntime, disposeStaged: async () => { } };
+    return {
+        get: (id) => (id === "staged_runtime" ? staged : undefined),
+        scopeOf: () => undefined,
+        has: (id) => id === "staged_runtime",
+        sealed: ["staged_runtime"],
+    };
+}
+describe("sandbox run site", () => {
+    it("test_sandbox_site_registers_staging_bridges_and_lease_in_ledger", async () => {
+        const { site, registered } = makeSite();
+        await site.placeWorkspace(makeContext("paperclip:c:a:t:fp"));
+        await site.startTransport(makeContext("paperclip:c:a:t:fp"));
+        const byId = new Set(registered.map((entry) => entry.id));
+        // Staging registers the staged runtime, the managed-home copy-back, and the
+        // per-session staging lease. Both bridge starts register their handles.
+        expect(byId).toEqual(new Set(["staged_runtime", "managed_home", "staging_lease", "control_bridge", "agent_bridge"]));
+        // The staged runtime is startup-rollback until a clean turn promotes it; the
+        // copy-back, the lease, and the bridges live through the whole run.
+        const scopeOf = (id) => registered.find((entry) => entry.id === id)?.scope;
+        expect(scopeOf("staged_runtime")).toBe("startup_rollback");
+        expect(scopeOf("managed_home")).toBe("per_run");
+        expect(scopeOf("staging_lease")).toBe("per_run");
+        expect(scopeOf("control_bridge")).toBe("per_run");
+        expect(scopeOf("agent_bridge")).toBe("per_run");
+    });
+    it("test_sandbox_site_place_workspace_carries_referenced_project_failure_reason", async () => {
+        // A referenced project that fails to stage carries its failure reason back on
+        // the placed-workspace result, so a reader of the run learns why it dropped.
+        const failedStaged = {
+            runtimeRootDir: "/remote/fail/.paperclip-runtime/acpx",
+            additionalSourceDirs: {},
+            additionalSourceFailures: [{ projectId: "proj-x", error: "extract failed: boom" }],
+        };
+        const { site } = makeSite({ stage: async () => failedStaged });
+        const placed = await site.placeWorkspace(makeContext("s"));
+        expect(placed).toEqual({
+            referencedProjectStagingFailures: [{ projectId: "proj-x", error: "extract failed: boom" }],
+        });
+    });
+    it("test_sandbox_site_preserves_bridge_overlap_and_callback_sequencing", async () => {
+        const events = [];
+        let releasePaperclip;
+        const paperclipGate = new Promise((resolve) => {
+            releasePaperclip = resolve;
+        });
+        let processLaunchEnv = null;
+        const { site } = makeSite({
+            startPaperclipBridge: async () => {
+                events.push("paperclip:start");
+                await paperclipGate;
+                events.push("paperclip:env-ready");
+                return { env: { PAPERCLIP_API_KEY: "run-token" }, stop: async () => { } };
+            },
+            startProcessSessionBridge: async ({ launchEnv }) => {
+                events.push("process-session:start");
+                // The launch awaits the sequencing point, so it observes the merged env.
+                processLaunchEnv = await launchEnv();
+                events.push("process-session:launch");
+                return { agentCommand: null, stop: async () => { } };
+            },
+        });
+        await site.placeWorkspace(makeContext("s"));
+        const transportPromise = site.startTransport(makeContext("s"));
+        // Both bridges start before the paperclip env resolves: their setup overlaps.
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(events).toContain("paperclip:start");
+        expect(events).toContain("process-session:start");
+        expect(events).not.toContain("process-session:launch");
+        // Release the paperclip env; the process-session launch now observes the
+        // merged run-scoped env (the single sequencing point).
+        releasePaperclip();
+        const transport = await transportPromise;
+        expect(events.indexOf("paperclip:env-ready")).toBeLessThan(events.indexOf("process-session:launch"));
+        expect(processLaunchEnv).toEqual({ BASE: "1", CODEX_HOME: "/remote/home", PAPERCLIP_API_KEY: "run-token" });
+        expect(transport.launchEnv).toEqual(processLaunchEnv);
+    });
+    it("test_sandbox_site_session_new_starts_only_after_the_sync_barrier_settles", async () => {
+        // The staging step wraps the inbound sync coordinator. Hold it open with a
+        // gate, so the sync barrier stays unsettled. `placeWorkspace` awaits staging,
+        // so it stays pending while the gate is held.
+        let releaseStaging;
+        const stagingGate = new Promise((resolve) => {
+            releaseStaging = resolve;
+        });
+        const freshStaged = makeStagedRuntime("fresh");
+        const { site, bridgeCalls } = makeSite({
+            stage: async () => {
+                await stagingGate;
+                return freshStaged;
+            },
+        });
+        // Drive the real run order: the engine awaits `placeWorkspace`, then starts the
+        // transport. `startProcessSessionBridge` models the ACP `session/new` startup.
+        let placed = false;
+        const run = (async () => {
+            await site.placeWorkspace(makeContext("s"));
+            placed = true;
+            await site.startTransport(makeContext("s"));
+        })();
+        run.catch(() => undefined);
+        // The sync barrier is still open, so `placeWorkspace` has not resolved and the
+        // process-session bridge that starts `session/new` has not started.
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(placed).toBe(false);
+        expect(bridgeCalls).not.toContain("process-session:start");
+        // Settle the sync barrier. `placeWorkspace` resolves, then the transport starts
+        // `session/new`.
+        releaseStaging();
+        await run;
+        expect(placed).toBe(true);
+        expect(bridgeCalls).toContain("process-session:start");
+    });
+    it("test_sandbox_site_borrow_yields_files_and_runtime_is_still_created", async () => {
+        const cachedRuntime = makeStagedRuntime("cached");
+        const stagedRuntimes = new Map([
+            [
+                "paperclip:c:a:t:fp",
+                {
+                    stagedRuntime: cachedRuntime,
+                    envDelta: { CODEX_HOME: "/remote/home" },
+                    teardown: async () => ({ ok: true }),
+                    dispose: async () => { },
+                    lastUsedAt: 500,
+                },
+            ],
+        ]);
+        const { site, env } = makeSite({ stagedRuntimes, isCompatibleResume: true });
+        // A borrow reads the staged entry without removal, so an overlapping run of
+        // the same session still reads it.
+        const borrowed = site.reuse().borrow("paperclip:c:a:t:fp");
+        expect(borrowed?.stagedRuntime).toBe(cachedRuntime);
+        expect(stagedRuntimes.has("paperclip:c:a:t:fp")).toBe(true);
+        // A reuse hit yields the staged FILES (not a live runtime): `placeWorkspace`
+        // reports `reused` and re-applies the seam env delta, and the reuse candidate
+        // names the staged files only. So the run still creates the runtime and runs
+        // the handshake against the reused files.
+        await site.placeWorkspace(makeContext("paperclip:c:a:t:fp"));
+        expect(site.staged?.reused).toBe(true);
+        expect(site.staged?.stagedRuntime).toBe(cachedRuntime);
+        expect(env.CODEX_HOME).toBe("/remote/home");
+        const candidate = site.reuseCandidate(makeReady(cachedRuntime));
+        expect(candidate).toEqual({ stagedRuntime: cachedRuntime });
+        expect("runtime" in candidate).toBe(false);
+        expect("sessionHandle" in candidate).toBe(false);
+    });
+    it("test_site_plan_supplies_session_cwd_spawn_cwd_and_tracing_before_the_fingerprint_build", () => {
+        const { site } = makeSite();
+        // `plan()` is synchronous and reads no staged state, so it runs before the
+        // fingerprint build. It binds the session to the in-sandbox cwd, redirects the
+        // relay-proxy spawn to the host cwd, and enables sandbox tracing.
+        expect(site.plan(makeContext("s"))).toEqual({
+            sessionCwd: "/remote/workspace",
+            spawnCwd: "/host/workspace",
+            tracingEnabled: true,
+        });
+    });
+    it("test_bridge_contribution_is_not_retained_by_site_ledger_or_reuse_payload", async () => {
+        const { site, registered } = makeSite();
+        await site.placeWorkspace(makeContext("s"));
+        const transport = await site.startTransport(makeContext("s"));
+        // The ledger holds the bridge HANDLES, never the run-scoped token env.
+        const control = registered.find((entry) => entry.id === "control_bridge");
+        expect(control?.payload).toBe(transport.controlBridge);
+        // The staged reuse payload carries the staged files only — no credential
+        // material and no bridge token.
+        const candidate = site.reuseCandidate(makeReady(site.staged.stagedRuntime));
+        expect(Object.keys(candidate)).toEqual(["stagedRuntime"]);
+        // Compile-time (Amendment B): a run-scoped contribution is not assignable to
+        // the staged reuse payload. This function never runs; the assertion holds at
+        // typecheck only. A runtime call on a synthetic value would crash.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        function _staged_reuse_payload_rejects_a_run_scoped_contribution(contribution) {
+            // @ts-expect-error a launch-environment contribution is not a staged reuse payload
+            const payload = contribution;
+            void payload;
+        }
+    });
+});
+//# sourceMappingURL=run-site-sandbox.test.js.map

package/dist/acpx-engine/run-site-sandbox.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-site-sandbox.test.js","sourceRoot":"","sources":["../../src/acpx-engine/run-site-sandbox.test.ts"],"names":[],"mappings":"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"}

package/dist/acpx-engine/session-codec.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterSessionCodec } from "@tickernelz/paperclip-pro-adapter-utils";
+export declare const sessionCodec: AdapterSessionCodec;
+//# sourceMappingURL=session-codec.d.ts.map

package/dist/acpx-engine/session-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-codec.d.ts","sourceRoot":"","sources":["../../src/acpx-engine/session-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAUnF,eAAO,MAAM,YAAY,EAAE,mBAwC1B,CAAC"}

package/dist/acpx-engine/session-codec.js

@@ -0,0 +1,49 @@
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function readRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? { ...value } : null;
+}
+export const sessionCodec = {
+    deserialize(raw) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return null;
+        const record = raw;
+        const runtimeSessionName = readString(record.runtimeSessionName);
+        const acpSessionId = readString(record.acpSessionId);
+        const agentSessionId = readString(record.agentSessionId);
+        const remoteExecution = readRecord(record.remoteExecution);
+        if (!runtimeSessionName && !acpSessionId && !agentSessionId)
+            return null;
+        return {
+            ...(runtimeSessionName ? { runtimeSessionName } : {}),
+            ...(record.interruptedCheckpoint === true ? { interruptedCheckpoint: true } : {}),
+            ...(readString(record.sessionKey) ? { sessionKey: readString(record.sessionKey) } : {}),
+            ...(readString(record.acpxRecordId) ? { acpxRecordId: readString(record.acpxRecordId) } : {}),
+            ...(acpSessionId ? { acpSessionId } : {}),
+            ...(agentSessionId ? { agentSessionId } : {}),
+            ...(readString(record.agent) ? { agent: readString(record.agent) } : {}),
+            ...(readString(record.cwd) ? { cwd: readString(record.cwd) } : {}),
+            ...(readString(record.mode) ? { mode: readString(record.mode) } : {}),
+            ...(readString(record.stateDir) ? { stateDir: readString(record.stateDir) } : {}),
+            ...(readString(record.configFingerprint) ? { configFingerprint: readString(record.configFingerprint) } : {}),
+            ...(readString(record.workspaceId) ? { workspaceId: readString(record.workspaceId) } : {}),
+            ...(readString(record.repoUrl) ? { repoUrl: readString(record.repoUrl) } : {}),
+            ...(readString(record.repoRef) ? { repoRef: readString(record.repoRef) } : {}),
+            ...(remoteExecution ? { remoteExecution } : {}),
+        };
+    },
+    serialize(params) {
+        if (!params)
+            return null;
+        return this.deserialize(params);
+    },
+    getDisplayId(params) {
+        if (!params)
+            return null;
+        return (readString(params.runtimeSessionName) ??
+            readString(params.acpSessionId) ??
+            readString(params.agentSessionId));
+    },
+};
+//# sourceMappingURL=session-codec.js.map

package/dist/acpx-engine/session-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-codec.js","sourceRoot":"","sources":["../../src/acpx-engine/session-codec.ts"],"names":[],"mappings":"AAEA,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAI,KAAiC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACjI,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAwB;IAC/C,WAAW,CAAC,GAAY;QACtB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/E,MAAM,MAAM,GAAG,GAA8B,CAAC;QAC9C,MAAM,kBAAkB,GAAG,UAAU,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACjE,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACrD,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACzD,MAAM,eAAe,GAAG,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC3D,IAAI,CAAC,kBAAkB,IAAI,CAAC,YAAY,IAAI,CAAC,cAAc;YAAE,OAAO,IAAI,CAAC;QAEzE,OAAO;YACL,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,MAAM,CAAC,qBAAqB,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7F,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,UAAU,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5G,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1F,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC;IACJ,CAAC;IACD,SAAS,CAAC,MAAsC;QAC9C,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IACD,YAAY,CAAC,MAAsC;QACjD,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO,CACL,UAAU,CAAC,MAAM,CAAC,kBAAkB,CAAC;YACrC,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC;YAC/B,UAAU,CAAC,MAAM,CAAC,cAAc,CAAC,CAClC,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/acpx-engine/session-reuse-store.d.ts

@@ -0,0 +1,62 @@
+import type { SessionReuseStore } from "./run-contracts.js";
+/**
+ * The construction options for a reuse store. The public `SessionReuseStore<T>`
+ * surface stays generic; these options carry the per-lane behavior the store
+ * needs but the interface does not name: the backing map, the clock, the idle
+ * bound, how to read an entry's last-used time and per-entry timer, how to
+ * release an entry, whether to arm a per-entry timer, and the optional eviction
+ * lease.
+ */
+export interface SessionReuseStoreConfig<T> {
+    /**
+     * The map the store reads and writes. The caller owns it, so a caller that
+     * inspects the map still reads the same entries. The map persists across runs.
+     */
+    readonly entries: Map<string, T>;
+    /** The clock. The store reads it for the idle deadline and the sweep. */
+    readonly now: () => number;
+    /**
+     * The idle bound, in milliseconds. When it is `0` or less, the store arms no
+     * per-entry timer and the sweep evicts nothing.
+     */
+    readonly idleMs: number;
+    /** Read an entry's last-used time. The store compares it to the idle bound. */
+    readonly lastUsedAt: (entry: T) => number;
+    /**
+     * Release an entry's resources. The store calls it once per entry on a
+     * discard, on a per-entry timer fire, or on an idle sweep. The store guards
+     * every release with a map-identity check, so a discarded entry never
+     * releases twice.
+     */
+    readonly release: (entry: T) => void | Promise<void>;
+    /**
+     * Read an entry's per-entry idle timer, or `undefined` when it holds none.
+     * The host lane supplies this; the sandbox lane omits it and arms no timer.
+     */
+    readonly getTimer?: (entry: T) => ReturnType<typeof setTimeout> | undefined;
+    /**
+     * Write (or clear with `undefined`) an entry's per-entry idle timer. The host
+     * lane supplies this; the sandbox lane omits it.
+     */
+    readonly setTimer?: (entry: T, timer: ReturnType<typeof setTimeout> | undefined) => void;
+    /**
+     * Arm a per-entry idle timer on `save`. The host lane sets it true. The
+     * sandbox lane leaves it false and relies on the run-start sweep only.
+     */
+    readonly perEntryTimer?: boolean;
+    /**
+     * Run each eviction critical section under a per-key lease. The sandbox lane
+     * supplies its per-key staging lease so the sweep re-checks the entry inside
+     * the lease. The host lane omits it and the sweep runs the critical section
+     * directly.
+     */
+    readonly withEvictLease?: (key: string, critical: () => Promise<void>) => Promise<void>;
+}
+/**
+ * Create a generic per-session reuse store over the caller-provided map. The
+ * store holds at most one entry per session key. Each entry carries its saved
+ * value, its last-used time, and an optional per-entry idle timer, all read
+ * through the config accessors.
+ */
+export declare function createSessionReuseStore<T>(config: SessionReuseStoreConfig<T>): SessionReuseStore<T>;
+//# sourceMappingURL=session-reuse-store.d.ts.map

package/dist/acpx-engine/session-reuse-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reuse-store.d.ts","sourceRoot":"","sources":["../../src/acpx-engine/session-reuse-store.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,SAAS,CAAC;IAC5E;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;IACzF;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACjC,iBAAiB,CAAC,CAAC,CAAC,CA2FtB"}

package/dist/acpx-engine/session-reuse-store.js

@@ -0,0 +1,134 @@
+// The generic per-session reuse store.
+//
+// One `SessionReuseStore<T>` implementation backs both site caches. The host
+// site saves a live runtime and session handle. The sandbox site saves the
+// staged files. The store is generic in the saved type, so a generic `save`
+// cannot read what a site saves. `RunSite.reuseCandidate()` names the concrete
+// type per site.
+//
+// The store operates OVER a caller-provided map, not a private internal map.
+// The host lane passes its warm-handle map; the sandbox lane passes its staged-
+// runtime map. Both maps persist across runs, so a saved entry stays visible to
+// a later run of the same session. Each entry carries its own last-used time and
+// its own optional per-entry idle timer, so the store reads and writes those
+// through the caller-supplied accessors. This keeps the exact shape both caches
+// had before this refactor, so a caller that inspects the map still reads the
+// same entries.
+//
+// The store keeps the exact behavior the two caches had before this refactor:
+//
+//   * `borrow` reads without removal. It keeps today's visibility for
+//     overlapping runs of the same session. It clears the entry's per-entry
+//     idle timer, because an in-use entry must not expire under its own timer.
+//   * `save` sets the entry in the map. When the store has a per-entry idle
+//     timer, `save` arms an unref'd timer that discards the entry at the idle
+//     deadline without a run (today's `scheduleIdleHandleCleanup`).
+//   * `discard` is an identity-guarded removal that fires the idempotent
+//     release once. It acts on the entry that is at the key now, so a re-saved
+//     entry is safe and a second discard is a no-op.
+//   * `evictIdle` is the run-start sweep (today's `cleanupIdleHandles` and
+//     `cleanupIdleStagedRuntimes`). The host lane runs the critical section
+//     directly. The sandbox lane runs it under its per-key staging lease and
+//     re-checks the idle window inside the lease.
+/**
+ * Create a generic per-session reuse store over the caller-provided map. The
+ * store holds at most one entry per session key. Each entry carries its saved
+ * value, its last-used time, and an optional per-entry idle timer, all read
+ * through the config accessors.
+ */
+export function createSessionReuseStore(config) {
+    const { entries } = config;
+    function clearEntryTimer(entry) {
+        const timer = config.getTimer?.(entry);
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        config.setTimer?.(entry, undefined);
+    }
+    // Release an entry once and drop it from the map when it is still the current
+    // entry at the key. The map-identity guard makes the release idempotent: the
+    // synchronous `delete` runs before the awaited release, so a second release of
+    // the same entry finds a different or absent entry at the key and stops.
+    async function releaseEntry(key, entry) {
+        clearEntryTimer(entry);
+        if (entries.get(key) !== entry)
+            return;
+        entries.delete(key);
+        await config.release(entry);
+    }
+    function armTimer(key, entry) {
+        if (!config.perEntryTimer || config.idleMs <= 0)
+            return;
+        clearEntryTimer(entry);
+        const delayMs = Math.max(1, config.lastUsedAt(entry) + config.idleMs - config.now());
+        const timer = setTimeout(() => {
+            void (async () => {
+                if (entries.get(key) !== entry)
+                    return;
+                // A later touch can move `lastUsedAt` forward, so re-check the idle
+                // window and re-arm the timer when the entry is still in use.
+                if (config.now() - config.lastUsedAt(entry) < config.idleMs) {
+                    armTimer(key, entry);
+                    return;
+                }
+                await releaseEntry(key, entry);
+            })();
+        }, delayMs);
+        timer.unref?.();
+        config.setTimer?.(entry, timer);
+    }
+    return {
+        borrow(sessionKey) {
+            const entry = entries.get(sessionKey);
+            if (entry === undefined)
+                return undefined;
+            // The entry is in use now, so clear its per-entry idle timer. The next
+            // `save` re-arms a fresh timer after the run finishes.
+            clearEntryTimer(entry);
+            return entry;
+        },
+        save(sessionKey, entry) {
+            // The caller sets the entry's last-used time before it saves, so `save`
+            // sets the entry as-is and arms its timer from that time.
+            entries.set(sessionKey, entry);
+            armTimer(sessionKey, entry);
+        },
+        discard(sessionKey) {
+            const entry = entries.get(sessionKey);
+            // `releaseEntry` deletes the key synchronously and then fires the release,
+            // so the returned promise lets the caller await the release when it must
+            // finish before a downstream resource release.
+            if (entry === undefined)
+                return Promise.resolve();
+            return releaseEntry(sessionKey, entry);
+        },
+        async evictIdle(now) {
+            if (config.idleMs <= 0)
+                return;
+            const stale = [];
+            for (const [key, entry] of entries.entries()) {
+                if (now - config.lastUsedAt(entry) >= config.idleMs)
+                    stale.push([key, entry]);
+            }
+            for (const [key, entry] of stale) {
+                const critical = async () => {
+                    if (entries.get(key) !== entry)
+                        return;
+                    // Under a lease the sweep re-checks the idle window, so a run that
+                    // re-saved the key while the lease was held keeps its entry.
+                    if (config.withEvictLease && config.now() - config.lastUsedAt(entry) < config.idleMs) {
+                        return;
+                    }
+                    await releaseEntry(key, entry);
+                };
+                if (config.withEvictLease) {
+                    await config.withEvictLease(key, critical);
+                }
+                else {
+                    await critical();
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=session-reuse-store.js.map

package/dist/acpx-engine/session-reuse-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reuse-store.js","sourceRoot":"","sources":["../../src/acpx-engine/session-reuse-store.ts"],"names":[],"mappings":"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"}

package/dist/acpx-engine/session-reuse-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-reuse-store.test.d.ts.map

package/dist/acpx-engine/session-reuse-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reuse-store.test.d.ts","sourceRoot":"","sources":["../../src/acpx-engine/session-reuse-store.test.ts"],"names":[],"mappings":""}