@tickernelz/paperclip-pro-adapter-utils 2026.1005.10 → 2026.1006.1

package/dist/acpx-engine/execute.js

@@ -1,4 +1,5 @@
 import { cancellableSandboxStartup } from "./startup-cancellation.js";
+import { withAdapterExecutionPhase } from "../execution-phase.js";
 import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import os from "node:os";
@@ -6,16 +7,19 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createHash, randomUUID } from "node:crypto";
+import { parseFrontmatterMarkdown } from "@tickernelz/paperclip-pro-shared";
 import { fileURLToPath } from "node:url";
 import { adapterExecutionTargetSessionIdentity, describeAdapterExecutionTarget, adapterExecutionTargetDuplexObservabilityRecorder, adapterExecutionTargetEnablesSandboxDuplexBridge, formatAdapterExecutionTimeoutErrorMessage, formatAdapterExecutionTimeoutStartLogLine, prepareAdapterExecutionTargetRuntime, readAdapterExecutionTarget, resolveAdapterExecutionTargetTimeout, resolveReferencedSourceIgnore, runAdapterExecutionTargetShellCommand, startAdapterExecutionTargetPaperclipBridge, startAdapterExecutionTargetProcessSessionBridge, } from "@tickernelz/paperclip-pro-adapter-utils/execution-target";
 import { captureLocalProcess, capturedProcessExited, killCapturedLocalProcess } from "./local-process-control.js";
 import { DUPLEX_CHANNEL_LOST_ERROR_CODE } from "../bridge-transport-contract.js";
+import { classifyToolDefinitionFailure, formatTerminalSessionFailure, sanitizeTerminalSessionFailure, } from "./terminal-session-failure.js";
 import { classifyWorkspaceRestoreFailure, describeWorkspaceRestoreFailure, } from "../workspace-restore-merge.js";
-import { paperclipAgentPromptTemplate, DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE, applyPaperclipWorkspaceEnv, asNumber, asString, buildInvocationEnvForLogs, buildPaperclipEnv, ensureAbsoluteDirectory, ensurePathInEnv, ensurePaperclipSkillSymlink, isForbiddenConfigEnvKey, isPaperclipExternalChatTurn, isPaperclipRuntimeEnvKey, joinPromptSections, materializePaperclipSkillCopy, parseObject, isPaperclipSkillSourceMissing, readPaperclipRuntimeSkillEntries, readPaperclipIssueWorkModeFromContext, renderPaperclipWakePrompt, renderTemplate, resolvePaperclipInstanceRootForAdapter, selectPaperclipTaskMarkdown, resolveLegacyPaperclipDesiredSkillNames, removeMaintainerOnlySkillSymlinks, rewriteWorkspaceCwdEnvVarsForExecution, shapePaperclipWorkspaceEnvForExecution, } from "@tickernelz/paperclip-pro-adapter-utils/server-utils";
+import { paperclipAgentPromptTemplate, DEFAULT_PAPERCLIP_CONVERSATION_PROMPT_TEMPLATE, applyPaperclipWorkspaceEnv, asNumber, asString, buildInvocationEnvForLogs, buildPaperclipEnv, ensureAbsoluteDirectory, ensurePathInEnv, ensurePaperclipSkillSymlink, isForbiddenConfigEnvKey, isPaperclipExternalChatTurn, isPaperclipRuntimeEnvKey, joinPromptSections, materializePaperclipSkillCopy, parseObject, isPaperclipSkillSourceMissing, readPaperclipRuntimeSkillEntries, readPaperclipIssueWorkModeFromContext, renderTemplate, resolvePaperclipInstanceRootForAdapter, hydrateFreshSessionHandoff, selectInitialCommunicationGuidance, selectPaperclipPromptSections, resolveLegacyPaperclipDesiredSkillNames, removeMaintainerOnlySkillSymlinks, rewriteWorkspaceCwdEnvVarsForExecution, shapePaperclipWorkspaceEnvForExecution, } from "@tickernelz/paperclip-pro-adapter-utils/server-utils";
 import { PAPERCLIP_MCP_SERVER_NAME, paperclipAccessGuidance, paperclipAccessMode, paperclipMcpToolsets, } from "@tickernelz/paperclip-pro-adapter-utils/paperclip-mcp";
 import { paperclipMcpHttpTarget } from "@tickernelz/paperclip-pro-adapter-utils/paperclip-mcp-mount";
 import { shellQuote } from "@tickernelz/paperclip-pro-adapter-utils/ssh";
 import { runToolProfile } from "@tickernelz/paperclip-pro-adapter-utils/tool-profile";
+import { createEphemeralSessionEnvironmentStore } from "./ephemeral-session-environment.js";
 import { createAcpRuntime, createAgentRegistry, createRuntimeStore, isAcpRuntimeError, } from "acpx/runtime";
 import { ACPX_DUPLEX_LOSS_CANCEL_DEADLINE_MS, ACPX_HANDSHAKE_TIMEOUT_MS, ACPX_HANDSHAKE_TRANSPORT_POLL_MS, DEFAULT_ACP_ENGINE_AGENT, DEFAULT_ACP_ENGINE_MODE, DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS, DEFAULT_ACP_ENGINE_PERMISSION_MODE, DEFAULT_ACP_ENGINE_TIMEOUT_SEC, DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS, } from "./constants.js";
 import { createRunResourceLedger } from "./run-resource-ledger.js";
@@ -337,6 +341,9 @@ function isCodexCredentialStoreHome(homePath) {
     const segments = resolved.slice(companiesRoot.length + 1).split(path.sep);
     return segments.length >= 2 && segments[1] === "codex-auth-cache";
 }
+function resolveManagedCodexApiKeyHomeDir(companyId, agentId) {
+    return path.join(defaultStateDir(companyId, agentId), "codex-home");
+}
 // Mirrors `resolveManagedGrokHomeDir` in
 // `packages/adapters/grok-local/src/server/grok-home.ts` — this package
 // cannot import that adapter package (it would invert the dependency
@@ -627,11 +634,25 @@ async function prepareClaudeSkillRuntime(input) {
         }
     }
     const selectedNames = materializedNames.sort();
+    const skillDescriptions = await Promise.all(selectedNames.map(async (name) => {
+        const file = path.join(skillsHome, name, "SKILL.md");
+        let description = "";
+        try {
+            const parsed = parseFrontmatterMarkdown(await fs.readFile(file, "utf8"));
+            description = asString(parsed.frontmatter.description, "").replace(/\s+/g, " ").trim().slice(0, 512);
+        }
+        catch {
+            // A readable skill without valid routing metadata remains available.
+            // Do not substitute its body for a missing description.
+        }
+        return `- ${name}${description ? `: ${description}` : ""} (file: ${file})`;
+    }));
     const promptInstructions = selectedNames.length > 0
         ? [
             "Paperclip has materialized selected runtime skills for this ACPX Claude session.",
             `Skill root: ${skillsHome}`,
             `Selected skills: ${selectedNames.join(", ")}`,
+            ...skillDescriptions,
             "When a task calls for one of these skills, read its SKILL.md from that root and follow it.",
         ].join("\n")
         : "";
@@ -725,8 +746,10 @@ async function prepareCodexSkillRuntime(input) {
         : process.env.OPENAI_API_KEY?.trim() || process.env.CODEX_API_KEY?.trim();
     const apiKey = input.env.OPENAI_API_KEY?.trim() || input.env.CODEX_API_KEY?.trim()
         || hostApiKey;
+    // Keep API-key auth separate from the company home used by subscription
+    // agents, so one agent cannot switch another agent's login on its next turn.
     const managedCodexHome = apiKey
-        ? path.join(defaultStateDir(input.companyId, input.agentId), "codex-home")
+        ? resolveManagedCodexApiKeyHomeDir(input.companyId, input.agentId)
         : resolveManagedCodexHomeDir(input.companyId);
     const effectiveCodexHome = configuredCodexHome ??
         await prepareManagedCodexHome({
@@ -945,6 +968,7 @@ function buildSessionParams(input) {
         mode: prepared.mode,
         stateDir: prepared.stateDir,
         configFingerprint: prepared.fingerprint,
+        mcpFingerprint: shortHash(prepared.mcpIdentity),
         ...(prepared.requestedModel ? { model: prepared.requestedModel } : {}),
         ...(prepared.requestedThinkingEffort ? { thinkingEffort: prepared.requestedThinkingEffort } : {}),
         ...(prepared.fastMode ? { fastMode: true } : {}),
@@ -1379,7 +1403,11 @@ async function buildRuntime(input) {
         paperclipClaudeSettings = await writePaperclipClaudeSettings({
             cwd,
             stateDir,
-            agentHome,
+            // A run's writable AGENT_HOME moves, but the existing permission root
+            // must not invalidate its resumable conversation. Run copies are covered
+            // by the company root already granted in these settings; the process env
+            // still receives this run's actual AGENT_HOME.
+            agentHome: asString(workspaceContext.agentHomeForPermissions, agentHome),
             companyId: agent.companyId,
         });
         skillCommandNotes.push(`Wrote Paperclip-managed Claude settings to ${paperclipClaudeSettings.filePath} (defaultMode=${paperclipClaudeSettings.defaultMode}${paperclipClaudeSettings.overrodeDontAsk ? "; overrode user dontAsk" : ""}, +${paperclipClaudeSettings.additionalDirectories.length} read root(s), +${paperclipClaudeSettings.allow.length} allow rule(s)).`);
@@ -1510,7 +1538,9 @@ async function buildRuntime(input) {
                 defaultMode: paperclipClaudeSettings.defaultMode,
             }
             : null,
-        mcpServers: mcpIdentity,
+        // Qualified built-in ACP harnesses reconnect to the supplied MCP servers
+        // on session/load. Keep their conversation identity independent of tools.
+        mcpServers: ["claude", "codex", "grok", "gemini", "kimi"].includes(acpxAgent) ? [] : mcpIdentity,
         ...(toolProfile === "read_only" ? { toolProfile } : {}),
         secretManifestHash: shortHash(secretManifest),
         // Fold the resolved adapter env (all applied user-configured values —
@@ -2204,16 +2234,13 @@ async function buildPrompt(ctx, resumedSession, env, paperclipAccess, paperclipT
     const renderedBootstrapPrompt = !resumedSession && bootstrapPromptTemplate.trim().length > 0
         ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
         : "";
-    const taskContextNote = selectPaperclipTaskMarkdown(context, { resumedSession });
-    const externalChatTurn = isPaperclipExternalChatTurn(context.paperclipWake);
-    const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, {
+    await hydrateFreshSessionHandoff(ctx, { resumedSession });
+    const { taskContextNote, wakePrompt } = selectPaperclipPromptSections(context, {
         resumedSession,
-        conversationMode: context.conversationMode === true,
-        // The task-context markdown is the authoritative brief on this lane; keep
-        // the wake prompt's description copy out so the prompt carries it once.
-        suppressIssueDescription: taskContextNote.length > 0,
+        includeCommunicationGuidance: false,
         paperclipAccess,
     });
+    const externalChatTurn = isPaperclipExternalChatTurn(context.paperclipWake);
     const shouldUseResumeDeltaPrompt = resumedSession && wakePrompt.length > 0;
     const promptInstructionsPrefix = shouldUseResumeDeltaPrompt ? "" : instructionsPrefix;
     const renderedPrompt = shouldUseResumeDeltaPrompt || (externalChatTurn && !hasCustomPromptTemplate)
@@ -2225,6 +2252,7 @@ async function buildPrompt(ctx, resumedSession, env, paperclipAccess, paperclipT
     const prompt = joinPromptSections([
         promptInstructionsPrefix,
         renderedBootstrapPrompt,
+        selectInitialCommunicationGuidance(context, { resumedSession }),
         wakePrompt,
         sessionHandoffNote,
         taskContextNote,
@@ -2717,12 +2745,13 @@ async function closeWarmHandle(input) {
         input.handles.delete(input.key);
     }
     clearWarmHandleTimer(input.entry);
-    await input.entry.runtime.close({
+    const stopped = await input.entry.runtime.close({
         handle: input.entry.handle,
         reason: input.reason,
         discardPersistentState: input.discardPersistentState ?? false,
-    }).catch(() => { });
+    }).then(() => true, () => false);
     flushChildStderr(input.entry.childStderrState);
+    return stopped;
 }
 function warmHandleMatches(entry, runtime, handle) {
     return entry !== undefined && entry.runtime === runtime && entry.handle === handle;
@@ -3130,9 +3159,9 @@ export function createAcpxEngineExecutor(deps = {}) {
                     : teardownErr instanceof Error
                         ? teardownErr.message
                         : String(teardownErr);
-                await ctx
+                await withAdapterExecutionPhase(ctx, "phase_reporting", () => ctx
                     .onLog("stderr", `[paperclip] ACPX teardown step "${step}" failed: ${reason}\n`)
-                    .catch(() => { });
+                    .catch(() => { }));
             };
             // Emit one per-phase timing run-log event. It is not an OpenTelemetry
             // export and it is not a Telemetry event: it carries the phase name
@@ -3145,19 +3174,20 @@ export function createAcpxEngineExecutor(deps = {}) {
             const timedPhase = async (phase, run) => {
                 const start = now();
                 try {
-                    await run();
+                    await withAdapterExecutionPhase(ctx, phase, run);
                 }
                 catch (error) {
-                    await emitPhase(phase, start, "failed");
+                    await withAdapterExecutionPhase(ctx, "phase_reporting", () => emitPhase(phase, start, "failed"));
                     throw error;
                 }
-                await emitPhase(phase, start, "ok");
+                await withAdapterExecutionPhase(ctx, "phase_reporting", () => emitPhase(phase, start, "ok"));
             };
             // 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 = null;
             let terminalFailureClassification = null;
+            let terminalSessionFailure = 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
@@ -3268,7 +3298,14 @@ export function createAcpxEngineExecutor(deps = {}) {
                     // 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;
+                    let cached = canResume ? hostStore.borrow(prepared.sessionKey) : undefined;
+                    if (cached && (ctx.context.refreshTools === true
+                        || asString(previousParams.mcpFingerprint, "") !== shortHash(prepared.mcpIdentity)
+                        // MCP bearer credentials are run-scoped, even for an unchanged catalog.
+                        || prepared.mcpServers.length > 0)) {
+                        await hostStore.discard(prepared.sessionKey);
+                        cached = undefined;
+                    }
                     childStderrState = cached?.childStderrState ?? { logPath: null, pendingLiveLine: "" };
                     processIdentitySink = cached?.processIdentitySink ?? {
                         current: ctx.onSpawn,
@@ -3281,27 +3318,9 @@ export function createAcpxEngineExecutor(deps = {}) {
                     flushChildStderr(childStderrState);
                     childStderrState.logPath = prepared.childStderrLogPath;
                     const persistedRuntimeStore = createRuntimeStore({ stateDir: prepared.stateDir });
-                    const runtimeStore = {
-                        async load(id) {
-                            const record = await persistedRuntimeStore.load(id);
-                            if (!record)
-                                return undefined;
-                            // ACPX resumes from the stored session options rather than the
-                            // options passed to ensureSession. Keep conversation state, but
-                            // launch the provider with this run's credentials and scratch paths.
-                            return {
-                                ...record,
-                                acpx: {
-                                    ...record.acpx,
-                                    session_options: {
-                                        ...record.acpx?.session_options,
-                                        env: { ...prepared.env },
-                                    },
-                                },
-                            };
-                        },
-                        save: (record) => persistedRuntimeStore.save(record),
-                    };
+                    // Resume with this run's launch environment; keep it out of the saved
+                    // conversation record without mutating the live runtime's options.
+                    const runtimeStore = createEphemeralSessionEnvironmentStore(persistedRuntimeStore, prepared.env);
                     const runtimeOptions = {
                         cwd: prepared.cwd,
                         // Host-only spawn cwd for the relay proxy on the remote process-session
@@ -3741,6 +3760,8 @@ export function createAcpxEngineExecutor(deps = {}) {
                 };
                 let eventBreakdown = null;
                 let eventCostUsd = null;
+                let lastRuntimeEventAt = null;
+                let observedRuntimeEvents = 0;
                 // 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-
@@ -3831,14 +3852,13 @@ export function createAcpxEngineExecutor(deps = {}) {
                         timeoutMs: startTimeoutMs,
                         signal,
                         // The callback belongs to this turn, including when a runtime is reused.
-                        // Raw provider text must never enter the result or the run log.
-                        ...(deps.classifyTerminalSessionFailure
-                            ? {
-                                onTerminalSessionFailure: (failure) => {
-                                    terminalFailureClassification = deps.classifyTerminalSessionFailure(failure, new Date(now()));
-                                },
-                            }
-                            : {}),
+                        // Diagnostics are retained even when an adapter has no recovery
+                        // classifier. Redact before bounding so partial secrets cannot leak.
+                        onTerminalSessionFailure: (failure) => {
+                            terminalFailureClassification = classifyToolDefinitionFailure(failure)
+                                ?? deps.classifyTerminalSessionFailure?.(failure, new Date(now())) ?? null;
+                            terminalSessionFailure = sanitizeTerminalSessionFailure(failure, prepared.env, ctx.authToken, parseObject(ctx.config.env));
+                        },
                     });
                     activeTurn = turn;
                     // A latched sandbox duplex-channel loss otherwise has no way to reach
@@ -3895,7 +3915,7 @@ export function createAcpxEngineExecutor(deps = {}) {
                         armStopDeadline();
                     return {
                         cancel: async (reason) => {
-                            await turn.cancel({ reason });
+                            await withAdapterExecutionPhase(ctx, "cancel_turn", () => turn.cancel({ reason }));
                         },
                     };
                 };
@@ -3914,6 +3934,8 @@ export function createAcpxEngineExecutor(deps = {}) {
                     const toolTitles = new Map();
                     const drainEvents = (async () => {
                         for await (const event of turn.events) {
+                            lastRuntimeEventAt = now();
+                            observedRuntimeEvents += 1;
                             // ACPX currently flattens client-side filesystem/terminal receipts
                             // into status text. They cannot establish complete action outcomes.
                             if (event.type === "status" && /^(fs|terminal)\//.test(event.text))
@@ -3972,6 +3994,16 @@ export function createAcpxEngineExecutor(deps = {}) {
                     return await Promise.race([turn.result, lossDeadline.then(() => LOSS_DEADLINE_TERMINAL)]);
                 };
                 const stepTurnFinalize = async (input) => {
+                    // Capture runtime activity before usage reads, error logs, or cleanup
+                    // make an otherwise silent turn look active at its execution deadline.
+                    const lastEventAgeMs = lastRuntimeEventAt === null ? undefined : now() - lastRuntimeEventAt;
+                    const activityDiagnostics = {
+                        acpObservedEventCount: observedRuntimeEvents,
+                        ...(lastEventAgeMs !== undefined && Number.isSafeInteger(lastEventAgeMs) && lastEventAgeMs >= 0
+                            ? { acpLastEventAgeMs: lastEventAgeMs } : {}),
+                        acpPendingToolCount: [...interruptionTools.values()].filter((tool) => tool.status !== "completed" && tool.status !== "failed" && tool.status !== "cancelled").length,
+                        acpToolInventoryComplete: !incompleteToolInventory,
+                    };
                     if (input.kind === "terminal") {
                         const terminal = input.terminal;
                         const timedOut = input.timedOut;
@@ -4055,11 +4087,14 @@ export function createAcpxEngineExecutor(deps = {}) {
                             cancelTurnReason: null,
                             skipRemoteClose: channelLost,
                         };
+                        const failureDiagnostic = !timedOut && !channelLost && terminal.status === "failed"
+                            ? terminalSessionFailure
+                            : null;
                         const errorMessage = timedOut
                             ? formatAdapterExecutionTimeoutErrorMessage(prepared.timeoutResolution)
                             : channelLost
                                 ? channelLostMessage
-                                : resultErrorMessage(terminal);
+                                : formatTerminalSessionFailure(resultErrorMessage(terminal), failureDiagnostic);
                         const terminalStopReason = terminal.status === "failed" ? terminal.error.message : terminal.stopReason;
                         const classifiedFailure = !timedOut && !channelLost && terminal.status === "failed"
                             ? terminalFailureClassification
@@ -4098,6 +4133,8 @@ export function createAcpxEngineExecutor(deps = {}) {
                             costUsd: turnUsage.costUsd,
                             resultJson: {
                                 status: channelLost ? "failed" : terminal.status,
+                                ...activityDiagnostics,
+                                ...(failureDiagnostic ? { terminalSessionFailure: failureDiagnostic } : {}),
                                 ...(classifiedFailure?.errorFamily ? { errorFamily: classifiedFailure.errorFamily } : {}),
                                 ...(classifiedFailure?.retryNotBefore
                                     ? {
@@ -4228,7 +4265,7 @@ export function createAcpxEngineExecutor(deps = {}) {
                         ...referencedProjectStagingFailuresField,
                         model: prepared.requestedModel || null,
                         clearSession: clearSession || timedOut,
-                        resultJson: { phase },
+                        resultJson: { phase, ...activityDiagnostics },
                         summary: message,
                     };
                     // Return a typed failed completion so the coordinator settles for a cause
@@ -4334,7 +4371,7 @@ export function createAcpxEngineExecutor(deps = {}) {
                         : baseSettlement;
                     // Cancel a running turn before the close (the turn-error path).
                     if (settlement.cancelTurnReason && activeTurn) {
-                        await activeTurn.cancel({ reason: settlement.cancelTurnReason }).catch(() => { });
+                        await withAdapterExecutionPhase(ctx, "cancel_turn", () => activeTurn.cancel({ reason: settlement.cancelTurnReason }).catch(() => { }));
                     }
                     const existing = warmHandles.get(prepared.sessionKey);
                     // Re-read the duplex control-channel disposition here, at the
@@ -4371,26 +4408,26 @@ export function createAcpxEngineExecutor(deps = {}) {
                         existing) {
                         // A matching warm entry closes through the warm store, which also
                         // clears its idle timer and flushes its child stderr.
-                        await closeWarmHandle({
+                        runtimeStopConfirmed = await withAdapterExecutionPhase(ctx, "close_session", () => closeWarmHandle({
                             handles: warmHandles,
                             key: prepared.sessionKey,
                             entry: existing,
                             reason: settlement.reason,
                             discardPersistentState: settlement.discardPersistentState,
-                        });
+                        }));
                         return;
                     }
                     const onCloseError = settlement.recordCloseError || ctx.signal?.aborted
                         ? (closeErr) => recordTeardownError("runtime-close", closeErr)
                         : () => { };
-                    await runtime
+                    await withAdapterExecutionPhase(ctx, "close_session", () => runtime
                         .close({
                         handle: settlement.handle,
                         reason: settlement.reason,
                         discardPersistentState: settlement.discardPersistentState,
                     })
                         .then(() => { runtimeStopConfirmed = true; })
-                        .catch(onCloseError);
+                        .catch(onCloseError));
                     if (settlement.dropWarmEntry && warmHandleMatches(existing, runtime, settlement.handle) && existing) {
                         clearWarmHandleTimer(existing);
                         warmHandles.delete(prepared.sessionKey);
@@ -4418,12 +4455,29 @@ export function createAcpxEngineExecutor(deps = {}) {
                 // runs, so the host mints a `traceparent` for the provider spans, and the
                 // per-task restore spans parent to `sandbox.syncBack`.
                 syncBack: () => timedPhase("sync_back", async () => {
-                    await runRuntimeSpan("sandbox.syncBack", async () => {
-                        const restoreOutcome = await syncBackManagedHome(prepared);
-                        if (!restoreOutcome.ok) {
-                            workspaceRestoreFailureField = { workspaceRestoreFailure: restoreOutcome.code };
-                        }
-                    });
+                    // A transport error or terminal narrative cannot authorize collecting
+                    // mutable provider files. Require the owned close or local OS handle.
+                    const stopped = runtimeStopConfirmed || (!prepared.processSessionBridge && capturedProcessExited(processIdentitySink?.localProcess));
+                    try {
+                        if (stopped)
+                            await withAdapterExecutionPhase(ctx, "instruction_collection", () => ctx.onProviderStopped?.());
+                    }
+                    catch {
+                        // Match ACP's fail-soft teardown policy without describing this as
+                        // a workspace restore failure or exposing paths from a raw error.
+                        await recordTeardownError("instruction-collection", new Error("Instruction collection failed after provider stop. No instruction save is claimed."));
+                    }
+                    finally {
+                        await withAdapterExecutionPhase(ctx, "workspace_restore", () => runRuntimeSpan("sandbox.syncBack", async () => {
+                            const restoreOutcome = await syncBackManagedHome(prepared);
+                            if (!restoreOutcome.ok) {
+                                workspaceRestoreFailureField = {
+                                    workspaceRestoreFailure: restoreOutcome.code,
+                                    ...(restoreOutcome.diagnostic ? { workspaceRestoreDiagnostic: restoreOutcome.diagnostic } : {}),
+                                };
+                            }
+                        }));
+                    }
                 }),
                 // 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
@@ -4492,6 +4546,15 @@ export function createAcpxEngineExecutor(deps = {}) {
                                 } },
                         };
                     }
+                    // Preserve the policy resolved for this execution target. The server
+                    // cannot reconstruct sandbox defaults from the stored agent config.
+                    capturedResult = {
+                        ...capturedResult,
+                        resultJson: {
+                            ...capturedResult.resultJson,
+                            adapterExecutionTimeout: { ...prepared.timeoutResolution },
+                        },
+                    };
                     // The sync-back settlement step runs before this reproduces the result
                     // (settlement precedes reproduction), so a failed workspace restore is
                     // already recorded by the time we get here. Merge it into `resultJson`