The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
refactor(acpx-engine): coordinator-owned ACP run lifecycle with a typed resource ledger (#11576)
Nicky Leachb446ff59bfd4
diff --git a/doc/acp-run-lifecycle.md b/doc/acp-run-lifecycle.mdnew file mode 100644index 0000000000..ea68b76d1c--- /dev/null+++ b/doc/acp-run-lifecycle.md@@ -0,0 +1,101 @@+# ACP run lifecycle++This document describes how one ACP agent run starts, runs its turn, and releases+its resources. It covers the run coordinator, the six run resources, the+settlement order, the server-owned staging lease, and the known limitations.++## The run coordinator++One `run()` coordinator owns one attempt. It sequences four steps in a fixed+order:++1. **Startup.** Bring up the runtime and establish the session.+2. **Turn.** Run the agent turn against the ready runtime.+3. **Settlement.** Release every resource the run acquired.+4. **Result reproduction.** Return the external result to the caller.++The coordinator holds the routing table as data. It reads the startup outcome and+routes on it:++- A build failure or a partial-bridge failure throws from startup. The coordinator+ replays the startup-rollback entries and rethrows the original error.+- A runtime-create, handshake, missing-handle, or configuration failure produces a+ settle result. The coordinator settles the resources, then reproduces the error+ result.+- Every other startup outcome produces a ready result. The coordinator runs the+ turn, settles the resources, then reproduces the turn result.++The coordinator has no catch around the turn: the turn never rejects and returns a+typed completion. The coordinator reproduces the external result AFTER settlement,+so a caller never observes a result before the run releases its resources.++## The six run resources++A run resource ledger holds the resources between acquisition and settlement. The+ledger is the single owner. The closed set of run resources is:++- `acp_runtime` — the composite of the runtime, the session handle, and the child+ process. `runtime.close()` is the one release boundary for all three.+- `staged_runtime` — the workspace and the runtime staged into the sandbox, plus+ the one-time host-side cleanup of the staged temporary files.+- `control_bridge` — the control-plane callback bridge.+- `agent_bridge` — the agent process-session bridge.+- `managed_home` — the per-run managed-home copy-back hook.+- `staging_lease` — the per-session staging lease.++The host lane acquires only `acp_runtime`. The sandbox lane also acquires the+staging and transport resources. Each resource enters the ledger the moment it+exists, so the settlement always closes it, even on an early failure.++## The settlement order++The settlement sequence is the one live cleanup owner for every settled path. It+claims the ledger once, makes the pure reuse decision, then runs the ordered+steps:++1. `end_session` — close every runtime the reuse decision did not transfer, and+ drop the warm entry when it closes.+2. `settle_reuse` — perform the decision. A save transfers the reuse candidate to+ the site store; every other case discards it.+3. `stop_transport` — stop both bridges in one settled batch.+4. `sync_back` — run the site sync-back (the managed-home copy-back).+5. `release_staging_lease` — release the staging lease last (see below).++An error policy governs every step: a step records its error, and the later steps+still run. Every step is a no-op on an empty resource slot.++The reuse decision is pure and runs before any close. A save is eligible only when+a candidate exists, the settlement cause permits a save, and no run-scoped+credential that the candidate would carry into the store remains valid.++## The server-owned staging lease outer context++The staging lease is a per-session lease. Only one run of a session may stage into+the same remote workspace at a time. A second run of the same session waits on the+lease until the first run releases it.++The lease releases as the run's final act, after the coordinator settles every+other resource AND reproduces the result. This ordering keeps a same-session+second run blocked on the lease until the first run fully returns, so the second+run never re-stages into a workspace the first run still uses. The release runs in+a `finally`, so an earlier teardown fault never strands the lease.++## Per-phase telemetry++The run emits one telemetry event per named lifecycle phase. Each event carries+only the phase name, the wall-time duration, and the outcome (`ok` or `failed`).+The phase name is one member of a closed allowlist. An event never carries a+command, an argument, a path, an environment value, or a raw identifier. A+telemetry failure never fails the run.++## Known limitations and deferred work++- **Host-lane runtime reuse is disabled.** A run-minted API key is a stateless+ token that the control plane never revokes on run end. A warm host runtime would+ carry a still-valid credential into the next run. The host lane therefore closes+ and relaunches on every run, rather than keeping the runtime warm, until a+ run-scoped credential rebind protocol exists.+- **The sandbox staged-files reuse stays enabled.** Its reuse payload carries no+ credential, so a compatible resume reuses the already-staged runtime.+- **The per-phase telemetry is observability-only.** It records the duration and+ the outcome of each phase; it does not change run control flow.diff --git a/packages/adapter-utils/src/acpx-engine/composed-run-characterization.test.ts b/packages/adapter-utils/src/acpx-engine/composed-run-characterization.test.tsindex b9723bebc5..67e4e4df06 100644--- a/packages/adapter-utils/src/acpx-engine/composed-run-characterization.test.ts+++ b/packages/adapter-utils/src/acpx-engine/composed-run-characterization.test.ts@@ -715,7 +715,7 @@ describe("composed ACPX run: host-lane warm handle set", () => {vi.clearAllMocks();});- it("warm-saves a persistent local runtime and reuses it for the next compatible run", async () => {+ it("closes and relaunches a persistent local runtime, so the next compatible run re-creates it", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");let createCount = 0;@@ -746,8 +746,9 @@ describe("composed ACPX run: host-lane warm handle set", () => {onEvent: async () => {},} as never);expect(first.exitCode).toBe(0);- // A persistent local completed turn warm-saves the runtime handle.- expect(warmHandles.size).toBe(1);+ // Amendment B: a persistent local completed turn closes and relaunches the+ // runtime instead of warm-saving it (the run-minted API key is never revoked).+ expect(warmHandles.size).toBe(0);expect(createCount).toBe(1);const second = await execute({@@ -761,9 +762,8 @@ describe("composed ACPX run: host-lane warm handle set", () => {onEvent: async () => {},} as never);expect(second.exitCode).toBe(0);- // The compatible second run reuses the warm runtime, so createRuntime is not- // called again.- expect(createCount).toBe(1);+ // No warm runtime survived, so the compatible second run re-creates it.+ expect(createCount).toBe(2);});it("closes (does not warm-save) a completed non-persistent runtime, so the next run re-creates", async () => {@@ -819,7 +819,7 @@ describe("composed ACPX run: host-lane warm handle set", () => {expect(createCount).toBe(2);});- it("emits a skipped acp.handshake event on a warm-handle hit and does not re-create the runtime", async () => {+ it("runs a fresh acp.handshake on the second run and re-creates the runtime (no warm reuse)", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");let createCount = 0;@@ -863,15 +863,14 @@ describe("composed ACPX run: host-lane warm handle set", () => {},} as never);- // The warm-hit skips the handshake work: it emits exactly one acp.handshake- // event with outcome = skipped and a zero wall time, and never re-creates the- // runtime.+ // Amendment B: the first run closed and relaunched, so no warm handle survives.+ // The second run runs a fresh acp.handshake (outcome ok, not skipped) and+ // re-creates the runtime.const handshakeEvents = secondEvents.filter((event) => event.eventType === "run.startup.step" && event.payload?.step === "acp.handshake",);expect(handshakeEvents).toHaveLength(1);- expect(handshakeEvents[0]!.payload?.outcome).toBe("skipped");- expect(handshakeEvents[0]!.payload?.durationMs).toBe(0);- expect(createCount).toBe(1);+ expect(handshakeEvents[0]!.payload?.outcome).not.toBe("skipped");+ expect(createCount).toBe(2);});});diff --git a/packages/adapter-utils/src/acpx-engine/execute-identity.test.ts b/packages/adapter-utils/src/acpx-engine/execute-identity.test.tsnew file mode 100644index 0000000000..b182d61242--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/execute-identity.test.ts@@ -0,0 +1,95 @@+// Identity split and launch-environment finalization tests (Phase 17).+//+// Two tests are compile-time: the real assertion is that this file typechecks.+// A `@ts-expect-error` marks an assignment that MUST fail; if it starts to+// compile, tsc reports the unused directive and the typecheck fails. Each+// compile-time assertion lives in a declared, unexecuted function, so vitest+// never runs a synthetic value.++import { describe, expect, it } from "vitest";+import { buildSessionFingerprint, finalizeLaunchEnvironment } from "./execute.js";+import type {+ LaunchEnvironment,+ RunScopedContribution,+ RunSiteReuseCandidate,+ SessionFingerprintIdentity,+} from "./run-contracts.js";++// A complete fingerprint identity with representative values for the 17 fields.+const SAMPLE_FINGERPRINT_IDENTITY: SessionFingerprintIdentity = {+ acpxAgent: "claude",+ agentCommand: "claude",+ cwd: "/work",+ mode: "persistent",+ permissionMode: "approve-all",+ nonInteractivePermissions: "deny",+ requestedModel: "",+ requestedThinkingEffort: "",+ fastMode: false,+ remoteExecutionIdentity: null,+ additionalSourcesIdentity: {},+ skillsIdentity: {},+ skillPromptInstructions: "",+ paperclipClaudeSettings: null,+ mcpServers: [],+ secretManifestHash: "0000",+ adapterEnvHash: "0000",+};++describe("acpx identity split and launch environment", () => {+ it("test_fingerprint_builder_accepts_only_session_fingerprint_identity", () => {+ // The builder accepts a fingerprint identity and returns a stable hash.+ const first = buildSessionFingerprint(SAMPLE_FINGERPRINT_IDENTITY);+ const second = buildSessionFingerprint(SAMPLE_FINGERPRINT_IDENTITY);+ expect(first).toBe(second);+ expect(first).toMatch(/^[0-9a-f]{16}$/);++ // The compile-time assertions live in an unexecuted function.+ function _assertOnlyIdentity(): void {+ // An outer-key field is not a fingerprint field, so the builder rejects it.+ // @ts-expect-error companyId is not a SessionFingerprintIdentity field.+ buildSessionFingerprint({ ...SAMPLE_FINGERPRINT_IDENTITY, companyId: "c" });+ // @ts-expect-error taskKey is not a SessionFingerprintIdentity field.+ buildSessionFingerprint({ ...SAMPLE_FINGERPRINT_IDENTITY, taskKey: "t" });+ }+ void _assertOnlyIdentity;+ });++ it("test_finalize_launch_environment_is_sole_constructor_of_branded_environment", () => {+ // The finalizer merges every contribution and freezes the launch env.+ const baseEnv: Record<string, string> = { LAUNCH_ENV_TEST_BASE: "base" };+ const launchEnvironment = finalizeLaunchEnvironment(baseEnv, [+ { scope: "session", env: { LAUNCH_ENV_TEST_CONTRIB: "contrib" } },+ ]);+ expect(launchEnvironment.env.LAUNCH_ENV_TEST_BASE).toBe("base");+ expect(launchEnvironment.env.LAUNCH_ENV_TEST_CONTRIB).toBe("contrib");+ expect(Object.isFrozen(launchEnvironment.env)).toBe(true);++ // No plain object literal can stand in for the branded environment; it lacks+ // the private brand that only `finalizeLaunchEnvironment` sets.+ function _assertBrand(): void {+ // @ts-expect-error missing the private launch-environment brand.+ const _fake: LaunchEnvironment = { env: {} };+ void _fake;+ }+ void _assertBrand;+ });++ it("test_run_scoped_contribution_is_not_assignable_to_a_reuse_payload", () => {+ // A run-scoped contribution and the branded launch environment must never+ // enter a reuse payload (Amendment B). The reuse candidate types reject both.+ function _assertNotReusable(+ contribution: RunScopedContribution,+ launchEnvironment: LaunchEnvironment,+ ): void {+ // @ts-expect-error a run-scoped contribution is not a reuse candidate.+ const _a: RunSiteReuseCandidate = contribution;+ // @ts-expect-error the branded launch environment is not a reuse candidate.+ const _b: RunSiteReuseCandidate = launchEnvironment;+ void _a;+ void _b;+ }+ void _assertNotReusable;+ expect(true).toBe(true);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/execute.test.ts b/packages/adapter-utils/src/acpx-engine/execute.test.tsindex 35d89fccda..a61510c70b 100644--- a/packages/adapter-utils/src/acpx-engine/execute.test.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.test.ts@@ -336,7 +336,7 @@ const ALLOWED_TURN_SPAN_ATTRIBUTE_KEYS = new Set<string>([]);describe("shared ACPX engine runtime behavior", () => {- it("persists ACP agent process identity before prompting and reuses it for the next warm heartbeat", async () => {+ it("persists ACP agent process identity before prompting on each run (host lane re-creates, no warm reuse)", async () => {const root = await makeTempRoot();const startedAt = "2026-07-30T07:00:00.000Z";const processPid = 43_210;@@ -419,7 +419,9 @@ describe("shared ACPX engine runtime behavior", () => {} as never);expect(second.exitCode).toBe(0);- expect(runtimeCreateCount).toBe(1);+ // Amendment B: the host lane closes and relaunches (no warm reuse), so the+ // second run re-creates the runtime and re-persists the process identity.+ expect(runtimeCreateCount).toBe(2);expect(secondOnSpawn).toHaveBeenCalledOnce();expect(turnStartedBeforeProcessIdentity).toBe(false);});@@ -4382,7 +4384,7 @@ describe("ACPX engine per-step startup timing (run.startup.step events)", () =>}});- it("emits a skipped acp.handshake event when a warm-handle hit skips the handshake", async () => {+ it("runs a fresh acp.handshake on a compatible second run (host lane re-creates, no warm hit)", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");const warmHandles = new Map();@@ -4408,9 +4410,9 @@ describe("ACPX engine per-step startup timing (run.startup.step events)", () =>onMeta: async () => {},onEvent: async () => {},} as never);- // The second run reuses the warm handle, so the handshake does no work. It- // must emit exactly one acp.handshake event with outcome = skipped and a- // zero wall time, not a misleading zero-work `ok` event.+ // Amendment B: the first run closed and relaunched (no warm save), so the+ // compatible second run re-creates the runtime and runs a fresh handshake — one+ // acp.handshake event whose outcome is not `skipped`.await execute({runId: "run-warm-2",agent: { id: "agent-1", companyId: "company-1" },@@ -4428,8 +4430,7 @@ describe("ACPX engine per-step startup timing (run.startup.step events)", () =>(event) => event.eventType === "run.startup.step" && event.payload?.step === "acp.handshake",);expect(handshakeEvents).toHaveLength(1);- expect(handshakeEvents[0]!.payload?.outcome).toBe("skipped");- expect(handshakeEvents[0]!.payload?.durationMs).toBe(0);+ expect(handshakeEvents[0]!.payload?.outcome).not.toBe("skipped");});it("does not emit startup-step events on a local (non-sandbox) run except workspace.resolve", async () => {@@ -4663,7 +4664,7 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everyruntimeSessionName: "runtime-session",};- it("test_handshake_failure_closes_runtime_and_removes_warm_entry", async () => {+ it("test_persistent_host_failure_closes_recreated_runtime_no_warm_reuse", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");const closeSpy = vi.fn(async () => {});@@ -4709,10 +4710,13 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everyonSpawn: async () => {},} as never);expect(first.exitCode).toBe(0);- expect(warmHandles.size).toBe(1);+ // Amendment B: the first clean persistent turn closes and relaunches instead of+ // warm-saving, so no warm handle survives.+ expect(warmHandles.size).toBe(0);expect(created).toBe(1);- // The warm-hit reuses runtime #1 and fails while persisting process identity.+ // The second run finds no warm handle, so it re-creates the runtime and fails+ // while persisting process identity.const second = await execute({runId: "warm-handshake-2",agent: { id: "agent-1", companyId: "company-1" },@@ -4726,11 +4730,11 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for every},} as never);- expect(created).toBe(1);+ expect(created).toBe(2);expect(second.exitCode).toBe(1);expect(second.resultJson?.phase).toBe("ensure_session");- // The reused runtime is closed and the warm entry removed.- expect(closeSpy).toHaveBeenCalledTimes(1);+ // Each run closed its own runtime (one per run); no warm entry survived.+ expect(closeSpy).toHaveBeenCalledTimes(2);expect(warmHandles.size).toBe(0);});@@ -4768,7 +4772,7 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everyexpect(closeSpy).toHaveBeenCalledTimes(1);});- it("test_warm_hit_failure_closes_runtime_and_does_not_rearm_idle_timer", async () => {+ it("test_host_lane_closes_and_relaunches_every_run_and_leaves_no_warm_entry", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");let created = 0;@@ -4816,9 +4820,13 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everyonSpawn: async () => {},} as never);expect(first.exitCode).toBe(0);- expect(warmHandles.size).toBe(1);+ // Amendment B: the first clean persistent turn closes runtime #1 and leaves no+ // warm entry, so the host lane never keeps a live runtime warm.+ expect(warmHandles.size).toBe(0);+ expect(closes).toEqual([1]);- // A warm-hit whose identity-persist step fails reuses runtime #1 (no new create).+ // The second run finds no warm entry, so it re-creates runtime #2 and fails+ // while persisting process identity; runtime #2 closes.const second = await execute({runId: "warm-timer-2",agent: { id: "agent-1", companyId: "company-1" },@@ -4831,15 +4839,12 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everythrow new Error("onSpawn boom");},} as never);- expect(created).toBe(1);+ expect(created).toBe(2);expect(second.exitCode).toBe(1);- // Runtime #1 is closed and its warm entry removed. The warm-hit already cleared- // the idle timer, and the failure does not re-arm it, so the map is empty.- expect(closes).toEqual([1]);+ expect(closes).toEqual([1, 2]);expect(warmHandles.size).toBe(0);- // A later heartbeat finds no warm entry and constructs a fresh runtime, proving- // the failed warm-hit did not leave a re-armed entry behind.+ // A later heartbeat also finds no warm entry and constructs a fresh runtime.const third = await execute({runId: "warm-timer-3",agent: { id: "agent-1", companyId: "company-1" },@@ -4851,7 +4856,7 @@ describe("ACPX engine run lifecycle corrections (F2: close the runtime for everyonSpawn: async () => {},} as never);expect(third.exitCode).toBe(0);- expect(created).toBe(2);+ expect(created).toBe(3);});});diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.tsindex 99f1e8a02e..47118fbf75 100644--- a/packages/adapter-utils/src/acpx-engine/execute.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.ts@@ -84,8 +84,43 @@ import {DEFAULT_ACP_ENGINE_TIMEOUT_SEC,DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS,} from "./constants.js";+import type {+ AcpRunContext,+ AcquiredRunResources,+ LaunchEnvironment,+ LaunchEnvironmentContribution,+ PreTurnFailedCause,+ SessionFingerprintIdentity,+ SessionKeyIdentity,+ SettlementCause,+ StartupReady,+ StartupResult,+ TurnCompletion,+} from "./run-contracts.js";+import { createRunResourceLedger } from "./run-resource-ledger.js";+import { settleAcpRun, type SettlementSteps } from "./settlement-sequence.js";+import {+ runAttempt,+ type RunPlan,+ type SettlementReason,+ type SettlementDispositionReport,+} from "./run-coordinator.js";+import {+ runTurn as runTurnSequence,+ type StartedTurn,+ type TurnFinalizeInput,+} from "./turn-sequence.js";+import {+ createHostRunSite,+ type AcpxAgentProcessIdentity,+ type AcpxProcessIdentitySink,+ type ChildStderrState,+ type RuntimeCacheEntry,+} from "./run-site-host.js";+import { createSandboxRunSite, type SandboxRunSite } from "./run-site-sandbox.js";import {createRuntimeSpanRunner,+ emitRunPhaseTiming,emitSkippedStartupStep,getActiveStepContext,measureStartupStep,@@ -105,11 +140,6 @@ const defaultModuleDir = path.dirname(fileURLToPath(import.meta.url));const PAPERCLIP_MANAGED_CODEX_SKILLS_MANIFEST = ".paperclip-managed-skills.json";const BENIGN_NES_CLOSE_STDERR = /method: ['"]nes\/close['"].*-32601/;-interface ChildStderrState {- logPath: string | null;- pendingLiveLine: string;-}-function routeChildStderr(state: ChildStderrState, chunk: string) {if (state.logPath) {fsSync.mkdirSync(path.dirname(state.logPath), { recursive: true });@@ -137,8 +167,6 @@ function flushChildStderr(state: ChildStderrState) {state.pendingLiveLine = "";}-type AcpxAgentProcessIdentity = { pid: number; startedAt: string };-type PaperclipAcpRuntimeOptions = AcpRuntimeOptions & {onAgentSpawn?: (meta: AcpxAgentProcessIdentity) => Promise<void>;// Return the current-run parent-context token. It is the `task.run` token@@ -148,23 +176,8 @@ type PaperclipAcpRuntimeOptions = AcpRuntimeOptions & {getRuntimeParentContext?: () => StartupSpanContext | undefined;};-type AcpxProcessIdentitySink = {- current: AdapterExecutionContext["onSpawn"];- latest: AcpxAgentProcessIdentity | null;-};-type AcpxRuntimeFactory = (options: PaperclipAcpRuntimeOptions) => AcpRuntime;-export interface RuntimeCacheEntry {- runtime: AcpRuntime;- handle: AcpRuntimeHandle;- childStderrState: ChildStderrState;- processIdentitySink: AcpxProcessIdentitySink;- fingerprint: string;- lastUsedAt: number;- cleanupTimer?: NodeJS.Timeout;-}-/*** A remote runner-backed session's staged runtime, kept warm across runs so a* compatible resume reuses it instead of re-shipping the workspace / re-seeding@@ -348,6 +361,14 @@ export interface AcpxEngineExecutorOptions {prepareRemoteManagedHome?: (input: AcpxRemoteManagedHomeContext,) => Promise<AcpxRemoteManagedHomeResult>;+ /**+ * Observe the final per-resource disposition report the run records at the end+ * of the attempt (`finalized` vs `transferred`). The coordinator records it on+ * every exit path: the settlement path reports what the settlement decided, and+ * the startup-rollback path reports every rolled-back entry as `finalized`. The+ * engine never reads it back; a test injects this hook to assert the report.+ */+ onSettlementDisposition?: (report: SettlementDispositionReport) => void;}interface AcpxPreparedRuntime {@@ -388,8 +409,8 @@ interface AcpxPreparedRuntime {stagedRuntime: PreparedAdapterExecutionTargetRuntime | null;// Per-run copy-back hook from the per-adapter remote managed-home seam: runs// the codex auth copy-back (via `restoreWorkspace()`). Invoked once on every- // exit path by `cleanupRemoteBridges`; it never removes staged temp, so it is- // safe on every compatible resume. Null for local runs, the runner-less+ // exit path by the settlement `syncBack` step; it never removes staged temp, so+ // it is safe on every compatible resume. Null for local runs, the runner-less// fallback, and adapters with no seam.remoteManagedHomeTeardown: (() => Promise<void>) | null;// One-time host-side staged-resource cleanup from the seam (remove staged temp@@ -451,6 +472,46 @@ function shortHash(value: unknown): string {return createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 16);}+/**+ * Hash the session fingerprint. The builder accepts only a+ * `SessionFingerprintIdentity`, so no company, agent, or task identifier can+ * enter the hash. Those identifiers scope the outer session key only (see+ * `SessionKeyIdentity`).+ */+export function buildSessionFingerprint(identity: SessionFingerprintIdentity): string {+ return shortHash(identity);+}++/**+ * Build the session key from the fingerprint and the outer-key identity. The key+ * form is `paperclip:companyId:agentId:taskKey:fingerprint`.+ */+export function buildSessionKey(identity: SessionKeyIdentity, fingerprint: string): string {+ return `paperclip:${identity.companyId}:${identity.agentId}:${identity.taskKey}:${fingerprint}`;+}++/**+ * Build the single branded launch environment for a run. This is the sole+ * constructor of `LaunchEnvironment`. It applies each contribution into the base+ * env in registration order, then resolves and freezes the launch env.+ *+ * A contribution carries its credential scope. A run-scoped contribution (the+ * run API key, a bridge token) and a session-scoped contribution (the Codex auth+ * copy-back material) both merge here. Neither scope can escape into a reuse+ * payload, because the branded contribution type and the branded environment+ * type forbid it.+ */+export function finalizeLaunchEnvironment(+ baseEnv: Record<string, string>,+ contributions: readonly LaunchEnvironmentContribution[],+): LaunchEnvironment {+ for (const contribution of contributions) {+ Object.assign(baseEnv, contribution.env);+ }+ const env = Object.freeze(resolveRuntimeEnv(baseEnv));+ return { env } as unknown as LaunchEnvironment;+}+// Directory names the staging path never ships for a referenced project (heavy// build/cache output and git history). The content signature skips them so it// reflects only the staged tree and never reads their bytes. Keep this set equal@@ -1405,6 +1466,14 @@ async function buildRuntime(input: {ctx: AdapterExecutionContext;engine: AcpxEngineSettings;deps: AcpxEngineExecutorOptions;+ // The run resource ledger. `executeAcpxEngine` creates the one ledger for the+ // attempt and passes it here, so the sandbox run site registers what it+ // acquires into that single ledger (one ledger until Phase 20 formalizes the+ // coordinator).+ ledger: AcquiredRunResources;+ // The staged-runtime idle bound, in milliseconds. The sandbox run site takes+ // it for its reuse store's idle policy.+ stagedIdleMs: number;// The injected tracer, the root-span parent-context token, and the// context-builder. Merged into every startup-step option set, so each// boundary span parents to the one root span (`sandbox.startup`) that the@@ -1777,7 +1846,10 @@ async function buildRuntime(input: {useRemoteProcessSession && executionTarget?.kind === "remote"? executionTarget.remoteCwd: cwd;- const fingerprint = shortHash({+ // The 17 fields the session fingerprint hashes. Company, agent, and task+ // identifiers are NOT here; they scope the outer session key only (see+ // `keyIdentity`). The fingerprint builder accepts only this identity.+ const fingerprintIdentity: SessionFingerprintIdentity = {acpxAgent,agentCommand: agentCommand ?? acpxAgent,cwd: path.resolve(sessionCwd),@@ -1792,7 +1864,7 @@ async function buildRuntime(input: {// added, removed, or re-pinned) invalidates a warm/resumable session so the// next launch stages the current referenced-project trees instead of reusing// a stale staged tree.- additionalSourcesIdentity,+ additionalSourcesIdentity: additionalSourcesIdentity as unknown as Record<string, unknown>,skillsIdentity,skillPromptInstructions,paperclipClaudeSettings: paperclipClaudeSettings@@ -1812,9 +1884,17 @@ async function buildRuntime(input: {// edits and same-version secret rotations. Per-wake runtime vars never enter// resolvedAdapterEnv, so they don't churn the fingerprint every heartbeat.adapterEnvHash: shortHash(resolvedAdapterEnv),- });+ };+ const fingerprint = buildSessionFingerprint(fingerprintIdentity);const taskKey = asString(input.ctx.runtime.taskKey, "") || wakeTaskId || workspaceId || "default";- const sessionKey = `paperclip:${agent.companyId}:${agent.id}:${taskKey}:${fingerprint}`;+ // Company, agent, and task identity for the outer session key. These parts+ // stay out of the fingerprint hash.+ const keyIdentity: SessionKeyIdentity = {+ companyId: agent.companyId,+ agentId: agent.id,+ taskKey,+ };+ const sessionKey = buildSessionKey(keyIdentity, fingerprint);// Ship the workspace into the sandbox and capture `{ workspaceRemoteDir,// runtimeRootDir, assetDirs, restoreWorkspace }`. Done once here, before the@@ -1866,58 +1946,28 @@ async function buildRuntime(input: {let remoteStagingDispose: (() => Promise<void>) | null = null;let remoteStagingEnvDelta: Record<string, string> | null = null;let sessionStagingLeaseRelease: (() => void) | null = null;+ // The sandbox run site owns the sandbox lane's staging, the per-session+ // staging lease, both host-side bridges, the launch-environment contribution,+ // and sync-back. `buildRuntime` injects the leaf primitives (the workspace+ // stage call, the managed-home seam, the two bridge starts, the step timers,+ // and the launch-env finalizer) and reads the site's results back onto the+ // prepared-runtime fields, so the existing settlement path stays unchanged.+ let sandboxSite: SandboxRunSite | null = null;if (useRemoteProcessSession && executionTarget?.kind === "remote") {const remoteTarget = executionTarget;- const staged = await withSessionStagingLease(stagingLocks, sessionKey, async (): Promise<{- stagedRuntime: PreparedAdapterExecutionTargetRuntime;- teardown: (() => Promise<void>) | null;- dispose: (() => Promise<void>) | null;- envDelta: Record<string, string>;- }> => {- const cachedStaged = isCompatibleResume ? stagedRuntimes.get(sessionKey) : undefined;- if (cachedStaged) {- // Reuse the already-staged in-sandbox workspace + managed home. Re-apply- // the env keys the seam repointed onto the in-sandbox home (deterministic,- // identical across the session's runs) and reuse the seam's per-run- // copy-back so the codex auth copy-back still fires on THIS run's teardown- // — the copy-back cadence stays exactly per-run, unchanged from PR 2. The- // copy-back reads the sandbox auth.json live at teardown, so the reused- // closure copies back the current credential, never a stale snapshot, and- // it never removes the staged in-sandbox home (host staged-temp cleanup- // moved to `dispose`, fired only when the entry is dropped), so reusing it- // can't leave this run without its staged home.- // (The workspace restore in that same closure diffs against the ORIGINAL- // staging run's host baseline — an accepted consequence of "reuse, don't- // re-ship": the in-sandbox workspace is the source of truth mid-session- // and the host stays synced from it each run.)- Object.assign(env, cachedStaged.envDelta);- cachedStaged.lastUsedAt = nowMs();- await input.ctx.onLog(- "stdout",- "[paperclip] Reusing the staged in-sandbox runtime for this resumed session (no workspace re-ship / managed-home re-seed).\n",- );- return {- stagedRuntime: cachedStaged.stagedRuntime,- teardown: cachedStaged.teardown,- dispose: cachedStaged.dispose,- envDelta: cachedStaged.envDelta,- };- }- // Not a compatible resume (or no cache entry): stage fresh. If a stale- // entry sits at this key (e.g. an incompatible new session colliding on- // company/agent/task/fingerprint), drop it and release its host staged- // resources first so we neither reuse nor leak it.- const stale = stagedRuntimes.get(sessionKey);- if (stale) {- stagedRuntimes.delete(sessionKey);- if (stale.dispose) await stale.dispose().catch(() => {});- }- // Record each successful `stage()` result before the seam can fail. A seam- // that throws AFTER a successful stage never returns its `disposeStaged`, so- // the engine disposes the fresh staged runtime here (see the catch below).- let freshlyStagedRuntime: PreparedAdapterExecutionTargetRuntime | null = null;- const stage = async (assets: AdapterManagedRuntimeAsset[]) => {- const staged = await stageAcpRemoteRuntime({+ sandboxSite = createSandboxRunSite({+ ledger: input.ledger,+ stagedRuntimes,+ stagingLocks,+ now: nowMs,+ idleMs: input.stagedIdleMs,+ sessionCwd,+ spawnCwd: cwd,+ target: remoteTarget,+ env,+ isCompatibleResume,+ stage: (assets) =>+ stageAcpRemoteRuntime({runId,target: remoteTarget,adapterKey: input.engine.adapterType,@@ -1929,33 +1979,10 @@ async function buildRuntime(input: {onLog: input.ctx.onLog,onRuntimeProgress: input.ctx.onRuntimeProgress,runtimeSpan: input.stageRuntimeSpan,- });- freshlyStagedRuntime = staged;- return staged;- };- // Snapshot env before the seam so we can capture exactly which keys it- // repointed onto the in-sandbox home (e.g. `CODEX_HOME`) and replay them- // verbatim on a later compatible resume. Add/change only — every seam sets- // (never deletes) its home env var, so a set-based delta is complete.- const envBeforeStage = { ...env };- // Step 4 — stage.sync: ship the workspace (and, via the seam, the managed- // home) into the sandbox. Only fires on a fresh stage; a compatible resume- // that reuses an already-staged runtime skips this block entirely. The- // measured callback returns the staged result so the timing wrap does not- // disturb definite-assignment of the outer bindings.- const {- stagedRuntime: freshStagedRuntime,- teardown: freshTeardown,- dispose: freshDispose,- } = await measureStartupStep(input.ctx, nowMs, "stage.sync", async (): Promise<{- stagedRuntime: PreparedAdapterExecutionTargetRuntime;- teardown: (() => Promise<void>) | null;- dispose: (() => Promise<void>) | null;- }> => {- if (input.deps.prepareRemoteManagedHome) {- let seeded: AcpxRemoteManagedHomeResult;- try {- seeded = await input.deps.prepareRemoteManagedHome({+ }),+ seedManagedHome: input.deps.prepareRemoteManagedHome+ ? async (stage) => {+ const seeded = await input.deps.prepareRemoteManagedHome!({acpxAgent,companyId: agent.companyId,runId,@@ -1968,96 +1995,46 @@ async function buildRuntime(input: {onRuntimeProgress: input.ctx.onRuntimeProgress,stage,});- } catch (seamErr) {- // The seam failed after a possible successful stage. Dispose the fresh- // staged runtime so the abandoned in-sandbox managed home does not leak,- // then rethrow the seam error.- if (freshlyStagedRuntime) {- await disposeFreshStagedRuntime({- runId,- target: remoteTarget,- stagedRuntime: freshlyStagedRuntime,- cwd: sessionCwd,- timeoutSec,- onLog: input.ctx.onLog,- });- }- throw seamErr;+ return {+ stagedRuntime: seeded.stagedRuntime,+ teardown: seeded.teardown ?? null,+ dispose: seeded.disposeStaged ?? null,+ };}- return {- stagedRuntime: seeded.stagedRuntime,- teardown: seeded.teardown ?? null,- dispose: seeded.disposeStaged ?? null,- };+ : undefined,+ disposeFreshStagedRuntime: (freshStagedRuntime) =>+ disposeFreshStagedRuntime({+ runId,+ target: remoteTarget,+ stagedRuntime: freshStagedRuntime,+ cwd: sessionCwd,+ timeoutSec,+ onLog: input.ctx.onLog,+ }),+ measureStageStep: (run) => measureStartupStep(input.ctx, nowMs, "stage.sync", run, stepMetrics),+ publishStagedProjectHints: (stagedProjectDirs) => {+ const shapedHints = shapePaperclipWorkspaceEnvForExecution({+ workspaceCwd: effectiveWorkspaceCwd,+ workspaceWorktreePath,+ workspaceHints,+ executionTargetIsRemote,+ executionCwd: effectiveExecutionCwd,+ stagedProjectDirs,+ }).workspaceHints;+ if (shapedHints.length > 0) {+ env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(shapedHints);}- return { stagedRuntime: await stage([]), teardown: null, dispose: null };- }, stepMetrics);- const delta: Record<string, string> = {};- for (const [key, value] of Object.entries(env)) {- if (envBeforeStage[key] !== value) delta[key] = value;- }- return {- stagedRuntime: freshStagedRuntime,- teardown: freshTeardown,- dispose: freshDispose,- envDelta: delta,- };- });- sessionStagingLeaseRelease = staged.release;- stagedRuntime = staged.value.stagedRuntime;- remoteManagedHomeTeardown = staged.value.teardown;- remoteStagingDispose = staged.value.dispose;- remoteStagingEnvDelta = staged.value.envDelta;- // Publish the referenced-project workspace hints to the in-sandbox agent. The staged-directory- // map (`project-<projectId>`) is known only after staging above, so this runs here rather than- // with the initial workspace shaping. Each referenced hint repoints at its staged directory; a- // referenced hint whose project did not stage loses its cwd, so the agent never receives an- // unstaged path. Only the confined sandbox lane stages referenced trees, so only it publishes- // the hints; the local and runner-less lanes keep their env untouched. The set `env` write wins- // over an inherited value in the merged launch env.- const stagedProjectDirs = stagedRuntime?.additionalSourceDirs ?? {};- if (Object.keys(stagedProjectDirs).length > 0) {- const shapedHints = shapePaperclipWorkspaceEnvForExecution({- workspaceCwd: effectiveWorkspaceCwd,- workspaceWorktreePath,- workspaceHints,- executionTargetIsRemote,- executionCwd: effectiveExecutionCwd,- stagedProjectDirs,- }).workspaceHints;- if (shapedHints.length > 0) {- env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(shapedHints);- }- }- }- // Both bridge starts run under one try so a failure at EITHER — including the- // paperclip callback bridge — fires the same abandon-path cleanup. The- // paperclip bridge starts after the workspace + managed home were already- // staged and the per-session staging lease is already held, so leaving it- // outside the catch would strand the lease (and the staged temp) on a- // start failure and deadlock the next run of this session.- let paperclipBridge: AdapterExecutionTargetPaperclipBridgeHandle | null = null;- let processSessionBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null = null;- let runtimeEnv: Record<string, string> = {};- try {- if (useRemoteProcessSession) {- // Steps 5 + 6 — bring up BOTH host-side sandbox bridges concurrently. Their- // remote subtrees are disjoint (`…/paperclip-bridge/…` vs- // `…/process-sessions/…`), so the env-INDEPENDENT setup of each overlaps,- // trending wall time from serial (~bridge.paperclip + ~bridge.process-session)- // toward ~max(the two). The ONE real dependency — the paperclip bridge's- // returned `env` must reach the process-session LAUNCH — is sequenced by- // `finalizeLaunchEnv`: the process-session bridge runs its env-independent- // dir/script setup first, then awaits that thunk right before its launch, so- // the launch always observes the merged paperclip env.- //- // Both `run.startup.step` events still emit — `measureStartupStep` records- // them in a `finally`, even on a start failure.- const paperclipStart = measureStartupStep(input.ctx, nowMs, "bridge.paperclip", () =>+ },+ onReuseLog: () =>+ input.ctx.onLog(+ "stdout",+ "[paperclip] Reusing the staged in-sandbox runtime for this resumed session (no workspace re-ship / managed-home re-seed).\n",+ ),+ startPaperclipBridge: (runtimeRootDir) =>startAdapterExecutionTargetPaperclipBridge({runId,- target: { ...executionTarget, streamRunLogs: false },- runtimeRootDir: stagedRuntime?.runtimeRootDir ?? null,+ target: { ...remoteTarget, streamRunLogs: false },+ runtimeRootDir,adapterKey: input.engine.adapterType,timeoutSec,hostApiToken: env.PAPERCLIP_API_KEY,@@ -2065,62 +2042,84 @@ async function buildRuntime(input: {getRuntimeParentContext: input.getRuntimeParentContext,runtimeSpan: input.runtimeSpan,}),- concurrentBridgeStepMetrics,- );- // The single sequencing point (paperclip `env` → process-session launch).- // Memoized so the merge + log + `runtimeEnv` build run EXACTLY once whether- // the process-session bridge consumes it at launch or we finalize it below.- let launchEnvPromise: Promise<Record<string, string>> | null = null;- const finalizeLaunchEnv = (): Promise<Record<string, string>> =>- (launchEnvPromise ??= (async () => {- const paperclip = await paperclipStart;- if (paperclip) {- Object.assign(env, paperclip.env);- await input.ctx.onLog("stdout", "[paperclip] Sandbox ACP API callback bridge enabled for this run.\n");- }- return (runtimeEnv = resolveRuntimeEnv(env));- })());- const processSessionStart = measureStartupStep(input.ctx, nowMs, "bridge.process-session", () =>+ startProcessSessionBridge: ({ runtimeRootDir, launchEnv }) =>startAdapterExecutionTargetProcessSessionBridge({runId,- target: executionTarget,- runtimeRootDir: stagedRuntime?.runtimeRootDir ?? null,+ target: remoteTarget,+ runtimeRootDir,adapterKey: input.engine.adapterType,command: "sh",args: ["-lc", `exec ${agentCommandShell}`],cwd: sessionCwd,- // Deferred: the process-session bridge runs its env-independent setup,- // then calls this to get the launch env AFTER the paperclip env merge.- env: finalizeLaunchEnv,+ env: launchEnv,timeoutSec,onLog: input.ctx.onLog,getRuntimeParentContext: input.getRuntimeParentContext,runtimeSpan: input.runtimeSpan,streamOutputViaSession: streamAgentSessionOutput,}),- concurrentBridgeStepMetrics,- );- // Settle BOTH starts (mirrors `cleanupRemoteBridges`' `Promise.allSettled`):- // collect whichever handles started plus the first failure. Both handles- // stay individually declared so the catch below can stop whichever started.- const started = await settleRemoteBridgeStarts(paperclipStart, processSessionStart);- paperclipBridge = started.paperclipBridge;- processSessionBridge = started.processSessionBridge;- if (started.failure) throw started.failure;- // Guarantee the paperclip env merge ran even if the process-session bridge- // returned without consuming the launch env (memoized ⇒ a no-op if it did).- await finalizeLaunchEnv();+ measureBridgeStep: (step, run) =>+ measureStartupStep(input.ctx, nowMs, step, run, concurrentBridgeStepMetrics),+ finalizeLaunchEnv: (contributions) => finalizeLaunchEnvironment(env, contributions).env,+ onPaperclipBridgeLog: () =>+ input.ctx.onLog("stdout", "[paperclip] Sandbox ACP API callback bridge enabled for this run.\n"),+ stopBridges: async ({ controlBridge, agentBridge }) => {+ await Promise.allSettled([agentBridge?.stop(), controlBridge?.stop()]);+ if (remoteManagedHomeTeardown) {+ await remoteManagedHomeTeardown().catch(() => {});+ }+ },+ });+ // Place the workspace (stage fresh or reuse the already-staged runtime) under+ // the per-session staging lease, then read the staged result back onto the+ // prepared-runtime fields the settlement path consumes.+ const placeWorkspaceStart = nowMs();+ await sandboxSite.placeWorkspace({ sessionKey } as unknown as AcpRunContext);+ await emitRunPhaseTiming(input.ctx, "place_workspace", nowMs() - placeWorkspaceStart, "ok");+ const placedStaged = sandboxSite.staged;+ stagedRuntime = placedStaged?.stagedRuntime ?? null;+ remoteManagedHomeTeardown = placedStaged?.teardown ?? null;+ remoteStagingDispose = placedStaged?.dispose ?? null;+ remoteStagingEnvDelta = placedStaged?.envDelta ?? null;+ sessionStagingLeaseRelease = sandboxSite.stagingLeaseRelease;+ }+ // Both bridge starts run under one try so a failure at EITHER — including the+ // paperclip callback bridge — fires the same abandon-path cleanup. The+ // paperclip bridge starts after the workspace + managed home were already+ // staged and the per-session staging lease is already held, so leaving it+ // outside the catch would strand the lease (and the staged temp) on a+ // start failure and deadlock the next run of this session.+ let paperclipBridge: AdapterExecutionTargetPaperclipBridgeHandle | null = null;+ let processSessionBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null = null;+ let runtimeEnv: Record<string, string> = {};+ const startTransportStart = nowMs();+ try {+ if (useRemoteProcessSession && sandboxSite) {+ // The sandbox run site brings up both host-side bridges concurrently, keeps+ // the one paperclip-env → process-session-launch dependency at a single+ // sequencing point, settles both starts, and returns the started handles+ // plus the finalized launch env. On a partial failure it stops nothing and+ // rethrows; the catch below stops whichever bridge the site started.+ const transport = await sandboxSite.startTransport({ sessionKey } as unknown as AcpRunContext);+ paperclipBridge = transport.controlBridge;+ processSessionBridge = transport.agentBridge;+ runtimeEnv = transport.launchEnv;+ await emitRunPhaseTiming(input.ctx, "start_transport", nowMs() - startTransportStart, "ok");} else {- // Local / runner-less lanes never start a bridge, but the returned prepared- // runtime and the log builder still read `runtimeEnv`.- runtimeEnv = resolveRuntimeEnv(env);+ // Local / runner-less lanes never start a bridge, so they add no+ // contribution. `finalizeLaunchEnvironment` still produces the one branded+ // launch env the prepared runtime and the log builder read.+ runtimeEnv = finalizeLaunchEnvironment(env, []).env;}} catch (err) {// On a partial concurrent bring-up failure, ONE bridge may have started while// the other threw; `Promise.allSettled` stops whichever started so no live- // bridge leaks (mirrors `cleanupRemoteBridges`). Both handles are individually- // declared above, so either may be non-null here.- await Promise.allSettled([paperclipBridge?.stop(), processSessionBridge?.stop()]);+ // bridge leaks (mirrors the settlement `stopTransport` step). The site sets its+ // started bridges before it rethrows, so read them from the site here (the+ // local handles stay null when `startTransport` throws before it returns).+ const startedControl = sandboxSite?.controlBridge ?? paperclipBridge;+ const startedAgent = sandboxSite?.agentBridge ?? processSessionBridge;+ await Promise.allSettled([startedControl?.stop(), startedAgent?.stop()]);// The staged home / copy-back teardown must run even if a bridge fails to// start after the workspace + managed home were already staged into the// sandbox, so a refreshed credential is copied back on this error path too.@@ -2128,7 +2127,7 @@ async function buildRuntime(input: {// dispose here (it no longer rides the per-run copy-back) — the run is being// abandoned, so its staged temp must be released — and release the per-session// staging lease so the abandoned run does not strand the next same-session run- // (cleanupRemoteBridges, which normally releases it, is never reached here).+ // (the run root `finally`, which normally releases it, is never reached here).//// Route the dispose through the same ownership-guarded removal// `discardStagedRuntime` uses. When this run BORROWED the cached staged runtime@@ -2145,6 +2144,7 @@ async function buildRuntime(input: {dispose: remoteStagingDispose,});sessionStagingLeaseRelease?.();+ await emitRunPhaseTiming(input.ctx, "start_transport", nowMs() - startTransportStart, "failed");throw err;}const overrideCommand = processSessionBridge?.agentCommand ?? agentCommand;@@ -2274,60 +2274,50 @@ function resolveRuntimeEnv(env: Record<string, string>): Record<string, string>);}-/**- * Bring up the two host-side sandbox bridges concurrently and settle both.- *- * Mirrors `cleanupRemoteBridges`' `Promise.allSettled` idiom (settle, not- * `Promise.all`): running BOTH starts to completion is what lets the caller STOP- * a bridge that DID start when its sibling threw — so a partial failure never- * leaks a live bridge. Returns whichever handles started plus the first failure- * (paperclip before process-session) for the caller to rethrow through the- * shared abandon path.- */-async function settleRemoteBridgeStarts(- paperclipStart: Promise<AdapterExecutionTargetPaperclipBridgeHandle | null>,- processSessionStart: Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null>,-): Promise<{- paperclipBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;- processSessionBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;- failure: unknown;-}> {- const [paperclip, processSession] = await Promise.allSettled([- paperclipStart,- processSessionStart,+// Stop both host-side bridges in one `allSettled`. This is the settlement+// `stopTransport` effect. The bridge tokens are run-scoped, so they die with the+// bridges here (Amendment B).+async function stopRunTransport(prepared: AcpxPreparedRuntime): Promise<void> {+ await Promise.allSettled([+ prepared.processSessionBridge?.stop(),+ prepared.paperclipBridge?.stop(),]);- return {- paperclipBridge: paperclip.status === "fulfilled" ? paperclip.value : null,- processSessionBridge: processSession.status === "fulfilled" ? processSession.value : null,- failure:- paperclip.status === "rejected"- ? paperclip.reason- : processSession.status === "rejected"- ? processSession.reason- : null,- };}-async function cleanupRemoteBridges(prepared: AcpxPreparedRuntime): Promise<void> {- try {- await Promise.allSettled([- prepared.processSessionBridge?.stop(),- prepared.paperclipBridge?.stop(),- ]);- // Runs AFTER the bridges stop (mirrors the CLI finally: stop bridge → restore- // workspace). Fires the codex auth copy-back via `restoreWorkspace()` and- // removes staged temp dirs. The seam logs and swallows its own failures — an- // unclean-teardown copy-back miss is the accepted, loud `refresh_token_reused`- // residual on the next host Codex use, never silent HOST-credential corruption- // — so a teardown fault never masks or fails the run result here.- if (prepared.remoteManagedHomeTeardown) {- await prepared.remoteManagedHomeTeardown().catch(() => {});- }- } finally {- // Release the per-session staging lease in a finally, so an earlier teardown- // fault never strands it and deadlocks the next run of this session.- prepared.sessionStagingLeaseRelease?.();+// The site sync-back. This is the settlement `syncBack` effect. It runs AFTER the+// bridges stop (mirrors the CLI finally: stop bridge → restore workspace). It+// fires the codex auth copy-back via `restoreWorkspace()` and removes staged temp+// dirs. The seam logs and swallows its own failures — an unclean-teardown+// copy-back miss is the accepted, loud `refresh_token_reused` residual on the+// next host Codex use, never silent HOST-credential corruption — so a teardown+// fault never masks or fails the run result here.+async function syncBackManagedHome(prepared: AcpxPreparedRuntime): Promise<void> {+ if (prepared.remoteManagedHomeTeardown) {+ await prepared.remoteManagedHomeTeardown().catch(() => {});}+ // The per-session staging lease does NOT release here. The settlement releases+ // it last, in its own `finally`, so a same-session second run cannot re-stage+ // until this run fully settles and the caller observes the result.+}++/** How the settlement `endSession` step releases the runtime a run acquired. */+interface RuntimeSettlementPlan {+ // "direct" closes the runtime itself and swallows or records the close error;+ // "warm_or_close" prefers a matching warm entry (which also flushes its stderr).+ readonly mode: "direct" | "warm_or_close";+ readonly handle: AcpRuntimeHandle;+ readonly reason: string;+ readonly discardPersistentState: boolean;+ // Drop a matching warm entry after a direct close (the pre-turn and turn-error+ // paths remove a warm-hit entry that failed).+ readonly dropWarmEntry: boolean;+ // Record a direct-close error to the run log; a warm_or_close error is+ // swallowed. This keeps today's split (the failure paths log, the turn path+ // swallows).+ readonly recordCloseError: boolean;+ // Cancel the running turn with this reason before the close (the turn-error+ // path cancels before it closes). Null on every other path.+ readonly cancelTurnReason: string | null;}function renderPaperclipEnvNote(env: Record<string, string>): string {@@ -2799,31 +2789,10 @@ function isResumeFailure(err: unknown): boolean {return /resume|load|not found|no session|unknown session|conversation/i.test(message);}-async function cleanupIdleHandles(input: {- handles: Map<string, RuntimeCacheEntry>;- now: number;- idleMs: number;-}) {- if (input.idleMs <= 0) return;-- const stale: Array<[string, RuntimeCacheEntry]> = [];- for (const entry of input.handles.entries()) {- if (input.now - entry[1].lastUsedAt >= input.idleMs) stale.push(entry);- }- for (const [key, entry] of stale) {- await closeWarmHandle({- handles: input.handles,- key,- entry,- reason: "paperclip idle cleanup",- });- }-}-// Drop staged-runtime entries the session has not touched within the warm-idle// window, so the cache does not accumulate abandoned sessions (e.g. every time// a config change shifts the fingerprint to a new key). The per-run copy-back-// already ran on the entry's last run's `cleanupRemoteBridges`; eviction fires+// already ran on the entry's last run's settlement `syncBack`; eviction fires// the entry's one-time `dispose` (host staged-temp cleanup) — the only place// the staged temp is removed now that it no longer rides the per-run teardown.// A later run of the same session simply re-stages fresh (re-shipping into the@@ -2979,37 +2948,6 @@ async function closeWarmHandle(input: {flushChildStderr(input.entry.childStderrState);}-function scheduleIdleHandleCleanup(input: {- handles: Map<string, RuntimeCacheEntry>;- key: string;- entry: RuntimeCacheEntry;- idleMs: number;- now: () => number;-}) {- clearWarmHandleTimer(input.entry);- if (input.idleMs <= 0) return;-- const delayMs = Math.max(1, input.entry.lastUsedAt + input.idleMs - input.now());- input.entry.cleanupTimer = setTimeout(() => {- void (async () => {- const current = input.handles.get(input.key);- if (current !== input.entry) return;- const idleForMs = input.now() - input.entry.lastUsedAt;- if (idleForMs < input.idleMs) {- scheduleIdleHandleCleanup(input);- return;- }- await closeWarmHandle({- handles: input.handles,- key: input.key,- entry: input.entry,- reason: "paperclip idle cleanup",- });- })();- }, delayMs);- input.entry.cleanupTimer.unref?.();-}-function warmHandleMatches(entry: RuntimeCacheEntry | undefined,runtime: AcpRuntime,@@ -3249,6 +3187,24 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {billingType: billingIdentity?.billingType ?? ("unknown" as const),};const warmIdleMs = asNumber(ctx.config.warmHandleIdleMs, DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS);+ // The host run site owns the warm-handle store on this run. It operates over+ // the engine's persistent `warmHandles` map, so a warm runtime stays live for+ // the next compatible resume. The store arms the per-entry idle timer on a+ // warm save, sweeps idle entries at run start, and closes a released entry+ // through `closeWarmEntry`. The run reads `warmHandleIdleMs` per run, so the+ // site takes this run's bound.+ const hostSite = createHostRunSite({+ warmHandles,+ now,+ idleMs: warmIdleMs,+ closeWarmEntry: async (entry) => {+ await entry.runtime+ .close({ handle: entry.handle, reason: "paperclip idle cleanup", discardPersistentState: false })+ .catch(() => {});+ flushChildStderr(entry.childStderrState);+ },+ });+ const hostStore = hostSite.reuse();// The `task.run` and `sandbox.startup` spans must not cover a local or SSH// run: those runs have no sandbox, so they stay out of sandbox telemetry.// Open a real root span only when the target is a remote sandbox and the@@ -3301,6 +3257,12 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// until the run reaches a clean completed turn, so every failure and every// early exit closes the span with error status.let runFailed = true;+ // The run's per-session staging lease release. `buildRuntime` returns it on+ // `prepared` after it acquires the lease; the startup step captures it here so+ // the run root `finally` can release it as the final settlement act. It stays+ // null on the host lane (no staging) and on a build failure (where+ // `buildRuntime` already released its own partial lease).+ let releaseStagingLease: (() => void) | null = null;try {// Evict idle staged runtimes BEFORE building the runtime, since buildRuntime// consults the staged cache to decide whether a compatible resume may reuse@@ -3366,37 +3328,78 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {let referencedProjectStagingFailuresField:| { referencedProjectStagingFailures: Array<{ projectId: string }> }| Record<string, never> = {};- // One teardown policy for the run. `settleRunResources` stops the bridges,- // runs the managed-home copy-back, releases the staging lease (in a finally- // inside cleanupRemoteBridges), and flushes the child stderr. It runs at most- // once, records each step error, and never throws, so a result-emission- // failure or an earlier teardown fault never skips a later step.- let runResourcesSettled = false;- // `turnTeardownDone` marks that the turn path already closed the runtime and- // settled the staged runtime, so a result-mapping throw after the close does- // not run the turn teardown a second time.- let turnTeardownDone = false;const recordTeardownError = async (step: string, teardownErr: unknown) => {const reason = teardownErr instanceof Error ? teardownErr.message : String(teardownErr);await ctx.onLog("stderr", `[paperclip] ACPX teardown step "${step}" failed: ${reason}\n`).catch(() => {});};- const settleRunResources = async () => {- if (runResourcesSettled) return;- runResourcesSettled = true;- try {- await cleanupRemoteBridges(prepared);- } catch (teardownErr) {- await recordTeardownError("cleanup-remote-bridges", teardownErr);- }+ // Emit one per-phase timing telemetry event. It is observability-only: it+ // carries the phase name (from the closed allowlist), the wall time, and the+ // outcome, and never a command, a path, an environment value, or an+ // identifier. Telemetry failure never fails the run.+ const emitPhase = (phase: string, startMs: number, outcome: "ok" | "failed"): Promise<void> =>+ emitRunPhaseTiming(ctx, phase, now() - startMs, outcome);+ // Time a settlement step and emit its phase timing on every path. A step+ // error still emits `failed` before it re-throws to the Phase 3 error policy.+ const timedPhase = async (phase: string, run: () => Promise<void> | void): Promise<void> => {+ const start = now();try {- if (childStderrState) flushChildStderr(childStderrState);- } catch (teardownErr) {- await recordTeardownError("flush-child-stderr", teardownErr);+ await run();+ } catch (error) {+ await emitPhase(phase, start, "failed");+ throw error;}+ await emitPhase(phase, start, "ok");};- try {+ // The turn the run started. It is hoisted to the run scope so the settlement+ // `endSession` step can cancel a running turn before it closes the runtime+ // (the cancel-before-close order). The turn wrapper assigns it in `turnStart`.+ let activeTurn: AcpRuntimeTurn | null = null;+ // How the settlement `endSession` step must release the runtime for the path+ // this run took. Each exit path that acquired the runtime records it before it+ // returns; a build or create-runtime failure never registers the runtime, so+ // the step no-ops on the empty slot and this stays null.+ let runtimeSettlement: RuntimeSettlementPlan | null = null;+ // A synthetic close handle from the prepared identity, for a close that has no+ // established session handle (a cold `ensureSession` throw or a missing+ // handle). `runtime.close` reads the session key and the runtime session name.+ const syntheticCloseHandle = (): AcpRuntimeHandle => ({+ sessionKey: prepared.sessionKey,+ backend: prepared.acpxAgent,+ runtimeSessionName: prepared.sessionKey,+ });+ // The run coordinator owns the one ledger for the attempt. The engine+ // creates it here, passes it into `buildRuntime` (the sandbox site registers+ // what it acquires into it), and hands it to `runAttempt` as the plan+ // ledger. The turn and settlement code still runs inline in the step+ // wrappers below; Phases 21-22 move it into its own modules.+ const runResourceLedger = createRunResourceLedger();+ // The step wrappers build the external result inline (today's behavior) and+ // record it here; the coordinator reproduces it after settlement. An empty+ // consumed set satisfies the `settle` result shape without claiming the run+ // ledger, because the inline teardown reads `prepared.*`, not the ledger, in+ // this phase.+ let capturedResult: AdapterExecutionResult | null = null;+ const emptyConsumed = createRunResourceLedger().takeForSettlement();+ // Build the `settle` startup result for a pre-turn failure. The step wrapper+ // already recorded the external result and ran the inline teardown; this+ // carries only the routing kind and the cause for the coordinator.+ const settleFor = (phase: PreTurnFailedCause["phase"], error: unknown): StartupResult => ({+ kind: "settle",+ cause: {+ kind: "pre_turn_failed",+ phase,+ error: error instanceof Error ? error : new Error(String(error)),+ },+ resources: emptyConsumed,+ });+ // The startup step: bring up the runtime, establish the session, and apply+ // the session config. It returns `ready` on success, `settle` on a pre-turn+ // failure after the ledger acquired resources, and throws on a build failure+ // or a partial-bridge failure (the coordinator owns that rollback).+ const startup = async (): Promise<StartupResult> => {+ try {// Publish the `sandbox.startup` context to the runtime-parent store for// the whole bring-up. A startup-body exec that runs outside a measured// step reads this token and parents its span to `sandbox.startup`, not to@@ -3405,9 +3408,22 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// parents to its step span. On a local or SSH target// `spanParent.parentContext` is a no-op token, so the wrap is inert.prepared = await runWithRuntimeParent(spanParent.parentContext, () =>- buildRuntime({ ctx, engine, deps, spanParent, getRuntimeParentContext, runtimeSpan: runRuntimeSpan, stageRuntimeSpan: runStageSpan }),+ buildRuntime({+ ctx,+ engine,+ deps,+ ledger: runResourceLedger,+ stagedIdleMs: warmIdleMs,+ spanParent,+ getRuntimeParentContext,+ runtimeSpan: runRuntimeSpan,+ stageRuntimeSpan: runStageSpan,+ }),);buildRuntimeSettled = true;+ // Capture the run's staging lease release now that the runtime built. The+ // run root `finally` releases it as the final settlement act.+ releaseStagingLease = prepared.sessionStagingLeaseRelease;// Per-project staging outcomes for the referenced (mentioned) projects, surfaced back to the// server on the run result. A referenced project that failed to stage into the sandbox is a// first-class, counted failure in the requested-vs-synced observability, not only a warning. The@@ -3427,12 +3443,16 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {"stderr",`[paperclip] ${formatAdapterExecutionTimeoutStartLogLine(prepared.timeoutResolution)}\n`,);- await cleanupIdleHandles({ handles: warmHandles, now: now(), idleMs: warmIdleMs });+ await hostStore.evictIdle(now());const previousParams = parseObject(ctx.runtime.sessionParams);const canResume = isCompatibleSession(previousParams, prepared);const resumeSessionId = canResume ? asString(previousParams.acpSessionId, "") || undefined : undefined;- const cached = canResume ? warmHandles.get(prepared.sessionKey) : undefined;+ // Borrow the warm entry without removing it, so an overlapping run of the+ // same session still sees it. The borrow clears the entry's idle timer, so+ // the reused runtime cannot expire under its own timer while this run uses+ // it (today's `clearWarmHandleTimer(cached)` after the reuse decision).+ const cached = canResume ? hostStore.borrow(prepared.sessionKey) : undefined;childStderrState = cached?.childStderrState ?? { logPath: null, pendingLiveLine: "" };processIdentitySink = cached?.processIdentitySink ?? {current: ctx.onSpawn,@@ -3493,8 +3513,27 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {const createRuntimeStart = now();runtime = createRuntime(runtimeOptions);createRuntimeMs = now() - createRuntimeStart;+ // The create_runtime phase runs only on a cold start.+ await emitRunPhaseTiming(ctx, "create_runtime", createRuntimeMs, "ok");}- if (cached) clearWarmHandleTimer(cached);+ // Register the runtime composite in the ledger now that it exists. The+ // settlement `endSession` step closes it on every path the reuse decision+ // does not transfer. Registration here (before `ensureSession`) closes the+ // cold-handshake leak: a cold `ensureSession` throw before a handle exists+ // still leaves the runtime in the ledger for `endSession` to close. A+ // create-runtime failure throws before this line, so the runtime never+ // enters the ledger and the settlement no-ops on the empty slot. The+ // session handle fills in below; the payload carries the best-known handle+ // for the composite (`runtime.close` is the one release boundary).+ runResourceLedger.register({+ id: "acp_runtime",+ payload: {+ runtime,+ sessionHandle: cached?.handle ?? syntheticCloseHandle(),+ childProcessPid: processIdentitySink.latest?.pid ?? null,+ },+ scope: "per_run",+ });if (!canResume && asString(previousParams.runtimeSessionName, "")) {await ctx.onLog("stdout",@@ -3503,6 +3542,9 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {}let handle = cached?.handle ?? null;+ // The ensure_session phase covers the handshake (session establishment or+ // resume) up to the established handle.+ const ensureSessionPhaseStart = now();resumedSession = Boolean(handle ?? resumeSessionId);try {@@ -3585,106 +3627,32 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {});}} catch (err) {- // Close the runtime on a pre-turn handshake failure and drop the matching- // warm entry, the same as the configuration failure path. A warm-hit- // reuse already cleared the idle timer before the handshake ran, so the- // failure must close and remove the entry, never re-arm it. The close and- // the staged-runtime drop run before the result emission, so a throwing- // emission never skips them; `settleRunResources` in the finally stops the- // bridges, releases the staging lease, and flushes the child stderr.- if (handle) {- await runtime.close({- handle,- reason: "paperclip handshake cleanup",- discardPersistentState: false,- }).catch((closeErr) => recordTeardownError("runtime-close", closeErr));- const existing = warmHandles.get(prepared.sessionKey);- if (warmHandleMatches(existing, runtime, handle) && existing) {- clearWarmHandleTimer(existing);- warmHandles.delete(prepared.sessionKey);- }- }- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- try {- const { classified, message } = await emitAcpxFailure({- ctx,- prepared,- err,- phase: "ensure_session",- });- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: message,- ...classified,- ...billingFields,- ...referencedProjectStagingFailuresField,- model: prepared.requestedModel || null,- clearSession,- resultJson: { phase: "ensure_session" },- summary: message,- };- } finally {- await settleRunResources();- }- }-- if (!handle) {- // ensureSession returned no session handle. Close the runtime the run- // constructed so its child process cannot leak. There is no established- // handle, so build a minimal one from the prepared identity; the close is- // best effort and never blocks the error result.- await runtime.close({- handle: {- sessionKey: prepared.sessionKey,- backend: prepared.acpxAgent,- runtimeSessionName: prepared.sessionKey,- },- reason: "paperclip missing-handle cleanup",+ // Record how the settlement closes the runtime on a pre-turn handshake+ // failure: a direct close that drops a matching warm entry, the same as+ // the configuration-failure path. A warm-hit reuse already cleared the+ // idle timer before the handshake ran, so the failure must close and+ // remove the entry, never re-arm it. A cold `ensureSession` throw has no+ // established handle, so the settlement closes the synthetic handle — the+ // ledger now holds the runtime, so `endSession` closes it and the former+ // cold-handshake leak is gone. The settlement stops the bridges, releases+ // the staging lease, and flushes the child stderr on every exit path.+ runtimeSettlement = {+ mode: "direct",+ handle: handle ?? syntheticCloseHandle(),+ reason: "paperclip handshake cleanup",discardPersistentState: false,- }).catch((closeErr) => recordTeardownError("runtime-close", closeErr));- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- try {- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: "ACPX did not return a runtime session handle.",- errorCode: "acpx_runtime_error",- ...billingFields,- ...referencedProjectStagingFailuresField,- model: prepared.requestedModel || null,- resultJson: { phase: "ensure_session" },- summary: "ACPX did not return a runtime session handle.",- };- } finally {- await settleRunResources();- }- }- sessionHandle = handle;- startupFailed = false;- } catch (err) {- if (!buildRuntimeSettled) {- // buildRuntime failed before it staged or bridged anything, so there is- // nothing to settle here. The finally below ends the sandbox.startup- // span; let the failure propagate.- throw err;- }- // The post-build runtime-creation window failed after buildRuntime returned- // live bridges and a held staging lease. Drop the staged runtime, then emit- // and settle: `settleRunResources` in the finally stops the bridges,- // releases the staging lease, and flushes the child stderr even if the- // emission throws.- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- try {+ dropWarmEntry: true,+ recordCloseError: true,+ cancelTurnReason: null,+ };+ await emitPhase("ensure_session", ensureSessionPhaseStart, "failed");const { classified, message } = await emitAcpxFailure({ctx,prepared,err,- phase: "create_runtime",+ phase: "ensure_session",});- return {+ capturedResult = {exitCode: 1,signal: null,timedOut: false,@@ -3694,18 +3662,86 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {...referencedProjectStagingFailuresField,model: prepared.requestedModel || null,clearSession,- resultJson: { phase: "create_runtime" },+ resultJson: { phase: "ensure_session" },summary: message,};- } finally {- await settleRunResources();+ return settleFor("handshake", err);+ }++ if (!handle) {+ // ensureSession returned no session handle. The ledger holds the runtime+ // the run constructed, so record a direct close of the synthetic handle+ // for the settlement `endSession` step (the child process cannot leak).+ runtimeSettlement = {+ mode: "direct",+ handle: syntheticCloseHandle(),+ reason: "paperclip missing-handle cleanup",+ discardPersistentState: false,+ dropWarmEntry: false,+ recordCloseError: true,+ cancelTurnReason: null,+ };+ await emitPhase("ensure_session", ensureSessionPhaseStart, "failed");+ capturedResult = {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: "ACPX did not return a runtime session handle.",+ errorCode: "acpx_runtime_error",+ ...billingFields,+ ...referencedProjectStagingFailuresField,+ model: prepared.requestedModel || null,+ resultJson: { phase: "ensure_session" },+ summary: "ACPX did not return a runtime session handle.",+ };+ return settleFor(+ "session_handle_missing",+ new Error("ACPX did not return a runtime session handle."),+ );}+ sessionHandle = handle;+ startupFailed = false;+ await emitPhase("ensure_session", ensureSessionPhaseStart, "ok");+ } catch (err) {+ if (!buildRuntimeSettled) {+ // buildRuntime failed before it staged or bridged anything, so there is+ // nothing to settle here. The finally below ends the sandbox.startup+ // span; let the failure propagate.+ throw err;+ }+ // The post-build runtime-creation window failed after buildRuntime returned+ // live bridges and a held staging lease. `createRuntime` throws before the+ // ledger registers the runtime, so the settlement `endSession` step no-ops+ // on the empty slot (create_runtime never closes a runtime). The settlement+ // still stops the bridges, discards the staged runtime, releases the staging+ // lease, and flushes the child stderr.+ const { classified, message } = await emitAcpxFailure({+ ctx,+ prepared,+ err,+ phase: "create_runtime",+ });+ capturedResult = {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: message,+ ...classified,+ ...billingFields,+ ...referencedProjectStagingFailuresField,+ model: prepared.requestedModel || null,+ clearSession,+ resultJson: { phase: "create_runtime" },+ summary: message,+ };+ return settleFor("runtime_create", err);} finally {// End the sandbox.startup span exactly once, on every return and on every// throw. It covers buildRuntime through acp.handshake and no further; the// agent turn runs after and is out of the span's scope.rootSpan.end(startupFailed);}+ const configureSessionStart = now();try {await applySessionConfigOptions({runtime,@@ -3713,63 +3749,78 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {prepared,onLog: ctx.onLog,});+ await emitPhase("configure_session", configureSessionStart, "ok");} catch (err) {- // Close the runtime and drop the matching warm entry and the staged runtime- // before the result emission, so a throwing emission never skips them.- // `settleRunResources` in the finally stops the bridges, releases the- // staging lease, and flushes the child stderr.- await runtime.close({+ // Record a direct close that drops the matching warm entry for the+ // settlement `endSession` step. The settlement stops the bridges, discards+ // the staged runtime, releases the staging lease, and flushes the child+ // stderr on this exit path too.+ runtimeSettlement = {+ mode: "direct",handle: sessionHandle,reason: "paperclip config cleanup",discardPersistentState: false,- }).catch((closeErr) => recordTeardownError("runtime-close", closeErr));- const existing = warmHandles.get(prepared.sessionKey);- if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {- clearWarmHandleTimer(existing);- warmHandles.delete(prepared.sessionKey);- }- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- try {- const { classified, message } = await emitAcpxFailure({- ctx,- prepared,- err,+ dropWarmEntry: true,+ recordCloseError: true,+ cancelTurnReason: null,+ };+ await emitPhase("configure_session", configureSessionStart, "failed");+ const { classified, message } = await emitAcpxFailure({+ ctx,+ prepared,+ err,+ phase: "configure_session",+ });+ capturedResult = {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: message,+ ...classified,+ ...billingFields,+ ...referencedProjectStagingFailuresField,+ model: prepared.requestedModel || null,+ clearSession,+ resultJson: {phase: "configure_session",- });- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: message,- ...classified,- ...billingFields,- ...referencedProjectStagingFailuresField,- model: prepared.requestedModel || null,- clearSession,- resultJson: {- phase: "configure_session",- agent: prepared.acpxAgent,- requestedModel: prepared.requestedModel || null,- requestedThinkingEffort: prepared.requestedThinkingEffort || null,- fastMode: prepared.fastMode,- },- summary: message,- };- } finally {- await settleRunResources();- }+ agent: prepared.acpxAgent,+ requestedModel: prepared.requestedModel || null,+ requestedThinkingEffort: prepared.requestedThinkingEffort || null,+ fastMode: prepared.fastMode,+ },+ summary: message,+ };+ return settleFor("session_configuration", err);}- let cancelActiveTurn: ((reason: string) => Promise<void>) | null = null;- let controller: AbortController | null = null;- let timeout: NodeJS.Timeout | null = null;- let timedOut = false;+ // Startup succeeded: seal the ledger (promotes the startup_rollback entries+ // that survived to `per_run`) and hand the ready resources to the turn. The+ // turn wrapper reads the run state through the shared closure locals in this+ // phase, so the sealed view and the context are the contract carriers only.+ return {+ kind: "ready",+ resources: runResourceLedger.seal([]),+ context: { sessionKey: prepared.sessionKey } as unknown as AcpRunContext,+ };+ };+ // The turn step: run the turn sequence and settle the runtime inline+ // (today's behavior). The sequence owns the wall-clock timer and the abort+ // controller and never rejects; it returns a `TurnCompletion`. The step+ // bodies below record the external result for the coordinator to reproduce.+ const runTurn = async (_ready: StartupReady): Promise<TurnCompletion> => {const textParts: string[] = [];let eventBreakdown: AcpRuntimeUsageBreakdown | null = null;let eventCostUsd: number | null = null;- // `turnStarted` separates a pre-turn preparation failure (prompt build or- // metadata emit) from a failure of the running turn, so the turn catch below- // reports the right phase and settles the runtime on both.- let turnStarted = false;+ // The turn-local state the sequence steps share. `promptBuild` sets the+ // prompt, `preTurnUsage` sets the pre-turn status, `turnStart` sets the+ // active turn, and `turnFinalize` reads all three. `activeTurn` is the run-+ // scoped hoisted local, so the settlement `endSession` step can cancel it.+ let runPrompt = "";+ let preTurnStatus: AcpRuntimeStatus | null = null;+ // Phase-timing markers for the prepare_turn and turn phases. The prepare+ // phase covers the prompt build and the pre-turn usage snapshot; the turn+ // phase covers the started turn and the event relay.+ let preparePhaseStart = now();+ let turnPhaseStart = now();// Open the agent turn span as a child of the run root span. It wraps the// whole turn: the executor holds `turnSpan.parentContext` for later exec// parenting, and the `finally` below ends the span once on every path. The@@ -3779,12 +3830,13 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// a detached exec during the turn parents to `agent.turn`. The turn// `finally` resets the holder to the `task.run` token.currentRunParentContext = turnSpan.parentContext;- try {+ const stepPromptBuild = async (_signal: AbortSignal): Promise<void> => {// Build the prompt and emit the run metadata inside the turn failure- // boundary. A failure here settles the runtime through the turn catch and- // returns an error result with phase `prepare_turn`.+ // boundary. A failure here returns an error result with phase+ // `prepare_turn`.+ preparePhaseStart = now();const { prompt, promptMetrics, commandNotes } = await buildPrompt(ctx, resumedSession, prepared.env);- const runPrompt = joinPromptSections([prepared.skillPromptInstructions, prompt]);+ runPrompt = joinPromptSections([prepared.skillPromptInstructions, prompt]);await emitAcpxLog(ctx, {type: "acpx.session",agent: prepared.acpxAgent,@@ -3828,30 +3880,34 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {context: ctx.context,});}+ };+ const stepPreTurnUsage = async (): Promise<void> => {// Snapshot pre-turn usage so cumulative agent-reported cost can be// attributed to this run alone.- const preTurnStatus = await readRuntimeStatus(runtime, sessionHandle);- const timeoutMs = prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined;- controller = new AbortController();- if (timeoutMs) {- timeout = setTimeout(() => {- timedOut = true;- controller?.abort();- void cancelActiveTurn?.(formatAdapterExecutionTimeoutErrorMessage(prepared.timeoutResolution)).catch(() => {});- }, timeoutMs);- }+ preTurnStatus = await readRuntimeStatus(runtime, sessionHandle);+ // The prepare phase (prompt build + usage snapshot) finished; the turn+ // phase starts next.+ await emitPhase("prepare_turn", preparePhaseStart, "ok");+ turnPhaseStart = now();+ };+ const stepTurnStart = (signal: AbortSignal, startTimeoutMs: number | undefined): StartedTurn => {const turn = runtime.startTurn({handle: sessionHandle,text: runPrompt,mode: "prompt",requestId: ctx.runId,- timeoutMs,- signal: controller?.signal,+ timeoutMs: startTimeoutMs,+ signal,});- turnStarted = true;- cancelActiveTurn = async (reason: string) => {- await turn.cancel({ reason });+ activeTurn = turn;+ return {+ cancel: async (reason: string) => {+ await turn.cancel({ reason });+ },};+ };+ const stepEventRelay = async (): Promise<AcpRuntimeTurnResult> => {+ const turn = activeTurn as AcpRuntimeTurn;const toolTitles = new Map<string, string>();for await (const event of turn.events) {if (event.type === "text_delta") textParts.push(event.text);@@ -3861,9 +3917,15 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {}await emitRuntimeEvent(ctx, event, toolTitles);}- const terminal = await turn.result;- if (timeout) clearTimeout(timeout);- // Read usage before the close/warm-handle paths below can discard state.+ return await turn.result;+ };+ const stepTurnFinalize = async (+ input: TurnFinalizeInput<AcpRuntimeTurnResult>,+ ): Promise<TurnCompletion> => {+ if (input.kind === "terminal") {+ const terminal = input.terminal;+ const timedOut = input.timedOut;+ // Read usage before the settlement can discard runtime state.const postTurnStatus = await readRuntimeStatus(runtime, sessionHandle);const turnUsage = summarizeAcpxTurnUsage({preStatus: preTurnStatus,@@ -3871,81 +3933,29 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {eventBreakdown,eventCostUsd,});- if (terminal.status === "failed" || terminal.status === "cancelled" || timedOut) {- const existing = warmHandles.get(prepared.sessionKey);- if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {- await closeWarmHandle({- handles: warmHandles,- key: prepared.sessionKey,- entry: existing,- reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,- discardPersistentState: terminal.status === "cancelled" || timedOut,- });- } else {- await runtime.close({- handle: sessionHandle,- reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,- discardPersistentState: terminal.status === "cancelled" || timedOut,- }).catch(() => {});- }- } else if (prepared.mode === "persistent" && warmIdleMs > 0 && !prepared.processSessionBridge) {- const existing = warmHandles.get(prepared.sessionKey);- if (existing && !warmHandleMatches(existing, runtime, sessionHandle)) {- await runtime.close({- handle: sessionHandle,- reason: "paperclip duplicate warm handle cleanup",- discardPersistentState: false,- }).catch(() => {});- } else {- const entry: RuntimeCacheEntry = {- runtime,- handle: sessionHandle,- childStderrState,- processIdentitySink,- fingerprint: prepared.fingerprint,- lastUsedAt: now(),- };- warmHandles.set(prepared.sessionKey, entry);- scheduleIdleHandleCleanup({- handles: warmHandles,- key: prepared.sessionKey,- entry,- idleMs: warmIdleMs,- now,- });- }- } else {- const existing = warmHandles.get(prepared.sessionKey);- if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {- await closeWarmHandle({- handles: warmHandles,- key: prepared.sessionKey,- entry: existing,- reason: "paperclip completed turn cleanup",- });- } else {- await runtime.close({- handle: sessionHandle,- reason: "paperclip completed turn cleanup",- discardPersistentState: false,- }).catch(() => {});- }- }-- // PR 3: keep the staged runtime warm for the next compatible resume only- // after a clean turn; a failed/cancelled/timed-out turn discards it so the- // next run stages fresh instead of reusing a torn-down session's staged- // credentials. Copy-back still fires for every outcome via- // `cleanupRemoteBridges` below (unchanged from PR 2).- if (terminal.status === "completed" && !timedOut) {- saveStagedRuntimeAfterCleanTurn({ handles: stagedRuntimes, prepared, now: now() });- } else {- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- }- // The turn path has closed the runtime and settled the staged runtime. Mark- // it done so a result-mapping throw below runs the turn teardown once, not a- // second time through the catch.- turnTeardownDone = true;+ const failedTurn = terminal.status === "failed" || terminal.status === "cancelled" || timedOut;+ // Record how the settlement `endSession` step closes the runtime for this+ // outcome. A clean persistent host turn is save-eligible, but the+ // Amendment B credential gate fails on the host lane (the run API key is+ // never revoked), so the reuse decision discards and `endSession` closes it+ // (close-and-relaunch). The sandbox lane always closes the runtime; its+ // staged files are the reuse. A matching warm entry closes through the warm+ // store (which also flushes its stderr); otherwise the runtime closes+ // directly. The settlement then stops the bridges, saves or discards the+ // staged runtime, releases the staging lease, and flushes the child stderr.+ runtimeSettlement = {+ mode: "warm_or_close",+ handle: sessionHandle,+ reason: timedOut+ ? "paperclip timeout cleanup"+ : failedTurn+ ? `paperclip turn ${terminal.status}`+ : "paperclip completed turn cleanup",+ discardPersistentState: terminal.status === "cancelled" || timedOut,+ dropWarmEntry: false,+ recordCloseError: false,+ cancelTurnReason: null,+ };const errorMessage = timedOut? formatAdapterExecutionTimeoutErrorMessage(prepared.timeoutResolution)@@ -3957,17 +3967,10 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {stopReason: terminalStopReason,message: errorMessage,});- // Settle the run resources once: stop the bridges, run the copy-back,- // release the staging lease (in a finally inside cleanupRemoteBridges), and- // flush the child stderr. Mark them settled first so a result-mapping throw- // below does not run the teardown again through the turn catch.- runResourcesSettled = true;- await cleanupRemoteBridges(prepared);- flushChildStderr(childStderrState);// The one clean-completion path clears the run failure flag; every other// path keeps it set, so the run root span closes with error status.runFailed = terminal.status === "completed" && !timedOut ? false : true;- return {+ capturedResult = {exitCode: terminal.status === "completed" ? 0 : 1,signal: timedOut ? "SIGTERM" : null,timedOut,@@ -3997,64 +4000,117 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {summary: textParts.join("").trim() || terminalStopReason || terminal.status,clearSession,};- } catch (err) {- if (timeout) clearTimeout(timeout);- // A failure before `startTurn` returned is a turn-preparation failure; a- // failure after it is a running-turn failure. The teardown is the same;- // only the reported phase differs.- const phase: AcpxExecutionPhase = turnStarted ? "turn" : "prepare_turn";+ // The turn phase finished. A completed, non-timed-out turn is `ok`; every+ // other terminal outcome is `failed`.+ await emitPhase(+ "turn",+ turnPhaseStart,+ terminal.status === "completed" && !timedOut ? "ok" : "failed",+ );+ // Return the typed turn completion so the coordinator settles for the right+ // cause. The completion carries no live resources; the settlement claims the+ // ledger and owns the release. A clean completed turn carries no cause, so+ // the reuse decision can permit a save; a timed-out, failed, or cancelled+ // turn carries its cause, which forbids the save.+ if (timedOut) {+ return {+ kind: "timed_out",+ cause: { kind: "turn_timed_out", timeoutSec: prepared.timeoutSec },+ resources: emptyConsumed,+ };+ }+ if (terminal.status === "failed") {+ return {+ kind: "failed",+ cause: {+ kind: "turn_failed",+ error: terminal.error instanceof Error ? terminal.error : new Error(String(terminal.error)),+ },+ resources: emptyConsumed,+ };+ }+ if (terminal.status === "cancelled") {+ return {+ kind: "cancelled",+ cause: { kind: "turn_cancelled", reason: terminal.stopReason ?? "cancelled" },+ resources: emptyConsumed,+ };+ }+ return { kind: "finalized" };+ }+ const err = input.error;+ const timedOut = input.timedOut;+ // The failure phase comes from the sequence: a failure before the turn+ // started is `prepare_turn`; a failure after it is `turn`. The teardown is+ // the same; only the reported phase differs.+ const phase: AcpxExecutionPhase = input.phase;+ // Emit the failed phase timing for the phase the sequence reported.+ if (phase === "prepare_turn") {+ await emitPhase("prepare_turn", preparePhaseStart, "failed");+ } else {+ await emitPhase("turn", turnPhaseStart, "failed");+ }const messageOverride = timedOut? formatAdapterExecutionTimeoutErrorMessage(prepared.timeoutResolution): undefined;- const cancel = cancelActiveTurn as ((reason: string) => Promise<void>) | null;const preEmitMessage =messageOverride ?? (err instanceof Error ? err.message : String(err));- // Skip the cancel, close, and staged-runtime drop when the success path- // already ran them: a result-mapping throw after the close reaches this- // catch, and the turn teardown must not run twice. The close records its- // error and never blocks the later teardown; `settleRunResources` in the- // finally stops the bridges, releases the staging lease, and flushes the- // child stderr even if the emission throws.- if (!turnTeardownDone) {- turnTeardownDone = true;- if (cancel) await cancel(preEmitMessage).catch(() => {});- await runtime.close({- handle: sessionHandle,- reason: timedOut ? "paperclip timeout cleanup" : "paperclip error cleanup",- discardPersistentState: timedOut,- }).catch((closeErr) => recordTeardownError("runtime-close", closeErr));- const existing = warmHandles.get(prepared.sessionKey);- if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {- clearWarmHandleTimer(existing);- warmHandles.delete(prepared.sessionKey);- }- await discardStagedRuntime({ handles: stagedRuntimes, prepared });- }+ // Record a direct close for the settlement `endSession` step: cancel the+ // running turn first (cancel-before-close), then close the runtime and drop+ // a matching warm entry. The settlement discards the staged runtime, stops+ // the bridges, releases the staging lease, and flushes the child stderr.+ runtimeSettlement = {+ mode: "direct",+ handle: sessionHandle,+ reason: timedOut ? "paperclip timeout cleanup" : "paperclip error cleanup",+ discardPersistentState: timedOut,+ dropWarmEntry: true,+ recordCloseError: true,+ cancelTurnReason: preEmitMessage,+ };+ // Emit the failure best-effort. `turnFinalize` must not reject, so a+ // failing emission never propagates: the settlement owns the teardown, and+ // it runs only after this returns a completion. On an emission failure the+ // run records a degraded result from the pre-emit message.+ let emitted: Awaited<ReturnType<typeof emitAcpxFailure>> | null = null;try {- const { classified, message } = await emitAcpxFailure({- ctx,- prepared,- err,- phase,- messageOverride,- });- return {- exitCode: 1,- signal: timedOut ? "SIGTERM" : null,- timedOut,- errorMessage: message,- errorCode: timedOut ? "acpx_timeout" : classified.errorCode,- errorMeta: classified.errorMeta,- ...billingFields,- ...referencedProjectStagingFailuresField,- model: prepared.requestedModel || null,- clearSession: clearSession || timedOut,- resultJson: { phase },- summary: message,- };- } finally {- await settleRunResources();+ emitted = await emitAcpxFailure({ ctx, prepared, err, phase, messageOverride });+ } catch {+ emitted = null;}+ const message = emitted?.message ?? preEmitMessage;+ capturedResult = {+ exitCode: 1,+ signal: timedOut ? "SIGTERM" : null,+ timedOut,+ errorMessage: message,+ errorCode: timedOut ? "acpx_timeout" : (emitted?.classified.errorCode ?? null),+ errorMeta: emitted?.classified.errorMeta,+ ...billingFields,+ ...referencedProjectStagingFailuresField,+ model: prepared.requestedModel || null,+ clearSession: clearSession || timedOut,+ resultJson: { phase },+ summary: message,+ };+ // Return a typed failed completion so the coordinator settles for a cause+ // that forbids the save. The reported phase lives on the recorded result.+ return {+ kind: "failed",+ cause: { kind: "turn_failed", error: err instanceof Error ? err : new Error(String(err)) },+ resources: emptyConsumed,+ };+ };+ try {+ return await runTurnSequence<AcpRuntimeTurnResult>({+ timeoutMs: prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined,+ timeoutMessage: formatAdapterExecutionTimeoutErrorMessage(prepared.timeoutResolution),+ promptBuild: stepPromptBuild,+ preTurnUsage: stepPreTurnUsage,+ turnStart: stepTurnStart,+ eventRelay: stepEventRelay,+ turnFinalize: stepTurnFinalize,+ });} finally {// End the agent turn span exactly once, on every return and on a throw.// `runFailed` is `false` only on a completed, non-timed-out turn, so the@@ -4065,9 +4121,182 @@ export function createAcpxEngineExecutor(deps: AcpxEngineExecutorOptions = {}) {// exec after the turn parents to `task.run`.currentRunParentContext = runRootSpan.parentContext;}+ };+ // A live run-scoped credential marker. The host-lane reuse candidate carries+ // it, so the Amendment B credential gate blocks the host warm save: the+ // run-minted API key is never revoked, so it stays valid and forces a+ // close-and-relaunch. It is a non-secret marker; the settlement reads only its+ // presence, and no report or reuse payload carries it.+ const LIVE_RUN_SCOPED_API_KEY = "paperclip-run-scoped-api-key";+ // Record the final per-resource disposition report where a test can observe+ // it. The engine never reads it back.+ const recordDispositionReport = (report: SettlementDispositionReport): void => {+ deps.onSettlementDisposition?.(report);+ };+ // The settlement sequence is the one live cleanup owner for every settled path+ // (Phase 22). It claims the ledger once, makes the pure reuse decision, then+ // runs the ordered steps: `endSession`, `settleReuse`, `stopTransport`,+ // `syncBack`, and `releaseStagingLease` (in a finally). Each step reads the run+ // state through the shared closure locals and no-ops on an empty ledger slot.+ // The Phase 3 error policy governs every step. The coordinator alone owns the+ // startup rollback.+ const settlementSteps: SettlementSteps = {+ // Derive the reuse candidate. Only a clean turn (no cause) can save. The+ // host lane would save the live runtime, but the Amendment B credential gate+ // fails there: the run-minted API key is never revoked, so a live run-scoped+ // credential stays valid and the decision discards (close-and-relaunch). The+ // sandbox lane saves its staged files, which carry no credential.+ reuseCandidate: (slots, cause) => {+ const clean = cause === null;+ if (prepared.processSessionBridge) {+ // Sandbox lane: the staged files are the reuse. Save only after a clean+ // turn and only when the run holds a staged runtime.+ if (!clean || !slots.has("staged_runtime")) return null;+ return { kind: "sandbox", causePermitsSave: true, liveRunScopedCredentials: [] };+ }+ // Host lane: save a clean persistent warm-eligible turn, but carry the+ // live run-scoped credential so the gate blocks the transfer.+ if (!slots.has("acp_runtime")) return null;+ const permits = clean && prepared.mode === "persistent" && warmIdleMs > 0;+ if (!permits) return null;+ return { kind: "host", causePermitsSave: true, liveRunScopedCredentials: [LIVE_RUN_SCOPED_API_KEY] };+ },+ // Close every runtime the decision did not transfer, and drop the warm entry+ // on close.+ endSession: (slots, decision) => timedPhase("end_session", async () => {+ if (!slots.has("acp_runtime")) return;+ if (decision.kind === "save" && decision.savedId === "acp_runtime") return;+ const settlement: RuntimeSettlementPlan = runtimeSettlement ?? {+ mode: "direct",+ handle: syntheticCloseHandle(),+ reason: "paperclip cleanup",+ discardPersistentState: false,+ dropWarmEntry: false,+ recordCloseError: true,+ cancelTurnReason: null,+ };+ // Cancel a running turn before the close (the turn-error path).+ if (settlement.cancelTurnReason && activeTurn) {+ await activeTurn.cancel({ reason: settlement.cancelTurnReason }).catch(() => {});+ }+ const existing = warmHandles.get(prepared.sessionKey);+ if (+ settlement.mode === "warm_or_close" &&+ warmHandleMatches(existing, runtime, settlement.handle) &&+ existing+ ) {+ // A matching warm entry closes through the warm store, which also+ // clears its idle timer and flushes its child stderr.+ await closeWarmHandle({+ handles: warmHandles,+ key: prepared.sessionKey,+ entry: existing,+ reason: settlement.reason,+ discardPersistentState: settlement.discardPersistentState,+ });+ return;+ }+ const onCloseError = settlement.recordCloseError+ ? (closeErr: unknown) => recordTeardownError("runtime-close", closeErr)+ : () => {};+ await runtime+ .close({+ handle: settlement.handle,+ reason: settlement.reason,+ discardPersistentState: settlement.discardPersistentState,+ })+ .catch(onCloseError);+ if (settlement.dropWarmEntry && warmHandleMatches(existing, runtime, settlement.handle) && existing) {+ clearWarmHandleTimer(existing);+ warmHandles.delete(prepared.sessionKey);+ }+ }),+ // Perform the reuse decision. A save transfers the staged files to the site+ // store (which arms the idle policy); every other case discards the staged+ // runtime. The host warm save is closed in `endSession`.+ settleReuse: (slots, decision) => timedPhase("settle_reuse", async () => {+ if (!slots.has("staged_runtime")) return;+ if (decision.kind === "save" && decision.savedId === "staged_runtime") {+ saveStagedRuntimeAfterCleanTurn({ handles: stagedRuntimes, prepared, now: now() });+ return;+ }+ await discardStagedRuntime({ handles: stagedRuntimes, prepared });+ }),+ // Stop both bridges in one allSettled.+ stopTransport: () => timedPhase("stop_transport", async () => {+ await stopRunTransport(prepared);+ }),+ // The site sync-back (the managed-home copy-back).+ syncBack: () => timedPhase("sync_back", async () => {+ await syncBackManagedHome(prepared);+ }),+ // The staging lease releases as the run's final act, AFTER the coordinator+ // reproduces the result, in the run root `finally` below. This step stays a+ // no-op in the live engine: a same-session second run must stay blocked on+ // the lease until this run fully returns, not merely until the settlement+ // sync-back finishes, so the release cannot move earlier into settlement.+ releaseStagingLease: () => {},+ recordError: async (step, error) => {+ await recordTeardownError(`settlement-${step}`, error);+ },+ };+ // Drive the attempt through the coordinator routing table. The startup step+ // returns `ready` or `settle` (or throws on a build or partial-bridge+ // failure); the coordinator runs the turn on the ready path, settles, then+ // reproduces the recorded result.+ const plan: RunPlan<AdapterExecutionResult> = {+ ledger: runResourceLedger,+ startup,+ runTurn,+ // The coordinator owns the startup rollback: `buildRuntime` runs its own+ // partial-bring-up rollback and throws, so no ledger resource is left to+ // release here.+ rollbackStartup: () => {},+ recordDisposition: recordDispositionReport,+ // The settlement sequence is the one live cleanup owner. It claims the+ // ledger, releases every settled resource, and returns the final+ // disposition report. The child stderr flushes after the sync-back on every+ // settled exit path (it stays null before the run reads the warm entry).+ settle: async (reason: SettlementReason) => {+ const cause: SettlementCause | null =+ reason.kind === "pre_turn"+ ? reason.cause+ : reason.completion.kind === "finalized"+ ? null+ : reason.completion.cause;+ const report = await settleAcpRun(runResourceLedger, cause, settlementSteps);+ recordDispositionReport(report);+ if (childStderrState) flushChildStderr(childStderrState);+ },+ reproduceResult: (): AdapterExecutionResult => {+ if (!capturedResult) {+ throw new Error("run coordinator reproduced a result before the run recorded one");+ }+ return capturedResult;+ },+ };+ return await runAttempt(plan);} finally {// End the run root span exactly once, on every return and on a throw.runRootSpan.end(runFailed);+ // Release the per-session staging lease as the run's final act, AFTER the+ // coordinator settled every other resource and reproduced the result. It runs+ // last, in this `finally`, so a same-session second run stays blocked on the+ // lease until this run fully returns (not merely until the settlement+ // sync-back finishes) and an earlier teardown fault never strands the lease.+ // It stays null on a build failure (where `buildRuntime` released its own+ // partial lease) and on the host lane (no staging). The settlement stopped the+ // bridges and ran the sync-back before this point, so the ordering is+ // bridge-stop → sync-back → lease release.+ const leaseRelease = releaseStagingLease as (() => void) | null;+ if (leaseRelease) {+ const leaseStart = now();+ leaseRelease();+ // Fire-and-forget the phase timing: the release is the run's final act, so+ // the run must not await telemetry here. `emitRunPhaseTiming` swallows a+ // sink failure, so this never rejects.+ void emitRunPhaseTiming(ctx, "release_staging_lease", now() - leaseStart, "ok");+ }}};}diff --git a/packages/adapter-utils/src/acpx-engine/run-contracts.test.ts b/packages/adapter-utils/src/acpx-engine/run-contracts.test.tsnew file mode 100644index 0000000000..14dcaea70f--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-contracts.test.ts@@ -0,0 +1,85 @@+// Compile-time type tests for the run contracts.+//+// The real assertion in each test is that this file compiles. A `@ts-expect-error`+// marks an assignment that MUST fail to typecheck; if it starts to compile, tsc+// reports the unused directive and the typecheck fails. The runtime body only+// keeps vitest happy, so each test names the property it proves.++import { describe, expect, it } from "vitest";+import type {+ AcquiredRunResources,+ ConsumedRunResources,+ PreTurnFailedCause,+ ReadyRunResources,+ SessionFingerprintIdentity,+ TurnCause,+} from "./run-contracts.js";++// A type-level equality check. `Equal<A, B>` is true only when A and B are the+// same type.+type Equal<A, B> =+ (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;+type Expect<T extends true> = T;++describe("run contracts", () => {+ it("test_a_turn_cause_is_not_assignable_where_pre_turn_failed_cause_is_required", () => {+ function requiresPreTurn(_cause: PreTurnFailedCause): void {}+ const turnCause: TurnCause = { kind: "turn_failed", error: new Error("boom") };++ // A turn cause has a different `kind` and no `phase`, so it is not+ // assignable where a `PreTurnFailedCause` is required.+ // @ts-expect-error a TurnCause is not a PreTurnFailedCause.+ requiresPreTurn(turnCause);++ expect(turnCause.kind).toBe("turn_failed");+ });++ it("test_only_seal_produces_ready_run_resources_and_only_take_for_settlement_produces_consumed_run_resources", () => {+ // The assertions live in an unexecuted function so tsc checks the types+ // without a runtime call on a synthetic ledger.+ function _assertBrands(ledger: AcquiredRunResources): void {+ // `seal()` is the only source of a `ReadyRunResources`;+ // `takeForSettlement()` is the only source of a `ConsumedRunResources`.+ const ready: ReadyRunResources = ledger.seal([]);+ const consumed: ConsumedRunResources = ledger.takeForSettlement();++ // The two brands are distinct: neither result is assignable to the other.+ // @ts-expect-error a ReadyRunResources is not a ConsumedRunResources.+ const _crossA: ConsumedRunResources = ready;+ // @ts-expect-error a ConsumedRunResources is not a ReadyRunResources.+ const _crossB: ReadyRunResources = consumed;++ // A plain object cannot stand in for a branded result; it lacks the+ // private brand that only `seal()` / `takeForSettlement()` can set.+ // @ts-expect-error missing the private ready brand.+ const _fakeReady: ReadyRunResources = {+ get: () => undefined,+ scopeOf: () => undefined,+ has: () => false,+ sealed: [],+ };+ // @ts-expect-error missing the private consumed brand.+ const _fakeConsumed: ConsumedRunResources = { entries: () => [] };++ void ready;+ void consumed;+ void _crossA;+ void _crossB;+ void _fakeReady;+ void _fakeConsumed;+ }++ void _assertBrands;+ expect(true).toBe(true);+ });++ it("test_session_fingerprint_identity_has_no_company_agent_or_task_member", () => {+ // None of the outer-key parts appear as a fingerprint field.+ type ForbiddenKey = "companyId" | "agentId" | "taskKey";+ type LeakedKey = Extract<keyof SessionFingerprintIdentity, ForbiddenKey>;+ type _noLeak = Expect<Equal<LeakedKey, never>>;++ const _ok: _noLeak = true;+ expect(_ok).toBe(true);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-contracts.ts b/packages/adapter-utils/src/acpx-engine/run-contracts.tsnew file mode 100644index 0000000000..a82501bd47--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-contracts.ts@@ -0,0 +1,509 @@+// Contract types for the ACPX run coordinator refactor.+//+// This module declares the types only. No production code consumes them yet.+// Each placeholder type maps to a field that `AcpxPreparedRuntime` carries in+// `execute.ts` today. The later coordinator phases move the ownership of those+// fields onto these contracts one seam at a time.+//+// Two brands (`ReadyRunResources`, `ConsumedRunResources`) mark a resource set+// that only the resource ledger can produce. Two more brands mark a run-scoped+// launch contribution and the finalized launch environment. A brand is a private+// `unique symbol`, so no other module can build a branded value by a plain+// object literal. Only the module that owns the symbol returns the value.++import type { AcpRuntime, AcpRuntimeHandle } from "acpx/runtime";+import type {+ AdapterExecutionTarget,+ AdapterExecutionTargetPaperclipBridgeHandle,+ AdapterExecutionTargetProcessSessionBridgeHandle,+ PreparedAdapterExecutionTargetRuntime,+} from "@paperclipai/adapter-utils/execution-target";++// ---------------------------------------------------------------------------+// Resource identity+// ---------------------------------------------------------------------------++/**+ * The closed set of run resources the ledger can hold. The set is fixed; a new+ * resource needs a new member here and a payload in `RunResourcePayloads`.+ *+ * `acp_runtime` is a composite of the runtime, the session handle, and the+ * child process. `runtime.close()` is the one release boundary for all three.+ *+ * These are NOT resources and never enter the ledger: `sessionKey`, the+ * environment lease, the realized execution target, the cleanup registrations,+ * the reuse-store entries, the three OTel spans, the turn timer, the child+ * stderr flush state, and the idle timers.+ */+export type ResourceId =+ | "acp_runtime"+ | "staged_runtime"+ | "control_bridge"+ | "agent_bridge"+ | "managed_home"+ | "staging_lease";++/**+ * The outcome the ledger records for a resource when it leaves the ledger.+ * `finalized` means the run released the resource here. `transferred` means the+ * run handed ownership to settlement.+ */+export type ResourceDisposition = "finalized" | "transferred";++/**+ * The lifetime a cleanup belongs to.+ *+ * A `startup_rollback` cleanup runs only when startup fails, to undo a partial+ * bring-up. A `per_run` cleanup runs at settlement, at the end of the run. A+ * successful `seal()` promotes each promotable `startup_rollback` entry to+ * `per_run`, because the resource now lives through the whole run.+ */+export type CleanupScope = "startup_rollback" | "per_run";++// ---------------------------------------------------------------------------+// Resource payloads+// ---------------------------------------------------------------------------++/**+ * The `acp_runtime` composite. `runtime.close()` releases the runtime, the+ * session handle, and the child process together. Maps to the runtime, the+ * session handle, and the spawned child that `execute.ts` builds in+ * `buildRuntime`.+ */+export interface AcpRuntimeResource {+ readonly runtime: AcpRuntime;+ readonly sessionHandle: AcpRuntimeHandle;+ /** The pid of the spawned agent child, or null before the first spawn. */+ readonly childProcessPid: number | null;+}++/**+ * The staged in-sandbox runtime and its one-time host-side cleanup. Maps to+ * `AcpxPreparedRuntime.stagedRuntime` and `remoteStagingDispose`.+ */+export interface StagedRuntimeResource {+ readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;+ /** Remove the host-side staged temp. Fired only when the stage is dropped. */+ readonly disposeStaged: () => Promise<void>;+}++/**+ * The per-adapter managed-home seam. Maps to+ * `AcpxPreparedRuntime.remoteManagedHomeTeardown` and `remoteStagingEnvDelta`.+ */+export interface ManagedHomeResource {+ /** Per-run copy-back hook. Runs the auth copy-back on every exit path. */+ readonly teardown: () => Promise<void>;+ /** The env keys the seam mutated on this run. */+ readonly envDelta: Record<string, string>;+}++/**+ * The per-session staging lease. Maps to+ * `AcpxPreparedRuntime.sessionStagingLeaseRelease`.+ */+export interface StagingLeaseResource {+ /** Release the staging lease so a later overlapping run can re-stage. */+ readonly release: () => void;+}++/**+ * Maps each resource id to its payload. The `control_bridge` is the Paperclip+ * control-plane bridge; the `agent_bridge` is the agent process-session bridge.+ */+export interface RunResourcePayloads {+ readonly acp_runtime: AcpRuntimeResource;+ readonly staged_runtime: StagedRuntimeResource;+ readonly control_bridge: AdapterExecutionTargetPaperclipBridgeHandle;+ readonly agent_bridge: AdapterExecutionTargetProcessSessionBridgeHandle;+ readonly managed_home: ManagedHomeResource;+ readonly staging_lease: StagingLeaseResource;+}++/** One resource the caller registers into the ledger. */+export interface RunResourceRegistration<Id extends ResourceId = ResourceId> {+ readonly id: Id;+ readonly payload: RunResourcePayloads[Id];+ readonly scope: CleanupScope;+ /**+ * Marks a `startup_rollback` entry that `seal()` promotes to `per_run`.+ * Default true. Set false to pin the entry as rollback-only. Ignored for a+ * `per_run` entry.+ */+ readonly promotable?: boolean;+ /**+ * The ledger calls this once when it finalizes or transfers the resource. It+ * records the disposition. It runs no release itself.+ */+ readonly onDisposition?: (disposition: ResourceDisposition) => void;+}++/** One resource the settlement claim carries out of the ledger. */+export interface SettledResourceEntry<Id extends ResourceId = ResourceId> {+ readonly id: Id;+ readonly payload: RunResourcePayloads[Id];+ readonly scope: CleanupScope;+ readonly disposition: ResourceDisposition;+}++// ---------------------------------------------------------------------------+// Ledger surface and its two branded results+// ---------------------------------------------------------------------------++declare const READY_RUN_RESOURCES: unique symbol;+declare const CONSUMED_RUN_RESOURCES: unique symbol;++/**+ * The sealed, validated resource set. Only `AcquiredRunResources.seal()`+ * produces this brand. The turn reads its resources through this handle.+ */+export interface ReadyRunResources {+ readonly [READY_RUN_RESOURCES]: true;+ /** The payload for a resource id, or undefined when the slot is empty. */+ get<Id extends ResourceId>(id: Id): RunResourcePayloads[Id] | undefined;+ /** The scope of a resource id after promotion, or undefined when empty. */+ scopeOf(id: ResourceId): CleanupScope | undefined;+ /** True when the slot holds a resource. */+ has(id: ResourceId): boolean;+ /** The required ids that `seal()` validated. */+ readonly sealed: readonly ResourceId[];+}++/**+ * The one-time settlement claim. Only `AcquiredRunResources.takeForSettlement()`+ * produces this brand. Settlement releases the resources this claim carries.+ */+export interface ConsumedRunResources {+ readonly [CONSUMED_RUN_RESOURCES]: true;+ /** The resources, each with its final scope and disposition. */+ entries(): readonly SettledResourceEntry[];+}++/**+ * The write surface the startup path holds while it acquires resources.+ * `register` is the only writer. `seal` and `takeForSettlement` end the write+ * phase. The state machine is `open -> sealed -> consumed` or `open ->+ * consumed`.+ */+export interface AcquiredRunResources {+ register<Id extends ResourceId>(registration: RunResourceRegistration<Id>): void;+ seal(required: readonly ResourceId[]): ReadyRunResources;+ takeForSettlement(): ConsumedRunResources;+}++/** The error the ledger throws on an out-of-order or duplicate operation. */+export class LedgerStateError extends Error {+ constructor(message: string) {+ super(message);+ this.name = "LedgerStateError";+ }+}++// ---------------------------------------------------------------------------+// Startup, turn, and settlement outcomes+// ---------------------------------------------------------------------------++/**+ * The four phases a pre-turn failure can occur in. A pre-turn failure happens+ * after the ledger acquires resources but before the turn runs.+ */+export interface PreTurnFailedCause {+ readonly kind: "pre_turn_failed";+ readonly phase:+ | "runtime_create"+ | "handshake"+ | "session_handle_missing"+ | "session_configuration";+ readonly error: Error;+}++/** The turn ran and failed with an error. */+export interface TurnFailedCause {+ readonly kind: "turn_failed";+ readonly error: Error;+}++/** The caller cancelled the turn. */+export interface TurnCancelledCause {+ readonly kind: "turn_cancelled";+ readonly reason: string;+}++/** The turn hit its wall-clock timeout. */+export interface TurnTimedOutCause {+ readonly kind: "turn_timed_out";+ readonly timeoutSec: number;+}++/** A cause that the turn itself produced. Disjoint from `PreTurnFailedCause`. */+export type TurnCause = TurnFailedCause | TurnCancelledCause | TurnTimedOutCause;++/** Any cause that leads a run into settlement. */+export type SettlementCause = PreTurnFailedCause | TurnCause;++/**+ * Startup produced a ready runtime. The turn can run against these resources.+ */+export interface StartupReady {+ readonly kind: "ready";+ readonly resources: ReadyRunResources;+ readonly context: AcpRunContext;+}++/**+ * Startup failed after it acquired resources, so the run must settle them. A+ * build failure and a partial-bridge failure do NOT reach here — they throw,+ * and the coordinator owns that rollback (Phase 20).+ */+export interface StartupSettle {+ readonly kind: "settle";+ readonly cause: PreTurnFailedCause;+ readonly resources: ConsumedRunResources;+}++export type StartupResult = StartupReady | StartupSettle;++/**+ * The turn finished and released everything in place. It carries no resources,+ * so settlement has nothing to do.+ */+export interface FinalizedTurn {+ readonly kind: "finalized";+}++/** The turn failed. Settlement releases the carried resources. */+export interface FailedTurn {+ readonly kind: "failed";+ readonly cause: TurnFailedCause;+ readonly resources: ConsumedRunResources;+}++/** The caller cancelled the turn. Settlement releases the carried resources. */+export interface CancelledTurn {+ readonly kind: "cancelled";+ readonly cause: TurnCancelledCause;+ readonly resources: ConsumedRunResources;+}++/** The turn timed out. Settlement releases the carried resources. */+export interface TimedOutTurn {+ readonly kind: "timed_out";+ readonly cause: TurnTimedOutCause;+ readonly resources: ConsumedRunResources;+}++/** The four ways a turn completes. Only `FinalizedTurn` is resourceless. */+export type TurnCompletion = FinalizedTurn | FailedTurn | CancelledTurn | TimedOutTurn;++// ---------------------------------------------------------------------------+// Run site+// ---------------------------------------------------------------------------++/** The host site runs on the host. The sandbox site runs in a remote runner. */+export type RunSiteKind = "host" | "sandbox";++/**+ * The synchronous plan a site produces before the fingerprint build. `plan()`+ * must be synchronous, because `sessionCwd` is a fingerprint input.+ */+export interface SitePlan {+ /**+ * The cwd the session binds to and the fingerprint reads. `placeWorkspace` is+ * not its source; the site derives it before it places the workspace.+ */+ readonly sessionCwd: string;+ /**+ * The host-only spawn cwd for the relay proxy on the remote process-session+ * lane. Undefined on every other lane. Maps to `AcpxPreparedRuntime.+ * hostSpawnCwd`.+ */+ readonly spawnCwd: string | undefined;+ /** True only for a sandbox target, where the run emits real OTel spans. */+ readonly tracingEnabled: boolean;+}++/** One referenced project whose staging into the sandbox failed. */+export interface ReferencedProjectStagingFailure {+ readonly projectId: string;+}++/**+ * The result of placing the workspace. Carries the referenced-project staging+ * failures the run reports back on its result.+ */+export interface PlacedWorkspace {+ readonly referencedProjectStagingFailures: readonly ReferencedProjectStagingFailure[];+}++/** The transport handles the site started for the run. */+export interface RunSiteTransport {+ readonly controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;+ readonly agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;+}++/** What the host site's store can save: the live runtime and session handle. */+export interface HostReuseCandidate {+ readonly runtime: AcpRuntime;+ readonly sessionHandle: AcpRuntimeHandle;+}++/** What the sandbox site's store can save: the staged files. */+export interface SandboxReuseCandidate {+ readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;+}++export type RunSiteReuseCandidate = HostReuseCandidate | SandboxReuseCandidate;++/** Construction options for a `SessionReuseStore`. */+export interface SessionReuseStoreOptions {+ /**+ * The optional per-entry idle timeout, in milliseconds. When set, `evictIdle`+ * drops an entry that stayed idle longer than this bound.+ */+ readonly idleMs?: number;+}++/**+ * The per-site store that saves a reuse candidate across runs. The store is+ * generic in the saved type, so a generic `save` cannot know what a site saves.+ * `RunSite.reuseCandidate()` names the concrete type per site.+ */+export interface SessionReuseStore<T> {+ borrow(sessionKey: string): T | undefined;+ save(sessionKey: string, entry: T): void;+ /**+ * Identity-guarded removal that fires the idempotent release. It removes the+ * key synchronously, so a later reuse never reads a discarded entry. It+ * returns a promise the caller can await when the release must finish before+ * the run releases a downstream resource (e.g. the staging lease).+ */+ discard(sessionKey: string): void | Promise<void>;+ /**+ * Run-start idle sweep. It removes each stale key synchronously, so+ * `buildRuntime` never reuses an expired entry. It returns a promise the+ * caller can await so the sweep completes before the run reads the cache.+ */+ evictIdle(now: number): void | Promise<void>;+}++/**+ * A run site. The host site and the sandbox site differ in what they place,+ * what transport they start, and what their store saves.+ */+export interface RunSite<TReuse extends RunSiteReuseCandidate = RunSiteReuseCandidate> {+ readonly kind: RunSiteKind;+ /** Synchronous. Runs before the fingerprint build. */+ plan(context: AcpRunContext): SitePlan;+ placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace>;+ startTransport(context: AcpRunContext): Promise<RunSiteTransport>;+ reuse(): SessionReuseStore<TReuse>;+ /** Names the concrete candidate this site's store can save. */+ reuseCandidate(resources: ReadyRunResources): TReuse;+ syncBack(context: AcpRunContext): Promise<void>;+}++// ---------------------------------------------------------------------------+// Identity, launch environment, and run context+// ---------------------------------------------------------------------------++export type AcpxRunMode = "persistent" | "oneshot";+export type AcpxPermissionMode = "approve-all" | "approve-reads" | "deny-all";+export type AcpxNonInteractivePermissions = "deny" | "fail";++/** One MCP server, in the shape the fingerprint reads. */+export interface McpServerIdentity {+ readonly name: string;+ readonly url: string;+ readonly connectionId: string;+}++/** The Paperclip Claude settings the fingerprint reads. */+export interface PaperclipClaudeSettingsIdentity {+ readonly allow: readonly string[];+ readonly additionalDirectories: readonly string[];+ readonly defaultMode: string;+}++/**+ * The 17 fields the session fingerprint hashes. Company, agent, and task+ * identifiers are NOT here; they scope the outer session key only (see+ * `SessionKeyIdentity`). A change to any field here invalidates a warm handle+ * or a resumable session and forces a fresh launch.+ */+export interface SessionFingerprintIdentity {+ readonly acpxAgent: string;+ readonly agentCommand: string;+ readonly cwd: string;+ readonly mode: AcpxRunMode;+ readonly permissionMode: AcpxPermissionMode;+ readonly nonInteractivePermissions: AcpxNonInteractivePermissions;+ readonly requestedModel: string;+ readonly requestedThinkingEffort: string;+ readonly fastMode: boolean;+ readonly remoteExecutionIdentity: Record<string, unknown> | null;+ readonly additionalSourcesIdentity: Record<string, unknown>;+ readonly skillsIdentity: Record<string, unknown>;+ readonly skillPromptInstructions: string;+ readonly paperclipClaudeSettings: PaperclipClaudeSettingsIdentity | null;+ readonly mcpServers: readonly McpServerIdentity[];+ readonly secretManifestHash: string;+ readonly adapterEnvHash: string;+}++/**+ * The company, agent, and task parts of the session key. The key form is+ * `paperclip:companyId:agentId:taskKey:fingerprint`. These parts stay out of+ * the fingerprint hash.+ */+export interface SessionKeyIdentity {+ readonly companyId: string;+ readonly agentId: string;+ readonly taskKey: string;+}++declare const RUN_SCOPED_CONTRIBUTION: unique symbol;+declare const LAUNCH_ENVIRONMENT: unique symbol;++/**+ * A launch-environment contribution that lives for one run only. The run API+ * key and every bridge token are run-scoped. The brand makes this type+ * non-transferable: no reuse payload type can hold it (Amendment B).+ */+export interface RunScopedContribution {+ readonly scope: "run";+ readonly env: Record<string, string>;+ readonly [RUN_SCOPED_CONTRIBUTION]: true;+}++/**+ * A launch-environment contribution that lives for the whole session. The Codex+ * auth copy-back material is session-scoped.+ */+export interface SessionScopedContribution {+ readonly scope: "session";+ readonly env: Record<string, string>;+}++export type LaunchEnvironmentContribution = RunScopedContribution | SessionScopedContribution;++/**+ * The finalized launch environment. Only `finalizeLaunchEnvironment()`+ * (Phase 17) produces this brand. No reuse payload type can hold it.+ */+export interface LaunchEnvironment {+ readonly [LAUNCH_ENVIRONMENT]: true;+ readonly env: Readonly<Record<string, string>>;+}++/**+ * The context the coordinator threads through the run. The site reads the+ * execution target for its effective capabilities.+ */+export interface AcpRunContext {+ readonly executionTarget: AdapterExecutionTarget;+ readonly fingerprintIdentity: SessionFingerprintIdentity;+ readonly keyIdentity: SessionKeyIdentity;+ readonly fingerprint: string;+ readonly sessionKey: string;+ readonly launchEnvironment: LaunchEnvironment;+}diff --git a/packages/adapter-utils/src/acpx-engine/run-coordinator.test.ts b/packages/adapter-utils/src/acpx-engine/run-coordinator.test.tsnew file mode 100644index 0000000000..6818364b76--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-coordinator.test.ts@@ -0,0 +1,184 @@+import { describe, expect, it } from "vitest";+import { runAttempt, type RunPlan, type SettlementReason } from "./run-coordinator.js";+import { createRunResourceLedger } from "./run-resource-ledger.js";+import type {+ AcquiredRunResources,+ PreTurnFailedCause,+ ReadyRunResources,+ StartupReady,+ StartupResult,+ TurnCompletion,+} from "./run-contracts.js";++// The coordinator owns the run routing table. These tests drive it with fakes+// for the four steps (startup, turn, settle, reproduce) and assert the order and+// the routing, never the engine's real run state.++const readyResources = {} as ReadyRunResources;++function readyStartup(): StartupReady {+ return { kind: "ready", resources: readyResources, context: {} as StartupReady["context"] };+}++function preTurnCause(): PreTurnFailedCause {+ return { kind: "pre_turn_failed", phase: "handshake", error: new Error("handshake boom") };+}++function finalizedTurn(): TurnCompletion {+ return { kind: "finalized" };+}++// A minimal plan whose steps push their names into `order`, so a test reads the+// exact sequence the coordinator ran.+function makePlan(+ order: string[],+ overrides: Partial<RunPlan<string>> & { ledger?: AcquiredRunResources } = {},+): RunPlan<string> {+ const ledger = overrides.ledger ?? createRunResourceLedger();+ return {+ ledger,+ startup: overrides.startup ?? (async (): Promise<StartupResult> => {+ order.push("startup");+ return readyStartup();+ }),+ rollbackStartup: overrides.rollbackStartup ?? ((consumed) => {+ order.push(`rollback:${consumed.entries().length}`);+ }),+ recordDisposition: overrides.recordDisposition ?? ((report) => {+ order.push(`disposition:${report.records.map((r) => `${r.id}=${r.disposition}`).join(",")}`);+ }),+ runTurn: overrides.runTurn ?? (async (): Promise<TurnCompletion> => {+ order.push("turn");+ return finalizedTurn();+ }),+ settle: overrides.settle ?? (async (reason: SettlementReason) => {+ order.push(`settle:${reason.kind}`);+ }),+ reproduceResult: overrides.reproduceResult ?? (async (outcome) => {+ order.push(`reproduce:${outcome.kind}`);+ return "result";+ }),+ };+}++describe("ACPX run coordinator", () => {+ it("test_startup_throw_replays_startup_rollback_entries_and_rethrows", async () => {+ const order: string[] = [];+ // Fill a partial ledger with two startup_rollback entries that record their+ // release order when the rollback replays them.+ const ledger = createRunResourceLedger();+ const released: string[] = [];+ ledger.register({+ id: "staged_runtime",+ payload: {+ stagedRuntime: {} as never,+ disposeStaged: async () => {+ released.push("staged_runtime");+ },+ },+ scope: "startup_rollback",+ });+ ledger.register({+ id: "control_bridge",+ payload: { stop: async () => { released.push("control_bridge"); } } as never,+ scope: "startup_rollback",+ });++ const boom = new Error("build boom");+ const plan = makePlan(order, {+ ledger,+ startup: async (): Promise<StartupResult> => {+ order.push("startup");+ throw boom;+ },+ // Replay every claimed entry through its own release, newest first.+ rollbackStartup: async (consumed) => {+ for (const entry of [...consumed.entries()].reverse()) {+ if (entry.id === "staged_runtime") {+ await (entry.payload as { disposeStaged: () => Promise<void> }).disposeStaged();+ } else if (entry.id === "control_bridge") {+ await (entry.payload as { stop: () => Promise<void> }).stop();+ }+ }+ order.push("rollback");+ },+ });++ // The coordinator rethrows the original startup error.+ await expect(runAttempt(plan)).rejects.toBe(boom);+ // It replayed the startup_rollback entries through the partial ledger...+ expect(released).toEqual(["control_bridge", "staged_runtime"]);+ // ...recorded a disposition report that marks each claimed entry finalized...+ expect(order).toEqual([+ "startup",+ "rollback",+ "disposition:staged_runtime=finalized,control_bridge=finalized",+ ]);+ // ...and never ran the turn or the settlement.+ expect(order).not.toContain("turn");+ expect(order.some((step) => step.startsWith("settle"))).toBe(false);+ });++ it("test_settle_path_returns_error_result_after_settlement", async () => {+ const order: string[] = [];+ const cause = preTurnCause();+ const plan = makePlan(order, {+ startup: async (): Promise<StartupResult> => {+ order.push("startup");+ return { kind: "settle", cause, resources: createRunResourceLedger().takeForSettlement() };+ },+ settle: async (reason) => {+ expect(reason.kind).toBe("pre_turn");+ order.push("settle");+ },+ reproduceResult: async (outcome) => {+ expect(outcome.kind).toBe("pre_turn");+ order.push("reproduce");+ return "error-result";+ },+ });++ const result = await runAttempt(plan);+ expect(result).toBe("error-result");+ // The settle path never runs the turn; it settles first, then reproduces.+ expect(order).toEqual(["startup", "settle", "reproduce"]);+ });++ it("test_ready_path_runs_turn_then_settles_then_reproduces_result", async () => {+ const order: string[] = [];+ const plan = makePlan(order);++ const result = await runAttempt(plan);+ expect(result).toBe("result");+ // The ready path runs the turn, settles, then reproduces — in that order.+ expect(order).toEqual(["startup", "turn", "settle:turn", "reproduce:turn"]);+ });++ it("test_coordinator_has_no_catch_around_the_turn", async () => {+ // `runTurn` is contracted never to reject. This test proves the coordinator+ // holds no catch around the turn: an (illegal) turn rejection propagates out+ // of `runAttempt` unchanged, and neither settlement nor result reproduction+ // runs. A catch around the turn would swallow the rejection and route it into+ // settlement, so this rejection-propagation is the structural proof.+ const order: string[] = [];+ const boom = new Error("turn must never reject");+ const settleCalls: number[] = [];+ const reproduceCalls: number[] = [];+ const plan = makePlan(order, {+ runTurn: async (): Promise<TurnCompletion> => {+ throw boom;+ },+ settle: async () => {+ settleCalls.push(1);+ },+ reproduceResult: async () => {+ reproduceCalls.push(1);+ return "unreachable";+ },+ });++ await expect(runAttempt(plan)).rejects.toBe(boom);+ expect(settleCalls).toHaveLength(0);+ expect(reproduceCalls).toHaveLength(0);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-coordinator.ts b/packages/adapter-utils/src/acpx-engine/run-coordinator.tsnew file mode 100644index 0000000000..487d2e1e6b--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-coordinator.ts@@ -0,0 +1,125 @@+// The run coordinator.+//+// One `run()` coordinator owns the attempt. It sequences four steps: startup,+// turn, settlement, and result reproduction. It holds the routing table as+// data:+//+// * A build failure or a partial-bridge failure throws from startup. The+// coordinator's one catch replays the `startup_rollback` entries through the+// partial ledger, records the disposition report, and rethrows.+// * A runtime-create, handshake, missing-handle, or configuration failure+// produces a `settle` result. The coordinator settles the resources, then+// reproduces the error result.+// * Every other startup outcome produces a `ready` result. The coordinator+// runs the turn, settles the resources, then reproduces the turn result.+//+// The coordinator has no catch around the turn: the turn never rejects and+// returns a typed `TurnCompletion` (Phase 21). The external result is reproduced+// AFTER settlement, so a caller never observes a result before the run releases+// its resources.++import type {+ AcquiredRunResources,+ ConsumedRunResources,+ PreTurnFailedCause,+ ResourceDisposition,+ ResourceId,+ StartupReady,+ StartupResult,+ TurnCompletion,+} from "./run-contracts.js";++/** One resource's final disposition, as the coordinator or settlement records it. */+export interface ResourceDispositionRecord {+ readonly id: ResourceId;+ readonly disposition: ResourceDisposition;+}++/** The per-resource disposition report the coordinator records at each end. */+export interface SettlementDispositionReport {+ readonly records: readonly ResourceDispositionRecord[];+}++/** The cause the coordinator hands to settlement. A clean turn carries no cause. */+export type SettlementReason =+ | { readonly kind: "pre_turn"; readonly cause: PreTurnFailedCause }+ | { readonly kind: "turn"; readonly completion: TurnCompletion };++/** The outcome the coordinator hands to result reproduction. */+export type ReproducibleOutcome = SettlementReason;++/**+ * The four steps the coordinator sequences, plus the run ledger. The engine+ * supplies each step; the coordinator owns only the order and the startup+ * rollback. This keeps the coordinator free of the engine's private run state.+ */+export interface RunPlan<TResult> {+ /** The one run ledger for the attempt. The coordinator creates it (see `runAttempt`). */+ readonly ledger: AcquiredRunResources;+ /**+ * Run the startup sequence. It returns a `ready` or a `settle` result, or it+ * throws on a build failure or a partial-bridge failure.+ */+ startup(): Promise<StartupResult>;+ /**+ * Replay the `startup_rollback` entries the partial ledger carries. The+ * coordinator calls it only on a startup throw, with the claimed entries.+ */+ rollbackStartup(consumed: ConsumedRunResources): Promise<void> | void;+ /** Record the per-resource disposition report at the end of the run. */+ recordDisposition(report: SettlementDispositionReport): void;+ /** Run the turn against the ready resources. It never rejects. */+ runTurn(ready: StartupReady): Promise<TurnCompletion>;+ /**+ * Settle the run's resources for the given reason. The one cleanup owner. A+ * synchronous return adds no awaited boundary, so a step that already settled+ * inline keeps the caller's timing unchanged.+ */+ settle(reason: SettlementReason): void | Promise<void>;+ /** Reproduce the external result after settlement. */+ reproduceResult(outcome: ReproducibleOutcome): TResult | Promise<TResult>;+}++/**+ * Run the attempt through the routing table. The coordinator is the one owner of+ * the startup-to-settlement order.+ */+export async function runAttempt<TResult>(plan: RunPlan<TResult>): Promise<TResult> {+ let startupResult: StartupResult;+ try {+ startupResult = await plan.startup();+ } catch (startupError) {+ // The coordinator's only catch wraps startup. A build failure and a+ // partial-bridge failure reach here. Claim the partial ledger, replay its+ // `startup_rollback` entries, record the disposition report (each entry the+ // rollback released is `finalized`), and rethrow the original error.+ const consumed = plan.ledger.takeForSettlement();+ await plan.rollbackStartup(consumed);+ plan.recordDisposition(finalizedReport(consumed));+ throw startupError;+ }++ if (startupResult.kind === "settle") {+ // A pre-turn failure after the ledger acquired resources. Settle the+ // resources, then reproduce the error result AFTER settlement.+ const reason: SettlementReason = { kind: "pre_turn", cause: startupResult.cause };+ const settled = plan.settle(reason);+ if (settled) await settled;+ return plan.reproduceResult(reason);+ }++ // The ready path: run the turn, settle, then reproduce the result. There is no+ // catch around the turn — `runTurn` never rejects.+ const completion = await plan.runTurn(startupResult);+ const reason: SettlementReason = { kind: "turn", completion };+ const settled = plan.settle(reason);+ if (settled) await settled;+ return plan.reproduceResult(reason);+}++/** Build a disposition report that marks every claimed entry `finalized`. */+function finalizedReport(consumed: ConsumedRunResources): SettlementDispositionReport {+ return {+ records: consumed.entries().map((entry) => ({ id: entry.id, disposition: "finalized" as const })),+ };+}diff --git a/packages/adapter-utils/src/acpx-engine/run-fault-matrix.test.ts b/packages/adapter-utils/src/acpx-engine/run-fault-matrix.test.tsnew file mode 100644index 0000000000..eccb29c366--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-fault-matrix.test.ts@@ -0,0 +1,883 @@+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import {+ prepareAdapterExecutionTargetRuntime,+ startAdapterExecutionTargetPaperclipBridge,+ startAdapterExecutionTargetProcessSessionBridge,+} from "@paperclipai/adapter-utils/execution-target";+import { runChildProcess } from "../server-utils.js";++// The composed fault matrix.+//+// Each case drives the whole ACP run and asserts the run's final settlement+// disposition report. The report is the authority on which resources the run+// acquired and how each one left the run: `finalized` (the run released it) or+// `transferred` (the run saved it for reuse). For each case the file asserts:+//+// 1. the report keys equal the acquired subset of the six resource ids;+// 2. each resource carries exactly one disposition;+// 3. the external result equals the composed baseline for that exit path.+//+// The six resource ids are: acp_runtime, staged_runtime, control_bridge,+// agent_bridge, managed_home, staging_lease. The host lane acquires only+// acp_runtime; the sandbox lane acquires the staging and transport resources too.++// Wrap the staging seam and both sandbox bridges so a test can stub them without+// changing behavior for the other tests.+vi.mock("@paperclipai/adapter-utils/execution-target", async (importActual) => {+ const actual = await importActual<typeof import("@paperclipai/adapter-utils/execution-target")>();+ return {+ ...actual,+ prepareAdapterExecutionTargetRuntime: vi.fn(actual.prepareAdapterExecutionTargetRuntime),+ startAdapterExecutionTargetPaperclipBridge: vi.fn(actual.startAdapterExecutionTargetPaperclipBridge),+ startAdapterExecutionTargetProcessSessionBridge: vi.fn(actual.startAdapterExecutionTargetProcessSessionBridge),+ };+});++import {+ createAcpxEngineExecutor,+ type AcpxEngineExecutorOptions,+} from "./execute.js";+import { settleAcpRun, type SettlementSteps } from "./settlement-sequence.js";+import { createRunResourceLedger } from "./run-resource-ledger.js";+import { LedgerStateError, type ResourceId } from "./run-contracts.js";+import type { SettlementDispositionReport } from "./run-coordinator.js";++const tempRoots: string[] = [];++async function makeTempRoot() {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-acpx-fault-"));+ tempRoots.push(root);+ return root;+}++afterEach(async () => {+ await Promise.all(+ tempRoots.splice(0).map((root) =>+ fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 }),+ ),+ );+});++function createLocalSandboxRunner() {+ let counter = 0;+ return {+ execute: async (input: {+ command: string;+ args?: string[];+ cwd?: string;+ env?: Record<string, string>;+ stdin?: string;+ timeoutMs?: number;+ onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;+ onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;+ }) => {+ counter += 1;+ const command = input.command === "bash" ? "/bin/bash" : input.command;+ return await runChildProcess(`acpx-sandbox-run-${counter}`, command, input.args ?? [], {+ cwd: input.cwd ?? process.cwd(),+ env: input.env ?? {},+ stdin: input.stdin,+ timeoutSec: Math.max(1, Math.ceil((input.timeoutMs ?? 30_000) / 1000)),+ graceSec: 5,+ onLog: input.onLog ?? (async () => {}),+ onSpawn: input.onSpawn+ ? async (meta) => input.onSpawn?.({ pid: meta.pid, startedAt: meta.startedAt })+ : undefined,+ });+ },+ };+}++const okHandle = {+ backendSessionId: "backend-session",+ agentSessionId: "agent-session",+ runtimeSessionName: "runtime-session",+};++function completedTurn() {+ return {+ events: (async function* () {})(),+ result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),+ cancel: async () => {},+ };+}++function throwingTurn() {+ return {+ events: (async function* () {+ throw new Error("turn upstream boom");+ })(),+ result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),+ cancel: async () => {},+ };+}++function cancelledTurn() {+ return {+ events: (async function* () {})(),+ result: Promise.resolve({ status: "cancelled", stopReason: "cancelled" }),+ cancel: async () => {},+ };+}++// A runtime whose completed turn keeps the session handshake and turn simple.+function completedRuntime() {+ return {+ ensureSession: async () => okHandle,+ startTurn: () => completedTurn(),+ setConfigOption: async () => {},+ close: async () => {},+ } as never;+}++// A context whose only prompt-read field throws when read, so the prompt build+// fails after the session handshake and before the turn starts.+function throwingHandoffContext(): Record<string, unknown> {+ const context: Record<string, unknown> = {};+ Object.defineProperty(context, "paperclipSessionHandoffMarkdown", {+ enumerable: false,+ get() {+ throw new Error("prompt build boom");+ },+ });+ return context;+}++// Stub both sandbox bridges, so a case reaches the post-build window with live+// handles without running the real bridge transport. `stopRejects` makes the+// bridge stop reject during settlement.+function stubBridges(options: { stopRejects?: boolean } = {}) {+ const stop = options.stopRejects+ ? vi.fn(async () => {+ throw new Error("bridge stop boom");+ })+ : vi.fn(async () => {});+ vi.mocked(startAdapterExecutionTargetPaperclipBridge).mockImplementation(async () => {+ return { env: {}, stop } as never;+ });+ vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockImplementation(async () => {+ return { agentCommand: null, stop } as never;+ });+}++async function setupRemoteSandbox() {+ const root = await makeTempRoot();+ const stateDir = path.join(root, "state");+ const localCwd = path.join(root, "worktree");+ const remoteCwd = path.join(root, "remote-workspace");+ await fs.mkdir(localCwd, { recursive: true });+ await fs.mkdir(remoteCwd, { recursive: true });+ await fs.writeFile(path.join(localCwd, "hello.txt"), "hi", "utf8");+ const executionTarget = {+ kind: "remote",+ transport: "sandbox",+ providerKey: "fake-plugin",+ remoteCwd,+ runner: createLocalSandboxRunner(),+ };+ return { root, stateDir, localCwd, remoteCwd, executionTarget };+}++function remoteArgs(+ stateDir: string,+ localCwd: string,+ executionTarget: unknown,+ overrides: Record<string, unknown> = {},+) {+ return {+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: {},+ config: { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd: localCwd },+ context: {},+ authToken: "real-run-jwt",+ executionTarget,+ onLog: async () => {},+ onMeta: async () => {},+ onEvent: async () => {},+ ...overrides,+ };+}++// Seed the managed home through the staging seam and return a per-run copy-back+// so the run registers the managed_home resource. `teardownRejects` makes the+// copy-back reject during the settlement sync-back.+function managedHomeSeed(options: { teardownRejects?: boolean } = {}): AcpxEngineExecutorOptions["prepareRemoteManagedHome"] {+ return async (input) => {+ const stagedRuntime = await input.stage([]);+ return {+ stagedRuntime,+ teardown: options.teardownRejects+ ? async () => {+ throw new Error("copy-back boom");+ }+ : async () => {},+ };+ };+}++// Capture the final settlement disposition report the run records.+function captureDisposition() {+ const reports: SettlementDispositionReport[] = [];+ return {+ onSettlementDisposition: (report: SettlementDispositionReport) => {+ reports.push(report);+ },+ last(): SettlementDispositionReport | null {+ return reports.length > 0 ? reports[reports.length - 1]! : null;+ },+ };+}++// The shared per-case assertion. It proves the report keys equal the acquired+// subset, each resource carries exactly one disposition, and the transferred id+// (if any) is the only `transferred` entry.+function assertDispositionReport(+ report: SettlementDispositionReport | null,+ expected: { acquired: ResourceId[]; transferred?: ResourceId | null },+) {+ expect(report, "the run must record a disposition report").not.toBeNull();+ const records = report!.records;+ const ids = records.map((record) => record.id);+ // Each resource carries exactly one disposition (no duplicate id).+ expect(ids.length, "no resource is reported twice").toBe(new Set(ids).size);+ // The report keys equal the acquired subset of the six resource ids.+ expect(new Set(ids)).toEqual(new Set(expected.acquired));+ const transferred = expected.transferred ?? null;+ for (const record of records) {+ expect(["finalized", "transferred"]).toContain(record.disposition);+ if (record.id === transferred) {+ expect(record.disposition, `${record.id} must be transferred`).toBe("transferred");+ } else {+ expect(record.disposition, `${record.id} must be finalized`).toBe("finalized");+ }+ }+}++// The sandbox-lane resource set before the runtime is created (staging and+// transport), and after (adds the runtime). Without a managed-home seed the+// managed_home resource is absent.+const SANDBOX_PRE_RUNTIME: ResourceId[] = ["staged_runtime", "staging_lease", "control_bridge", "agent_bridge"];+const SANDBOX_WITH_RUNTIME: ResourceId[] = [...SANDBOX_PRE_RUNTIME, "acp_runtime"];+const SANDBOX_WITH_MANAGED_HOME: ResourceId[] = [+ "staged_runtime",+ "managed_home",+ "staging_lease",+ "control_bridge",+ "agent_bridge",+ "acp_runtime",+];++describe("composed ACPX run fault matrix", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ });++ // Case 1 — a build failure throws before the ledger acquires any resource.+ it("case_01_build_failure_throws_and_acquires_nothing", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ vi.mocked(prepareAdapterExecutionTargetRuntime).mockImplementationOnce(async () => {+ throw new Error("staging boom");+ });+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ await expect(+ execute({ runId: "fault-build", ...remoteArgs(stateDir, localCwd, executionTarget) } as never),+ ).rejects.toThrow("staging boom");++ assertDispositionReport(capture.last(), { acquired: [] });+ });++ // Case 2 — a partial bridge failure throws; the staged entry and the lease are+ // finalized (the rollback removed the borrowed staged entry).+ it("case_02_partial_bridge_failure_finalizes_staged_and_lease", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ const capture = captureDisposition();+ const stop = vi.fn(async () => {});+ vi.mocked(startAdapterExecutionTargetPaperclipBridge).mockImplementationOnce(async () => {+ throw new Error("paperclip bridge boom");+ });+ vi.mocked(startAdapterExecutionTargetProcessSessionBridge).mockImplementationOnce(+ async () => ({ agentCommand: null, stop }) as never,+ );+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ await expect(+ execute({ runId: "fault-bridge", ...remoteArgs(stateDir, localCwd, executionTarget) } as never),+ ).rejects.toThrow("paperclip bridge boom");++ assertDispositionReport(capture.last(), { acquired: ["staged_runtime", "staging_lease"] });+ });++ // Case 3 — a runtime-create failure settles the staging and transport resources.+ // The runtime never enters the ledger.+ it("case_03_runtime_create_failure_finalizes_staging_and_transport", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => {+ throw new Error("createRuntime boom");+ },+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-create",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("create_runtime");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_PRE_RUNTIME });+ });++ // Case 4 — a handshake failure closes the runtime; every resource finalizes.+ it("case_04_handshake_failure_closes_runtime", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => {+ throw new Error("ensureSession boom");+ },+ startTurn: () => completedTurn(),+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-handshake",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("ensure_session");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 5 — a missing session handle closes the runtime; the result carries a+ // null clearSession and no errorMeta.+ it("case_05_missing_handle_closes_runtime_null_error", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => undefined,+ startTurn: () => completedTurn(),+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-missing-handle",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("ensure_session");+ expect(result.errorCode).toBe("acpx_runtime_error");+ expect(result.clearSession).toBeUndefined();+ expect(result.errorMeta).toBeUndefined();+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 6 — a configuration failure closes the runtime.+ it("case_06_configuration_failure_closes_runtime", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => okHandle,+ startTurn: () => completedTurn(),+ setConfigOption: async () => {+ throw new Error("setConfigOption boom");+ },+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-configure",+ ...remoteArgs(stateDir, localCwd, executionTarget, {+ config: {+ agent: "custom",+ agentCommand: "node ./fake-acp.js",+ model: "custom-model-x",+ stateDir,+ cwd: localCwd,+ },+ }),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("configure_session");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 7 — a prompt-build failure fails the turn in the prepare phase.+ it("case_07_prompt_build_failure_finalizes_every_resource", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-prepare",+ ...remoteArgs(stateDir, localCwd, executionTarget, { context: throwingHandoffContext() }),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("prepare_turn");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 8 — a resume retry runs ensureSession twice but registers the runtime+ // once, so the acquired set has no doubled resource.+ it("case_08_resume_retry_does_not_double_resources", async () => {+ const root = await makeTempRoot();+ const stateDir = path.join(root, "state");+ const cwd = path.join(root, "worktree");+ await fs.mkdir(cwd, { recursive: true });+ const config = { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd };++ // A first clean host run mints the session params the second run resumes from.+ const firstExecute = createAcpxEngineExecutor({ createRuntime: () => completedRuntime() });+ const first = await firstExecute({+ runId: "fault-resume-a",+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: {},+ config,+ context: {},+ onLog: async () => {},+ onMeta: async () => {},+ } as never);+ expect(first.exitCode).toBe(0);++ // The second run resumes: the resume ensureSession fails, the fresh retry+ // succeeds. The runtime is created once, so acp_runtime registers once.+ const capture = captureDisposition();+ let created = 0;+ const secondExecute = createAcpxEngineExecutor({+ onSettlementDisposition: capture.onSettlementDisposition,+ createRuntime: () => {+ created += 1;+ return {+ ensureSession: async (session: Record<string, unknown>) => {+ if (session.resumeSessionId) throw new Error("resume session not found");+ return okHandle;+ },+ startTurn: () => completedTurn(),+ setConfigOption: async () => {},+ close: async () => {},+ } as never;+ },+ });+ const second = await secondExecute({+ runId: "fault-resume-b",+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: { sessionParams: (first as { sessionParams?: unknown }).sessionParams },+ config,+ context: {},+ onLog: async () => {},+ onMeta: async () => {},+ } as never);++ expect(second.exitCode).toBe(0);+ // The runtime was created exactly once across the resume and the fresh retry.+ expect(created).toBe(1);+ // The host lane acquires only the runtime, and it appears once.+ assertDispositionReport(capture.last(), { acquired: ["acp_runtime"] });+ });++ // Case 9 — a turn exception finalizes every resource (the staged runtime is+ // discarded, not transferred).+ it("case_09_turn_exception_discards_staged_runtime", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => okHandle,+ startTurn: () => throwingTurn(),+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-turn",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("turn");+ expect(result.errorCode).toBe("acpx_turn_failed");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 10 — a turn timeout finalizes every resource.+ it("case_10_turn_timeout_finalizes_every_resource", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ let releaseTurn: (() => void) | null = null;+ const turnCancelled = new Promise<void>((resolve) => {+ releaseTurn = resolve;+ });+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => okHandle,+ startTurn: () => ({+ events: (async function* () {+ await turnCancelled;+ })(),+ result: turnCancelled.then(() => ({ status: "cancelled", stopReason: "cancelled" })),+ cancel: async () => {+ releaseTurn?.();+ },+ }),+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-timeout",+ ...remoteArgs(stateDir, localCwd, executionTarget, {+ config: { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir, cwd: localCwd, timeoutSec: 1 },+ }),+ } as never);++ expect(result.timedOut).toBe(true);+ expect(result.errorCode).toBe("acpx_timeout");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ }, 15_000);++ // Case 11 — a cancelled turn finalizes every resource.+ it("case_11_turn_cancellation_finalizes_every_resource", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => okHandle,+ startTurn: () => cancelledTurn(),+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-cancel",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.status).toBe("cancelled");+ assertDispositionReport(capture.last(), { acquired: SANDBOX_WITH_RUNTIME });+ });++ // Case 12 — a clean success saves the staged runtime (transferred); every other+ // resource finalizes. A managed-home seed exercises the full six-resource set.+ it("case_12_clean_success_transfers_staged_runtime", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ prepareRemoteManagedHome: managedHomeSeed(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-success",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(0);+ expect(result.resultJson?.status).toBe("completed");+ assertDispositionReport(capture.last(), {+ acquired: SANDBOX_WITH_MANAGED_HOME,+ transferred: "staged_runtime",+ });+ });++ // Case 13 — a bridge stop that rejects during settlement never changes the+ // result or the report (allSettled absorbs the fault).+ it("case_13_bridge_stop_reject_does_not_change_result", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges({ stopRejects: true });+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-bridge-stop",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(0);+ expect(result.resultJson?.status).toBe("completed");+ assertDispositionReport(capture.last(), {+ acquired: SANDBOX_WITH_RUNTIME,+ transferred: "staged_runtime",+ });+ });++ // Case 14 — a sync-back copy-back that rejects during settlement never changes+ // the result or the report.+ it("case_14_sync_back_failure_does_not_change_result", async () => {+ const { stateDir, localCwd, executionTarget } = await setupRemoteSandbox();+ stubBridges();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ stagedRuntimes: new Map(),+ stagingLocks: new Map(),+ createRuntime: () => completedRuntime(),+ prepareRemoteManagedHome: managedHomeSeed({ teardownRejects: true }),+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-sync-back",+ ...remoteArgs(stateDir, localCwd, executionTarget),+ } as never);++ expect(result.exitCode).toBe(0);+ expect(result.resultJson?.status).toBe("completed");+ assertDispositionReport(capture.last(), {+ acquired: SANDBOX_WITH_MANAGED_HOME,+ transferred: "staged_runtime",+ });+ });++ // Case 15 — a concurrent double settlement is a structural error: the second+ // claim of the ledger throws a LedgerStateError.+ it("case_15_concurrent_double_settlement_throws_ledger_state_error", async () => {+ const ledger = createRunResourceLedger();+ ledger.register({+ id: "acp_runtime",+ payload: { runtime: {}, sessionHandle: {}, childProcessPid: null } as never,+ scope: "per_run",+ });+ const noopSteps: SettlementSteps = {+ reuseCandidate: () => null,+ endSession: () => {},+ settleReuse: () => {},+ stopTransport: () => {},+ syncBack: () => {},+ releaseStagingLease: () => {},+ recordError: () => {},+ };++ // The first settlement claims the ledger and produces the report.+ const report = await settleAcpRun(ledger, null, noopSteps);+ assertDispositionReport(report, { acquired: ["acp_runtime"] });++ // A second settlement of the same ledger is a structural error.+ await expect(settleAcpRun(ledger, null, noopSteps)).rejects.toBeInstanceOf(LedgerStateError);+ });++ // Case 16 — the host-lane credential gate. Constructed gate-passed: the runtime+ // transfers and never closes. Live host path (gate failed): the runtime closes+ // and never transfers.+ it("case_16_host_credential_gate_transfer_versus_close", async () => {+ // Constructed gate-passed condition: a host candidate with no live run-scoped+ // credential. The reuse decision saves, so the runtime transfers and endSession+ // never closes it.+ const ledger = createRunResourceLedger();+ ledger.register({+ id: "acp_runtime",+ payload: { runtime: {}, sessionHandle: {}, childProcessPid: null } as never,+ scope: "per_run",+ });+ let closed = false;+ const gatePassedSteps: SettlementSteps = {+ reuseCandidate: () => ({ kind: "host", causePermitsSave: true, liveRunScopedCredentials: [] }),+ endSession: (_slots, decision) => {+ if (decision.kind !== "save") closed = true;+ },+ settleReuse: () => {},+ stopTransport: () => {},+ syncBack: () => {},+ releaseStagingLease: () => {},+ recordError: () => {},+ };+ const gatePassedReport = await settleAcpRun(ledger, null, gatePassedSteps);+ expect(closed).toBe(false);+ assertDispositionReport(gatePassedReport, { acquired: ["acp_runtime"], transferred: "acp_runtime" });++ // Live host path: the engine populates the run-scoped credential, so the gate+ // fails, the runtime closes, and it never transfers.+ const root = await makeTempRoot();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ createRuntime: () => completedRuntime(),+ onSettlementDisposition: capture.onSettlementDisposition,+ });+ const result = await execute({+ runId: "fault-host-gate",+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: {},+ config: {+ agent: "custom",+ agentCommand: "node ./fake-acp.js",+ stateDir: path.join(root, "state"),+ mode: "persistent",+ warmHandleIdleMs: 60_000,+ },+ context: {},+ onLog: async () => {},+ onMeta: async () => {},+ } as never);++ expect(result.exitCode).toBe(0);+ // The live host path closes and never transfers the runtime.+ assertDispositionReport(capture.last(), { acquired: ["acp_runtime"], transferred: null });+ });++ // Case 17 — a host-lane turn failure finalizes (closes) the runtime.+ it("case_17_host_turn_failure_finalizes_runtime", async () => {+ const root = await makeTempRoot();+ const capture = captureDisposition();+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ createRuntime: () =>+ ({+ ensureSession: async () => okHandle,+ startTurn: () => throwingTurn(),+ setConfigOption: async () => {},+ close: async () => {},+ }) as never,+ onSettlementDisposition: capture.onSettlementDisposition,+ });++ const result = await execute({+ runId: "fault-host-turn-fail",+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: {},+ config: {+ agent: "custom",+ agentCommand: "node ./fake-acp.js",+ stateDir: path.join(root, "state"),+ mode: "persistent",+ warmHandleIdleMs: 60_000,+ },+ context: {},+ onLog: async () => {},+ onMeta: async () => {},+ } as never);++ expect(result.exitCode).toBe(1);+ expect(result.resultJson?.phase).toBe("turn");+ assertDispositionReport(capture.last(), { acquired: ["acp_runtime"], transferred: null });+ });+});++describe("composed ACPX run per-phase telemetry", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ });++ it("emits a run.phase.timing event for each lifecycle phase a clean host run reaches", async () => {+ const root = await makeTempRoot();+ const events: Array<{ eventType: string; payload?: Record<string, unknown> }> = [];+ const execute = createAcpxEngineExecutor({+ warmHandles: new Map(),+ createRuntime: () => completedRuntime(),+ });++ const result = await execute({+ runId: "phase-telemetry",+ agent: { id: "agent-1", companyId: "company-1" },+ runtime: {},+ config: { agent: "custom", agentCommand: "node ./fake-acp.js", stateDir: path.join(root, "state") },+ context: {},+ onLog: async () => {},+ onMeta: async () => {},+ onEvent: async (event: { eventType: string; payload?: Record<string, unknown> }) => {+ events.push(event);+ },+ } as never);++ expect(result.exitCode).toBe(0);+ const phases = events+ .filter((event) => event.eventType === "run.phase.timing")+ .map((event) => String(event.payload?.phase));+ // A clean host run runs the runtime, session, prepare, turn, and settlement+ // phases. Each phase emits a phase-timing event.+ for (const phase of ["create_runtime", "ensure_session", "prepare_turn", "turn", "end_session"]) {+ expect(phases, `missing phase telemetry for ${phase}`).toContain(phase);+ }+ // Every phase-timing event carries exactly the three closed fields.+ for (const event of events.filter((entry) => entry.eventType === "run.phase.timing")) {+ expect(Object.keys(event.payload ?? {}).sort()).toEqual(["durationMs", "outcome", "phase"]);+ }+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-resource-ledger.test.ts b/packages/adapter-utils/src/acpx-engine/run-resource-ledger.test.tsnew file mode 100644index 0000000000..20c8a1fda2--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-resource-ledger.test.ts@@ -0,0 +1,185 @@+import { describe, expect, it, vi } from "vitest";+import { createRunResourceLedger, createScopedCleanupRegistry } from "./run-resource-ledger.js";+import { LedgerStateError } from "./run-contracts.js";+import type { RunResourcePayloads } from "./run-contracts.js";++// A typed placeholder payload for a resource whose value the test never reads.+function stub<T>(): T {+ return undefined as unknown as T;+}++describe("run resource ledger", () => {+ it("test_register_throws_on_filled_slot", () => {+ const ledger = createRunResourceLedger();+ ledger.register({ id: "staging_lease", scope: "per_run", payload: { release: () => {} } });++ expect(() =>+ ledger.register({ id: "staging_lease", scope: "per_run", payload: { release: () => {} } }),+ ).toThrow(LedgerStateError);+ });++ it("test_register_throws_after_seal_and_after_take", () => {+ const sealed = createRunResourceLedger();+ sealed.register({ id: "staging_lease", scope: "per_run", payload: { release: () => {} } });+ sealed.seal(["staging_lease"]);+ expect(() =>+ sealed.register({+ id: "managed_home",+ scope: "per_run",+ payload: stub<RunResourcePayloads["managed_home"]>(),+ }),+ ).toThrow(LedgerStateError);++ const taken = createRunResourceLedger();+ taken.register({ id: "staging_lease", scope: "per_run", payload: { release: () => {} } });+ taken.takeForSettlement();+ expect(() =>+ taken.register({+ id: "managed_home",+ scope: "per_run",+ payload: stub<RunResourcePayloads["managed_home"]>(),+ }),+ ).toThrow(LedgerStateError);+ });++ it("test_seal_validates_site_declared_required_slots", () => {+ const ledger = createRunResourceLedger();+ ledger.register({+ id: "acp_runtime",+ scope: "per_run",+ payload: stub<RunResourcePayloads["acp_runtime"]>(),+ });++ // The site declares control_bridge required, but it is not registered, so+ // seal throws and leaves the ledger open.+ expect(() => ledger.seal(["acp_runtime", "control_bridge"])).toThrow(LedgerStateError);++ // The failed seal left the ledger open, so the missing slot can be filled.+ ledger.register({+ id: "control_bridge",+ scope: "per_run",+ payload: stub<RunResourcePayloads["control_bridge"]>(),+ });+ const ready = ledger.seal(["acp_runtime", "control_bridge"]);++ expect(ready.has("acp_runtime")).toBe(true);+ expect(ready.has("control_bridge")).toBe(true);+ expect([...ready.sealed]).toEqual(["acp_runtime", "control_bridge"]);+ });++ it("test_seal_promotes_startup_rollback_entries_to_per_run", () => {+ const ledger = createRunResourceLedger();+ // Promotable by default.+ ledger.register({+ id: "staged_runtime",+ scope: "startup_rollback",+ payload: stub<RunResourcePayloads["staged_runtime"]>(),+ });+ // Pinned as rollback-only.+ ledger.register({+ id: "control_bridge",+ scope: "startup_rollback",+ promotable: false,+ payload: stub<RunResourcePayloads["control_bridge"]>(),+ });+ ledger.register({+ id: "acp_runtime",+ scope: "per_run",+ payload: stub<RunResourcePayloads["acp_runtime"]>(),+ });++ const ready = ledger.seal(["staged_runtime", "control_bridge", "acp_runtime"]);++ expect(ready.scopeOf("staged_runtime")).toBe("per_run");+ expect(ready.scopeOf("control_bridge")).toBe("startup_rollback");+ expect(ready.scopeOf("acp_runtime")).toBe("per_run");+ });++ it("test_take_for_settlement_is_synchronous_one_time_claim", () => {+ const ledger = createRunResourceLedger();+ ledger.register({+ id: "acp_runtime",+ scope: "per_run",+ payload: stub<RunResourcePayloads["acp_runtime"]>(),+ });++ const consumed = ledger.takeForSettlement();++ // Synchronous: the claim comes back directly, not as a promise.+ expect(consumed).not.toBeInstanceOf(Promise);+ expect(consumed.entries().map((entry) => entry.id)).toContain("acp_runtime");++ // One-time: a second claim throws.+ expect(() => ledger.takeForSettlement()).toThrow(LedgerStateError);+ });++ it("test_second_take_throws_ledger_state_error_before_any_side_effect", () => {+ const ledger = createRunResourceLedger();+ const onDisposition = vi.fn();+ ledger.register({+ id: "staging_lease",+ scope: "per_run",+ payload: { release: () => {} },+ onDisposition,+ });++ const first = ledger.takeForSettlement();+ expect(first.entries().map((entry) => entry.id)).toEqual(["staging_lease"]);+ expect(onDisposition).toHaveBeenCalledTimes(1);+ expect(onDisposition).toHaveBeenCalledWith("transferred");++ let thrown: unknown;+ try {+ ledger.takeForSettlement();+ } catch (err) {+ thrown = err;+ }++ expect(thrown).toBeInstanceOf(LedgerStateError);+ // The second claim threw before it marked a disposition a second time.+ expect(onDisposition).toHaveBeenCalledTimes(1);+ });++ it("scoped cleanup registry runs and promotes cleanups by scope", async () => {+ const registry = createScopedCleanupRegistry();+ const order: string[] = [];+ registry.add("startup_rollback", () => {+ order.push("rollback-a");+ });+ registry.add("startup_rollback", async () => {+ order.push("rollback-b");+ });+ registry.add("per_run", () => {+ order.push("per-run");+ });+ expect(registry.size("startup_rollback")).toBe(2);++ registry.promote("startup_rollback", "per_run");+ expect(registry.size("startup_rollback")).toBe(0);+ expect(registry.size("per_run")).toBe(3);++ await registry.run("per_run");++ // Reverse registration order (last in, first out).+ expect(order).toEqual(["rollback-b", "rollback-a", "per-run"]);+ expect(registry.size("per_run")).toBe(0);+ });++ it("scoped cleanup registry runs every cleanup even when one fails", async () => {+ const registry = createScopedCleanupRegistry();+ const ran: string[] = [];+ registry.add("per_run", () => {+ ran.push("first");+ });+ registry.add("per_run", () => {+ throw new Error("boom");+ });+ registry.add("per_run", () => {+ ran.push("third");+ });++ await expect(registry.run("per_run")).rejects.toBeInstanceOf(AggregateError);+ // The failing cleanup did not skip the others.+ expect(ran).toEqual(["third", "first"]);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-resource-ledger.ts b/packages/adapter-utils/src/acpx-engine/run-resource-ledger.tsnew file mode 100644index 0000000000..3e1e978039--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-resource-ledger.ts@@ -0,0 +1,201 @@+// The run resource ledger and the scoped cleanup registry.+//+// The ledger is the single owner of the run resources between acquisition and+// settlement. `register` is the only writer. `seal` ends acquisition and+// validates the required set. `takeForSettlement` makes the one-time claim that+// hands the resources to settlement. The state machine is `open -> sealed ->+// consumed` or `open -> consumed`.+//+// The scoped cleanup registry holds cleanup thunks by lifetime. The coordinator+// runs the `startup_rollback` scope when startup fails and the `per_run` scope+// at settlement. A successful seal promotes the rollback cleanups to per_run.++import { LedgerStateError } from "./run-contracts.js";+import type {+ AcquiredRunResources,+ CleanupScope,+ ConsumedRunResources,+ ReadyRunResources,+ ResourceDisposition,+ ResourceId,+ RunResourcePayloads,+ RunResourceRegistration,+ SettledResourceEntry,+} from "./run-contracts.js";++type LedgerState = "open" | "sealed" | "consumed";++interface LedgerSlot {+ readonly id: ResourceId;+ readonly payload: RunResourcePayloads[ResourceId];+ scope: CleanupScope;+ readonly promotable: boolean;+ readonly onDisposition?: (disposition: ResourceDisposition) => void;+}++/**+ * Create a run resource ledger. The ledger starts `open`. `register` fills at+ * most one slot per resource id. `seal` validates the required set and promotes+ * promotable `startup_rollback` entries to `per_run`. `takeForSettlement` makes+ * the one-time settlement claim.+ */+export function createRunResourceLedger(): AcquiredRunResources {+ const slots = new Map<ResourceId, LedgerSlot>();+ let state: LedgerState = "open";+ let sealedRequired: readonly ResourceId[] = [];++ function readyView(): ReadyRunResources {+ const view = {+ get(id: ResourceId): RunResourcePayloads[ResourceId] | undefined {+ return slots.get(id)?.payload;+ },+ scopeOf(id: ResourceId): CleanupScope | undefined {+ return slots.get(id)?.scope;+ },+ has(id: ResourceId): boolean {+ return slots.has(id);+ },+ sealed: sealedRequired,+ };+ return view as unknown as ReadyRunResources;+ }++ return {+ register(registration: RunResourceRegistration): void {+ if (state !== "open") {+ throw new LedgerStateError(+ state === "sealed"+ ? "cannot register a resource after the ledger is sealed"+ : "cannot register a resource after the ledger is taken for settlement",+ );+ }+ if (slots.has(registration.id)) {+ throw new LedgerStateError(`resource slot "${registration.id}" is already filled`);+ }+ slots.set(registration.id, {+ id: registration.id,+ payload: registration.payload,+ scope: registration.scope,+ promotable: registration.promotable ?? true,+ onDisposition: registration.onDisposition,+ });+ },++ seal(required: readonly ResourceId[]): ReadyRunResources {+ if (state !== "open") {+ throw new LedgerStateError(+ state === "sealed"+ ? "the ledger is already sealed"+ : "cannot seal the ledger after it is taken for settlement",+ );+ }+ // Validate the required set first. A failed seal must leave the ledger+ // open and unchanged, so the caller can register the missing slot and+ // seal again.+ const missing = required.filter((id) => !slots.has(id));+ if (missing.length > 0) {+ throw new LedgerStateError(`seal is missing required resource(s): ${missing.join(", ")}`);+ }+ // Promote every promotable startup_rollback entry to per_run in one pass.+ // The resource now lives through the whole run, so settlement owns it.+ for (const slot of slots.values()) {+ if (slot.scope === "startup_rollback" && slot.promotable) {+ slot.scope = "per_run";+ }+ }+ state = "sealed";+ sealedRequired = [...required];+ return readyView();+ },++ takeForSettlement(): ConsumedRunResources {+ // The one-time claim. Check the state first, so a second claim throws+ // before it can mark a disposition or hand the resources out again.+ if (state === "consumed") {+ throw new LedgerStateError("run resources are already taken for settlement");+ }+ state = "consumed";+ const entries: SettledResourceEntry[] = [];+ for (const slot of slots.values()) {+ slot.onDisposition?.("transferred");+ entries.push({+ id: slot.id,+ payload: slot.payload,+ scope: slot.scope,+ disposition: "transferred",+ });+ }+ const consumed = { entries: () => entries };+ return consumed as unknown as ConsumedRunResources;+ },+ };+}++/**+ * A registry of cleanup thunks, grouped by lifetime scope. The coordinator adds+ * a cleanup under a scope, promotes a scope's cleanups to another scope, and+ * runs a scope's cleanups.+ */+export interface ScopedCleanupRegistry {+ /** Add a cleanup under a scope. */+ add(scope: CleanupScope, cleanup: () => void | Promise<void>): void;+ /** Move every cleanup from one scope to another, in registration order. */+ promote(from: CleanupScope, to: CleanupScope): void;+ /** The count of cleanups in a scope. */+ size(scope: CleanupScope): number;+ /**+ * Run and clear a scope's cleanups in reverse registration order. Run every+ * cleanup even when one fails. Throw an `AggregateError` at the end when one+ * or more failed, so no error is lost and no cleanup is skipped.+ */+ run(scope: CleanupScope): Promise<void>;+}++/** Create an empty scoped cleanup registry. */+export function createScopedCleanupRegistry(): ScopedCleanupRegistry {+ const byScope = new Map<CleanupScope, Array<() => void | Promise<void>>>();++ function bucket(scope: CleanupScope): Array<() => void | Promise<void>> {+ let list = byScope.get(scope);+ if (!list) {+ list = [];+ byScope.set(scope, list);+ }+ return list;+ }++ return {+ add(scope: CleanupScope, cleanup: () => void | Promise<void>): void {+ bucket(scope).push(cleanup);+ },++ promote(from: CleanupScope, to: CleanupScope): void {+ if (from === to) return;+ const source = byScope.get(from);+ if (!source || source.length === 0) return;+ const target = bucket(to);+ target.push(...source);+ byScope.set(from, []);+ },++ size(scope: CleanupScope): number {+ return byScope.get(scope)?.length ?? 0;+ },++ async run(scope: CleanupScope): Promise<void> {+ const list = byScope.get(scope) ?? [];+ byScope.set(scope, []);+ const errors: unknown[] = [];+ for (let index = list.length - 1; index >= 0; index -= 1) {+ try {+ await list[index]();+ } catch (err) {+ errors.push(err);+ }+ }+ if (errors.length > 0) {+ throw new AggregateError(errors, `cleanup scope "${scope}" had ${errors.length} failure(s)`);+ }+ },+ };+}diff --git a/packages/adapter-utils/src/acpx-engine/run-site-host.test.ts b/packages/adapter-utils/src/acpx-engine/run-site-host.test.tsnew file mode 100644index 0000000000..681c6552f4--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-site-host.test.ts@@ -0,0 +1,113 @@+// Tests for the host run site (Phase 18).+//+// The host site is the null path with a warm-runtime store. These tests pin its+// warm-hit and warm-save behavior against the baseline warm sets, and confirm+// the null-path operations: host cwd plan, no staging failures, no transport,+// and no sync-back.++import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { createHostRunSite, type RuntimeCacheEntry } from "./run-site-host.js";+import type { AcpRunContext, ReadyRunResources } from "./run-contracts.js";++function makeEntry(id: string, lastUsedAt: number): RuntimeCacheEntry {+ return {+ runtime: { id, close: async () => {} } as never,+ handle: { sessionKey: id } as never,+ childStderrState: { logPath: null, pendingLiveLine: "" },+ processIdentitySink: { current: undefined, latest: null },+ fingerprint: `fp-${id}`,+ lastUsedAt,+ };+}++describe("host run site", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ });+ afterEach(() => {+ vi.useRealTimers();+ });++ it("test_host_site_warm_hit_and_warm_save_match_baseline_sets", async () => {+ const warmHandles = new Map<string, RuntimeCacheEntry>();+ const closed: RuntimeCacheEntry[] = [];+ const site = createHostRunSite({+ warmHandles,+ now: () => Date.now(),+ idleMs: 60_000,+ closeWarmEntry: async (entry) => {+ closed.push(entry);+ },+ });+ const store = site.reuse();++ // Warm save: the entry lands in the caller's map as the sole warm entry, the+ // same set the baseline warm-save path produces (`warmHandles.size` is 1).+ const entry = makeEntry("paperclip:c:a:t:fp", Date.now());+ store.save(entry.handle.sessionKey, entry);+ expect(new Set(warmHandles.keys())).toEqual(new Set(["paperclip:c:a:t:fp"]));+ expect(warmHandles.get("paperclip:c:a:t:fp")).toBe(entry);+ // The save armed a per-entry idle timer.+ expect(entry.cleanupTimer).toBeDefined();++ // Warm hit: a borrow returns the same entry and leaves it in the map, so an+ // overlapping run of the same session still reads it. The borrow cleared the+ // idle timer, so the reused runtime does not expire while it is in use.+ expect(store.borrow("paperclip:c:a:t:fp")).toBe(entry);+ expect(warmHandles.size).toBe(1);+ await vi.advanceTimersByTimeAsync(120_000);+ expect(closed).toEqual([]);+ expect(warmHandles.get("paperclip:c:a:t:fp")).toBe(entry);++ // A discard drops the entry and closes its runtime once, matching the+ // baseline drop set (empty map, one close).+ await store.discard("paperclip:c:a:t:fp");+ expect(warmHandles.size).toBe(0);+ expect(closed).toEqual([entry]);+ });++ it("test_host_site_plan_and_null_path_operations", async () => {+ const site = createHostRunSite({+ warmHandles: new Map(),+ now: () => 0,+ idleMs: 0,+ closeWarmEntry: async () => {},+ });++ const context = {+ fingerprintIdentity: { cwd: "/work/dir" },+ } as unknown as AcpRunContext;++ // The plan binds the session to the host cwd, names no relay-proxy spawn cwd,+ // and disables sandbox tracing.+ expect(site.plan(context)).toEqual({+ sessionCwd: "/work/dir",+ spawnCwd: undefined,+ tracingEnabled: false,+ });++ // The host runs in place, so it places nothing, starts no transport, and+ // syncs nothing back.+ expect(await site.placeWorkspace(context)).toEqual({ referencedProjectStagingFailures: [] });+ expect(await site.startTransport(context)).toEqual({ controlBridge: null, agentBridge: null });+ await expect(site.syncBack(context)).resolves.toBeUndefined();+ });++ it("test_host_site_reuse_candidate_names_runtime_and_session_handle", () => {+ const site = createHostRunSite({+ warmHandles: new Map(),+ now: () => 0,+ idleMs: 0,+ closeWarmEntry: async () => {},+ });++ const runtime = { id: "rt" };+ const sessionHandle = { id: "handle" };+ const resources = {+ get: (id: string) =>+ id === "acp_runtime" ? { runtime, sessionHandle, childProcessPid: 42 } : undefined,+ } as unknown as ReadyRunResources;++ expect(site.reuseCandidate(resources)).toEqual({ runtime, sessionHandle });+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-site-host.ts b/packages/adapter-utils/src/acpx-engine/run-site-host.tsnew file mode 100644index 0000000000..6ed9d921a0--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-site-host.ts@@ -0,0 +1,146 @@+// The host run site.+//+// The host site is the literal null path: it runs the agent on the host, with+// no sandbox, no staging, and no bridges. Its store keeps a live ACP runtime and+// session handle warm across runs of the same session, so a compatible resume+// reuses the running agent instead of a fresh spawn. This is today's warm-handle+// cache, factored behind the generic reuse store.+//+// The site owns the warm store only. The engine still drives the run body; the+// site's `plan`, `placeWorkspace`, `startTransport`, and `syncBack` are the null+// operations the host lane always did (host cwd, no staging failures, no+// transport, no sync-back). A later phase routes the whole lane through the site.++import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";+import type { AcpRuntime, AcpRuntimeHandle } from "acpx/runtime";+import type {+ AcpRunContext,+ HostReuseCandidate,+ PlacedWorkspace,+ ReadyRunResources,+ RunSiteTransport,+ SessionReuseStore,+ SitePlan,+} from "./run-contracts.js";+import { createSessionReuseStore } from "./session-reuse-store.js";++/** The agent child's identity, as the runtime reports it on each spawn. */+export type AcpxAgentProcessIdentity = { pid: number; startedAt: string };++/**+ * The mutable spawn-callback target and the last spawn identity a warm runtime+ * carries across runs. A warm handle can outlive the run that created it, so the+ * `current` callback stays mutable: a later heartbeat repoints it to its own+ * `onSpawn`, and `latest` lets that heartbeat re-announce the running agent.+ */+export type AcpxProcessIdentitySink = {+ current: AdapterExecutionContext["onSpawn"];+ latest: AcpxAgentProcessIdentity | null;+};++/** The live-line buffer and log path a warm runtime's child stderr carries. */+export interface ChildStderrState {+ logPath: string | null;+ pendingLiveLine: string;+}++/**+ * One warm host runtime the store keeps for the next compatible resume. It is+ * the value the host warm-handle map holds. The entry carries its own last-used+ * time and its own optional idle timer, which the store reads and writes.+ */+export interface RuntimeCacheEntry {+ runtime: AcpRuntime;+ handle: AcpRuntimeHandle;+ childStderrState: ChildStderrState;+ processIdentitySink: AcpxProcessIdentitySink;+ fingerprint: string;+ lastUsedAt: number;+ cleanupTimer?: ReturnType<typeof setTimeout>;+}++/** Construction options for the host site. */+export interface HostRunSiteOptions {+ /**+ * The warm-handle map the store operates over. The engine owns it and reuses+ * it across runs, so a saved runtime stays warm for the next resume.+ */+ readonly warmHandles: Map<string, RuntimeCacheEntry>;+ readonly now: () => number;+ /** The warm-idle bound, in milliseconds. `0` or less disables the store. */+ readonly idleMs: number;+ /**+ * Close a warm runtime and flush its child stderr. The store fires it when the+ * per-entry timer expires, when the run-start sweep evicts an idle entry, and+ * on an explicit discard. The engine injects it, because the close reason and+ * the stderr flush live in the engine module.+ */+ readonly closeWarmEntry: (entry: RuntimeCacheEntry) => Promise<void>;+}++/**+ * The host run site. Its store keeps warm runtimes; every other operation is the+ * null path the host lane always ran.+ */+export interface HostRunSite {+ readonly kind: "host";+ plan(context: AcpRunContext): SitePlan;+ placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace>;+ startTransport(context: AcpRunContext): Promise<RunSiteTransport>;+ reuse(): SessionReuseStore<RuntimeCacheEntry>;+ reuseCandidate(resources: ReadyRunResources): HostReuseCandidate;+ syncBack(context: AcpRunContext): Promise<void>;+}++/** Create the host run site over the engine's warm-handle map. */+export function createHostRunSite(options: HostRunSiteOptions): HostRunSite {+ const store = createSessionReuseStore<RuntimeCacheEntry>({+ entries: options.warmHandles,+ now: options.now,+ idleMs: options.idleMs,+ lastUsedAt: (entry) => entry.lastUsedAt,+ getTimer: (entry) => entry.cleanupTimer,+ setTimer: (entry, timer) => {+ entry.cleanupTimer = timer;+ },+ // The host lane arms a per-entry idle timer on every warm save, so an idle+ // runtime closes on its own without a later run.+ perEntryTimer: true,+ release: (entry) => options.closeWarmEntry(entry),+ });++ return {+ kind: "host",+ plan(context: AcpRunContext): SitePlan {+ // The host binds the session to the run cwd. There is no relay-proxy spawn+ // cwd off the host, and the host emits no sandbox trace spans.+ return {+ sessionCwd: context.fingerprintIdentity.cwd,+ spawnCwd: undefined,+ tracingEnabled: false,+ };+ },+ async placeWorkspace(): Promise<PlacedWorkspace> {+ // The host runs in place, so it stages nothing and reports no referenced-+ // project staging failure.+ return { referencedProjectStagingFailures: [] };+ },+ async startTransport(): Promise<RunSiteTransport> {+ // The host lane starts no control bridge and no agent bridge.+ return { controlBridge: null, agentBridge: null };+ },+ reuse(): SessionReuseStore<RuntimeCacheEntry> {+ return store;+ },+ reuseCandidate(resources: ReadyRunResources): HostReuseCandidate {+ const runtime = resources.get("acp_runtime");+ if (!runtime) {+ throw new Error("host run site cannot name a reuse candidate without an acp_runtime resource");+ }+ return { runtime: runtime.runtime, sessionHandle: runtime.sessionHandle };+ },+ async syncBack(): Promise<void> {+ // The host runs in place, so there is nothing to sync back.+ },+ };+}diff --git a/packages/adapter-utils/src/acpx-engine/run-site-sandbox.test.ts b/packages/adapter-utils/src/acpx-engine/run-site-sandbox.test.tsnew file mode 100644index 0000000000..14ad2ff1cc--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-site-sandbox.test.ts@@ -0,0 +1,257 @@+// 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,+ type ManagedHomeSeamResult,+ type SandboxRunSiteOptions,+ type StagedRuntimeStoreEntry,+} from "./run-site-sandbox.js";+import type {+ AcpRunContext,+ AcquiredRunResources,+ LaunchEnvironmentContribution,+ ReadyRunResources,+ ResourceId,+ RunResourceRegistration,+ SandboxReuseCandidate,+ StagedRuntimeResource,+} from "./run-contracts.js";+import type { PreparedAdapterExecutionTargetRuntime } from "@paperclipai/adapter-utils/execution-target";++function makeStagedRuntime(id: string): PreparedAdapterExecutionTargetRuntime {+ return {+ runtimeRootDir: `/remote/${id}/.paperclip-runtime/acpx`,+ additionalSourceDirs: {},+ additionalSourceFailures: [],+ } as unknown as PreparedAdapterExecutionTargetRuntime;+}++function makeLedger(): { ledger: AcquiredRunResources; registered: RunResourceRegistration[] } {+ const registered: RunResourceRegistration[] = [];+ const ledger: AcquiredRunResources = {+ register(registration) {+ registered.push(registration as RunResourceRegistration);+ },+ 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: string): AcpRunContext {+ return { sessionKey } as unknown as AcpRunContext;+}++/** Build a site over injectable fakes. Every option has a sensible default. */+function makeSite(overrides: Partial<SandboxRunSiteOptions> = {}) {+ const { ledger, registered } = makeLedger();+ const env: Record<string, string> = { BASE: "1" };+ const stagedRuntimes = new Map<string, StagedRuntimeStoreEntry>();+ const stagingLocks = new Map<string, Promise<unknown>>();+ const freshStaged = makeStagedRuntime("fresh");+ const bridgeCalls: string[] = [];+ const options: SandboxRunSiteOptions = {+ ledger,+ stagedRuntimes,+ stagingLocks,+ now: () => 1000,+ idleMs: 60_000,+ sessionCwd: "/remote/workspace",+ spawnCwd: "/host/workspace",+ target: { kind: "remote" } as unknown as SandboxRunSiteOptions["target"],+ 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 () => {}, dispose: async () => {} } satisfies ManagedHomeSeamResult;+ },+ disposeFreshStagedRuntime: async () => {},+ measureStageStep: (run) => run(),+ publishStagedProjectHints: () => {},+ onReuseLog: async () => {},+ startPaperclipBridge: async () => {+ bridgeCalls.push("paperclip:start");+ return { env: { PAPERCLIP_API_KEY: "run-token" }, stop: async () => {} } as never;+ },+ startProcessSessionBridge: async ({ launchEnv }) => {+ bridgeCalls.push("process-session:start");+ await launchEnv();+ return { agentCommand: null, stop: async () => {} } as never;+ },+ 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: PreparedAdapterExecutionTargetRuntime): ReadyRunResources {+ const staged: StagedRuntimeResource = { stagedRuntime, disposeStaged: async () => {} };+ return {+ get: (id: ResourceId) => (id === "staged_runtime" ? staged : undefined),+ scopeOf: () => undefined,+ has: (id: ResourceId) => id === "staged_runtime",+ sealed: ["staged_runtime"],+ } as unknown as ReadyRunResources;+}++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<ResourceId>(["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: ResourceId) => 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_preserves_bridge_overlap_and_callback_sequencing", async () => {+ const events: string[] = [];+ let releasePaperclip!: () => void;+ const paperclipGate = new Promise<void>((resolve) => {+ releasePaperclip = resolve;+ });+ let processLaunchEnv: Record<string, string> | null = 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 () => {} } as never;+ },+ 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 () => {} } as never;+ },+ });++ 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_borrow_yields_files_and_runtime_is_still_created", async () => {+ const cachedRuntime = makeStagedRuntime("cached");+ const stagedRuntimes = new Map<string, StagedRuntimeStoreEntry>([+ [+ "paperclip:c:a:t:fp",+ {+ stagedRuntime: cachedRuntime,+ envDelta: { CODEX_HOME: "/remote/home" },+ teardown: async () => {},+ 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: SandboxReuseCandidate = 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: LaunchEnvironmentContribution,+ ): void {+ // @ts-expect-error a launch-environment contribution is not a staged reuse payload+ const payload: SandboxReuseCandidate = contribution;+ void payload;+ }+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/run-site-sandbox.ts b/packages/adapter-utils/src/acpx-engine/run-site-sandbox.tsnew file mode 100644index 0000000000..58f7a0f2c3--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/run-site-sandbox.ts@@ -0,0 +1,459 @@+// The sandbox run site.+//+// The sandbox site runs the agent in a remote runner. It owns the four concerns+// the host site never has: it stages the workspace and the managed home into the+// sandbox, it holds the per-session staging lease, it starts both host-side+// bridges, and it syncs the managed home back on teardown. Its store keeps the+// staged files warm across runs of the same session, so a compatible resume+// reuses the already-staged in-sandbox runtime instead of re-shipping.+//+// The site owns the orchestration and the policy: the staging lease, the reuse+// and stale decision, the ledger registrations, the launch-environment envelope,+// the bridge overlap, and the single callback-environment sequencing point. The+// engine injects the leaf input/output primitives — the workspace stage call, the+// managed-home seam, the two bridge starts, and the step timer — so this module+// stays free of the engine's private staging helpers and the unit tests drive it+// with fakes.+//+// Amendment B (credential scope): `startTransport` builds the run-scoped bridge+// contribution and hands it to the injected `finalizeLaunchEnv`, the sole+// consumer of a contribution. The site, its ledger entries, and its reuse+// candidate never retain a run-scoped contribution or a bridge token. The staged+// reuse payload carries the staged files only.++import type {+ AdapterExecutionTarget,+ AdapterExecutionTargetPaperclipBridgeHandle,+ AdapterExecutionTargetProcessSessionBridgeHandle,+ AdapterManagedRuntimeAsset,+ PreparedAdapterExecutionTargetRuntime,+} from "@paperclipai/adapter-utils/execution-target";+import type {+ AcpRunContext,+ AcquiredRunResources,+ LaunchEnvironmentContribution,+ PlacedWorkspace,+ ReadyRunResources,+ RunScopedContribution,+ RunSiteTransport,+ SandboxReuseCandidate,+ SessionReuseStore,+ SitePlan,+} from "./run-contracts.js";+import { createSessionReuseStore } from "./session-reuse-store.js";++/**+ * One staged in-sandbox runtime the store keeps for the next compatible resume.+ * It is the value the staged-runtime map holds. The engine still owns this shape;+ * the store reads its `lastUsedAt` and its `dispose` through the config+ * accessors. The staged cache has no per-entry idle timer, so the entry carries+ * none — the run-start sweep is the only eviction path.+ */+export interface StagedRuntimeStoreEntry {+ stagedRuntime: PreparedAdapterExecutionTargetRuntime;+ envDelta: Record<string, string>;+ teardown: (() => Promise<void>) | null;+ dispose: (() => Promise<void>) | null;+ lastUsedAt: number;+}++/**+ * The result of one workspace stage into the sandbox. The site records these+ * fields on the run and, after a clean turn, into the staged store.+ */+export interface StagedWorkspace {+ readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;+ readonly teardown: (() => Promise<void>) | null;+ readonly dispose: (() => Promise<void>) | null;+ readonly envDelta: Record<string, string>;+ /** True when the run reused an already-staged runtime rather than staging fresh. */+ readonly reused: boolean;+}++/** The leaf staging primitive the engine injects. It ships one asset set. */+export type StageWorkspace = (assets: AdapterManagedRuntimeAsset[]) => Promise<PreparedAdapterExecutionTargetRuntime>;++/**+ * The managed-home seam result, in the shape the site consumes. The engine maps+ * its adapter seam onto this before it passes the seam in.+ */+export interface ManagedHomeSeamResult {+ readonly stagedRuntime: PreparedAdapterExecutionTargetRuntime;+ readonly teardown: (() => Promise<void>) | null;+ readonly dispose: (() => Promise<void>) | null;+}++/** The construction options for the sandbox site. Every value is per run. */+export interface SandboxRunSiteOptions {+ /** The run ledger. `executeAcpxEngine` creates it and passes it in (one ledger). */+ readonly ledger: AcquiredRunResources;+ /** The staged-runtime map the store operates over. The engine owns it across runs. */+ readonly stagedRuntimes: Map<string, StagedRuntimeStoreEntry>;+ /** The per-key staging mutex the lease and the sweep share. */+ readonly stagingLocks: Map<string, Promise<unknown>>;+ readonly now: () => number;+ /** The staged-idle bound, in milliseconds. `0` or less disables the sweep. */+ readonly idleMs: number;+ /** The in-sandbox workspace dir the session binds to (a fingerprint input). */+ readonly sessionCwd: string;+ /** The host spawn cwd for the relay proxy on the remote process-session lane. */+ readonly spawnCwd: string;+ /** The remote runner-backed sandbox target. */+ readonly target: AdapterExecutionTarget;+ /**+ * The run env the site mutates in place. Staging repoints the managed-home env+ * var onto the in-sandbox home here, and the site captures the delta from it.+ */+ readonly env: Record<string, string>;+ /**+ * True when the supplied session params resume THIS staged session. Only a+ * compatible resume may reuse the already-staged runtime.+ */+ readonly isCompatibleResume: boolean;+ /** Ship the workspace (and, via the seam, the managed home) into the sandbox. */+ readonly stage: StageWorkspace;+ /**+ * Seed the managed home through `stage`, repoint the home env var, and wire the+ * per-run copy-back. Absent for custom agents and the shared-engine tests, where+ * the site stages the workspace with no home asset.+ */+ readonly seedManagedHome?: (stage: StageWorkspace) => Promise<ManagedHomeSeamResult>;+ /**+ * Remove a freshly staged in-sandbox runtime after the seam threw. The site+ * fires it when the seam fails after a successful stage.+ */+ readonly disposeFreshStagedRuntime: (stagedRuntime: PreparedAdapterExecutionTargetRuntime) => Promise<void>;+ /** Wrap the `stage.sync` step in the run's startup step timer. */+ readonly measureStageStep: <T>(run: () => Promise<T>) => Promise<T>;+ /** Publish the referenced-project workspace hints after a fresh stage. */+ readonly publishStagedProjectHints: (stagedProjectDirs: Record<string, string>) => void;+ readonly onReuseLog: () => Promise<void>;++ /** Start the host-side paperclip callback bridge. */+ readonly startPaperclipBridge: (+ runtimeRootDir: string | null,+ ) => Promise<AdapterExecutionTargetPaperclipBridgeHandle | null>;+ /** Start the host-side process-session bridge with a deferred launch env. */+ readonly startProcessSessionBridge: (input: {+ runtimeRootDir: string | null;+ launchEnv: () => Promise<Record<string, string>>;+ }) => Promise<AdapterExecutionTargetProcessSessionBridgeHandle | null>;+ /** Wrap each concurrent bridge start in the run's startup step timer. */+ readonly measureBridgeStep: <T>(step: "bridge.paperclip" | "bridge.process-session", run: () => Promise<T>) => Promise<T>;+ /**+ * Finalize the run's branded launch environment from the bridge contribution.+ * The engine owns `finalizeLaunchEnvironment`, so it stays the sole consumer of+ * a contribution; the site calls this capability at the sequencing point.+ */+ readonly finalizeLaunchEnv: (contributions: readonly LaunchEnvironmentContribution[]) => Record<string, string>;+ readonly onPaperclipBridgeLog: () => Promise<void>;++ /** Stop both bridges and run the managed-home copy-back on teardown. */+ readonly stopBridges: (input: {+ controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;+ agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;+ }) => Promise<void>;+}++/** The transport the sandbox site started, plus the run-scoped launch env. */+export interface SandboxRunSiteTransport extends RunSiteTransport {+ /** The finalized launch env for the process launch. */+ readonly launchEnv: Record<string, string>;+}++/** The sandbox run site. It owns staging, the lease, both bridges, and sync-back. */+export interface SandboxRunSite {+ readonly kind: "sandbox";+ plan(context: AcpRunContext): SitePlan;+ placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace>;+ startTransport(context: AcpRunContext): Promise<SandboxRunSiteTransport>;+ reuse(): SessionReuseStore<StagedRuntimeStoreEntry>;+ reuseCandidate(resources: ReadyRunResources): SandboxReuseCandidate;+ syncBack(context: AcpRunContext): Promise<void>;+ /** The staged workspace the run installed or reused, or null before `placeWorkspace`. */+ readonly staged: StagedWorkspace | null;+ /**+ * The paperclip callback bridge the run started, or null before+ * `startTransport` or on the host lane. `startTransport` sets it before it+ * rethrows a partial-bring-up failure, so an abandon path can stop the bridge+ * that started when its sibling threw.+ */+ readonly controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null;+ /** The process-session bridge the run started, or null before `startTransport`. */+ readonly agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null;+ /**+ * Release the per-session staging lease `placeWorkspace` acquired, or null+ * before `placeWorkspace`. An abandon path calls it to free the lease when the+ * run never reaches sync-back.+ */+ readonly stagingLeaseRelease: (() => void) | null;+}++/** Create the sandbox run site over the engine's staged-runtime map and ledger. */+export function createSandboxRunSite(options: SandboxRunSiteOptions): SandboxRunSite {+ const store = createSessionReuseStore<StagedRuntimeStoreEntry>({+ entries: options.stagedRuntimes,+ now: options.now,+ idleMs: options.idleMs,+ lastUsedAt: (entry) => entry.lastUsedAt,+ // The staged cache arms no per-entry timer; the run-start sweep is the only+ // eviction path, and it runs under the per-key staging lease.+ release: async (entry) => {+ if (entry.dispose) await entry.dispose().catch(() => {});+ },+ withEvictLease: async (key, critical) => {+ const lease = await withStagingLease(options.stagingLocks, key, critical);+ lease.release();+ },+ });++ // The lease the run holds from the stage-or-reuse decision through the active+ // turn until `syncBack` releases it. Held on the run, not on the store, because+ // a run keeps its lease across its whole lifetime.+ let leaseRelease: (() => void) | null = null;+ let staged: StagedWorkspace | null = null;+ let controlBridge: AdapterExecutionTargetPaperclipBridgeHandle | null = null;+ let agentBridge: AdapterExecutionTargetProcessSessionBridgeHandle | null = null;++ return {+ kind: "sandbox",++ plan(): SitePlan {+ // The sandbox binds the session to the in-sandbox workspace dir, redirects+ // the relay proxy spawn to the host cwd, and emits real sandbox trace spans.+ return {+ sessionCwd: options.sessionCwd,+ spawnCwd: options.spawnCwd,+ tracingEnabled: true,+ };+ },++ async placeWorkspace(context: AcpRunContext): Promise<PlacedWorkspace> {+ const sessionKey = context.sessionKey;+ const lease = await withStagingLease(options.stagingLocks, sessionKey, async (): Promise<StagedWorkspace> => {+ const cached = options.isCompatibleResume ? store.borrow(sessionKey) : undefined;+ if (cached) {+ // Reuse the already-staged in-sandbox workspace and managed home.+ // Re-apply the env keys the seam repointed and reuse the per-run+ // copy-back so the copy-back cadence stays exactly per run.+ Object.assign(options.env, cached.envDelta);+ cached.lastUsedAt = options.now();+ await options.onReuseLog();+ return {+ stagedRuntime: cached.stagedRuntime,+ teardown: cached.teardown,+ dispose: cached.dispose,+ envDelta: cached.envDelta,+ reused: true,+ };+ }+ // Not a compatible resume: stage fresh. Drop and dispose a stale entry+ // that collides on this key first, so a fresh stage neither reuses nor+ // leaks it.+ const stale = options.stagedRuntimes.get(sessionKey);+ if (stale) {+ options.stagedRuntimes.delete(sessionKey);+ if (stale.dispose) await stale.dispose().catch(() => {});+ }+ const envBeforeStage = { ...options.env };+ let freshlyStaged: PreparedAdapterExecutionTargetRuntime | null = null;+ const stage: StageWorkspace = async (assets) => {+ const result = await options.stage(assets);+ freshlyStaged = result;+ return result;+ };+ const seam = await options.measureStageStep(async (): Promise<ManagedHomeSeamResult> => {+ if (options.seedManagedHome) {+ try {+ return await options.seedManagedHome(stage);+ } catch (seamErr) {+ // The seam threw after a possible successful stage. Dispose the fresh+ // staged runtime so the abandoned in-sandbox managed home never leaks,+ // then rethrow the seam error.+ if (freshlyStaged) await options.disposeFreshStagedRuntime(freshlyStaged);+ throw seamErr;+ }+ }+ return { stagedRuntime: await stage([]), teardown: null, dispose: null };+ });+ const envDelta: Record<string, string> = {};+ for (const [key, value] of Object.entries(options.env)) {+ if (envBeforeStage[key] !== value) envDelta[key] = value;+ }+ return {+ stagedRuntime: seam.stagedRuntime,+ teardown: seam.teardown,+ dispose: seam.dispose,+ envDelta,+ reused: false,+ };+ });+ leaseRelease = lease.release;+ staged = lease.value;+ // Publish the referenced-project workspace hints (known only after staging).+ const stagedProjectDirs = staged.stagedRuntime.additionalSourceDirs ?? {};+ if (Object.keys(stagedProjectDirs).length > 0) {+ options.publishStagedProjectHints(stagedProjectDirs);+ }+ // Register the acquired resources into the ledger. A per-run copy-back and a+ // staging lease live through the whole run; the staged runtime is+ // startup-rollback until a clean turn promotes it.+ options.ledger.register({+ id: "staged_runtime",+ payload: { stagedRuntime: staged.stagedRuntime, disposeStaged: staged.dispose ?? (async () => {}) },+ scope: "startup_rollback",+ });+ if (staged.teardown) {+ options.ledger.register({+ id: "managed_home",+ payload: { teardown: staged.teardown, envDelta: staged.envDelta },+ scope: "per_run",+ });+ }+ if (leaseRelease) {+ const release = leaseRelease;+ options.ledger.register({+ id: "staging_lease",+ payload: { release },+ scope: "per_run",+ });+ }+ return {+ referencedProjectStagingFailures: (staged.stagedRuntime.additionalSourceFailures ?? []).map(+ (failure) => ({ projectId: failure.projectId }),+ ),+ };+ },++ async startTransport(): Promise<SandboxRunSiteTransport> {+ // Bring up both host-side bridges concurrently. Their remote subtrees are+ // disjoint, so their env-independent setup overlaps. The one real+ // dependency — the paperclip bridge's returned env must reach the+ // process-session launch — is sequenced by `launchEnv`, a memoized thunk the+ // process-session bridge awaits right before its launch.+ const stagedRootDir = staged?.stagedRuntime.runtimeRootDir ?? null;+ const paperclipStart = options.measureBridgeStep("bridge.paperclip", () =>+ options.startPaperclipBridge(stagedRootDir),+ );+ // The single sequencing point (paperclip env → process-session launch),+ // memoized so the merge runs exactly once whether the process-session bridge+ // consumes it at launch or `startTransport` finalizes it below.+ let launchEnvPromise: Promise<Record<string, string>> | null = null;+ let launchEnv: Record<string, string> = {};+ const finalizeLaunchEnv = (): Promise<Record<string, string>> =>+ (launchEnvPromise ??= (async () => {+ const paperclip = await paperclipStart;+ // The paperclip bridge token is run-scoped: it lives for this run only and+ // never enters a reuse payload (Amendment B). The site hands it to the+ // engine's `finalizeLaunchEnv`, the sole consumer of a contribution, and+ // retains nothing.+ const contributions: LaunchEnvironmentContribution[] = [];+ if (paperclip) {+ contributions.push({ scope: "run", env: paperclip.env } as unknown as RunScopedContribution);+ await options.onPaperclipBridgeLog();+ }+ launchEnv = options.finalizeLaunchEnv(contributions);+ return launchEnv;+ })());+ const processSessionStart = options.measureBridgeStep("bridge.process-session", () =>+ options.startProcessSessionBridge({ runtimeRootDir: stagedRootDir, launchEnv: finalizeLaunchEnv }),+ );+ // Settle BOTH starts, so a partial failure can stop whichever bridge started.+ const [paperclip, processSession] = await Promise.allSettled([paperclipStart, processSessionStart]);+ controlBridge = paperclip.status === "fulfilled" ? paperclip.value : null;+ agentBridge = processSession.status === "fulfilled" ? processSession.value : null;+ const failure =+ paperclip.status === "rejected"+ ? paperclip.reason+ : processSession.status === "rejected"+ ? processSession.reason+ : null;+ if (failure) throw failure;+ // Guarantee the merge ran even if the process-session bridge returned without+ // consuming the launch env (memoized, so a no-op if it did).+ await finalizeLaunchEnv();+ if (controlBridge) {+ options.ledger.register({ id: "control_bridge", payload: controlBridge, scope: "per_run" });+ }+ if (agentBridge) {+ options.ledger.register({ id: "agent_bridge", payload: agentBridge, scope: "per_run" });+ }+ return { controlBridge, agentBridge, launchEnv };+ },++ reuse(): SessionReuseStore<StagedRuntimeStoreEntry> {+ return store;+ },++ reuseCandidate(resources: ReadyRunResources): SandboxReuseCandidate {+ const stagedResource = resources.get("staged_runtime");+ if (!stagedResource) {+ throw new Error("sandbox run site cannot name a reuse candidate without a staged_runtime resource");+ }+ // The reuse payload carries the staged files only — no credential material.+ return { stagedRuntime: stagedResource.stagedRuntime };+ },++ async syncBack(): Promise<void> {+ try {+ // Stop both bridges, then run the managed-home copy-back (mirrors the CLI+ // finally: stop bridge, then restore workspace).+ await options.stopBridges({ controlBridge, agentBridge });+ } finally {+ // Release the per-session staging lease in a finally, so an earlier+ // teardown fault never strands it and deadlocks the next same-session run.+ leaseRelease?.();+ leaseRelease = null;+ }+ },++ get staged(): StagedWorkspace | null {+ return staged;+ },++ get controlBridge(): AdapterExecutionTargetPaperclipBridgeHandle | null {+ return controlBridge;+ },++ get agentBridge(): AdapterExecutionTargetProcessSessionBridgeHandle | null {+ return agentBridge;+ },++ get stagingLeaseRelease(): (() => void) | null {+ return leaseRelease;+ },+ };+}++// Per-`sessionKey` async lease: chains each caller after the previous one so the+// stage-or-reuse decision for a session runs serially, then keeps the lease held+// until the run releases it. Two overlapping runs of the same session can never+// stage into the same remote workspace at once: the loser waits, then re-checks+// the cache before it decides.+async function withStagingLease<T>(+ locks: Map<string, Promise<unknown>>,+ key: string,+ fn: () => Promise<T>,+): Promise<{ value: T; release: () => void }> {+ const prev = locks.get(key) ?? Promise.resolve();+ let releaseGate!: () => void;+ const gate = new Promise<void>((resolve) => {+ releaseGate = resolve;+ });+ const mine: Promise<unknown> = prev.then(() => gate);+ locks.set(key, mine);+ await prev.catch(() => {});+ let released = false;+ const release = () => {+ if (released) return;+ released = true;+ releaseGate();+ if (locks.get(key) === mine) locks.delete(key);+ };+ try {+ return { value: await fn(), release };+ } catch (error) {+ if (!released) release();+ throw error;+ }+}diff --git a/packages/adapter-utils/src/acpx-engine/session-reuse-store.test.ts b/packages/adapter-utils/src/acpx-engine/session-reuse-store.test.tsnew file mode 100644index 0000000000..0af143f389--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/session-reuse-store.test.ts@@ -0,0 +1,160 @@+// Tests for the generic per-session reuse store (Phase 18).+//+// The store backs both site caches over a caller-provided map. These tests pin+// the four behaviors the two caches had before the refactor: borrow reads+// without removal and clears the per-entry idle timer; discard is+// identity-guarded and releases once; save arms a per-entry idle timer that+// discards without a run; and the run-start sweep runs each eviction under the+// optional per-key lease.++import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { createSessionReuseStore } from "./session-reuse-store.js";++interface Entry {+ readonly id: string;+ lastUsedAt: number;+ cleanupTimer?: ReturnType<typeof setTimeout>;+}++function hostConfig(entries: Map<string, Entry>, released: Entry[], idleMs: number) {+ return {+ entries,+ now: () => Date.now(),+ idleMs,+ lastUsedAt: (entry: Entry) => entry.lastUsedAt,+ getTimer: (entry: Entry) => entry.cleanupTimer,+ setTimer: (entry: Entry, timer: ReturnType<typeof setTimeout> | undefined) => {+ entry.cleanupTimer = timer;+ },+ perEntryTimer: true,+ release: (entry: Entry) => {+ released.push(entry);+ },+ };+}++describe("session reuse store", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ });+ afterEach(() => {+ vi.useRealTimers();+ });++ it("test_borrow_reads_without_removal_and_clears_the_per_entry_idle_timer", async () => {+ const entries = new Map<string, Entry>();+ const released: Entry[] = [];+ const store = createSessionReuseStore<Entry>(hostConfig(entries, released, 1000));++ const entry: Entry = { id: "a", lastUsedAt: Date.now() };+ store.save("k", entry);+ expect(entry.cleanupTimer).toBeDefined();++ // A borrow reads the entry and leaves it in the store, so a second borrow+ // still finds it.+ expect(store.borrow("k")).toBe(entry);+ expect(store.borrow("k")).toBe(entry);++ // The borrow cleared the per-entry idle timer, so the entry does not expire+ // while it is in use. Advance well past the idle bound.+ await vi.advanceTimersByTimeAsync(5000);+ expect(released).toEqual([]);+ expect(store.borrow("k")).toBe(entry);+ // The entry stays in the caller's map for a later run to inspect.+ expect(entries.get("k")).toBe(entry);+ });++ it("test_discard_is_identity_guarded_and_fires_release_once", async () => {+ const entries = new Map<string, Entry>();+ const released: Entry[] = [];+ const store = createSessionReuseStore<Entry>({+ entries,+ now: () => Date.now(),+ idleMs: 0,+ lastUsedAt: (entry) => entry.lastUsedAt,+ release: (entry) => {+ released.push(entry);+ },+ });++ const first: Entry = { id: "first", lastUsedAt: Date.now() };+ store.save("k", first);++ // The first discard removes the entry and fires the release once.+ await store.discard("k");+ expect(released).toEqual([first]);+ expect(store.borrow("k")).toBeUndefined();++ // A second discard of the same key finds no entry, so it releases nothing.+ await store.discard("k");+ expect(released).toEqual([first]);++ // A re-saved entry is a new entry. A discard of the key releases the new+ // entry, never the already-released first entry again.+ const second: Entry = { id: "second", lastUsedAt: Date.now() };+ store.save("k", second);+ await store.discard("k");+ expect(released).toEqual([first, second]);+ });++ it("test_save_arms_a_per_entry_idle_timer_that_discards_without_a_run", async () => {+ const entries = new Map<string, Entry>();+ const released: Entry[] = [];+ const store = createSessionReuseStore<Entry>(hostConfig(entries, released, 1000));++ const entry: Entry = { id: "a", lastUsedAt: Date.now() };+ store.save("k", entry);++ // Before the idle deadline the entry is still present and unreleased.+ await vi.advanceTimersByTimeAsync(999);+ expect(released).toEqual([]);++ // At the idle deadline the armed timer discards the entry with no run and+ // no explicit discard call.+ await vi.advanceTimersByTimeAsync(1);+ expect(released).toEqual([entry]);+ expect(store.borrow("k")).toBeUndefined();+ expect(entries.has("k")).toBe(false);+ });++ it("test_evict_idle_sweep_runs_under_per_key_lease", async () => {+ const entries = new Map<string, Entry>();+ const released: Entry[] = [];+ const leaseOrder: string[] = [];+ let now = 0;+ const store = createSessionReuseStore<Entry>({+ entries,+ now: () => now,+ idleMs: 1000,+ lastUsedAt: (entry) => entry.lastUsedAt,+ // The sandbox lane leaves the per-entry timer off and relies on the+ // run-start sweep only.+ release: (entry) => {+ released.push(entry);+ },+ withEvictLease: async (key, critical) => {+ leaseOrder.push(`lease:${key}`);+ await critical();+ leaseOrder.push(`release:${key}`);+ },+ });++ store.save("stale", { id: "stale", lastUsedAt: 0 });+ store.save("fresh", { id: "fresh", lastUsedAt: 0 });++ // Move the clock so only the "stale" entry crosses the idle bound. Touch+ // "fresh" so it stays inside the window.+ now = 1500;+ store.borrow("fresh");+ store.save("fresh", { id: "fresh2", lastUsedAt: now });++ await store.evictIdle(now);++ // Only the stale entry evicts, and its critical section ran inside the+ // per-key lease (lease acquired, critical ran, lease released, in order).+ expect(released.map((entry) => entry.id)).toEqual(["stale"]);+ expect(leaseOrder).toEqual(["lease:stale", "release:stale"]);+ expect(store.borrow("stale")).toBeUndefined();+ expect(store.borrow("fresh")).toEqual({ id: "fresh2", lastUsedAt: 1500 });+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/session-reuse-store.ts b/packages/adapter-utils/src/acpx-engine/session-reuse-store.tsnew file mode 100644index 0000000000..a8ca1f8994--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/session-reuse-store.ts@@ -0,0 +1,189 @@+// 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.++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 function createSessionReuseStore<T>(+ config: SessionReuseStoreConfig<T>,+): SessionReuseStore<T> {+ const { entries } = config;++ function clearEntryTimer(entry: T): void {+ 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: string, entry: T): Promise<void> {+ clearEntryTimer(entry);+ if (entries.get(key) !== entry) return;+ entries.delete(key);+ await config.release(entry);+ }++ function armTimer(key: string, entry: T): void {+ 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: string): T | undefined {+ 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: string, entry: T): void {+ // 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: string): Promise<void> {+ 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: number): Promise<void> {+ if (config.idleMs <= 0) return;+ const stale: Array<[string, T]> = [];+ 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 (): Promise<void> => {+ 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();+ }+ }+ },+ };+}diff --git a/packages/adapter-utils/src/acpx-engine/settlement-characterization.test.ts b/packages/adapter-utils/src/acpx-engine/settlement-characterization.test.tsindex d5f9754a88..eb4aba4b1c 100644--- a/packages/adapter-utils/src/acpx-engine/settlement-characterization.test.ts+++ b/packages/adapter-utils/src/acpx-engine/settlement-characterization.test.ts@@ -354,9 +354,11 @@ describe("ACP settlement — Layer A: engine teardown orchestration", () => {expect(stagingLocks.size).toBe(0);});- it("test_clean_persistent_local_run_warm_saves_instead_of_closing", async () => {- // execute.ts:3886 keeps a clean persistent local turn warm (no runtime.close)- // when warmIdleMs>0 and there is no process-session bridge.+ it("test_clean_persistent_local_run_closes_and_relaunches_amendment_b", async () => {+ // Amendment B: a clean persistent local turn closes the runtime instead of+ // warm-saving it. The host-lane reuse candidate carries the run-minted API key,+ // which is never revoked, so the credential gate fails and the settlement+ // discards (close-and-relaunch).const root = await makeTempRoot();const closeSpy = vi.fn(async () => {});const warmHandles = new Map();@@ -393,16 +395,9 @@ describe("ACP settlement — Layer A: engine teardown orchestration", () => {} as never);expect(result.exitCode).toBe(0);- // The runtime stayed warm: no close, one warm entry.- expect(closeSpy).not.toHaveBeenCalled();- expect(warmHandles.size).toBe(1);-- // Clear the scheduled idle-cleanup timer so no timer outlives the test. The- // long idle window kept the timer from racing the assertions above; clearing- // it here makes cleanup deterministic instead of a timed drain.- for (const entry of warmHandles.values()) {- if (entry.cleanupTimer) clearTimeout(entry.cleanupTimer);- }+ // The runtime closed and relaunched: one close, no warm entry.+ expect(closeSpy).toHaveBeenCalledTimes(1);+ expect(warmHandles.size).toBe(0);});it("test_completed_non_persistent_local_run_closes_runtime_once", async () => {@@ -543,12 +538,12 @@ describe("ACP settlement — Layer A: engine teardown orchestration", () => {}});- it("test_handshake_failure_after_warm_hit_closes_runtime_and_removes_warm_entry", async () => {- // Mirror execute.test.ts F2 test_handshake_failure_closes_runtime_and_removes_warm_entry- // (:4666). The first run warms a handle; the second run reuses it and fails- // while persisting process identity (onSpawn throws). Because the warm hit- // already holds the handle, the handshake failure closes the reused runtime- // (execute.ts:3591) and removes the warm entry.+ it("test_handshake_failure_on_second_run_closes_the_recreated_runtime", async () => {+ // Amendment B: the first clean persistent turn closes and relaunches instead of+ // warm-saving, so the second run finds no warm handle. The second run re-creates+ // the runtime and fails while persisting process identity (onSpawn throws); the+ // handshake failure closes the re-created runtime. The host-lane warm-hit+ // teardown path itself is characterized by the composed fault matrix.const root = await makeTempRoot();const stateDir = path.join(root, "state");const startedAt = "2026-01-01T00:00:00.000Z";@@ -591,7 +586,8 @@ describe("ACP settlement — Layer A: engine teardown orchestration", () => {onSpawn: async () => {},} as never);expect(first.exitCode).toBe(0);- expect(warmHandles.size).toBe(1);+ // Amendment B: no warm entry survives the first clean persistent turn.+ expect(warmHandles.size).toBe(0);expect(created).toBe(1);const second = await execute({@@ -607,11 +603,12 @@ describe("ACP settlement — Layer A: engine teardown orchestration", () => {},} as never);- // The reused runtime (no new create) is closed and the warm entry removed.- expect(created).toBe(1);+ // The second run re-created the runtime (no warm reuse) and closed it on the+ // failure, reporting the ensure_session phase. Both runtimes closed.+ expect(created).toBe(2);expect(second.exitCode).toBe(1);expect(second.resultJson?.phase).toBe("ensure_session");- expect(closeSpy).toHaveBeenCalledTimes(1);+ expect(closeSpy).toHaveBeenCalledTimes(2);expect(warmHandles.size).toBe(0);});diff --git a/packages/adapter-utils/src/acpx-engine/settlement-sequence.test.ts b/packages/adapter-utils/src/acpx-engine/settlement-sequence.test.tsnew file mode 100644index 0000000000..6f3578e79a--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/settlement-sequence.test.ts@@ -0,0 +1,323 @@+import { describe, expect, it } from "vitest";+import {+ decideReuse,+ settleAcpRun,+ type ReuseCandidateInput,+ type ReuseDecision,+ type SettlementSlots,+ type SettlementSteps,+} from "./settlement-sequence.js";+import { createRunResourceLedger } from "./run-resource-ledger.js";+import type { AcquiredRunResources, ResourceId, SettlementCause } from "./run-contracts.js";++// The settlement sequence is the one cleanup owner. These tests drive it with+// fakes for the steps and assert the claim, the order, the Phase 3 error policy,+// the staging-lease finally, and the Amendment B credential gate. They never+// touch the engine's real run state.++// Register a per-run resource for each id, with an optional payload the steps+// read. The tests do not seal the ledger; `takeForSettlement` runs from `open`.+function ledgerWith(+ ids: readonly ResourceId[],+ payloads: Partial<Record<ResourceId, unknown>> = {},+): AcquiredRunResources {+ const ledger = createRunResourceLedger();+ const register = ledger.register as (registration: {+ id: ResourceId;+ payload: unknown;+ scope: "per_run";+ }) => void;+ for (const id of ids) {+ register({ id, payload: payloads[id] ?? {}, scope: "per_run" });+ }+ return ledger;+}++// Count the claims so a test proves the sequence claims the ledger once.+function countingLedger(inner: AcquiredRunResources): {+ ledger: AcquiredRunResources;+ claims: () => number;+} {+ let claims = 0;+ const ledger: AcquiredRunResources = {+ register: inner.register.bind(inner),+ seal: inner.seal.bind(inner),+ takeForSettlement: () => {+ claims += 1;+ return inner.takeForSettlement();+ },+ };+ return { ledger, claims: () => claims };+}++// A base set of steps whose bodies record their name. Each test overrides the+// steps it drives.+function baseSteps(order: string[], overrides: Partial<SettlementSteps> = {}): SettlementSteps {+ return {+ reuseCandidate: overrides.reuseCandidate ?? (() => null),+ endSession: overrides.endSession ?? (() => {+ order.push("end_session");+ }),+ settleReuse: overrides.settleReuse ?? (() => {+ order.push("settle_reuse");+ }),+ stopTransport: overrides.stopTransport ?? (() => {+ order.push("stop_transport");+ }),+ syncBack: overrides.syncBack ?? (() => {+ order.push("sync_back");+ }),+ releaseStagingLease: overrides.releaseStagingLease ?? (() => {+ order.push("release_staging_lease");+ }),+ recordError: overrides.recordError ?? (() => {}),+ };+}++const cleanTurnCause: SettlementCause | null = null;++describe("ACPX settlement sequence", () => {+ it("test_settlement_claims_ledger_once_then_runs_the_steps_in_order", async () => {+ const order: string[] = [];+ const { ledger, claims } = countingLedger(+ ledgerWith(["acp_runtime", "control_bridge", "agent_bridge", "staging_lease"]),+ );++ await settleAcpRun(ledger, cleanTurnCause, baseSteps(order));++ // The sequence claims the ledger exactly once.+ expect(claims()).toBe(1);+ // It runs the effect steps in the fixed order; the lease release runs last.+ expect(order).toEqual([+ "end_session",+ "settle_reuse",+ "stop_transport",+ "sync_back",+ "release_staging_lease",+ ]);+ });++ it("test_every_step_noops_on_empty_slot", async () => {+ const order: string[] = [];+ // An empty ledger: no slot holds a resource. Each step reads its slot and+ // no-ops when the slot is empty.+ const ledger = ledgerWith([]);+ const noopFor = (name: string, id: ResourceId) => (slots: SettlementSlots) => {+ order.push(slots.has(id) ? `${name}:work` : `${name}:noop`);+ };+ const steps = baseSteps(order, {+ endSession: noopFor("end_session", "acp_runtime"),+ settleReuse: noopFor("settle_reuse", "acp_runtime"),+ stopTransport: noopFor("stop_transport", "control_bridge"),+ syncBack: noopFor("sync_back", "staged_runtime"),+ releaseStagingLease: (slots) => {+ order.push(slots.has("staging_lease") ? "release_staging_lease:work" : "release_staging_lease:noop");+ },+ });++ const report = await settleAcpRun(ledger, cleanTurnCause, steps);++ // Every step saw an empty slot and no-opped.+ expect(order).toEqual([+ "end_session:noop",+ "settle_reuse:noop",+ "stop_transport:noop",+ "sync_back:noop",+ "release_staging_lease:noop",+ ]);+ // An empty ledger yields an empty disposition report.+ expect(report.records).toEqual([]);+ });++ it("test_transferred_runtime_is_never_closed_and_discarded_entry_is_finalized", async () => {+ const order: string[] = [];+ const ledger = ledgerWith(["acp_runtime", "staging_lease"], {+ acp_runtime: { runtime: {}, sessionHandle: {}, childProcessPid: null },+ });+ const steps = baseSteps(order, {+ // A clean host turn with no live run-scoped credential is save-eligible.+ reuseCandidate: (): ReuseCandidateInput => ({+ kind: "host",+ causePermitsSave: true,+ liveRunScopedCredentials: [],+ }),+ endSession: (_slots, decision) => {+ // The transferred runtime is never closed.+ order.push(decision.kind === "save" ? "kept" : "closed");+ },+ settleReuse: (_slots, decision) => {+ order.push(decision.kind === "save" ? "transferred" : "discarded");+ },+ });++ const report = await settleAcpRun(ledger, cleanTurnCause, steps);++ // The runtime transferred; it was never closed.+ expect(order).toContain("kept");+ expect(order).not.toContain("closed");+ expect(order).toContain("transferred");+ // The report marks the transferred runtime `transferred` and the discarded+ // staging lease `finalized`.+ expect(report.records).toEqual([+ { id: "acp_runtime", disposition: "transferred" },+ { id: "staging_lease", disposition: "finalized" },+ ]);+ });++ it("test_step_error_is_recorded_and_later_steps_still_run", async () => {+ const order: string[] = [];+ const recorded: string[] = [];+ const boom = new Error("end_session boom");+ const steps = baseSteps(order, {+ endSession: () => {+ throw boom;+ },+ recordError: (step, error) => {+ recorded.push(step);+ expect(error).toBe(boom);+ },+ });++ await settleAcpRun(ledgerWith(["acp_runtime", "staging_lease"]), cleanTurnCause, steps);++ // The failed step is recorded...+ expect(recorded).toContain("end_session");+ // ...and every later step still runs.+ expect(order).toEqual([+ "settle_reuse",+ "stop_transport",+ "sync_back",+ "release_staging_lease",+ ]);+ });++ it("test_staging_lease_release_runs_in_finally", async () => {+ const order: string[] = [];+ const recorded: string[] = [];+ const steps = baseSteps(order, {+ syncBack: () => {+ throw new Error("sync_back boom");+ },+ recordError: (step) => {+ recorded.push(step);+ },+ });++ await settleAcpRun(ledgerWith(["staging_lease"]), cleanTurnCause, steps);++ // The sync-back failure is recorded, and the lease release still runs.+ expect(recorded).toContain("sync_back");+ expect(order).toContain("release_staging_lease");+ });++ it("test_two_compatible_runs_do_not_share_run_scoped_credentials", async () => {+ // Two compatible runs each own their ledger, bridge token, and run API key.+ // Run B must never observe run A's run-scoped values.+ const observed: Array<{ run: string; token: unknown; credentials: readonly string[] }> = [];+ const settleRun = async (run: string, token: string, credential: string) => {+ const ledger = ledgerWith(["acp_runtime", "control_bridge"], {+ control_bridge: { token },+ });+ const steps = baseSteps([], {+ reuseCandidate: (): ReuseCandidateInput => ({+ kind: "host",+ causePermitsSave: true,+ liveRunScopedCredentials: [credential],+ }),+ stopTransport: (slots) => {+ const bridge = slots.get("control_bridge") as { token: unknown } | undefined;+ observed.push({ run, token: bridge?.token, credentials: [credential] });+ },+ });+ return settleAcpRun(ledger, cleanTurnCause, steps);+ };++ await settleRun("A", "token-A", "run-api-key-A");+ await settleRun("B", "token-B", "run-api-key-B");++ const runA = observed.find((o) => o.run === "A");+ const runB = observed.find((o) => o.run === "B");+ // Run B observed only its own bridge token and credential, never run A's.+ expect(runB?.token).toBe("token-B");+ expect(runB?.token).not.toBe(runA?.token);+ expect(runB?.credentials).not.toContain("run-api-key-A");+ });++ it("test_no_run_scoped_credential_appears_in_reuse_payload_or_telemetry", async () => {+ const runScopedCredential = "run-api-key-secret";+ let savedPayload: Record<string, unknown> | null = null;+ // A save-eligible sandbox candidate: the staged-files payload carries no+ // credential, and the bridge tokens already died with the bridges, so the+ // live run-scoped credential list is empty.+ const ledger = ledgerWith(["staged_runtime", "staging_lease"], {+ staged_runtime: { stagedRuntime: { files: ["a", "b"] } },+ });+ const steps = baseSteps([], {+ reuseCandidate: (): ReuseCandidateInput => ({+ kind: "sandbox",+ causePermitsSave: true,+ liveRunScopedCredentials: [],+ }),+ settleReuse: (slots, decision) => {+ if (decision.kind === "save") {+ const staged = slots.get("staged_runtime") as unknown as {+ stagedRuntime: Record<string, unknown>;+ };+ savedPayload = staged.stagedRuntime;+ }+ },+ });++ const report = await settleAcpRun(ledger, cleanTurnCause, steps);++ // The saved reuse payload carries no run-scoped credential.+ expect(savedPayload).not.toBeNull();+ expect(JSON.stringify(savedPayload)).not.toContain(runScopedCredential);+ // The disposition report (telemetry) carries no run-scoped credential.+ expect(JSON.stringify(report)).not.toContain(runScopedCredential);+ // The staged files transferred.+ expect(report.records).toContainEqual({ id: "staged_runtime", disposition: "transferred" });+ });++ it("test_warm_save_requires_credential_gate_pass_else_close_and_relaunch", async () => {+ const runWithCredentials = async (liveRunScopedCredentials: readonly string[]) => {+ const order: string[] = [];+ const ledger = ledgerWith(["acp_runtime"]);+ const steps = baseSteps(order, {+ reuseCandidate: (): ReuseCandidateInput => ({+ kind: "host",+ causePermitsSave: true,+ liveRunScopedCredentials,+ }),+ endSession: (_slots, decision) => {+ order.push(decision.kind === "save" ? "kept" : "closed");+ },+ });+ const report = await settleAcpRun(ledger, cleanTurnCause, steps);+ return { order, report };+ };++ // A live run-scoped credential fails the gate: close-and-relaunch, finalized.+ const gated = await runWithCredentials(["run-api-key"]);+ expect(gated.order).toContain("closed");+ expect(gated.report.records).toContainEqual({ id: "acp_runtime", disposition: "finalized" });++ // No live run-scoped credential passes the gate: the runtime transfers.+ const cleared = await runWithCredentials([]);+ expect(cleared.order).toContain("kept");+ expect(cleared.report.records).toContainEqual({ id: "acp_runtime", disposition: "transferred" });+ });++ it("decideReuse blocks a save when the Amendment B credential gate fails", () => {+ // A direct unit check on the pure decision, so the gate is legible on its own.+ const base: ReuseCandidateInput = { kind: "host", causePermitsSave: true, liveRunScopedCredentials: [] };+ expect(decideReuse(base)).toEqual({ kind: "save", savedId: "acp_runtime" } satisfies ReuseDecision);+ expect(decideReuse({ ...base, liveRunScopedCredentials: ["k"] }).kind).toBe("discard");+ expect(decideReuse({ ...base, causePermitsSave: false }).kind).toBe("discard");+ expect(decideReuse(null).kind).toBe("discard");+ expect(decideReuse({ ...base, kind: "sandbox" })).toEqual({+ kind: "save",+ savedId: "staged_runtime",+ } satisfies ReuseDecision);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/settlement-sequence.ts b/packages/adapter-utils/src/acpx-engine/settlement-sequence.tsnew file mode 100644index 0000000000..2db0fda9ea--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/settlement-sequence.ts@@ -0,0 +1,204 @@+// The settlement sequence.+//+// `settleAcpRun(ledger, cause, steps)` is the one cleanup owner for every site+// and every settled path. The one exception is the startup rollback, which the+// coordinator owns (Phase 20).+//+// The sequence claims the ledger once, makes the pure reuse decision, then runs+// the ordered steps:+//+// 1. endSession — close every runtime the decision did not transfer, and+// drop the warm entry when it closes.+// 2. settleReuse — perform the decision: a save transfers the candidate to the+// site store (which arms the per-entry idle timer); everything+// else discards.+// 3. stopTransport — stop both bridges in one `allSettled`.+// 4. syncBack — the site sync-back.+// 5. releaseStagingLease — runs in a `finally`, so an earlier step fault never+// strands the lease.+//+// The Phase 3 error policy governs every step: a step records its error and the+// later steps still run. Every step no-ops on an empty slot.+//+// Amendment B — the credential gate. A runtime is save-eligible only when no+// run-scoped credential issued to it remains valid. The decision is pure and+// runs before any close. Settlement stops both bridges before a sandbox-lane+// transfer, so the bridge tokens die with the bridges. The run API key is not+// invalidated on run end (grounded server-side), so the host-lane warm save+// discards instead of transfers (close-and-relaunch) until a credential-rebind+// protocol exists. The sandbox staged-files reuse is unaffected: its payload+// carries no credentials.++import type {+ AcquiredRunResources,+ ResourceDisposition,+ ResourceId,+ RunResourcePayloads,+ RunSiteKind,+ SettledResourceEntry,+ SettlementCause,+} from "./run-contracts.js";++/** The save-versus-discard decision the settlement makes before any close. */+export type ReuseDecision =+ | { readonly kind: "save"; readonly savedId: ResourceId }+ | { readonly kind: "discard"; readonly reason: string };++/**+ * The inputs the reuse decision reads. The site derives the candidate from the+ * settled slots. A null candidate means the run holds nothing to save.+ */+export interface ReuseCandidateInput {+ /** The site kind. "host" saves the runtime; "sandbox" saves the staged files. */+ readonly kind: RunSiteKind;+ /** True when the settlement cause permits a save (a clean persistent turn). */+ readonly causePermitsSave: boolean;+ /**+ * Amendment B: the run-scoped credentials the candidate would still carry into+ * the store. A save is eligible only when this list is empty — no run-scoped+ * credential issued to the runtime remains valid.+ */+ readonly liveRunScopedCredentials: readonly string[];+}++/** One resource's final disposition, as the settlement records it. */+export interface ResourceDispositionRecord {+ readonly id: ResourceId;+ readonly disposition: ResourceDisposition;+}++/** The per-resource disposition report the settlement produces at the end. */+export interface SettlementDispositionReport {+ readonly records: readonly ResourceDispositionRecord[];+}++/** The settled slots view a step reads. `get` returns undefined for an empty slot. */+export interface SettlementSlots {+ get<Id extends ResourceId>(id: Id): RunResourcePayloads[Id] | undefined;+ has(id: ResourceId): boolean;+}++/**+ * The effectful steps the sequence runs. The engine implements each step over+ * its own run state. Each step no-ops on an empty slot. A step must not throw+ * for the sequence to record its error and continue; a throw is caught and+ * recorded under the Phase 3 error policy.+ */+export interface SettlementSteps {+ /**+ * Derive the reuse candidate from the settled slots and the cause, or null+ * when the run holds nothing to save.+ */+ reuseCandidate(slots: SettlementSlots, cause: SettlementCause | null): ReuseCandidateInput | null;+ /** Close every runtime the decision did not transfer; drop the warm entry on close. */+ endSession(slots: SettlementSlots, decision: ReuseDecision): Promise<void> | void;+ /** Perform the decision: a save transfers to the site store; everything else discards. */+ settleReuse(slots: SettlementSlots, decision: ReuseDecision): Promise<void> | void;+ /** Stop both bridges in one `allSettled`. */+ stopTransport(slots: SettlementSlots): Promise<void> | void;+ /** The site sync-back. */+ syncBack(slots: SettlementSlots): Promise<void> | void;+ /** Release the staging lease. Runs in a `finally`. */+ releaseStagingLease(slots: SettlementSlots): void;+ /** Record a per-step error under the Phase 3 error policy. */+ recordError(step: string, error: unknown): Promise<void> | void;+}++/**+ * The pure reuse decision. A save is eligible only when a candidate exists, the+ * cause permits a save, and Amendment B holds: no run-scoped credential issued+ * to the candidate remains valid. Everything else discards, with a reason.+ */+export function decideReuse(candidate: ReuseCandidateInput | null): ReuseDecision {+ if (!candidate) {+ return { kind: "discard", reason: "no reuse candidate" };+ }+ if (!candidate.causePermitsSave) {+ return { kind: "discard", reason: "settlement cause forbids save" };+ }+ if (candidate.liveRunScopedCredentials.length > 0) {+ // Amendment B credential gate: a live run-scoped credential blocks the save.+ return { kind: "discard", reason: "run-scoped credential still valid" };+ }+ const savedId: ResourceId = candidate.kind === "host" ? "acp_runtime" : "staged_runtime";+ return { kind: "save", savedId };+}++/**+ * Settle the run's resources. Claims the ledger once, makes the reuse decision,+ * runs the ordered steps under the Phase 3 error policy, releases the staging+ * lease in a `finally`, and returns the final per-resource disposition report.+ */+export async function settleAcpRun(+ ledger: AcquiredRunResources,+ cause: SettlementCause | null,+ steps: SettlementSteps,+): Promise<SettlementDispositionReport> {+ // Claim the ledger once. Every later step reads the claimed slots.+ const consumed = ledger.takeForSettlement();+ const entries = consumed.entries();+ const slots = makeSlots(entries);++ // The reuse decision is pure and runs before any close.+ const candidate = steps.reuseCandidate(slots, cause);+ const decision = decideReuse(candidate);++ const runStep = async (name: string, run: () => Promise<void> | void): Promise<void> => {+ try {+ await run();+ } catch (error) {+ // The Phase 3 error policy: record the step error and let later steps run.+ await steps.recordError(name, error);+ }+ };++ try {+ await runStep("end_session", () => steps.endSession(slots, decision));+ await runStep("settle_reuse", () => steps.settleReuse(slots, decision));+ await runStep("stop_transport", () => steps.stopTransport(slots));+ await runStep("sync_back", () => steps.syncBack(slots));+ } finally {+ // The staging lease release runs in a `finally`, so an earlier step fault+ // never strands the lease.+ try {+ steps.releaseStagingLease(slots);+ } catch (error) {+ await steps.recordError("release_staging_lease", error);+ }+ }++ return buildReport(entries, decision);+}++/** Build the settled slots view from the claimed entries. */+function makeSlots(entries: readonly SettledResourceEntry[]): SettlementSlots {+ const byId = new Map<ResourceId, SettledResourceEntry>();+ for (const entry of entries) byId.set(entry.id, entry);+ return {+ get<Id extends ResourceId>(id: Id): RunResourcePayloads[Id] | undefined {+ return byId.get(id)?.payload as RunResourcePayloads[Id] | undefined;+ },+ has(id: ResourceId): boolean {+ return byId.has(id);+ },+ };+}++/**+ * Build the final per-resource disposition report. The claim-time value the+ * ledger stamps ("transferred") is not the final report; the settlement decides+ * it here. A saved resource is `transferred`; every other resource is+ * `finalized`.+ */+function buildReport(+ entries: readonly SettledResourceEntry[],+ decision: ReuseDecision,+): SettlementDispositionReport {+ const savedId = decision.kind === "save" ? decision.savedId : null;+ return {+ records: entries.map((entry) => ({+ id: entry.id,+ disposition: entry.id === savedId ? ("transferred" as const) : ("finalized" as const),+ })),+ };+}diff --git a/packages/adapter-utils/src/acpx-engine/startup-characterization.test.ts b/packages/adapter-utils/src/acpx-engine/startup-characterization.test.tsindex 8f55ec0ae6..9367f933e8 100644--- a/packages/adapter-utils/src/acpx-engine/startup-characterization.test.ts+++ b/packages/adapter-utils/src/acpx-engine/startup-characterization.test.ts@@ -629,7 +629,7 @@ describe("ACPX engine startup characterization", () => {expect(stop).toHaveBeenCalledTimes(1);});- it("cold ensure_session throw: ensure_session error, and the handshake-catch close does NOT fire (no handle yet)", async () => {+ it("cold ensure_session throw: ensure_session error, and the runtime closes (the cold-handshake leak is fixed)", async () => {const root = await makeTempRoot();const closeSpy = vi.fn(async () => {});const execute = createAcpxEngineExecutor({@@ -655,11 +655,10 @@ describe("ACPX engine startup characterization", () => {expect(result.exitCode).toBe(1);expect(result.resultJson?.phase).toBe("ensure_session");- // Current behavior (execute.ts ~:3590): the handshake catch closes the runtime- // only `if (handle)`. A cold `ensureSession` throw never assigns a handle, so- // this close never fires. The warm-hit path below has a cached handle and does- // close. This pins the real cold-path behavior, not an aspiration.- expect(closeSpy).not.toHaveBeenCalled();+ // The runtime enters the ledger the moment it is created, so a cold+ // `ensureSession` throw (before any handle exists) still closes it through the+ // settlement `endSession` step. This closes the former cold-handshake leak.+ expect(closeSpy).toHaveBeenCalledTimes(1);});it("missing session handle: ensure_session error and the minimal runtime closes", async () => {@@ -728,7 +727,7 @@ describe("ACPX engine startup characterization", () => {expect(closeSpy).toHaveBeenCalledTimes(1);});- it("warm-hit failure: reuses the runtime, fails with ensure_session, closes it, drops the warm entry", async () => {+ it("persistent host failure: the first run closes and relaunches, so a failing second run re-creates and closes", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");const startedAt = "2026-01-01T00:00:00.000Z";@@ -771,10 +770,13 @@ describe("ACPX engine startup characterization", () => {onSpawn: async () => {},} as never);expect(first.exitCode).toBe(0);- expect(warmHandles.size).toBe(1);+ // Amendment B: the first clean persistent turn closes and relaunches instead+ // of warm-saving the runtime, so no warm handle survives.+ expect(warmHandles.size).toBe(0);expect(created).toBe(1);- // The warm-hit reuses runtime #1 and fails while persisting process identity.+ // The second run finds no warm handle, so it re-creates the runtime and fails+ // while persisting process identity during ensure_session.const second = await execute({runId: "warm-2",agent: { id: "agent-1", companyId: "company-1" },@@ -788,12 +790,12 @@ describe("ACPX engine startup characterization", () => {},} as never);- // No new runtime was created; the reused runtime is closed and the warm entry- // removed, with the failure reported on the ensure_session phase.- expect(created).toBe(1);+ // The second run built runtime #2 (no warm reuse), closed it on the failure,+ // and reported the ensure_session phase. Both runtimes closed (one per run).+ expect(created).toBe(2);expect(second.exitCode).toBe(1);expect(second.resultJson?.phase).toBe("ensure_session");- expect(closeSpy).toHaveBeenCalledTimes(1);+ expect(closeSpy).toHaveBeenCalledTimes(2);expect(warmHandles.size).toBe(0);});});@@ -820,7 +822,7 @@ describe("ACPX engine startup characterization", () => {expect(runtimeOptions[0]?.cwd).toBe(localCwd);});- it("persistent host lane: warm-saves the handle so a second run reuses the runtime", async () => {+ it("persistent host lane: closes and relaunches the handle, so a second run re-creates the runtime", async () => {const root = await makeTempRoot();const stateDir = path.join(root, "state");let created = 0;@@ -857,9 +859,11 @@ describe("ACPX engine startup characterization", () => {expect(first.exitCode).toBe(0);expect(second.exitCode).toBe(0);- // The warm handle survives, so the second run reuses runtime #1.- expect(created).toBe(1);- expect(warmHandles.size).toBe(1);+ // Amendment B: the host lane never warm-saves a live runtime (the run-minted+ // API key is never revoked), so the first run closes and relaunches. No warm+ // handle survives, so the second run re-creates runtime #2.+ expect(created).toBe(2);+ expect(warmHandles.size).toBe(0);});it("remote process-session lane: does NOT warm-save the handle, so a second run re-creates the runtime", async () => {diff --git a/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts b/packages/adapter-utils/src/acpx-engine/startup-timing.test.tsindex 14c7e0bfe2..ea0decb916 100644--- a/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts+++ b/packages/adapter-utils/src/acpx-engine/startup-timing.test.ts@@ -4,12 +4,15 @@ import type { StartupSpan, StartupTraceContext, StartupTracer } from "./startup-import {clampSpanLabel,createRuntimeSpanRunner,+ emitRunPhaseTiming,emitSkippedStartupStep,getActiveStepContext,measureStartupStep,NOOP_STARTUP_SPAN,NOOP_STARTUP_TRACE_CONTEXT,normalizeProviderFamily,+ RUN_PHASE_NAMES,+ RUN_PHASE_TIMING_EVENT_TYPE,runWithoutActiveStep,runWithRuntimeParent,SANDBOX_STARTUP_SPAN_ATTR_PREFIX,@@ -712,3 +715,59 @@ describe("createRuntimeSpanRunner", () => {expect(childStep).toBeNull();});});++describe("run phase timing telemetry", () => {+ it("test_phase_telemetry_fields_are_exactly_phase_duration_outcome", async () => {+ const events: AdapterRuntimeEvent[] = [];+ const ctx = { onEvent: async (event: AdapterRuntimeEvent) => void events.push(event) };++ await emitRunPhaseTiming(ctx, "create_runtime", 12, "ok");++ expect(events).toHaveLength(1);+ const event = events[0]!;+ expect(event.eventType).toBe(RUN_PHASE_TIMING_EVENT_TYPE);+ // The payload carries exactly the three closed fields and nothing else.+ expect(Object.keys(event.payload ?? {}).sort()).toEqual(["durationMs", "outcome", "phase"]);+ expect(event.payload).toEqual({ phase: "create_runtime", durationMs: 12, outcome: "ok" });+ });++ it("test_phase_telemetry_emits_no_command_path_environment_or_identifier_value", async () => {+ const events: AdapterRuntimeEvent[] = [];+ const ctx = { onEvent: async (event: AdapterRuntimeEvent) => void events.push(event) };++ // Every allowlisted phase emits exactly one closed-shape event.+ for (const phase of RUN_PHASE_NAMES) {+ await emitRunPhaseTiming(ctx, phase, 5, "ok");+ }+ // A phase name outside the closed allowlist emits nothing, so a free-form+ // label (a command, a path, an environment value, or a raw identifier) can+ // never reach the stream.+ await emitRunPhaseTiming(ctx, "/usr/bin/node --flag /secret/path", 5, "ok");+ await emitRunPhaseTiming(ctx, "PAPERCLIP_API_KEY=abc123", 5, "ok");+ await emitRunPhaseTiming(ctx, "run-7f3a-agent-42", 5, "ok");++ expect(events).toHaveLength(RUN_PHASE_NAMES.length);+ for (const event of events) {+ // The phase field is only ever an allowlisted name.+ expect(RUN_PHASE_NAMES).toContain(event.payload?.phase);+ // No field carries a command, a path, an environment value, or an identifier.+ const serialized = JSON.stringify(event);+ expect(serialized).not.toContain("/usr/bin/node");+ expect(serialized).not.toContain("/secret/path");+ expect(serialized).not.toContain("PAPERCLIP_API_KEY");+ expect(serialized).not.toContain("abc123");+ expect(serialized).not.toContain("run-7f3a-agent-42");+ }+ });++ it("test_telemetry_failure_does_not_fail_the_run", async () => {+ const ctx = {+ onEvent: async () => {+ throw new Error("telemetry sink boom");+ },+ };++ // A throwing telemetry sink never propagates, so the run continues.+ await expect(emitRunPhaseTiming(ctx, "turn", 9, "failed")).resolves.toBeUndefined();+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/startup-timing.ts b/packages/adapter-utils/src/acpx-engine/startup-timing.tsindex ce91ca6a5b..5e70bdbdb3 100644--- a/packages/adapter-utils/src/acpx-engine/startup-timing.ts+++ b/packages/adapter-utils/src/acpx-engine/startup-timing.ts@@ -786,3 +786,72 @@ export async function emitSkippedStartupStep(// Observability must not change startup control flow.}}++/**+ * Structured event emitted once per named run-lifecycle phase, so the duration+ * and the outcome of each phase land in the run-events stream. It is+ * observability-only and rides the existing `ctx.onEvent` bridge. The payload is+ * a closed shape: exactly `phase`, `durationMs`, and `outcome`. The phase name is+ * from a closed allowlist, so the event never carries a command, an argument, a+ * path, an environment value, or a raw identifier.+ */+export const RUN_PHASE_TIMING_EVENT_TYPE = "run.phase.timing";++/**+ * The closed set of run-lifecycle phase names. A phase-timing event may name only+ * one of these. The list is fixed and low-cardinality; it never derives from run+ * or user data.+ */+export const RUN_PHASE_NAMES = [+ "place_workspace",+ "start_transport",+ "create_runtime",+ "ensure_session",+ "configure_session",+ "prepare_turn",+ "turn",+ "end_session",+ "settle_reuse",+ "stop_transport",+ "sync_back",+ "release_staging_lease",+] as const;++/** One run-lifecycle phase name from the closed allowlist. */+export type RunPhaseName = (typeof RUN_PHASE_NAMES)[number];++const RUN_PHASE_NAME_SET: ReadonlySet<string> = new Set(RUN_PHASE_NAMES);++/** The closed outcome set for a phase-timing event. */+export type RunPhaseOutcome = "ok" | "failed";++/**+ * Emit exactly one `run.phase.timing` event for a run-lifecycle phase. The+ * payload carries only `phase`, `durationMs`, and `outcome`. It never carries a+ * command, an argument, a path, an environment value, or a raw identifier. The+ * phase name must be one member of the closed allowlist; a name outside the+ * allowlist emits nothing, so a free-form label can never reach the stream. A+ * negative or a non-finite duration clamps to 0. Every sink call sits inside an+ * error swallow, so a throwing telemetry sink never fails the run.+ */+export async function emitRunPhaseTiming(+ ctx: Pick<AdapterExecutionContext, "onEvent">,+ phase: string,+ durationMs: number,+ outcome: RunPhaseOutcome,+): Promise<void> {+ if (!RUN_PHASE_NAME_SET.has(phase)) return;+ const safeDuration = Number.isFinite(durationMs) && durationMs > 0 ? durationMs : 0;+ const event: AdapterRuntimeEvent = {+ eventType: RUN_PHASE_TIMING_EVENT_TYPE,+ stream: "system",+ level: "info",+ message: `run phase: ${phase} (${safeDuration}ms)`,+ payload: { phase, durationMs: safeDuration, outcome },+ };+ try {+ await ctx.onEvent?.(event);+ } catch {+ // Telemetry never fails the run.+ }+}diff --git a/packages/adapter-utils/src/acpx-engine/turn-sequence.test.ts b/packages/adapter-utils/src/acpx-engine/turn-sequence.test.tsnew file mode 100644index 0000000000..aef9c72a91--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/turn-sequence.test.ts@@ -0,0 +1,190 @@+import { describe, expect, it, vi } from "vitest";+import { runTurn, type StartedTurn, type TurnFinalizeInput, type TurnSteps } from "./turn-sequence.js";+import { createRunResourceLedger } from "./run-resource-ledger.js";+import type { TurnCompletion } from "./run-contracts.js";++// The turn sequence owns the run order, the wall-clock timer, and the abort+// controller. These tests drive it with fakes for the five steps and assert the+// order, the never-reject guarantee, and the timer ownership. They never touch+// the engine's real run state.++function finalizedTurn(): TurnCompletion {+ return { kind: "finalized" };+}++function failedTurn(error: unknown): TurnCompletion {+ return {+ kind: "failed",+ cause: { kind: "turn_failed", error: error instanceof Error ? error : new Error(String(error)) },+ resources: createRunResourceLedger().takeForSettlement(),+ };+}++function noopStarted(): StartedTurn {+ return { cancel: async () => {} };+}++// A base set of steps whose bodies do nothing. Each test overrides the steps it+// drives and records the calls it cares about.+function baseSteps(order: string[], overrides: Partial<TurnSteps<string>> = {}): TurnSteps<string> {+ return {+ timeoutMs: overrides.timeoutMs,+ timeoutMessage: overrides.timeoutMessage ?? "timed out",+ promptBuild: overrides.promptBuild ?? (async () => {+ order.push("promptBuild");+ }),+ preTurnUsage: overrides.preTurnUsage ?? (async () => {+ order.push("preTurnUsage");+ }),+ turnStart: overrides.turnStart ?? (() => {+ order.push("turnStart");+ return noopStarted();+ }),+ eventRelay: overrides.eventRelay ?? (async () => {+ order.push("eventRelay");+ return "terminal";+ }),+ turnFinalize: overrides.turnFinalize ?? (async (input) => {+ order.push(`turnFinalize:${input.kind}`);+ return input.kind === "terminal" ? finalizedTurn() : failedTurn(input.error);+ }),+ };+}++describe("ACPX turn sequence", () => {+ it("test_run_turn_never_rejects_every_error_is_a_completion", async () => {+ // A step error must become a `TurnCompletion`, never a rejection. The event+ // relay throws after the turn started, so the sequence reports a `turn`+ // failure and returns a completion.+ const finalizeInputs: TurnFinalizeInput<string>[] = [];+ const boom = new Error("relay boom");+ const steps = baseSteps([], {+ eventRelay: async () => {+ throw boom;+ },+ turnFinalize: async (input) => {+ finalizeInputs.push(input);+ return input.kind === "terminal" ? finalizedTurn() : failedTurn(input.error);+ },+ });++ // The returned promise resolves; it never rejects.+ const completion = await runTurn(steps);+ expect(completion.kind).toBe("failed");+ // The error routed through the one finalize step with the `turn` phase.+ expect(finalizeInputs).toHaveLength(1);+ expect(finalizeInputs[0]).toMatchObject({ kind: "error", error: boom, phase: "turn" });+ });++ it("test_run_turn_owns_timer_and_abort_controller", async () => {+ vi.useFakeTimers();+ try {+ const captured: { signal: AbortSignal | null; cancelReason: string | null } = {+ signal: null,+ cancelReason: null,+ };+ let releaseRelay: (value: string) => void = () => {};+ const relayPromise = new Promise<string>((resolve) => {+ releaseRelay = resolve;+ });+ const finalizeInputs: TurnFinalizeInput<string>[] = [];+ const steps = baseSteps([], {+ timeoutMs: 1000,+ timeoutMessage: "wall-clock timeout",+ turnStart: (signal) => {+ captured.signal = signal;+ return {+ cancel: async (reason) => {+ captured.cancelReason = reason;+ },+ };+ },+ eventRelay: async () => relayPromise,+ turnFinalize: async (input) => {+ finalizeInputs.push(input);+ return input.kind === "terminal" ? finalizedTurn() : failedTurn(input.error);+ },+ });++ const runPromise = runTurn(steps);+ // Let promptBuild, preTurnUsage, and turnStart run.+ await vi.advanceTimersByTimeAsync(0);+ expect(captured.signal?.aborted).toBe(false);+ // Fire the wall-clock timeout the sequence owns.+ await vi.advanceTimersByTimeAsync(1000);+ // The sequence owns the abort controller: the shared signal is aborted...+ expect(captured.signal?.aborted).toBe(true);+ // ...and it cancelled the started turn with the timeout message.+ expect(captured.cancelReason).toBe("wall-clock timeout");+ // Complete the relay so the sequence finalizes the timed-out turn.+ releaseRelay("terminal");+ const completion = await runPromise;+ expect(completion).toEqual({ kind: "finalized" });+ // The finalize step saw the timeout flag the sequence tracked.+ expect(finalizeInputs).toHaveLength(1);+ expect(finalizeInputs[0]).toMatchObject({ kind: "terminal", timedOut: true });+ } finally {+ vi.useRealTimers();+ }+ });++ it("test_prompt_build_failure_is_failed_completion_with_prepare_turn", async () => {+ // A prompt-build failure happens before the turn starts, so the sequence+ // reports a `prepare_turn` failure and never runs the later steps.+ const order: string[] = [];+ const finalizeInputs: TurnFinalizeInput<string>[] = [];+ const boom = new Error("prompt build boom");+ const steps = baseSteps(order, {+ promptBuild: async () => {+ throw boom;+ },+ turnFinalize: async (input) => {+ finalizeInputs.push(input);+ return input.kind === "terminal" ? finalizedTurn() : failedTurn(input.error);+ },+ });++ const completion = await runTurn(steps);+ expect(completion.kind).toBe("failed");+ expect(finalizeInputs).toHaveLength(1);+ expect(finalizeInputs[0]).toMatchObject({ kind: "error", error: boom, phase: "prepare_turn" });+ // The later steps never ran.+ expect(order).not.toContain("preTurnUsage");+ expect(order).not.toContain("turnStart");+ expect(order).not.toContain("eventRelay");+ });++ it("test_run_turn_finalizes_no_resource", async () => {+ // Structural proof: the sequence borrows the resources and finalizes none.+ // The `TurnSteps` contract has no resource-release method; the sequence runs+ // only the five ordered steps. A test-side resource whose release the+ // sequence could never call stays untouched, and the recorded call order is+ // exactly the five steps. The coordinator settles the resources after the+ // turn, so a resource release inside the sequence would be a double release.+ const order: string[] = [];+ let released = false;+ // A resource the sequence has no hook to release. If the sequence ever+ // released a resource, it would have to reach one, and it cannot.+ const borrowedResource = {+ release: () => {+ released = true;+ },+ };+ void borrowedResource;++ const steps = baseSteps(order);+ const completion = await runTurn(steps);++ expect(completion).toEqual({ kind: "finalized" });+ // The sequence ran exactly the five ordered steps, then finalized.+ expect(order).toEqual([+ "promptBuild",+ "preTurnUsage",+ "turnStart",+ "eventRelay",+ "turnFinalize:terminal",+ ]);+ // It never released the borrowed resource.+ expect(released).toBe(false);+ });+});diff --git a/packages/adapter-utils/src/acpx-engine/turn-sequence.ts b/packages/adapter-utils/src/acpx-engine/turn-sequence.tsnew file mode 100644index 0000000000..b1abf77539--- /dev/null+++ b/packages/adapter-utils/src/acpx-engine/turn-sequence.ts@@ -0,0 +1,100 @@+// The turn sequence.+//+// `runTurn(steps)` is a plain sequence. It runs five steps in a fixed order:+// promptBuild, preTurnUsage, turnStart, eventRelay, turnFinalize. It never+// rejects: every step error becomes a typed `TurnCompletion` through the+// `turnFinalize` step. The sequence owns the wall-clock timer and the abort+// controller. It borrows the run resources; it finalizes no resource. The+// coordinator (Phase 20) settles the resources after the turn.+//+// The sequence is data, not a graph and not a state machine. The engine supplies+// each step; the sequence owns only the order, the timer, and the abort signal.+// This keeps the sequence free of the engine's private run state.++import type { TurnCompletion } from "./run-contracts.js";++/**+ * A turn the site started. The sequence borrows it to cancel it on a timeout; it+ * releases nothing. The engine's `eventRelay` step reads the events and the+ * terminal result.+ */+export interface StartedTurn {+ cancel(reason: string): Promise<void>;+}++/**+ * The input the sequence hands to the one `turnFinalize` step. A `terminal`+ * input carries the turn's terminal result; an `error` input carries the step+ * error and the phase it failed in. Both carry the wall-clock timeout flag.+ */+export type TurnFinalizeInput<TTerminal> =+ | { readonly kind: "terminal"; readonly terminal: TTerminal; readonly timedOut: boolean }+ | {+ readonly kind: "error";+ readonly error: unknown;+ readonly phase: "prepare_turn" | "turn";+ readonly timedOut: boolean;+ };++/**+ * The five steps the sequence runs, plus the timer inputs. The engine implements+ * each step over its own run state. `turnFinalize` maps a terminal result or a+ * step error to a `TurnCompletion`; it must not reject, so the sequence never+ * rejects.+ */+export interface TurnSteps<TTerminal> {+ /** The wall-clock timeout, in milliseconds, or undefined for no timeout. */+ readonly timeoutMs: number | undefined;+ /** The message the timeout cancel carries. */+ readonly timeoutMessage: string;+ /** Build the prompt and emit the run metadata. A failure here is `prepare_turn`. */+ promptBuild(signal: AbortSignal): Promise<void>;+ /** Snapshot the pre-turn usage, so this run's cost excludes earlier runs. */+ preTurnUsage(): Promise<void>;+ /** Start the turn with the run's six inputs. The sequence adds the signal and the timeout. */+ turnStart(signal: AbortSignal, timeoutMs: number | undefined): StartedTurn;+ /** Relay the turn events and return the terminal result. */+ eventRelay(turn: StartedTurn): Promise<TTerminal>;+ /** Map a terminal result or a step error to a `TurnCompletion`. Must not reject. */+ turnFinalize(input: TurnFinalizeInput<TTerminal>): Promise<TurnCompletion>;+}++/**+ * Run the turn sequence. It returns a `TurnCompletion` on every path and never+ * rejects. A failure before `turnStart` returns is a `prepare_turn` failure; a+ * failure after it is a `turn` failure. Only the reported phase differs.+ */+export async function runTurn<TTerminal>(steps: TurnSteps<TTerminal>): Promise<TurnCompletion> {+ const controller = new AbortController();+ let timeout: ReturnType<typeof setTimeout> | null = null;+ let timedOut = false;+ let started: StartedTurn | null = null;+ // `turnStarted` separates a pre-turn preparation failure from a running-turn+ // failure, so `turnFinalize` reports the right phase.+ let turnStarted = false;+ try {+ // Build the prompt and snapshot the pre-turn usage inside the failure+ // boundary. A failure here is a `prepare_turn` failure.+ await steps.promptBuild(controller.signal);+ await steps.preTurnUsage();+ // The sequence owns the wall-clock timer. On a timeout it marks the run timed+ // out, aborts the shared signal, and cancels the started turn. The cancel+ // no-ops before `turnStart` returns, because `started` is still null.+ if (steps.timeoutMs !== undefined) {+ timeout = setTimeout(() => {+ timedOut = true;+ controller.abort();+ void started?.cancel(steps.timeoutMessage).catch(() => {});+ }, steps.timeoutMs);+ }+ started = steps.turnStart(controller.signal, steps.timeoutMs);+ turnStarted = true;+ const terminal = await steps.eventRelay(started);+ if (timeout) clearTimeout(timeout);+ return await steps.turnFinalize({ kind: "terminal", terminal, timedOut });+ } catch (error) {+ if (timeout) clearTimeout(timeout);+ const phase: "prepare_turn" | "turn" = turnStarted ? "turn" : "prepare_turn";+ return await steps.turnFinalize({ kind: "error", error, phase, timedOut });+ }+}diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.mdindex 329640cdf8..7eb7c40f9a 100644--- a/packages/shared/src/telemetry/README.md+++ b/packages/shared/src/telemetry/README.md@@ -306,6 +306,45 @@ ensure-session sub-times.To read the detailed timing, use the startup spans. The spans need an OTLPendpoint. A run with no endpoint keeps only the three run-log fields above.+## Run Phase Timing Run-Log Event++Paperclip writes one `run.phase.timing` event to the run log for each+run-lifecycle phase. This event is a run-log record, not a first-party telemetry+event. The generated telemetry contract does not cover it, so this section is its+canonical contract. The producer is `emitRunPhaseTiming` in+`packages/adapter-utils/src/acpx-engine/startup-timing.ts`.++The event payload carries only three fields.++| Field | Type | Meaning |+| --- | --- | --- |+| `phase` | string | The run-lifecycle phase name from the closed allowlist below. |+| `durationMs` | number | The wall time of the phase. A negative or a non-finite value clamps to `0`. |+| `outcome` | string | The phase outcome (`ok` or `failed`). |++The `phase` field is one member of a closed, low-cardinality allowlist. The+producer drops any event whose phase name is outside this allowlist, so a+free-form label never reaches the run log. The allowlist has twelve phase names.++| Phase | Meaning |+| --- | --- |+| `place_workspace` | Place the run workspace. |+| `start_transport` | Start the agent transport. |+| `create_runtime` | Create the agent runtime. |+| `ensure_session` | Ensure the agent session exists. |+| `configure_session` | Configure the agent session. |+| `prepare_turn` | Prepare the turn. |+| `turn` | Run the turn. |+| `end_session` | End the agent session. |+| `settle_reuse` | Settle the session for reuse. |+| `stop_transport` | Stop the agent transport. |+| `sync_back` | Sync the workspace back. |+| `release_staging_lease` | Release the staging lease. |++The payload never carries a command, an argument, a path, an environment value,+or a raw identifier. The event rides the `ctx.onEvent` run-event bridge and is+observability-only. It needs no OTLP endpoint.+## Dimension ValuesTelemetry dimension values must be primitives. Use only the value types allowed