@cursor/july 0.1.95 → 0.1.97

package/src/internal/session-engine.ts

@@ -7,6 +7,7 @@
  * event handlers and hooks.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
@@ -52,12 +53,15 @@ import {
   type DiscoveredTool,
   type HookHandler,
   type HostContext,
+  type HostMcpRegistry,
   type HttpChannelDefinition,
+  isCursorAccountTransport,
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
   type McpToolAnnotations,
   type PendingApproval,
+  type PendingAuth,
   type ReceiveInput,
   type ResolvedAgent,
   type RunnerSubagent,
@@ -79,7 +83,10 @@ import {
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
 import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
-import { resolveAdvertisedTools } from "./advertise-tools.js";
+import {
+  type AdvertiseHostMcp,
+  resolveAdvertisedTools,
+} from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
@@ -125,7 +132,8 @@ import {
   parseContinuationToken,
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
-import { McpHost } from "./mcp-host.js";
+import { isMcpNeedsAuthError, McpHost } from "./mcp-host.js";
+import { McpOauthOnDemandHub } from "./mcp-oauth-on-demand.js";
 import type { OtelCollector } from "./otel/collector.js";
 import {
   shouldStartProcessMemoryTelemetry,
@@ -136,13 +144,14 @@ import {
   SCHEDULE_CHANNEL_PREFIX,
 } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
-import type { AgentRunner } from "./sdk-runner.js";
+import type { AgentRunner, SteerAckOutcome } from "./sdk-runner.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
+import { steeringEnabled } from "./steering.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
-import { decideToolCall, resolveEffect } from "./tool-policy.js";
+import { decideToolCall, directCallEffect } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -151,6 +160,7 @@ import {
 } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
 import { TurnLeaseStore } from "./turn-lease-store.js";
+import { TurnOutbox } from "./turn-outbox.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
@@ -257,6 +267,22 @@ export class ApprovalInterruptedError extends Error {
   }
 }
 
+export class AuthNotFoundError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(`No pending MCP auth for session ${sessionId} call ${callId}`);
+    this.name = "AuthNotFoundError";
+  }
+}
+
+export class AuthInterruptedError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(
+      `MCP auth for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`
+    );
+    this.name = "AuthInterruptedError";
+  }
+}
+
 export interface SessionEngineOptions {
   project: AgentProject;
   stateRoot: string;
@@ -311,6 +337,16 @@ interface ActiveToolContext {
   emit: (payload: SessionEventPayload) => void;
 }
 
+type McpAuthParkCtx = {
+  sessionId: string;
+  turnId: string;
+  callId: string;
+  toolName: string;
+  emit: (payload: SessionEventPayload) => void;
+};
+
+const mcpAuthAls = new AsyncLocalStorage<McpAuthParkCtx>();
+
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
   /**
@@ -345,6 +381,8 @@ export class SessionEngine {
   readonly askDedupe: SlackAskDedupeStore;
   /** Cross-process turn ownership under `<stateRoot>/turn-leases`. */
   readonly turnLeases: TurnLeaseStore;
+  /** Messages for turns another server owns, under `<stateRoot>/outbox`. */
+  readonly outbox: TurnOutbox<AdmitTurnOptions>;
   /**
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
@@ -369,6 +407,13 @@ export class SessionEngine {
   /** Sessions with a turn being admitted (before the run promise exists). */
   private readonly pendingTurns = new Set<string>();
   private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
+  /**
+   * Sessions whose workspace a turn in this process has materialized. A
+   * session is busy from admit — before the governor slot and the turn's
+   * own materialize — so a read running alongside a turn consults this,
+   * not busy, to know whether the workspace is ready to be left alone.
+   */
+  private readonly materializedWorkspaces = new Set<string>();
   /** Context used by the cloud turn's HTTP MCP callbacks. */
   private readonly activeToolContexts = new Map<string, ActiveToolContext>();
   /**
@@ -409,6 +454,11 @@ export class SessionEngine {
   private readonly mcpHost: McpHost;
   private readonly platforms: HostPlatforms;
   private readonly approvals = new ApprovalGate();
+  private readonly auths = new ApprovalGate<PendingAuth>();
+  private readonly oauthHub = new McpOauthOnDemandHub();
+  private probeCursorAccount:
+    | ((connection: string) => Promise<string | undefined>)
+    | undefined;
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
   private readonly otelHost: HostOtelSessionApi;
@@ -457,6 +507,7 @@ export class SessionEngine {
     this.turnLeases = new TurnLeaseStore(
       join(options.stateRoot, "turn-leases")
     );
+    this.outbox = new TurnOutbox(join(options.stateRoot, "outbox"));
     this.logs = new EventLogStore(
       (sessionId) => this.sessions.eventFilePath(sessionId),
       (sessionId, error) =>
@@ -564,10 +615,25 @@ export class SessionEngine {
     this.cloudServerToolsConnection = connection;
   }
 
+  setMcpOauthCallbackUrl(url: string): void {
+    this.oauthHub.callbackUrl = url;
+    this.mcpHost.setOAuthRedirectUrl(url);
+  }
+
+  setCursorAccountAuthProbe(
+    probe: (connection: string) => Promise<string | undefined>
+  ): void {
+    this.probeCursorAccount = probe;
+  }
+
+  get oauthCallbackHub(): McpOauthOnDemandHub {
+    return this.oauthHub;
+  }
+
   /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
   get host(): HostContext {
     return {
-      mcp: this.mcpHost,
+      mcp: this.wrapMcp(this.mcpHost),
       github: this.platforms.github,
       slack: this.platforms.slack,
       reminders: this.reminderApi,
@@ -698,6 +764,9 @@ export class SessionEngine {
     ) {
       return;
     }
+    if (steeringEnabled()) {
+      return;
+    }
     try {
       await materializeSlackNudgeCarrier({
         harnessCwd,
@@ -959,7 +1028,7 @@ export class SessionEngine {
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
-      ...(sendOptions.dryRun === true ? { dryRun: true } : {}),
+      dryRun: sendOptions.dryRun === true ? true : undefined,
       continuationKey: sendOptions.continuationToken ?? newContinuationKey(),
       auth,
       title: sendOptions.title,
@@ -977,7 +1046,10 @@ export class SessionEngine {
     this.storage?.sessionRecord(record);
     await this.appendEvent(record.sessionId, {
       type: "session.started",
-      data: { channelId },
+      data: {
+        channelId,
+        dryRun: record.dryRun === true ? true : undefined,
+      },
     });
     record = await this.enrollABs(record);
     const since = (await this.logs.get(record.sessionId)).count;
@@ -1227,7 +1299,14 @@ export class SessionEngine {
     const prior = this.admissionChains.get(sessionId) ?? Promise.resolve();
     const admitted = prior
       .catch(() => {})
-      .then(() => this.admitTurn(sessionId, message, options));
+      .then(async () => {
+        // Another server holds the turn: hand the message to it and coalesce.
+        if (await this.turnLeases.runningElsewhere(sessionId)) {
+          await this.outbox.post(sessionId, { message, options });
+          return true;
+        }
+        return this.admitTurn(sessionId, message, options);
+      });
     this.admissionChains.set(
       sessionId,
       admitted.catch(() => {})
@@ -1235,6 +1314,20 @@ export class SessionEngine {
     return admitted;
   }
 
+  /** Admit what other servers handed to this turn's holder. Never awaited by the lifecycle. */
+  private drainOutbox(sessionId: string): void {
+    void this.outbox
+      .takeAll(sessionId)
+      .then((items) => {
+        for (const item of items) {
+          void this.startTurn(sessionId, item.message, item.options).catch(
+            () => {}
+          );
+        }
+      })
+      .catch(() => {});
+  }
+
   private enqueueCoalesced(sessionId: string, item: CoalescedQueuedTurn): void {
     const queue = this.coalesceQueues.get(sessionId) ?? [];
     if (
@@ -1359,18 +1452,52 @@ export class SessionEngine {
     });
   }
 
+  private async steerIntoRunningTurn(
+    sessionId: string,
+    message: string
+  ): Promise<SteerAckOutcome> {
+    if (this.runner.steer === undefined) {
+      return "revert_to_followup";
+    }
+    try {
+      return await this.runner.steer({ sessionId, text: message });
+    } catch (error) {
+      this.logger(
+        `[session] steer failed for ${sessionId}: ${describeError(error)}`
+      );
+      return "revert_to_followup";
+    }
+  }
+
   private async admitTurn(
     sessionId: string,
     message: string,
     options: AdmitTurnOptions = {}
   ): Promise<boolean> {
     const admission = options.admission ?? "preempt";
+    if (
+      admission === "coalesce" &&
+      steeringEnabled() &&
+      this.isTurnRunning(sessionId)
+    ) {
+      const toolCtx = this.activeToolContexts.get(sessionId);
+      const steerOutcome = await this.steerIntoRunningTurn(sessionId, message);
+      if (steerOutcome === "complete_delivered") {
+        this.logger(`[session] steered into running turn ${sessionId}`);
+        if (toolCtx !== undefined) {
+          toolCtx.emit({ type: "message.received", data: { text: message } });
+          toolCtx.emit({ type: "nudge.delivered", data: {} });
+        }
+        return true;
+      }
+    }
+    // Re-checked after the steer: a turn that ended during it falls through
+    // and this message starts the next turn itself. Enqueueing here instead
+    // would orphan it — the completion drain already ran.
     if (admission === "coalesce" && this.isTurnRunning(sessionId)) {
       this.enqueueCoalesced(sessionId, {
         message,
-        ...(options.sourceTs === undefined
-          ? {}
-          : { sourceTs: options.sourceTs }),
+        sourceTs: options.sourceTs,
       });
       this.logger(`[session] coalesce enqueue ${sessionId}`);
       return true;
@@ -1438,6 +1565,8 @@ export class SessionEngine {
       let lifecycle!: Promise<TurnOutcome>;
       lifecycle = (async (): Promise<TurnOutcome> => {
         let outcome: TurnOutcome;
+        const poll = setInterval(() => this.drainOutbox(sessionId), 1_000);
+        poll.unref();
         try {
           outcome = await this.executeTurn(
             record,
@@ -1451,6 +1580,8 @@ export class SessionEngine {
             status: "error",
             errorMessage: describeError(error),
           };
+        } finally {
+          clearInterval(poll);
         }
         this.lastOutcomes.set(sessionId, outcome);
         const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
@@ -1480,6 +1611,10 @@ export class SessionEngine {
         // The drain may have nested a successor turn, which took its own
         // reference; the lease outlives this release until that one ends too.
         await lease.release();
+        // Handed off between the last poll and the release: nobody else will.
+        if (!abort.signal.aborted) {
+          this.drainOutbox(sessionId);
+        }
         return outcome;
       })();
       this.activeTurns.set(sessionId, lifecycle);
@@ -1524,6 +1659,7 @@ export class SessionEngine {
       this.coalesceDrains.has(sessionId) ||
       (this.coalesceQueues.get(sessionId)?.length ?? 0) > 0;
     this.clearCoalesced(sessionId);
+    await this.outbox.clear(sessionId);
     const record = await this.sessions.get(sessionId);
     const continuationKey = record?.continuationKey;
     if (continuationKey !== undefined && continuationKey !== null) {
@@ -1757,6 +1893,7 @@ export class SessionEngine {
           seed: isFirstTurn,
           stateRoot: this.stateRoot,
         });
+        this.materializedWorkspaces.add(sessionId);
         // Must precede the carrier: the harness resolves rules, skills,
         // `mcp.json` and hooks from its git root, so a workspace nested in an
         // outer repo would load that repo's hooks instead of the ones written
@@ -1841,11 +1978,14 @@ export class SessionEngine {
         }
       } catch (error) {
         this.approvals.cancelSession(sessionId, "deny");
+        this.auths.cancelSession(sessionId, "deny");
         outcome = { status: "error", errorMessage: describeError(error) };
       } finally {
         permit.release();
         this.approvals.cancelSession(sessionId, "deny");
+        this.auths.cancelSession(sessionId, "deny");
         await this.clearPendingApprovals(sessionId);
+        await this.clearPendingAuths(sessionId);
         // Anything still queued belongs to the next turn's boundary drain, not
         // to this turn's edge detection.
         this.deliveredNudges.delete(sessionId);
@@ -2480,11 +2620,21 @@ export class SessionEngine {
     // named passthroughs resolved fresh on every turn — reminder fires and
     // post-restart follow-ups included — and a listing failure throws,
     // failing the turn closed.
-    for (const tool of await resolveAdvertisedTools({
-      agent,
-      session: this.sessionInfo(record),
-      hostMcp: this.mcpHost,
-    })) {
+    for (const tool of await mcpAuthAls.run(
+      {
+        sessionId: record.sessionId,
+        turnId,
+        callId: newToolCallId("mcp"),
+        toolName: "mcp",
+        emit,
+      },
+      () =>
+        resolveAdvertisedTools({
+          agent,
+          session: this.sessionInfo(record),
+          hostMcp: this.advertiseMcp(),
+        })
+    )) {
       register(tool);
     }
     return tools;
@@ -2634,7 +2784,16 @@ export class SessionEngine {
       }
       const started = Date.now();
       this.logger(`[session] tool ${args.tool.name} start`);
-      const result = await execute(validation.value as never, toolCtx);
+      const result = await mcpAuthAls.run(
+        {
+          sessionId: args.record.sessionId,
+          turnId: args.turnId,
+          callId: toolCallId,
+          toolName: args.tool.name,
+          emit: args.emit,
+        },
+        () => execute(validation.value as never, toolCtx)
+      );
       this.logger(
         `[session] tool ${args.tool.name} done (${Date.now() - started}ms)`
       );
@@ -2670,10 +2829,10 @@ export class SessionEngine {
       args: args.args,
       requestedAt,
     };
-    const resolutionPromise = this.approvals.wait({
-      sessionId: args.sessionId,
-      ...pendingRecord,
-    });
+    const resolutionPromise = this.approvals.wait(
+      args.sessionId,
+      pendingRecord
+    );
     await this.updateRecord(args.sessionId, (current) => ({
       ...current,
       pendingApprovals: [
@@ -2793,6 +2952,318 @@ export class SessionEngine {
     }));
   }
 
+  private wrapMcp(inner: McpHost): HostMcpRegistry {
+    return {
+      names: () => inner.names(),
+      listTools: (name) => this.withMcpAuth(name, () => inner.listTools(name)),
+      callTool: (name, tool, args) =>
+        this.withMcpAuth(name, () => inner.callTool(name, tool, args)),
+    };
+  }
+
+  private advertiseMcp(): AdvertiseHostMcp {
+    return {
+      listTools: (name) =>
+        this.withMcpListAuth(name, () => this.mcpHost.listTools(name)),
+      callTool: (name, tool, args) =>
+        this.withMcpAuth(name, () => this.mcpHost.callTool(name, tool, args)),
+      oneOff: (connection) => {
+        const inner = this.mcpHost.oneOff(connection);
+        return {
+          listTools: () =>
+            this.withMcpListAuth(connection.name, () => inner.listTools()),
+          callTool: (tool, args) =>
+            this.withMcpAuth(connection.name, () => inner.callTool(tool, args)),
+        };
+      },
+    };
+  }
+
+  private withMcpListAuth<T>(
+    connection: string,
+    run: () => Promise<T>
+  ): Promise<T> {
+    const ctx = mcpAuthAls.getStore();
+    if (ctx === undefined) {
+      return this.withMcpAuth(connection, run);
+    }
+    const toolName = `mcp:${connection}`;
+    return mcpAuthAls.run(
+      {
+        ...ctx,
+        callId: newToolCallId(toolName),
+        toolName,
+      },
+      () => this.withMcpAuth(connection, run)
+    );
+  }
+
+  private async withMcpAuth<T>(
+    connection: string,
+    run: () => Promise<T>
+  ): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (!isMcpNeedsAuthError(error)) {
+        throw error;
+      }
+      return await this.parkAndRetryMcp(connection, run, error);
+    }
+  }
+
+  private async parkAndRetryMcp<T>(
+    connection: string,
+    run: () => Promise<T>,
+    error: unknown
+  ): Promise<T> {
+    const ctx = mcpAuthAls.getStore();
+    if (ctx === undefined) {
+      throw error;
+    }
+    const minted = await this.mintAuthUrl(connection, ctx.sessionId);
+    if (minted === undefined) {
+      throw error;
+    }
+    if ("authorized" in minted) {
+      await this.persistHostedMcpOauth(connection);
+      await this.mcpHost.dropClient(connection);
+      return await this.withMcpAuth(connection, run);
+    }
+    if (minted.state !== "") {
+      const bind = this.oauthHub.bind(minted.state, ctx.sessionId, ctx.callId);
+      if (bind === "already_done") {
+        await this.persistHostedMcpOauth(connection);
+        await this.mcpHost.dropClient(connection);
+        return await this.withMcpAuth(connection, run);
+      }
+    }
+    const decision = await this.parkForAuth({
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      callId: ctx.callId,
+      toolName: ctx.toolName,
+      connection,
+      authUrl: minted.authUrl,
+      emit: ctx.emit,
+    });
+    if (decision === "deny") {
+      throw new Error(
+        `MCP connection "${connection}" authorization was denied.`
+      );
+    }
+    await this.persistHostedMcpOauth(connection);
+    await this.mcpHost.dropClient(connection);
+    return await this.withMcpAuth(connection, run);
+  }
+
+  private async persistHostedMcpOauth(connection: string): Promise<void> {
+    const authored = this.authoredConnection(connection);
+    if (
+      authored === undefined ||
+      !isHostOauthConnectionTransport(authored.transport)
+    ) {
+      return;
+    }
+    await this.oauthHub.persistFor(connection, authored.transport.url);
+  }
+
+  private authoredConnection(name: string) {
+    return (
+      this.project.agent.connections.find((entry) => entry.name === name) ??
+      this.project.agent.hostConnections?.find((entry) => entry.name === name)
+    );
+  }
+
+  private async mintAuthUrl(
+    connection: string,
+    sessionId: string
+  ): Promise<
+    { authorized: true } | { authUrl: string; state: string } | undefined
+  > {
+    const authored = this.authoredConnection(connection);
+    if (authored === undefined) {
+      return undefined;
+    }
+    if (isCursorAccountTransport(authored.transport)) {
+      const probe = this.probeCursorAccount;
+      if (probe === undefined) {
+        return undefined;
+      }
+      const authUrl = await probe(connection);
+      if (authUrl === undefined || authUrl === "") {
+        return undefined;
+      }
+      return { authUrl, state: "" };
+    }
+    if (!isHostOauthConnectionTransport(authored.transport)) {
+      return undefined;
+    }
+    return await this.oauthHub.mint({
+      connection,
+      url: authored.transport.url,
+      type: authored.transport.type === "sse" ? "sse" : "http",
+      headers: authored.transport.headers,
+      sessionId,
+    });
+  }
+
+  private async parkForAuth(args: {
+    sessionId: string;
+    turnId: string;
+    callId: string;
+    toolName: string;
+    connection: string;
+    authUrl: string;
+    emit: (payload: SessionEventPayload) => void;
+  }): Promise<ApprovalDecision> {
+    const requestedAt = new Date().toISOString();
+    const pendingRecord: PendingAuth = {
+      callId: args.callId,
+      turnId: args.turnId,
+      toolName: args.toolName,
+      connection: args.connection,
+      authUrl: args.authUrl,
+      requestedAt,
+    };
+    const resolutionPromise = this.auths.wait(args.sessionId, pendingRecord);
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingAuths: [
+        ...(current.pendingAuths ?? []).filter(
+          (item) => item.callId !== args.callId
+        ),
+        pendingRecord,
+      ],
+    }));
+    args.emit({
+      type: "action.auth_requested",
+      data: {
+        callId: args.callId,
+        toolName: args.toolName,
+        connection: args.connection,
+        authUrl: args.authUrl,
+      },
+    });
+    this.logger(
+      `[session] tool ${args.toolName} awaiting MCP auth ${args.connection} (${args.callId})`
+    );
+    const { decision, by } = await resolutionPromise;
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingAuths: (current.pendingAuths ?? []).filter(
+        (item) => item.callId !== args.callId
+      ),
+    }));
+    args.emit({
+      type: "action.auth_resolved",
+      data: {
+        callId: args.callId,
+        toolName: args.toolName,
+        connection: args.connection,
+        decision,
+        by,
+      },
+    });
+    this.logger(
+      `[session] tool ${args.toolName} MCP auth ${decision} (${args.callId})`
+    );
+    return decision;
+  }
+
+  private async clearPendingAuths(sessionId: string): Promise<void> {
+    await this.oauthHub.abortSession(sessionId);
+    const current = await this.sessions.get(sessionId);
+    if (
+      current === undefined ||
+      current.pendingAuths === undefined ||
+      current.pendingAuths.length === 0
+    ) {
+      return;
+    }
+    await this.updateRecord(sessionId, (record) => ({
+      ...record,
+      pendingAuths: [],
+    }));
+  }
+
+  async listPendingAuths(sessionId: string): Promise<PendingAuth[]> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      return [];
+    }
+    const live = this.auths.list(sessionId);
+    if (live.length > 0) {
+      return live;
+    }
+    return record.pendingAuths ?? [];
+  }
+
+  async resolveAuth(
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    auth: AuthContext | null,
+    options?: { asSessionOwner?: boolean }
+  ): Promise<PendingAuth> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      throw new AuthNotFoundError(sessionId, callId);
+    }
+    const ownershipAuth = options?.asSessionOwner === true ? record.auth : auth;
+    if (!samePrincipal(record.auth, ownershipAuth)) {
+      throw new SessionAuthError(sessionId);
+    }
+    const pending =
+      (record.pendingAuths ?? []).find((item) => item.callId === callId) ??
+      this.auths.list(sessionId).find((item) => item.callId === callId);
+    if (pending === undefined) {
+      throw new AuthNotFoundError(sessionId, callId);
+    }
+    const resolvedBy = approvalResolverLabel(auth);
+    if (decision === "deny") {
+      await this.oauthHub.abortCall(sessionId, callId);
+    }
+    if (!this.auths.resolve(sessionId, callId, decision, resolvedBy)) {
+      await this.removePendingAuth(sessionId, callId);
+      throw new AuthInterruptedError(sessionId, callId);
+    }
+    return pending;
+  }
+
+  private async removePendingAuth(
+    sessionId: string,
+    callId: string
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingAuths: (current.pendingAuths ?? []).filter(
+        (item) => item.callId !== callId
+      ),
+    }));
+  }
+
+  async runWithMcpPark<T>(
+    sessionId: string,
+    toolName: string,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    const active = this.activeToolContexts.get(sessionId);
+    if (active === undefined) {
+      return fn();
+    }
+    return mcpAuthAls.run(
+      {
+        sessionId,
+        turnId: active.turnId,
+        callId: newToolCallId(toolName),
+        toolName,
+        emit: active.emit,
+      },
+      fn
+    );
+  }
+
   // ==========================================================================
   // Direct tool calls (deterministic invocation, no model turn)
   // ==========================================================================
@@ -2808,8 +3279,10 @@ export class SessionEngine {
    * and materialized workspace) and the call is recorded on the session's
    * event stream as `actions.requested` / `action.result` under a
    * per-call `turnId` (the call id), so it shows up in trajectories.
-   * Rejected with {@link SessionBusyError} while a model turn is running.
-   * Without a session, the tool runs against an **ephemeral** scratch
+   * While a model turn is running, a read-effect call runs alongside it
+   * (the turn's workspace is read as-is) and a write-effect call is
+   * rejected with {@link SessionBusyError}. Without a session, the tool
+   * runs against an **ephemeral** scratch
    * workspace under `<stateRoot>/tool-calls/<callId>` (materialized with
    * seed files, removed after the call returns).
    *
@@ -2835,6 +3308,12 @@ export class SessionEngine {
     session: SessionInfo;
     workspaceDir: string;
     scratchDir: string | undefined;
+    /**
+     * A model turn is running or queued on the session. Reported, not
+     * enforced: what it means depends on the call — a write waits, a read
+     * (including the catalog) runs alongside the turn.
+     */
+    busy: boolean;
   }> {
     if (
       options.sessionId !== undefined &&
@@ -2860,9 +3339,9 @@ export class SessionEngine {
         );
       }
       // A token that maps to a live (or restorable) session takes the
-      // session path: same owner check, same turn serialization, same
-      // event recording as an explicit sessionId. Skipping those just
-      // because the caller addressed the session by token would fail open.
+      // session path: same owner check, same busy semantics, same event
+      // recording as an explicit sessionId. Skipping those just because
+      // the caller addressed the session by token would fail open.
       record =
         (await this.sessions.findByContinuation(
           continuation.channelId,
@@ -2877,19 +3356,14 @@ export class SessionEngine {
       }
     }
     if (record !== undefined) {
-      // Direct calls respect the same serialization as follow-up sends: a
-      // running model turn owns the session workspace and event stream.
-      if (
-        this.activeTurns.has(record.sessionId) ||
-        this.pendingTurns.has(record.sessionId)
-      ) {
-        throw new SessionBusyError(record.sessionId);
-      }
       return {
         record,
         session: this.sessionInfo(record),
         workspaceDir: this.harnessCwd(record),
         scratchDir: undefined,
+        busy:
+          this.activeTurns.has(record.sessionId) ||
+          this.pendingTurns.has(record.sessionId),
       };
     }
     // No session behind the token (or no token at all): a synthetic
@@ -2909,6 +3383,7 @@ export class SessionEngine {
       },
       workspaceDir: scratchDir,
       scratchDir,
+      busy: false,
     };
   }
 
@@ -2951,6 +3426,43 @@ export class SessionEngine {
     };
   }
 
+  /**
+   * One catalog tool by name. Authored tools are local — their schema does
+   * not depend on session identity or connection listings — so a detail
+   * fetch for `ls` must not wait on every advertised MCP server.
+   */
+  async describeCatalogTool(
+    toolName: string,
+    options: Pick<
+      CallToolOptions,
+      "auth" | "sessionId" | "continuationToken"
+    > = {}
+  ): Promise<
+    | { tool: DiscoveredTool }
+    | {
+        tool: undefined;
+        availableTools: string[];
+        connectionErrors: Array<{ connection: string; message: string }>;
+      }
+  > {
+    const authored = this.project.agent.tools.find(
+      (tool) => tool.name === toolName
+    );
+    if (authored !== undefined) {
+      return { tool: authored };
+    }
+    const catalog = await this.listCatalogTools(options);
+    const tool = catalog.tools.find((entry) => entry.name === toolName);
+    if (tool === undefined) {
+      return {
+        tool: undefined,
+        availableTools: catalog.tools.map((entry) => entry.name),
+        connectionErrors: catalog.connectionErrors,
+      };
+    }
+    return { tool };
+  }
+
   async callTool(
     toolName: string,
     input: unknown = {},
@@ -2977,7 +3489,7 @@ export class SessionEngine {
       const advertised = await resolveAdvertisedTools({
         agent: this.project.agent,
         session,
-        hostMcp: this.mcpHost,
+        hostMcp: this.advertiseMcp(),
       });
       tool = advertised.find((t) => t.name === toolName);
     }
@@ -2997,6 +3509,19 @@ export class SessionEngine {
     if (!validation.ok) {
       throw new ToolInputError({ toolName, detail: validation.message });
     }
+    // A running model turn owns the session workspace: a direct write would
+    // race the harness's own edits, so it waits (409). A read runs alongside
+    // the turn — the operator inspecting a live session is the point — and
+    // its events stay separable by their per-call turnId. The effect can
+    // depend on the input, hence deciding after validation; an MCP tool
+    // nothing classifies is a write here, fail-closed.
+    if (
+      identity.busy &&
+      record !== undefined &&
+      directCallEffect(tool, validation.value) !== "read"
+    ) {
+      throw new SessionBusyError(record.sessionId);
+    }
     let workspaceUnavailable = false;
     try {
       await mkdir(workspaceDir, { recursive: true });
@@ -3015,35 +3540,59 @@ export class SessionEngine {
       // to write) authored tool may rely on ctx.workspaceDir being the
       // real session workspace, so silently relocating it is not safe —
       // fail typed instead.
+      //
+      // A shared `local.workspaceDir` (change-monitor's phantom /repo) is
+      // that path by design. Relocating it to scratch would flag a false
+      // session-state warning; keep the borrowed cwd and skip the flag.
       const relocatable =
         tool.advertised === true ||
-        resolveEffect(tool.definition.effect, validation.value) === "read";
+        directCallEffect(tool, validation.value) === "read";
       if (!relocatable) {
         throw new WorkspaceUnavailableError(toolName, error);
       }
-      this.logger(
-        `[session] tool ${toolName} workspace unavailable (direct ${callId}); using scratch: ${
-          error instanceof Error ? error.message : String(error)
-        }`
-      );
-      scratchDir = join(this.stateRoot, "tool-calls", callId);
-      workspaceDir = scratchDir;
-      workspaceUnavailable = true;
-      await mkdir(workspaceDir, { recursive: true });
+      if (this.project.agent.local?.workspaceDir !== undefined) {
+        this.logger(
+          `[session] tool ${toolName} harness cwd unavailable (direct ${callId}); keeping borrowed workspace`
+        );
+      } else {
+        this.logger(
+          `[session] tool ${toolName} workspace unavailable (direct ${callId}); using scratch: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        scratchDir = join(this.stateRoot, "tool-calls", callId);
+        workspaceDir = scratchDir;
+        workspaceUnavailable = true;
+        await mkdir(workspaceDir, { recursive: true });
+      }
     }
     // Match what a model turn would see: session workspaces get the same
     // scaffold as executeTurn (seeds only before the first turn); scratch
-    // workspaces are materialized fresh.
-    await materializeWorkspace({
-      agent: this.project.agent,
-      workspaceDir:
-        record === undefined || workspaceUnavailable
-          ? workspaceDir
-          : this.scaffoldDir(record),
-      seed:
-        record === undefined || workspaceUnavailable || record.turnCount === 0,
-      stateRoot: this.stateRoot,
-    });
+    // workspaces are materialized fresh. A read running alongside a turn
+    // that has materialized its workspace leaves it alone — re-seeding
+    // would restore files the agent deleted mid-turn. A session is busy
+    // from admit, though, so a read that lands while the first turn is
+    // still queued or scaffolding materializes the workspace itself, seeds
+    // included (turnCount is already 1 for that pending first turn).
+    const turnMaterialized =
+      record !== undefined &&
+      identity.busy &&
+      this.materializedWorkspaces.has(record.sessionId);
+    if (record === undefined || workspaceUnavailable || !turnMaterialized) {
+      await materializeWorkspace({
+        agent: this.project.agent,
+        workspaceDir:
+          record === undefined || workspaceUnavailable
+            ? workspaceDir
+            : this.scaffoldDir(record),
+        seed:
+          record === undefined ||
+          workspaceUnavailable ||
+          record.turnCount === 0 ||
+          (identity.busy && record.turnCount === 1),
+        stateRoot: this.stateRoot,
+      });
+    }
 
     // A per-call turnId keeps these events visible in trajectories (which
     // drop turn-less action events) without attributing them to a model turn.
@@ -3101,8 +3650,8 @@ export class SessionEngine {
         result = normalizeToolResult(decision.result);
         isError = false;
       } else {
-        result = normalizeToolResult(
-          await execute(validation.value as never, {
+        const run = () =>
+          execute(validation.value as never, {
             toolCallId: callId,
             session,
             workspaceDir,
@@ -3127,7 +3676,20 @@ export class SessionEngine {
             getSession: (channelId, sessionId) =>
               this.getChannelSession(channelId, sessionId),
             emit,
-          })
+          });
+        result = normalizeToolResult(
+          record !== undefined && emit !== undefined
+            ? await mcpAuthAls.run(
+                {
+                  sessionId: record.sessionId,
+                  turnId: callId,
+                  callId,
+                  toolName,
+                  emit,
+                },
+                run
+              )
+            : await run()
         );
         isError = isErrorEnvelope(result);
       }
@@ -3394,6 +3956,28 @@ export class SessionEngine {
   // Session handles
   // ==========================================================================
 
+  /**
+   * Wait until everything this session has already emitted is durably
+   * mirrored: its dispatch chain first (the chain's tail runs the turn-end
+   * storage flush, so the record carries the boundary event's handler
+   * mutations), then the storage delivery queue. Hosted v2 awaits this
+   * before the execution reply — the pod can be parked the moment the
+   * reply lands, and an unflushed session record would strand a
+   * conversation whose blobs persisted but whose record (which selects the
+   * conversation to hydrate) never reached the sink. No-op without a
+   * storage mirror.
+   */
+  async drainSessionDurability(sessionId: string): Promise<void> {
+    if (this.storage === undefined) {
+      return;
+    }
+    const chain = this.dispatchChains.get(sessionId);
+    if (chain !== undefined) {
+      await chain.catch(() => {});
+    }
+    await this.storage.whenIdle();
+  }
+
   async waitForCompletion(sessionId: string): Promise<TurnOutcome> {
     // Drain admission first so pendingTurns → activeTurns is visible before we
     // decide the session is idle (reminders use this for queueBehindTurn).
@@ -3525,6 +4109,75 @@ export class SessionEngine {
     };
   }
 
+  /**
+   * The single newest session visible to `caller` (`GET /v1/sessions?latest=1`).
+   *
+   * Short-circuits the full listing: the local store already holds every
+   * session this host created plus the startup bulk restore, so the common
+   * case answers from memory without a sink round trip. Only when the local
+   * store has nothing for the caller (fresh host, `restore: "off"`) does it
+   * ask the sink — for a bounded newest-written window when the backend
+   * can order by write time, else the full list. A session written by
+   * another replica moments ago can lose to a local one; callers that need
+   * the exact newest row should use the full listing.
+   */
+  async latestSessionWithSource(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<{ sessions: SessionSummary[]; source: SessionListSource }> {
+    const includeAll = options?.includeAll ?? false;
+    const newestVisible = (
+      records: readonly SessionRecord[]
+    ): SessionRecord | undefined => {
+      let newest: SessionRecord | undefined;
+      for (const record of records) {
+        if (!(includeAll || samePrincipal(record.auth, caller))) {
+          continue;
+        }
+        if (
+          newest === undefined ||
+          record.updatedAt.localeCompare(newest.updatedAt) > 0
+        ) {
+          newest = record;
+        }
+      }
+      return newest;
+    };
+    const local = newestVisible(await this.sessions.list());
+    if (local !== undefined) {
+      return {
+        sessions: this.summarizeSessionRecords([local], caller, includeAll),
+        source: "local",
+      };
+    }
+    if (this.storage?.isCursorHosted === true) {
+      try {
+        const window = await this.storage.listNewestSessionsFromSink(
+          LATEST_SESSION_SINK_WINDOW
+        );
+        if (window !== undefined) {
+          const stored = newestVisible(window);
+          if (stored !== undefined) {
+            return {
+              sessions: this.summarizeSessionRecords(
+                [stored],
+                caller,
+                includeAll
+              ),
+              source: "cursor-hosted",
+            };
+          }
+        }
+      } catch (error) {
+        this.logger(
+          `[agent-sdk] cursor-hosted newest-session lookup failed; falling back to the full list: ${describeError(error)}`
+        );
+      }
+    }
+    const listed = await this.listSessionsWithSource(caller, options);
+    return { sessions: listed.sessions.slice(0, 1), source: listed.source };
+  }
+
   /**
    * Durable sink rows plus local records (local wins on the same id when
    * newer — covers debounce windows that have not flushed yet). Newest
@@ -3578,6 +4231,7 @@ export class SessionEngine {
             : undefined,
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
+          dryRun: record.dryRun === true ? true : undefined,
           continuationToken:
             record.httpContinuationKey !== undefined
               ? formatContinuationToken(
@@ -3907,7 +4561,7 @@ export class SessionEngine {
       channelId: record.channelId,
       mode: record.mode,
       purpose: record.purpose === "eval" ? "eval" : "live",
-      ...(record.dryRun === true ? { dryRun: true } : {}),
+      dryRun: record.dryRun === true ? true : undefined,
       auth: record.auth,
       continuationKey: record.continuationKey,
       ...(record.abs === undefined ? {} : { abs: record.abs }),
@@ -4280,6 +4934,8 @@ export class SessionEngine {
   async close(): Promise<void> {
     this.stopMemoryTelemetry?.();
     this.approvals.cancelAll("deny");
+    this.auths.cancelAll("deny");
+    await this.oauthHub.close();
     await Promise.allSettled([...this.activeTurns.values()]);
     await Promise.allSettled([...this.backgroundWork]);
     await Promise.allSettled([...this.dispatchChains.values()]);
@@ -4297,6 +4953,13 @@ export class SessionEngine {
 /** Parallel event-stream loads during the startup bulk restore. */
 const RESTORE_FETCH_CONCURRENCY = 8;
 
+/**
+ * Newest-written sink rows fetched for `GET /v1/sessions?latest=1` when the
+ * local store has nothing for the caller. Wide enough that the caller's own
+ * session is normally inside it even when other principals are busier.
+ */
+const LATEST_SESSION_SINK_WINDOW = 50;
+
 /** NDJSON payload for a restored event stream; undefined when empty. */
 function mergePendingImages(
   current: Array<{ data: string; mimeType: string }> | undefined,