@stigmer/runner 3.14.1 → 3.15.0

package/dist/harness/turn-context.js

@@ -0,0 +1,739 @@
+/**
+ * The turn context — everything the runtime resolves for one agent turn
+ * before any harness runs, as small named phases producing one typed record.
+ *
+ * A turn begins with a dozen reads and provisions that have nothing to do
+ * with the engine that will run it: the execution and its session, the
+ * agent blueprint, the environment, the workspace and its lock, what the
+ * previous turn left waiting for approval, the MCP servers and their
+ * approval policies, the attachments, the standing context. Until S2 M2
+ * that sequence lived inline in the Cursor orchestrator
+ * (`activities/execute-cursor/index.ts` `executeCursorInner`, phases 1 to
+ * 9c); the native orchestrator carried a second copy in its `performSetup`.
+ * This module is the one copy. Each phase is a function that reads its
+ * inputs, reports its progress label, heartbeats once on entry, and returns
+ * a typed slice of the contract's `TurnInput`; {@link resolveTurnContext}
+ * sequences them, and the adapter runs its own harness-specific steps after
+ * the whole record exists.
+ *
+ * Shape, chosen against `execute-deep-agent/setup.ts`: a typed record built
+ * from small functions (the `SetupResult` mold), never one 775-line
+ * `performSetup`. The record is the adapter contract's `TurnInput`
+ * (`types.ts`): every phase returns a named slice of it, and
+ * {@link resolveTurnContext} composes the whole. There is no wider
+ * "runtime-private" record beside it — the lock release and the write-back
+ * coordinator a phase produces are the caller's `TurnFrame` resources, set
+ * the instant they exist so a `finally` sees them on every path (M2 had a
+ * `TurnContext extends TurnInput` for them; once the groups lifted, nothing
+ * read the extension after composition, so M3 deleted it).
+ *
+ * Three rules every phase obeys:
+ *
+ *  - It never persists and never returns a slim status. A phase that can end
+ *    the turn (the lock, the reinvocation reconcile) returns a
+ *    {@link TurnSettlement} naming WHAT was decided; the caller writes the
+ *    status, persists once and returns. The lock golden pins that persist as
+ *    the turn's one and only, which is why the rule is structural.
+ *  - It imports nothing from `src/activities/` (pinned by
+ *    `__tests__/import-direction.test.ts`). A fact only the harness knows
+ *    (its file-review identity, its vision profile) arrives through
+ *    `HarnessCapabilities`.
+ *  - Its heartbeat pulse and its cold-start timing marks are its own: the
+ *    step name it enters under is the mark name it emits, one vocabulary for
+ *    "where in setup are we" in Temporal heartbeat details and the
+ *    `execution_setup` log (Q-S2-10).
+ *
+ * What is deliberately NOT here, and where it is instead:
+ *
+ *  - Cursor's catalog validation of the requested model (`resolveModelId`),
+ *    the pricing preload and the MCP env pre-flight warning stay in the
+ *    Cursor adapter for S2: each reads a module in the adapter column of the
+ *    entry's disposition table, and the runtime carries the REQUESTED model
+ *    name so every harness validates against its own catalog (S2 M2 gate,
+ *    Q-M2-1). The skill mount was in that list until M3b found it reads the
+ *    control plane, which only the runtime holds; it is {@link mountSkills}.
+ *  - The approval grants, the HITL gate, the capture baseline pin and the
+ *    Cursor agent itself (phases 5c, 7, 8a, 9) are the adapter's.
+ *  - The memory selection is a memoized thunk, not a value: whether a prompt
+ *    carries standing context depends on how the ENGINE resolved (a resumed
+ *    agent already holds it), which the runtime learns only after the
+ *    adapter runs. The runtime prepares the selection once; the adapter
+ *    pulls it when its prompt needs it.
+ *
+ * Every `index.ts` line reference below was read from `2c06bc7ea` on
+ * 2026-09-11, before the orchestrator moved onto this module.
+ */
+import { CancelledFailure } from "@temporalio/activity";
+import { clone } from "@bufbuild/protobuf";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ApprovalAction, FileChangeSetStatus, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { resolveBlueprint } from "../shared/blueprint-resolver.js";
+import { resolveExecutionEnv } from "../shared/env-resolver.js";
+import { provisionSessionWorkspace } from "../shared/workspace/session-provision.js";
+import { WriteBackCoordinator } from "../shared/workspace/writeback-coordinator.js";
+import { statusProtoWriter } from "../shared/execution-status-writer.js";
+import { isGitWorkTree } from "../shared/filereview/git-substrate.js";
+import { applyCaptureDecisions, deriveCaptureMode } from "../shared/filereview/capture.js";
+import { casBlobReader } from "../shared/filereview/cas-substrate.js";
+import { acquireWorkspaceLock, WorkspaceLockCancelledError, WorkspaceLockTimeoutError, } from "../shared/workspace/workspace-lock.js";
+import { LocalWorkspaceBackend } from "../shared/workspace/local-backend.js";
+import { resolveMcpServers } from "../shared/mcp-resolver.js";
+import { resolveMcpTransportPosture } from "../shared/mcp-transport-guard.js";
+import { injectCallerIdentityEnv, resolveCallerIdentity } from "../shared/caller-identity.js";
+import { backfillMcpServersIfNeeded } from "../shared/connect-backfill.js";
+import { discoverChannelMessaging, synthesizeChannelAttachment } from "../shared/channel-attachment.js";
+import { readChannelConversationId, synthesizeConversationAttachment } from "../shared/conversation-attachment.js";
+import { synthesizeMemoryAttachment } from "../shared/memory-attachment.js";
+import { injectSynthesizedAttachment } from "../shared/synthesized-attachment.js";
+import { deriveActiveLeases, mergeApprovalPolicies } from "../shared/approval-policy.js";
+import { resolveAttachments } from "../shared/attachment-resolver.js";
+import { resolveSkills } from "../shared/skill-resolver.js";
+import { VisionBudget } from "../shared/attachment-vision.js";
+import { getModelVisionCapability } from "../shared/model-registry.js";
+import { applyApprovedWholeFileWrites } from "../shared/exact-apply.js";
+import { resolveEffectiveServiceTier } from "../shared/service-tier.js";
+import { resolveEffectiveThinkingMode } from "../shared/thinking-mode.js";
+import { readContextBridge } from "../shared/context-bridge.js";
+import { readSenderIdentity } from "../shared/sender-identity.js";
+import { readSessionContext } from "../shared/session-context.js";
+import { readDeclaredPreferences } from "../shared/declared-preferences.js";
+import { readConversationCatchup } from "../shared/conversation-catchup.js";
+import { selectRecalledFacts } from "../shared/memory-retrieval.js";
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for their tests and for the adapter kit)
+// ---------------------------------------------------------------------------
+/**
+ * Whether the engine already holds state for this execution, so this
+ * invocation resumes rather than begins. One function keyed on how the
+ * harness mints its state id (Q-S2-8):
+ *
+ *  - `engine-minted` (Cursor: the agent id): the runtime knows nothing until
+ *    the adapter binds an id, so a non-empty `threadId` IS the evidence.
+ *    Correct today because a pure-reconcile turn does not advance `turnSeq`
+ *    and the legacy positional wire shape yields 0, so `turnSeq` cannot be
+ *    the signal (`index.ts` L402-407).
+ *  - `deterministic` (native: the runtime-minted thread id): the id exists
+ *    on the FIRST turn too, so the evidence is the persisted transcript
+ *    (pending approvals, DECIDED sets). That arm lands in S3 with the native
+ *    adapter; until then this function refuses rather than guess.
+ */
+export function isReinvocation(stateIdSource, input) {
+    switch (stateIdSource) {
+        case "engine-minted":
+            return input.threadId !== "";
+        case "deterministic":
+            throw new Error("isReinvocation: the deterministic arm lands with the native adapter (S3); no S2 harness mints its state id deterministically");
+        default: {
+            const exhaustive = stateIdSource;
+            throw new Error(`isReinvocation: unknown state id source ${String(exhaustive)}`);
+        }
+    }
+}
+/**
+ * The runtime's one reader of approval decisions: every top-level tool-call
+ * row still WAITING_APPROVAL whose `approvalAction` the server has set,
+ * keyed by tool-call id. Derived from the status on every invocation, never
+ * stored, so it cannot drift from the rows. The same rows, in the same
+ * order, that the Cursor adapter's `reconstructAdjudicatedApprovals` reads
+ * for its own facts (the pending-approval protos and content digests); a
+ * test pins the two readers' agreement.
+ */
+export function approvalDecisionsOf(status) {
+    const decisions = new Map();
+    for (const message of status.messages) {
+        for (const row of message.toolCalls) {
+            if (row.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL)
+                continue;
+            if (row.approvalAction === ApprovalAction.UNSPECIFIED)
+                continue;
+            decisions.set(row.id, row.approvalAction);
+        }
+    }
+    return decisions;
+}
+/**
+ * How a reinvocation proceeds, decided once from the facts (`index.ts`
+ * L547-618): a REJECT of an irreversible action fails the turn; any other
+ * adjudicated decision runs the agent (the approved shell/MCP proceeds and
+ * may produce further edits); a resume that reconciled file review and
+ * decided nothing else is complete, because keeping or discarding a file
+ * never re-prompts the agent (Cursor-like). `undefined` means "run the
+ * agent".
+ */
+export function decideReinvocation(facts) {
+    if (facts.approvalDecisions.size > 0) {
+        const hasReject = [...facts.approvalDecisions.values()].some((a) => a === ApprovalAction.REJECT);
+        return hasReject ? { kind: "rejected-by-user" } : undefined;
+    }
+    if (facts.reconciledFileReview) {
+        return {
+            kind: "file-review-resolved",
+            failed: facts.fileReviewFailed,
+            failureDetail: facts.fileReviewFailureDetail,
+            discardedPaths: facts.discardedPaths,
+        };
+    }
+    return undefined;
+}
+/**
+ * Seed an in-progress status from the persisted execution on a durable
+ * resume (HITL approval, pause/resume, transient recovery) so the upcoming
+ * turn APPENDS onto prior history instead of replacing it.
+ *
+ * Why it is required: a resumed engine re-issues the previously gated tool
+ * calls with brand-new call ids. Without seeding, the harness's accumulator
+ * would rebuild the transcript from empty and emit a status that drops the
+ * already-committed tool-call ids. The backend's append-only-at-identity
+ * guard rejects any non-terminal update that drops a committed tool-call id,
+ * so the resumed progress would never persist: the run stalls in
+ * WAITING_FOR_APPROVAL with no pending approvals and the workflow watchdog
+ * fails it. Seeding makes the resume status a strict superset; the re-runs
+ * are then reconciled in place onto these seeded calls by canonical identity
+ * inside the accumulator.
+ *
+ * The persisted protos are cloned so the input execution stays immutable.
+ * Messages are pushed into `status.messages` (which the accumulator wraps by
+ * reference) BEFORE the accumulator is constructed. Sub-agent executions are
+ * NOT seeded here: the Cursor accumulator owns `status.subAgentExecutions`
+ * and overwrites it on every flush, so the adapter clones them itself from
+ * `input.execution.status` under the same "left a transcript" test.
+ *
+ * Moved from `execute-cursor/index.ts` `seedCursorTranscriptFromExecution`
+ * (L2468-2478); the native twin is `execute-deep-agent/index.ts`
+ * `seedStatusFromExecution` (S3 retires it).
+ */
+export function seedTranscriptFromExecution(status, execution) {
+    const persisted = execution.status;
+    if (!persisted || persisted.messages.length === 0)
+        return;
+    for (const message of persisted.messages) {
+        status.messages.push(clone(AgentMessageSchema, message));
+    }
+}
+// ---------------------------------------------------------------------------
+// The phases, in the order the turn runs them
+// ---------------------------------------------------------------------------
+/** Phase 1 (`index.ts` L325-330): hydrate the execution from the control plane. */
+export async function fetchExecution(deps) {
+    deps.enterPhase("fetch_execution");
+    await deps.reportProgress("Fetching execution");
+    const execution = await deps.client.getExecution(deps.input.executionId);
+    const spec = execution.spec;
+    deps.timing.mark("fetch_execution");
+    return { execution, spec, sessionId: spec.sessionId };
+}
+/** Phase 2 (`index.ts` L332-336): load the session and resolve the full agent blueprint through it. */
+export async function resolveAgentBlueprint(deps, sessionId) {
+    deps.enterPhase("resolve_blueprint");
+    await deps.reportProgress("Resolving agent blueprint");
+    const session = await deps.client.getSession(sessionId);
+    const blueprint = await resolveBlueprint(deps.client, session);
+    deps.timing.mark("resolve_blueprint");
+    return { session, blueprint };
+}
+/** Phase 2b (`index.ts` L338-343): the execution environment (MCP server credentials). */
+export async function resolveEnvironment(deps) {
+    deps.enterPhase("resolve_environment");
+    await deps.reportProgress("Resolving environment");
+    const { envVars, secretKeys } = await resolveExecutionEnv(deps.client, deps.input.executionId);
+    deps.timing.mark("resolve_environment");
+    return { envVars, secretKeys };
+}
+/**
+ * Phase 2c, first half (`index.ts` L351-408): provision the workspace (clone
+ * git repos / mount local paths) so the LOCAL agent operates on the actual
+ * repo, wire the git write-back coordinator, and decide the capture posture.
+ *
+ * Git provisioning is idempotent across multi-turn and HITL reinvocations.
+ * The write-back coordinator pushes the session's APPROVED tree to the
+ * session branch (stigmer/<session-id>) and keeps one PR open; finalize runs
+ * at exactly two seams (the pure file-review resume and terminal
+ * completion), never mid-turn, because the working tree is speculative until
+ * reviewed. Non-eligible workspaces (local paths, no credentials) make it a
+ * no-op coordinator, here `null`.
+ *
+ * Apply-then-review is the universal file-review model (Slice 2c): a git work
+ * tree captures per-file from the git diff at the turn boundary; a NON-git
+ * workspace captures every write via the path-scoped CAS substrate, which
+ * needs artifact storage to persist blobs, and falls back to the classic
+ * deny-gate without it. `gitWorkspace` selects the substrate; `captureMode`
+ * says whether file edits flow at all.
+ *
+ * The change-set id is minted from the workflow-threaded turn index so it is
+ * stable across a Temporal retry (idempotent ledger authoring) and unique per
+ * turn; a "wasted" id on a pure-reconcile resume (which never authors a
+ * baseline) is harmless.
+ */
+export async function provisionWorkspace(deps, args) {
+    deps.enterPhase("provision_workspace");
+    await deps.reportProgress("Provisioning workspace");
+    const provision = await provisionSessionWorkspace(deps.config, args.session, args.envVars, args.sessionId);
+    deps.timing.mark("provision_workspace");
+    const writeback = provision.provisionResults.length > 0
+        ? new WriteBackCoordinator({
+            statusWriter: statusProtoWriter(deps.status),
+            executionId: deps.input.executionId,
+            sessionId: args.sessionId,
+            githubToken: args.envVars.GITHUB_TOKEN ?? "",
+            provisionResults: provision.provisionResults,
+            workspaceEntries: args.session.spec?.workspaceEntries ?? [],
+            workspaceBackend: provision.workspaceBackend,
+        })
+        : null;
+    const primaryDir = provision.workspaceDirs[0];
+    const gitWorkspace = primaryDir ? await isGitWorkTree(primaryDir) : false;
+    const captureMode = deriveCaptureMode(primaryDir, gitWorkspace, !!deps.artifactStorage);
+    const changeSetId = `${deps.input.executionId}:${deps.input.turnSeq}`;
+    return {
+        workspace: { dirs: provision.workspaceDirs, primaryDir, gitWorkspace, captureMode, changeSetId, provision },
+        writeback,
+    };
+}
+/**
+ * Phase 2c, second half (`index.ts` L410-449): serialize this turn against
+ * every other execution sharing the primary working tree. Sessions declaring
+ * the same localPath (or the shared runner root) resolve to ONE directory,
+ * and an unserialized concurrent write lands inside this turn's
+ * baseline→candidate window, misattributing another session's file to this
+ * turn's review. Acquired before ANY tree mutation (decision reconcile, gate
+ * install, agent writes, capture); while another turn holds the lock this
+ * surfaces a visible waiting state and heartbeats; a cancel aborts the wait
+ * at once.
+ *
+ * Its own phase so the release handle reaches the caller the instant the
+ * lock exists: nothing runs between acquisition and hand-over, so nothing
+ * can throw and leave a held lock the caller's `finally` never sees.
+ */
+export async function acquireWorkspaceTurnLock(deps, primaryDir) {
+    deps.enterPhase("acquire_workspace_lock");
+    let release;
+    if (primaryDir) {
+        try {
+            release = await acquireWorkspaceLock(primaryDir, {
+                onWaiting: () => deps.reportProgress("Waiting for workspace — in use by another session"),
+                heartbeat: deps.heartbeat,
+                signal: deps.signal,
+                timeoutMs: deps.config.workspaceLockTimeoutMs,
+            });
+        }
+        catch (lockErr) {
+            if (lockErr instanceof WorkspaceLockCancelledError) {
+                throw new CancelledFailure("Activity cancelled while waiting for the workspace lock");
+            }
+            if (lockErr instanceof WorkspaceLockTimeoutError) {
+                return { kind: "settled", settlement: { kind: "workspace-lock-timeout", error: lockErr } };
+            }
+            throw lockErr;
+        }
+    }
+    deps.timing.mark("acquire_workspace_lock");
+    return { kind: "acquired", release };
+}
+/**
+ * `index.ts` L451-461: set OTel baggage so downstream calls carry execution
+ * context. Best-effort; tracing not initialized is a silent skip. Runs after
+ * the lock, as it always has.
+ */
+export async function bindTelemetryBaggage(deps, args) {
+    try {
+        const { setBaggage, BAGGAGE_EXECUTION_ID, BAGGAGE_SESSION_ID, BAGGAGE_ORG_ID } = await import("../otel.js");
+        await setBaggage({
+            [BAGGAGE_EXECUTION_ID]: deps.input.executionId,
+            [BAGGAGE_SESSION_ID]: args.sessionId,
+            [BAGGAGE_ORG_ID]: args.session.metadata?.org ?? "",
+        });
+    }
+    catch {
+        // Tracing not initialized — silently skip.
+    }
+}
+/**
+ * Phase 3 (`index.ts` L475-619): what the previous invocation left, and
+ * whether this one runs the agent at all.
+ *
+ * On a reinvocation, first seed the in-progress status from the persisted
+ * execution ({@link seedTranscriptFromExecution}), BEFORE the harness's
+ * accumulator wraps `status.messages`. Then the file-review reconcile (the
+ * dual-source half): every change set the server projected as DECIDED is
+ * reconciled from the ledger decisions and the pinned git refs (approved
+ * kept at their "after" bytes, rejected snapped back to baseline, all
+ * uncommitted, hash-verified) through the shared reconcile under the
+ * harness's {@link FileReviewIdentity}. Independent of tool approvals: a
+ * single turn can carry BOTH a DECIDED file change set AND an approved
+ * shell/MCP action. Tool approvals (shell / MCP / gitignored writes) still
+ * resolve from the message transcript, the deny-gate path, read here as
+ * {@link approvalDecisionsOf} after the reconcile, at the same point the
+ * orchestrator always read them.
+ *
+ * The outcome is {@link decideReinvocation}'s: a settlement the caller
+ * writes and persists, or the facts the turn proceeds with.
+ */
+export async function reconcileReinvocation(deps, args) {
+    deps.enterPhase("reconcile_reinvocation");
+    const reinvoked = isReinvocation(args.stateIdSource, deps.input);
+    let reconciledFileReview = false;
+    let fileReviewFailed = false;
+    let fileReviewFailureDetail = "";
+    const discardedPaths = [];
+    if (reinvoked) {
+        const existingStatus = args.execution.status;
+        seedTranscriptFromExecution(deps.status, args.execution);
+        if (args.workspace.captureMode && args.workspace.primaryDir) {
+            const decidedSets = (existingStatus?.fileChangeSets ?? []).filter((cs) => cs.status === FileChangeSetStatus.DECIDED);
+            for (const changeSet of decidedSets) {
+                const capResult = await applyCaptureDecisions({
+                    status: deps.status,
+                    gitRoot: args.workspace.primaryDir,
+                    executionId: deps.input.executionId,
+                    changeSet,
+                    harnessId: args.fileReview.harnessId,
+                    excludePaths: args.fileReview.excludePaths,
+                    // Thread the CAS store so CAS-captured files in the change set
+                    // reconcile from the durable manifest (approved after-blobs written,
+                    // rejected snapped back). In a non-git workspace this is the ONLY
+                    // reconcile; in a git tree it composes with the git-ref reconcile.
+                    storage: deps.artifactStorage,
+                    readBlob: deps.artifactStorage ? casBlobReader(deps.artifactStorage) : undefined,
+                    gitWorkspace: args.workspace.gitWorkspace,
+                });
+                if (!capResult.isCaptureTurn)
+                    continue;
+                reconciledFileReview = true;
+                if (capResult.failed) {
+                    fileReviewFailed = true;
+                    fileReviewFailureDetail = capResult.failureDetail ?? "file review reconcile failed";
+                }
+                if (capResult.hadReject)
+                    discardedPaths.push(...capResult.rejectedPaths);
+            }
+        }
+    }
+    const approvalDecisions = approvalDecisionsOf(deps.status);
+    const settlement = decideReinvocation({
+        approvalDecisions,
+        reconciledFileReview,
+        fileReviewFailed,
+        fileReviewFailureDetail,
+        discardedPaths,
+    });
+    if (settlement)
+        return { kind: "settled", settlement };
+    return { kind: "ready", reinvocation: { isReinvocation: reinvoked, approvalDecisions } };
+}
+/**
+ * Phases 4 to 4b (`index.ts` L620-770): the tool surface.
+ *
+ * The MCP-bound env map (and ONLY it, never the agent process env) carries
+ * the reserved caller-identity keys, so a server that declares them in
+ * spec.env can template the platform-verified caller into its headers;
+ * filterEnvToDeclaredKeys keeps every other server blind. The resolved list
+ * then mutates through the Connect backfill and three synthesized
+ * attachments, deliberately AFTER resolve + backfill so the backfill's
+ * destructiveHint tightener can never force-gate an attachment's tools:
+ *
+ *  - channel messaging (DD-006 D7/D8): the discovery read IS the attachment
+ *    decision, and every failure mode degrades to honest absence;
+ *  - conversation participation (channel-conversations DD-008 D-c): the
+ *    channel-id session label IS the decision, a free local read;
+ *  - memory capture (DD-005 D1): the recall snapshot's enabled bit IS the
+ *    decision, server-stamped at execution create.
+ *
+ * Their credential story (DD-006 D4): the exchanged scoped runner token
+ * authenticates the discovery reads per call; the exchange is opportunistic
+ * (every consumer degrades to an empty answer by contract, and the server
+ * refuses the ambient fallback safely), so a failed exchange must not kill
+ * the run, unlike the env read, where secrets are load-bearing.
+ *
+ * Approval policies merge last, from all layers, with two bypasses shared
+ * with the native harness (`shared/approval-policy.ts` `ActiveLeases`): the
+ * pre-armed spec.auto_approve_all is the one whole-run global bypass; an
+ * interactive APPROVE_ALL grants a run-lifetime lease scoped to that
+ * action's class. Layer-3 overrides ride each resolved server from its
+ * merged usage (issue #349). The harness projects its SDK config from
+ * `servers` after this returns, exactly once, so every mutation is visible
+ * by construction.
+ */
+export async function resolveMcpServersAndPolicies(deps, args) {
+    const { client, config } = deps;
+    const { executionId } = deps.input;
+    const { execution, session, sessionId, blueprint, environment } = args;
+    deps.enterPhase("resolve_mcp_servers");
+    await deps.reportProgress("Resolving MCP servers");
+    const transportPosture = resolveMcpTransportPosture(config.mode);
+    const mcpEnvVars = injectCallerIdentityEnv(environment.envVars, resolveCallerIdentity(blueprint.sessionSpec.metadata, session.status?.audit?.specAudit?.createdBy), sessionId);
+    let servers = (await resolveMcpServers(client, blueprint.mergedMcpServerUsages, mcpEnvVars, transportPosture)).resolvedServers;
+    deps.timing.mark("resolve_mcp_servers");
+    // Phase 4a: Connect backfill for undiscovered MCP servers.
+    const sessionOrg = session.metadata?.org ?? "";
+    servers = await backfillMcpServersIfNeeded(client, servers, blueprint.mergedMcpServerUsages, mcpEnvVars, sessionOrg, transportPosture, deps.heartbeat, environment.secretKeys);
+    deps.timing.mark("backfill_mcp");
+    let exchangedRunnerToken;
+    try {
+        exchangedRunnerToken =
+            await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    }
+    catch (err) {
+        console.warn("[turn-context] Scoped-token exchange failed for attachment/discovery " +
+            `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`);
+    }
+    const attachmentCredential = exchangedRunnerToken
+        ?? config.stigmerTokenRef?.current
+        ?? config.stigmerToken;
+    const attachmentEndpoints = {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: attachmentCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+    };
+    // Phase 4a2: the channel messaging attachment.
+    const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
+    if (channelMessaging.length > 0) {
+        const attachment = synthesizeChannelAttachment(channelMessaging, attachmentEndpoints);
+        if (attachment) {
+            servers = injectSynthesizedAttachment(servers, attachment, "channel messaging");
+        }
+    }
+    // Phase 4a4: the conversation participation attachment. HTTP-only:
+    // synthesize answers undefined with no bridge endpoint by design.
+    const conversationAttachment = synthesizeConversationAttachment(readChannelConversationId(session.metadata?.labels), attachmentEndpoints);
+    if (conversationAttachment) {
+        servers = injectSynthesizedAttachment(servers, conversationAttachment, "conversation participation");
+    }
+    // Phase 4a5: the memory capture attachment. The capture context is
+    // attribution the server verifies or trusts per edition; the subject is
+    // never threaded, it derives from the credential.
+    const memoryAttachment = synthesizeMemoryAttachment(execution.spec?.recalledMemories, {
+        org: session.metadata?.org ?? "",
+        agentId: blueprint.agent.metadata?.id ?? "",
+        sessionId,
+        agentExecutionId: executionId,
+    }, attachmentEndpoints);
+    if (memoryAttachment) {
+        servers = injectSynthesizedAttachment(servers, memoryAttachment, "memory capture");
+    }
+    // Phase 4b: merge approval policies from all layers.
+    const leases = deriveActiveLeases(execution);
+    const policies = mergeApprovalPolicies(servers, leases);
+    return { servers, channelMessaging, leases, policies };
+}
+/**
+ * Phase 5 (`index.ts` L493-501, the orchestrator's position between the
+ * tool surface and the attachments): mount the merged skills under the
+ * session's platform dir, reachable from the workspace through its
+ * `.stigmer` link, and return what a prompt renders (`shared/skill-
+ * resolver.ts`). Reads the control plane, which is why it is the runtime's
+ * and not a harness's; each harness places the returned metadata in its own
+ * prompt shape. The `.stigmer` link this and the attachment phase create is
+ * removed in the runtime's finally, after the harness's own teardown.
+ */
+export async function mountSkills(deps, args) {
+    deps.enterPhase("resolve_skills");
+    await deps.reportProgress("Resolving skills");
+    const skills = await resolveSkills(deps.client, args.blueprint.mergedSkillRefs, {
+        sessionId: args.sessionId,
+        primaryWorkspaceDir: args.primaryDir,
+    });
+    deps.timing.mark("resolve_skills");
+    return skills;
+}
+/**
+ * Phase 5b (`index.ts` L803-838): resolve the turn's attachments, fail-hard
+ * (they are explicit user inputs; see `shared/attachment-resolver.ts`).
+ * Downloads by storage key through the same artifact storage resolved for
+ * status offload. The vision budget rides along so image attachments are
+ * selected for inline delivery while their bytes are already in hand
+ * (`shared/attachment-vision.ts` owns all policy); it carries the requested
+ * model's registry vision capability, looked up from the raw
+ * executionConfig name, because full model validation isn't needed for
+ * this and ""/"default" (the Auto pool) resolves to unknown, which the
+ * policy treats as sighted. The vision profile is the harness's (each
+ * engine accepts different image shapes), so it arrives as an argument.
+ */
+export async function resolveTurnAttachments(deps, args) {
+    deps.enterPhase("resolve_attachments");
+    const visionBudget = new VisionBudget(args.visionProfile, {
+        modelVision: await getModelVisionCapability(args.spec.executionConfig?.modelName ?? ""),
+    });
+    const results = await resolveAttachments(args.spec.attachments, {
+        sessionId: args.sessionId,
+        primaryWorkspaceDir: args.primaryDir,
+        mode: deps.config.mode,
+        storage: deps.artifactStorage,
+        visionBudget,
+    });
+    // Vision facts, derived once from the single resolution result: the
+    // images the model will see inline (in attachment order) and the ones
+    // that degraded to path-only, disclosed in the prompt.
+    const visionImages = results.flatMap((a) => (a.vision ? [a.vision] : []));
+    const visionNotViewable = results.flatMap((a) => a.visionDegraded ? [{ path: a.relativePath, reason: a.visionDegraded }] : []);
+    if (visionImages.length > 0 || visionNotViewable.length > 0) {
+        console.log(`[attachment-vision] execution=${deps.input.executionId} inline=${visionImages.length} ` +
+            `(${visionImages.reduce((n, v) => n + v.byteSize, 0)} bytes) ` +
+            `degraded=${JSON.stringify(visionNotViewable.map((d) => `${d.path}:${d.reason}`))}`);
+    }
+    deps.timing.mark("resolve_attachments");
+    return { results, visionImages, visionNotViewable };
+}
+/**
+ * Phase 5b3 (`index.ts` L849-867): exact-apply approved whole-file writes
+ * (HITL "what you approve is what gets applied"). A deny-only harness
+ * reinvokes the model, which regenerates content, so a resource grant alone
+ * cannot guarantee the bytes that land match the bytes the user approved.
+ * The runner therefore writes the EXACT approved whole-file content itself
+ * and marks those tool calls COMPLETED; the harness then issues NO grant for
+ * them, so any FURTHER change the model makes to those files is re-gated.
+ * Hunk edits / shell / MCP stay on the grant + reinvocation path, and every
+ * uncertain case degrades to that path, so this can never corrupt a file
+ * (see `shared/exact-apply.ts`).
+ *
+ * Scoped OUT of capture mode, which does not reinvoke the model for file
+ * edits: it applies the exact captured bytes itself in the reconcile.
+ *
+ * The caller persists when the returned set is non-empty (the applied state
+ * must be durable before the continuation runs, and the UI reflects it at
+ * once); this phase, like every phase, never persists.
+ */
+export async function applyApprovedWrites(deps, args) {
+    const { workspace, reinvocation } = args;
+    if (workspace.captureMode || !reinvocation.isReinvocation || reinvocation.approvalDecisions.size === 0) {
+        return new Set();
+    }
+    deps.enterPhase("apply_approved_writes");
+    return applyApprovedWholeFileWrites({
+        messages: deps.status.messages,
+        workspaceBackend: new LocalWorkspaceBackend(workspace.primaryDir),
+        workspaceDirs: workspace.dirs,
+        executionId: deps.input.executionId,
+    });
+}
+/**
+ * Phase 6, the harness-agnostic half (`index.ts` L998, L1005-1006): the
+ * requested model name as the execution states it, and the effective service
+ * tier and thinking mode. UNSPECIFIED → STANDARD (#357) and UNSPECIFIED →
+ * DISABLED (#772) resolve here and nowhere else; every upstream layer
+ * preserves the caller's raw enum values. Validating the NAME against a
+ * catalog is the harness's (Cursor's `resolveModelId`), so it is not here.
+ */
+export function resolveModelPreferences(spec) {
+    return {
+        requested: spec.executionConfig?.modelName || "default",
+        serviceTier: resolveEffectiveServiceTier(spec.executionConfig?.serviceTier),
+        thinkingMode: resolveEffectiveThinkingMode(spec.executionConfig?.thinkingMode),
+    };
+}
+/** Phase 9b (`index.ts` L1183-1184): the structured-output schema the execution asks for, if any. */
+export function structuredOutputSchemaOf(spec) {
+    return spec.executionConfig?.structuredOutputSchema;
+}
+/**
+ * Phase 9c (`index.ts` L1186-1216, and the metadata reads at L1240-1245):
+ * the standing context, read once, and the memory selection prepared once.
+ *
+ * Selection runs against the frozen first message's semantics: above the
+ * activation threshold it picks top-k for spec.message, otherwise (and on
+ * any failure) it injects the full candidate set. The outcome report is
+ * stamped on the turn's status ONCE, picked up by the next persist; a
+ * re-invocation replays the report already persisted on the execution
+ * rather than re-selecting (the written-once rule). Memoized because a
+ * resumed-agent primary send carries no memories, but a mid-send
+ * poisoned-handle failure rebuilds on a FRESH agent whose recovery prompt
+ * does, so every memory-carrying build site awaits this lazily.
+ */
+export function resolveStandingContext(deps, args) {
+    const { execution, spec, blueprint } = args;
+    let memorySelection;
+    const selectRecalledMemories = () => {
+        memorySelection ??= selectRecalledFacts(spec.recalledMemories, spec.message, {
+            proxyEndpoint: deps.config.proxyEndpoint,
+            stigmerToken: deps.config.stigmerToken,
+            executionId: deps.input.executionId,
+            priorReport: execution.status?.recalledMemoriesReport,
+        }).then((selection) => {
+            if (selection.report !== undefined) {
+                deps.status.recalledMemoriesReport = selection.report;
+            }
+            return selection.content;
+        });
+        return memorySelection;
+    };
+    return {
+        contextBridge: readContextBridge(blueprint.sessionSpec.metadata),
+        senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
+        sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
+        declaredPreferences: readDeclaredPreferences(spec.declaredPreferences),
+        conversationCatchup: readConversationCatchup(spec.conversationCatchup),
+        selectRecalledMemories,
+    };
+}
+/**
+ * Run the twelve phases in order and compose the turn's `TurnInput`, or
+ * stop at the first settlement.
+ *
+ * The order is the orchestrator's, with its harness-specific steps gone
+ * (they run inside `adapter.runTurn`, after this returns): the tool surface,
+ * the skills, the attachments, the exact-apply, then the reads that need no
+ * network.
+ *
+ * The one persist a phase requires — the applied writes must be durable
+ * before the continuation runs — goes through the caller's chokepoint
+ * (`persist`), so the rule that phases never persist holds here too.
+ */
+export async function resolveTurnContext(deps, capabilities, frame, persist) {
+    const { execution, spec, sessionId } = await fetchExecution(deps);
+    const { session, blueprint } = await resolveAgentBlueprint(deps, sessionId);
+    const environment = await resolveEnvironment(deps);
+    const { workspace, writeback } = await provisionWorkspace(deps, { session, sessionId, envVars: environment.envVars });
+    frame.primaryDir = workspace.primaryDir;
+    frame.writeback = writeback;
+    const lock = await acquireWorkspaceTurnLock(deps, workspace.primaryDir);
+    if (lock.kind === "settled")
+        return { kind: "settled", settlement: lock.settlement };
+    frame.releaseWorkspaceLock = lock.release;
+    await bindTelemetryBaggage(deps, { session, sessionId });
+    const reinvoked = await reconcileReinvocation(deps, {
+        stateIdSource: capabilities.stateIdSource,
+        execution,
+        workspace,
+        fileReview: capabilities.fileReview,
+    });
+    if (reinvoked.kind === "settled")
+        return { kind: "settled", settlement: reinvoked.settlement };
+    const mcp = await resolveMcpServersAndPolicies(deps, { execution, session, sessionId, blueprint, environment });
+    const skills = await mountSkills(deps, { blueprint, sessionId, primaryDir: workspace.primaryDir });
+    const attachments = await resolveTurnAttachments(deps, {
+        spec,
+        sessionId,
+        primaryDir: workspace.primaryDir,
+        visionProfile: capabilities.visionProfile,
+    });
+    const appliedToolCallIds = await applyApprovedWrites(deps, { workspace, reinvocation: reinvoked.reinvocation });
+    if (appliedToolCallIds.size > 0) {
+        // Persist the applied writes (tool calls now COMPLETED with the approved
+        // diff) before reinvocation, so the applied state is durable even if the
+        // continuation fails, and the UI reflects it immediately.
+        await persist();
+    }
+    return {
+        kind: "ready",
+        input: {
+            executionId: deps.input.executionId,
+            threadId: deps.input.threadId,
+            turnSeq: deps.input.turnSeq,
+            sessionId,
+            approvalDecisions: reinvoked.reinvocation.approvalDecisions,
+            execution,
+            session,
+            blueprint,
+            environment,
+            workspace,
+            mcp,
+            skills,
+            attachments,
+            appliedToolCallIds,
+            model: resolveModelPreferences(spec),
+            structuredOutputSchema: structuredOutputSchemaOf(spec),
+            standing: resolveStandingContext(deps, { execution, spec, blueprint }),
+            artifactStorage: deps.artifactStorage,
+        },
+    };
+}
+//# sourceMappingURL=turn-context.js.map