@cursor/july 0.1.102 → 0.1.104

package/src/internal/session-engine.ts

@@ -28,12 +28,26 @@ import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channe
 import {
   AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
   agentStoreKeys,
+  DEPLOYMENT_STORE_MOUNT_PATH,
+  type FileSink,
+  USER_STORE_MOUNT_PATH,
 } from "../files.js";
 import {
   cursorHostedFiles,
   isCursorHostedFilesAvailable,
   isCursorUserStoreFilesAvailable,
 } from "../files-backends/cursor-hosted.js";
+import {
+  type FileSystem,
+  isFileSystemToolAlias,
+  isMutatingFileSystemTool,
+  localFileSystem,
+  resolveFileSystemTools,
+  resolveHostHarnessToolOptions,
+  tempFs,
+  unionFs,
+  writeWorkspaceFilesToRoot,
+} from "../filesystem.js";
 import { storageKeysForArchitecture } from "../storage.js";
 import {
   type AgentProject,
@@ -66,10 +80,12 @@ import {
   type PendingAuth,
   type ReceiveInput,
   type ResolvedAgent,
+  type RootContext,
   type RunnerSubagent,
   type RunnerTurnRequest,
   type SendMessageFn,
   type SendMessageOptions,
+  type SessionContext,
   type SessionEvent,
   type SessionEventPayload,
   type SessionInfo,
@@ -116,9 +132,21 @@ import {
   resolveV2Key,
   V2EngineError,
 } from "./continuation-identity.js";
+import { describeError } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import {
+  applyWebScratchUpdate,
+  ingestHostAgentToolsScratch,
+  remapScratchPaths,
+} from "./filesystem/scratch.js";
+import {
+  fileSystemTool,
+  hostFileToolsFromAuthored,
+  rootFileToolsFromAuthored,
+  synthesizeFileSystemTools,
+} from "./filesystem/tools.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
@@ -152,6 +180,7 @@ import {
   SCHEDULE_CHANNEL_PREFIX,
 } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
+import { applyAuthoredResult } from "./result-output.js";
 import type { AgentRunner, SteerAckOutcome } from "./sdk-runner.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
@@ -173,16 +202,29 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  buildCloudWorkspaceSection,
   ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
-  writeWorkspaceFiles,
 } from "./workspace.js";
+import { syncWorkspaceToStore } from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 
+/** Authored surfaces mirrored onto the Agent Store before a first cloud prompt. */
+type CloudSyncSurface = "skills" | "workspace";
+
+/** The Agent Store cloud turns read authored files from, and where the VM mounts it. */
+interface CloudStoreTarget {
+  sink: FileSink;
+  mountPath: string;
+  skillsPrefix: string;
+  workspacePrefix: string;
+  label: string;
+}
+
 export class SessionBusyError extends Error {
   constructor(sessionId: string) {
     super(
@@ -406,8 +448,8 @@ export class SessionEngine {
   >();
   /** Once-per-process cache for the A/B snapshot backfill (see abSnapshot). */
   private restoredAbSnapshot: Promise<ABSnapshot | undefined> | undefined;
-  /** In-flight skills → Agent Store sync (see ensureCloudSkillsSynced). */
-  private cloudSkillsSync: Promise<boolean> | undefined;
+  /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+  private readonly cloudSyncs = new Map<CloudSyncSurface, Promise<boolean>>();
 
   private readonly runner: AgentRunner;
   private readonly logger: (line: string) => void;
@@ -490,6 +532,15 @@ export class SessionEngine {
   private readonly cloudCostBackfillDone = new Set<string>();
   /** Deduped in-flight cloud cost backfills, keyed by session id. */
   private readonly cloudCostBackfill = new Map<string, Promise<void>>();
+  /** Per-session FileSystem handle cache (not a tree snapshot). */
+  private readonly sessionRoots = new Map<string, FileSystem>();
+  /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+  private readonly sessionRootInflight = new Map<string, Promise<FileSystem>>();
+  /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+  private readonly turnRoots = new Map<
+    string,
+    { root: FileSystem; cwd: string }
+  >();
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
@@ -678,9 +729,9 @@ export class SessionEngine {
   }
 
   /**
-   * Host services with `files` bound to one session, so a relative path in a
-   * tool or hook resolves to that session's scope and can never be read as
-   * another session's. Unbound (no session) keeps `host.files` usable for
+   * Host services with `files` and `otel` bound to one session, so a relative
+   * path resolves to that session's scope and can never read another
+   * session's. Unbound (no session) keeps `host.files` usable for
    * `{ scope: "deployment" }` and fails loudly on session-scoped calls.
    */
   private hostForSession(sessionId: string | undefined): HostContext {
@@ -1773,6 +1824,261 @@ export class SessionEngine {
     return this.interrupt(existing.sessionId);
   }
 
+  private hasRootOverride(): boolean {
+    return this.project.agent.root !== undefined;
+  }
+
+  /**
+   * FileSystem for this turn or `callTool`. Authored `root` (static or
+   * factory) is cached per session when `cache` is set; unscoped
+   * `callTool` passes the invocation id and does not cache, so factories
+   * cannot share one tree across callers. A static handle is used as
+   * authored — every session sees that same object. Host-default agents
+   * get `localFileSystem` against the harness cwd — same path verbs as
+   * the Cursor SDK natives, always through the synthesized tools.
+   */
+  private async resolveFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+    cwd: string;
+  }): Promise<FileSystem> {
+    const authored = this.project.agent.root;
+    if (authored === undefined) {
+      return localFileSystem({ cwd: options.cwd });
+    }
+    const authoredRoot = await this.resolveAuthoredFileSystem(options);
+    if (options.cache) {
+      const existing = this.turnRoots.get(options.sessionId);
+      if (existing !== undefined) {
+        return existing.root;
+      }
+    }
+    const root = unionFs({
+      "/": authoredRoot,
+      "/tmp": tempFs(),
+    });
+    if (options.cache && this.isTurnRunning(options.sessionId)) {
+      this.turnRoots.set(options.sessionId, { root, cwd: options.cwd });
+    }
+    return root;
+  }
+
+  private async resolveAuthoredFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+  }): Promise<FileSystem> {
+    const authored = this.project.agent.root;
+    if (authored === undefined) {
+      throw new Error("resolveAuthoredFileSystem requires an authored root");
+    }
+    if (options.cache) {
+      const cached = this.sessionRoots.get(options.sessionId);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const inflight = this.sessionRootInflight.get(options.sessionId);
+      if (inflight !== undefined) {
+        return inflight;
+      }
+    }
+    const resolve = async (): Promise<FileSystem> => {
+      if (typeof authored !== "function") {
+        return authored;
+      }
+      const host = this.hostForSession(
+        options.cache ? options.sessionId : undefined
+      );
+      const ctx: RootContext = {
+        sessionId: options.sessionId,
+        agentName: this.project.agent.name,
+        ...(options.continuationKey === undefined
+          ? {}
+          : { continuationKey: options.continuationKey }),
+        host: { files: host.files, reminders: host.reminders },
+      };
+      return await authored(ctx);
+    };
+    if (!options.cache) {
+      return resolve();
+    }
+    const pending = resolve();
+    this.sessionRootInflight.set(options.sessionId, pending);
+    try {
+      const resolved = await pending;
+      this.sessionRoots.set(options.sessionId, resolved);
+      return resolved;
+    } finally {
+      this.sessionRootInflight.delete(options.sessionId);
+    }
+  }
+
+  private dropTurnFileSystem(sessionId: string): void {
+    this.turnRoots.delete(sessionId);
+  }
+
+  private async prepareScratchToolInput(options: {
+    sessionId?: string;
+    input: Record<string, unknown>;
+  }): Promise<Record<string, unknown>> {
+    if (options.sessionId === undefined) {
+      return options.input;
+    }
+    const turn = this.turnRoots.get(options.sessionId);
+    if (turn === undefined) {
+      return options.input;
+    }
+    await ingestHostAgentToolsScratch({
+      cwd: turn.cwd,
+      root: turn.root,
+    });
+    return remapScratchPaths(options.input, turn.cwd);
+  }
+
+  private withTurnScratchTools(
+    tools: DiscoveredTool[],
+    sessionId: string
+  ): DiscoveredTool[] {
+    const turn = this.turnRoots.get(sessionId);
+    if (turn === undefined) {
+      return tools;
+    }
+    return tools.map((tool) => {
+      const execute = tool.definition.execute;
+      if (typeof execute !== "function") {
+        return tool;
+      }
+      return {
+        ...tool,
+        definition: {
+          ...tool.definition,
+          execute: async (input, ctx) => {
+            const remapped = await this.prepareScratchToolInput({
+              sessionId,
+              input:
+                input !== null &&
+                typeof input === "object" &&
+                !Array.isArray(input)
+                  ? (input as Record<string, unknown>)
+                  : {},
+            });
+            return execute(remapped as never, ctx);
+          },
+        },
+      };
+    });
+  }
+
+  private async nativeFileSystemOutcome(options: {
+    toolName: string;
+    input: unknown;
+    callId: string;
+    sessionId?: string;
+    continuationKey?: string;
+    cwd: string;
+    dryRun?: boolean;
+  }): Promise<ToolCallOutcome | undefined> {
+    const { toolName, input, callId } = options;
+    if (!isFileSystemToolAlias(toolName)) {
+      return undefined;
+    }
+    // Same policy the authored callTool path asks: a dry-run write is
+    // answered by the host. Native edit/delete used to return before
+    // decideToolCall and persist through the FileSystem.
+    const decision = decideToolCall({
+      dryRun: options.dryRun === true,
+      effect: isMutatingFileSystemTool(toolName) ? "write" : "read",
+      input,
+    });
+    if (decision.kind === "answer") {
+      return {
+        callId,
+        toolName,
+        isError: false,
+        result: decision.result,
+        durationMs: 0,
+        sessionId: options.sessionId,
+      };
+    }
+    const root = await this.resolveFileSystem({
+      sessionId: options.sessionId ?? callId,
+      continuationKey: options.continuationKey,
+      cache: options.sessionId !== undefined,
+      cwd: options.cwd,
+    });
+    const rawArgs =
+      input !== null && typeof input === "object" && !Array.isArray(input)
+        ? (input as Record<string, unknown>)
+        : {};
+    const args = await this.prepareScratchToolInput({
+      sessionId: options.sessionId,
+      input: rawArgs,
+    });
+    const tool = fileSystemTool(root, toolName, args);
+    const execute = tool?.definition.execute;
+    if (tool === undefined || typeof execute !== "function") {
+      // A resolved root owns this native name. Falling through would let
+      // an authored lookalike run, or surface UnknownToolError after we
+      // already advertised the FileSystem tool.
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: {
+          status: "error",
+          error: { message: `FileSystem cannot handle ${toolName}` },
+        },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: `FileSystem cannot handle ${toolName}`,
+      };
+    }
+    const validation = validateToolInput(tool.definition.inputSchema, args);
+    if (!validation.ok) {
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: {
+          status: "error",
+          error: { message: validation.message },
+        },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: validation.message,
+      };
+    }
+    try {
+      const value = await execute(
+        validation.value as never,
+        {
+          toolCallId: callId,
+          workspaceDir: options.cwd,
+        } as never
+      );
+      return {
+        callId,
+        toolName,
+        isError: false,
+        result: normalizeToolResult(value),
+        durationMs: 0,
+        sessionId: options.sessionId,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: { status: "error", error: { message } },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: message,
+      };
+    }
+  }
+
   /**
    * Local harness cwd for a session: per-send override, else the shared
    * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
@@ -1820,19 +2126,22 @@ export class SessionEngine {
     if (
       workspaceDir === undefined ||
       agent.runtime !== "local" ||
+      this.hasRootOverride() ||
       this.runner.prewarm === undefined
     ) {
       return;
     }
     const startedAt = Date.now();
     try {
+      const harness = resolveHostHarnessToolOptions(agent.allowedTools);
       const outcome = await this.runner.prewarm({
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
-        ...(agent.allowedTools === undefined
+        ...(harness.tools === undefined ? {} : { tools: harness.tools }),
+        ...(harness.disallowedTools === undefined
           ? {}
-          : { tools: agent.allowedTools }),
+          : { disallowedTools: harness.disallowedTools }),
         // No session yet, so auth'd connections are omitted rather than
         // warmed without an identity; the per-send flag still has to match
         // the turns' requests or the warmed executor is one no turn asks for.
@@ -1922,22 +2231,24 @@ export class SessionEngine {
         // cwd is overridden (e.g. a PR worktree). A/B variant instruction
         // overlays are applied via agentForSession.
         const agent = this.agentForSession(record);
-        await materializeWorkspace({
-          agent,
-          workspaceDir,
-          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
-        // just below. Only for directories this session owns — a borrowed
-        // checkout or worktree keeps its own root.
-        if (!this.hasBorrowedWorkspace(record)) {
-          await ensureOwnGitRoot(harnessCwd);
+        if (!this.hasRootOverride()) {
+          await materializeWorkspace({
+            agent,
+            workspaceDir,
+            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
+          // just below. Only for directories this session owns — a borrowed
+          // checkout or worktree keeps its own root.
+          if (!this.hasBorrowedWorkspace(record)) {
+            await ensureOwnGitRoot(harnessCwd);
+          }
+          await this.materializeNudgeCarrier(record, harnessCwd);
         }
-        await this.materializeNudgeCarrier(record, harnessCwd);
         // Baseline before the agent can run, so a follow-up that arrives and
         // drains before the first tool boundary still counts as an increase.
         await this.baselineDeliveredNudges(record);
@@ -1947,7 +2258,13 @@ export class SessionEngine {
           pendingFiles !== undefined &&
           Object.keys(pendingFiles).length > 0
         ) {
-          await writeWorkspaceFiles(harnessCwd, pendingFiles);
+          const root = await this.resolveFileSystem({
+            sessionId,
+            continuationKey: record.continuationKey ?? undefined,
+            cache: true,
+            cwd: harnessCwd,
+          });
+          await writeWorkspaceFilesToRoot(root, pendingFiles);
         }
         if (
           (pendingFiles !== undefined &&
@@ -1984,6 +2301,14 @@ export class SessionEngine {
           instructionsInvisibleToHarness,
           emit,
           async (update) => {
+            const turn = this.turnRoots.get(sessionId);
+            if (turn !== undefined) {
+              update = await applyWebScratchUpdate({
+                cwd: turn.cwd,
+                root: turn.root,
+                update,
+              });
+            }
             mapper.handleUpdate(update);
             // Yield so the HTTP NDJSON writer can flush tool start/result
             // events while sibling parallel tools are still executing.
@@ -2006,7 +2331,9 @@ export class SessionEngine {
         this.activeToolContexts.set(sessionId, { record, turnId, emit });
         this.stubbedCallIds.set(sessionId, stubbed);
         try {
-          outcome = await this.runner.runTurn(request);
+          outcome = await this.runTurnExecute(record, turnId, () =>
+            this.runner.runTurn(request)
+          );
         } finally {
           this.activeToolContexts.delete(sessionId);
           this.stubbedCallIds.delete(sessionId);
@@ -2017,6 +2344,7 @@ export class SessionEngine {
         outcome = { status: "error", errorMessage: describeError(error) };
       } finally {
         permit.release();
+        this.dropTurnFileSystem(sessionId);
         this.approvals.cancelSession(sessionId, "deny");
         this.auths.cancelSession(sessionId, "deny");
         await this.clearPendingApprovals(sessionId);
@@ -2049,14 +2377,39 @@ export class SessionEngine {
       outcome = { ...outcome, cost: finalCost };
     }
 
+    const authored = this.project.result;
+    if (outcome.status === "finished" && authored !== undefined) {
+      const settled = await applyAuthoredResult({
+        definition: authored,
+        text: finalResult,
+        dryRun: record.dryRun === true,
+        ctx: {
+          session: this.sessionInfo(record),
+          host: this.hostForSession(sessionId),
+          artifacts: this.artifactsApi({ sessionId, turnId }),
+          stateRoot: this.stateRoot,
+          workspaceDir: harnessCwd,
+        },
+      });
+      if (!settled.ok) {
+        outcome = {
+          status: "error",
+          result: finalResult,
+          errorMessage: `turn output failed: ${settled.message}`,
+          usage: finalUsage,
+          cost: finalCost,
+        };
+      }
+    }
+
     if (outcome.status === "finished") {
       await this.appendEvent(sessionId, {
         type: "turn.completed",
         turnId,
         data: {
-          ...(finalResult === undefined ? {} : { result: finalResult }),
-          ...(finalUsage === undefined ? {} : { usage: finalUsage }),
-          ...(finalCost === undefined ? {} : { cost: finalCost }),
+          result: finalResult,
+          usage: finalUsage,
+          cost: finalCost,
         },
       });
     } else {
@@ -2098,8 +2451,8 @@ export class SessionEngine {
 
     return {
       ...outcome,
-      ...(finalResult === undefined ? {} : { result: finalResult }),
-      ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+      result: finalResult,
+      usage: finalUsage,
     };
   }
 
@@ -2110,48 +2463,75 @@ export class SessionEngine {
    * first-turn S3 scan can discover them. False when the sync fails: the
    * turn then runs without store skills rather than pointing discovery at
    * paths that do not exist.
-   *
-   * With skills authored, every first cloud turn re-copies the authored
+   */
+  private ensureCloudSkillsSynced(store: CloudStoreTarget): Promise<boolean> {
+    const skills = this.project.agent.skills;
+    return this.syncToCloudStore("skills", store, skills.length > 0, () =>
+      syncSkillsToStore({
+        sink: store.sink,
+        agentName: this.project.name,
+        skills,
+        skillsPrefix: store.skillsPrefix,
+      })
+    );
+  }
+
+  /**
+   * Sync `agent/sandbox/workspace/**` seeds onto the Agent Store at
+   * `workspace/…` (hosted) or `agent-serve/<agent>/workspace/…`
+   * (personal-key local+cloud) before the first cloud prompt, which names
+   * the mounted directory (see buildCloudWorkspaceSection).
+   */
+  private ensureCloudWorkspaceSynced(
+    store: CloudStoreTarget
+  ): Promise<boolean> {
+    const seedFiles = this.project.agent.seedFiles;
+    return this.syncToCloudStore("workspace", store, seedFiles.length > 0, () =>
+      syncWorkspaceToStore({
+        sink: store.sink,
+        seedFiles,
+        workspacePrefix: store.workspacePrefix,
+      })
+    );
+  }
+
+  /**
+   * With files authored, every first cloud turn re-copies the authored
    * bytes and the memo only dedupes concurrent first turns. The mount is
    * writable from cloud sessions, so a once-per-process copy would let one
    * session's edits masquerade as agent definition for every later session
    * until the engine restarts; re-syncing keeps the store true to discovery
    * the same way local materialization always rewrites skills. Without
-   * skills the sync is best-effort stale cleanup and one attempt per
-   * process is enough, success or not — a deployment without the files
+   * authored files the sync is best-effort stale cleanup and one attempt
+   * per process is enough, success or not — a deployment without the files
    * surface must not fail and log on every new session for a feature it
    * does not use.
    */
-  private ensureCloudSkillsSynced(): Promise<boolean> {
-    if (this.cloudSkillsSync !== undefined) {
-      return this.cloudSkillsSync;
-    }
-    const target = this.cloudSkillsStore();
-    if (target === undefined) {
-      this.cloudSkillsSync = Promise.resolve(false);
-      return this.cloudSkillsSync;
+  private syncToCloudStore(
+    surface: CloudSyncSurface,
+    store: CloudStoreTarget,
+    authored: boolean,
+    run: () => Promise<void>
+  ): Promise<boolean> {
+    const inFlight = this.cloudSyncs.get(surface);
+    if (inFlight !== undefined) {
+      return inFlight;
     }
-    const skills = this.project.agent.skills;
-    let sync = syncSkillsToStore({
-      sink: target.sink,
-      agentName: this.project.name,
-      skills,
-      skillsPrefix: target.skillsPrefix,
-    }).then(
+    let sync = run().then(
       () => true,
       (error) => {
         this.logger(
-          `[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
+          `[${surface}] ${store.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
         );
         return false;
       }
     );
-    if (skills.length > 0) {
+    if (authored) {
       sync = sync.finally(() => {
-        this.cloudSkillsSync = undefined;
+        this.cloudSyncs.delete(surface);
       });
     }
-    this.cloudSkillsSync = sync;
+    this.cloudSyncs.set(surface, sync);
     return sync;
   }
 
@@ -2159,39 +2539,36 @@ export class SessionEngine {
    * Hosted deployments own the deployment store. Local `serve`/`run` with
    * a personal API key writes into the USER store under `agent-serve/`.
    */
-  private cloudSkillsStore():
-    | {
-        sink: ReturnType<typeof cursorHostedFiles>;
-        skillsPrefix: string;
-        label: string;
-      }
-    | undefined {
+  private cloudStore(): CloudStoreTarget | undefined {
     const v2Hosting = resolveAgentV2Hosting({
       architecture: this.project.agent.architecture,
     });
+    const deployment = {
+      mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
+      skillsPrefix: agentStoreKeys.skillsPrefix(),
+      workspacePrefix: agentStoreKeys.workspacePrefix(),
+      label: "deployment store",
+    };
     if (v2Hosting.kind === "cursor-managed") {
       return {
         sink: cursorHostedFiles({
           resolveStoreSourceId: () =>
             v2Hosting.resolveStoreIds().deploymentStoreSourceId,
         }),
-        skillsPrefix: agentStoreKeys.skillsPrefix(),
-        label: "deployment store",
+        ...deployment,
       };
     }
     if (v2Hosting.kind === "not-v2" && isCursorHostedFilesAvailable()) {
-      return {
-        sink: cursorHostedFiles(),
-        skillsPrefix: agentStoreKeys.skillsPrefix(),
-        label: "deployment store",
-      };
+      return { sink: cursorHostedFiles(), ...deployment };
     }
     if (isCursorUserStoreFilesAvailable()) {
       return {
         sink: cursorHostedFiles({
           storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
         }),
+        mountPath: USER_STORE_MOUNT_PATH,
         skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+        workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
         label: "user store",
       };
     }
@@ -2220,6 +2597,17 @@ export class SessionEngine {
     // allowlist, and a restriction that silently does not apply is worse
     // than a refused turn. Non-local agents already fail discovery; this
     // guards hybrid agents' per-send cloud sessions.
+    //
+    // Factory roots omit `allowedTools` at discovery (the live handle is
+    // resolved per session). The allowlist guard below therefore never
+    // fires for `defineAgent({ root: (ctx) => … })` with omitted `tools`,
+    // and a per-send `cloud` attach would skip the virtual-root allowlist
+    // and run unrestricted on a VM. Any authored root refuses non-local turns.
+    if (runtime !== "local" && this.hasRootOverride()) {
+      throw new Error(
+        `Agent "${agent.name}" declares root, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`
+      );
+    }
     if (runtime !== "local" && agent.allowedTools !== undefined) {
       throw new Error(
         `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`
@@ -2248,6 +2636,48 @@ export class SessionEngine {
             override: record.cloudOverride,
           })
         : undefined;
+    const authoredRoot = this.hasRootOverride();
+    const root =
+      runtime === "local"
+        ? await this.resolveFileSystem({
+            sessionId: record.sessionId,
+            continuationKey: record.continuationKey ?? undefined,
+            cache: true,
+            cwd: this.harnessCwd(record),
+          })
+        : undefined;
+    const harnessTools =
+      runtime === "local" && root !== undefined
+        ? authoredRoot
+          ? {
+              tools: resolveFileSystemTools({
+                root,
+                tools: agent.allowedTools,
+              }),
+            }
+          : resolveHostHarnessToolOptions(agent.allowedTools)
+        : undefined;
+    const fileTools =
+      root === undefined
+        ? []
+        : synthesizeFileSystemTools(
+            root,
+            authoredRoot
+              ? rootFileToolsFromAuthored(agent.allowedTools)
+              : hostFileToolsFromAuthored(agent.allowedTools)
+          );
+    // Host-default keeps native SemanticSearch (the host index).
+    // `localFileSystem.search` is empty, so synthesizing would
+    // replace a working index with an empty custom tool.
+    const synthesized =
+      root === undefined
+        ? []
+        : this.withTurnScratchTools(
+            authoredRoot
+              ? fileTools
+              : fileTools.filter((tool) => tool.name !== "SemanticSearch"),
+            record.sessionId
+          );
     let turnPrompt = prompt;
     if (isFirstTurn) {
       const contextBlock = buildSessionContextBlock({
@@ -2263,13 +2693,14 @@ export class SessionEngine {
     if (isFirstTurn) {
       if (runtime === "cloud") {
         // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies. On hosted deployments authored
-        // skills land on the store mount for native discovery, and the
-        // shared memory journal is on that mount too — say where. When the
-        // turn carries the session-bound server-tool MCP endpoint, the
-        // preamble catalogs server tools under that MCP server name *before*
-        // the agent-tool "write the script if missing" recipe, so a model
-        // told to "use <server tool>" calls MCP instead of inventing a .sh.
+        // including agent tool script bodies. Authored skills and workspace
+        // seeds land on the store mount (skills for native discovery, seeds
+        // for the model's file tools), and on hosted deployments the shared
+        // memory journal is on that mount too — say where. When the turn
+        // carries the session-bound server-tool MCP endpoint, the preamble
+        // catalogs server tools under that MCP server name *before* the
+        // agent-tool "write the script if missing" recipe, so a model told
+        // to "use <server tool>" calls MCP instead of inventing a .sh.
         const preamble = buildAgentsMdContent(agent, {
           includeScripts: true,
           serverToolsMcpName:
@@ -2278,17 +2709,42 @@ export class SessionEngine {
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
         const hosted = isCursorHostedFilesAvailable();
-        // Synced whenever a store is reachable, not just when skills exist:
-        // removing the last skill has to delete its store copies too.
-        // Discovery is native (`--agent-store-skills-dir`); this only has
-        // to land the bytes.
-        if (hosted || isCursorUserStoreFilesAvailable()) {
-          await this.ensureCloudSkillsSynced();
+        // Synced whenever a store is reachable, not just when skills or
+        // seeds exist: removing the last one has to delete its store copies
+        // too.
+        const store =
+          hosted || isCursorUserStoreFilesAvailable()
+            ? this.cloudStore()
+            : undefined;
+        let sections = "";
+        if (store !== undefined) {
+          const [, seedsSynced] = await Promise.all([
+            this.ensureCloudSkillsSynced(store),
+            this.ensureCloudWorkspaceSynced(store),
+          ]);
+          // Only name the mount when the bytes landed; a failed sync must
+          // not send the model looking for files that are not there.
+          if (seedsSynced && agent.seedFiles.length > 0) {
+            const dir = `${store.mountPath}/${store.workspacePrefix}`;
+            sections += `\n\n${buildCloudWorkspaceSection(dir)}`;
+          }
+        }
+        if (hosted) {
+          sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
         }
-        const memorySection = hosted
-          ? `\n\n${buildCloudMemorySection(this.project.name)}`
-          : "";
-        turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
+        turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
+      } else if (runtime === "local" && authoredRoot) {
+        // Virtual roots skip materialize, so AGENTS.md never lands on disk.
+        // Ship the same preamble the borrowed-cwd local path uses.
+        const preamble = buildAgentsMdContent(
+          { ...agent, tools: [...agent.tools, ...synthesized] },
+          { includeScripts: true }
+        );
+        const workspaceInfo = `<user_info>\nWorkspace Path: /\n</user_info>`;
+        turnPrompt =
+          preamble === ""
+            ? `${workspaceInfo}\n\n${turnPrompt}`
+            : `${workspaceInfo}\n\n${preamble}\n\n${turnPrompt}`;
       } else if (runtime === "local" && instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
         // borrowed harness cwd, agent tool scripts live only in the durable
@@ -2307,9 +2763,18 @@ export class SessionEngine {
         ? {}
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
-      sandbox: this.project.agent.local?.sandbox === true,
-      ...(runtime === "local" && agent.allowedTools !== undefined
-        ? { tools: agent.allowedTools }
+      sandbox: authoredRoot
+        ? false
+        : this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && harnessTools !== undefined
+        ? {
+            ...(harnessTools.tools === undefined
+              ? {}
+              : { tools: harnessTools.tools }),
+            ...(harnessTools.disallowedTools === undefined
+              ? {}
+              : { disallowedTools: harnessTools.disallowedTools }),
+          }
         : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
@@ -2333,7 +2798,13 @@ export class SessionEngine {
         : {}),
       customTools:
         runtime === "local"
-          ? await this.buildCustomTools(record, agent, turnId, emit)
+          ? await this.buildCustomTools(
+              record,
+              agent,
+              turnId,
+              emit,
+              synthesized
+            )
           : {},
       mcpServers: this.buildMcpServers(
         runtime,
@@ -2627,7 +3098,8 @@ export class SessionEngine {
     record: SessionRecord,
     agent: ResolvedAgent,
     turnId: string,
-    emit: (payload: SessionEventPayload) => void
+    emit: (payload: SessionEventPayload) => void,
+    extraTools: DiscoveredTool[] = []
   ): Promise<Record<string, SDKCustomTool>> {
     const tools: Record<string, SDKCustomTool> = {};
     const register = (tool: ResolvedAgent["tools"][number]): void => {
@@ -2657,7 +3129,7 @@ export class SessionEngine {
         },
       };
     };
-    for (const tool of agent.tools) {
+    for (const tool of [...agent.tools, ...extraTools]) {
       if (tool.execution !== "server") {
         continue;
       }
@@ -2880,6 +3352,31 @@ export class SessionEngine {
     }
   }
 
+  /**
+   * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+   * turn span for the whole harness run. Host files / VFS RPCs happen
+   * here, not under `runInCall`. No-op when OTel is off.
+   */
+  private runTurnExecute<T>(
+    record: SessionRecord,
+    turnId: string,
+    fn: () => T | Promise<T>
+  ): Promise<T> {
+    const otel = this.otel;
+    const run = (): Promise<T> => Promise.resolve(fn());
+    if (otel === undefined) {
+      return run();
+    }
+    return otel.runInTurn(
+      {
+        sessionId: record.sessionId,
+        session: this.sessionInfo(record),
+        turnId,
+      },
+      run
+    );
+  }
+
   /**
    * Bind outbound inject (Factory / Cursor API `traceparent`) to the
    * tool span. No-op when OTel is off.
@@ -3572,6 +4069,27 @@ export class SessionEngine {
     const session = identity.session;
     let workspaceDir = identity.workspaceDir;
     let scratchDir = identity.scratchDir;
+    if (
+      isFileSystemToolAlias(toolName) &&
+      identity.busy &&
+      record !== undefined &&
+      isMutatingFileSystemTool(toolName)
+    ) {
+      throw new SessionBusyError(record.sessionId);
+    }
+    const native = await this.nativeFileSystemOutcome({
+      toolName,
+      input,
+      callId,
+      sessionId: record?.sessionId,
+      continuationKey:
+        record?.continuationKey ?? session.continuationKey ?? undefined,
+      cwd: workspaceDir,
+      dryRun: record?.dryRun === true,
+    });
+    if (native !== undefined) {
+      return native;
+    }
     let tool = this.project.agent.tools.find((t) => t.name === toolName);
     if (
       tool === undefined &&
@@ -3673,7 +4191,10 @@ export class SessionEngine {
       record !== undefined &&
       identity.busy &&
       this.materializedWorkspaces.has(record.sessionId);
-    if (record === undefined || workspaceUnavailable || !turnMaterialized) {
+    if (
+      !this.hasRootOverride() &&
+      (record === undefined || workspaceUnavailable || !turnMaterialized)
+    ) {
       await materializeWorkspace({
         agent: this.project.agent,
         workspaceDir:
@@ -4011,7 +4532,10 @@ export class SessionEngine {
       return;
     }
 
-    const sessionCtx = { session: this.sessionInfo(record) };
+    const sessionCtx: SessionContext = {
+      session: this.sessionInfo(record),
+      host: this.hostForSession(record.sessionId),
+    };
     const channelEvents = this.channelEventHandlersFor(record.channelId);
     if (channelEvents !== undefined) {
       // Handlers are declared against the narrowed event for their key; the
@@ -4054,14 +4578,13 @@ export class SessionEngine {
         }
         try {
           await handler(event, {
+            ...sessionCtx,
             agent: { name: this.project.name },
             channel: {
               id: record.channelId,
               continuationToken: record.continuationKey,
             },
-            session: this.sessionInfo(record),
             stateRoot: this.stateRoot,
-            host: this.hostForSession(record.sessionId),
             artifacts: this.artifactsApi({
               sessionId: record.sessionId,
               turnId: event.turnId,
@@ -4078,12 +4601,12 @@ export class SessionEngine {
     if (this.abCollector.enabled) {
       await this.abCollector.onEvent(
         event,
-        this.sessionInfo(record),
+        sessionCtx.session,
         this.project.name
       );
     }
 
-    this.otel?.onEvent(event, this.sessionInfo(record));
+    this.otel?.onEvent(event, sessionCtx.session);
   }
 
   private channelEventHandlersFor(
@@ -4633,9 +5156,8 @@ export class SessionEngine {
     }
     const record = await this.sessions.get(sessionId);
     const sdkAgentId =
-      (record?.sdkAgentId !== undefined && record.sdkAgentId.startsWith("bc-")
-        ? record.sdkAgentId
-        : undefined) ?? cloudSdkAgentIdFromEvents(events);
+      (record?.sdkAgentId?.startsWith("bc-") ? record.sdkAgentId : undefined) ??
+      cloudSdkAgentIdFromEvents(events);
     if (sdkAgentId === undefined) {
       return;
     }
@@ -5191,10 +5713,6 @@ function buildRunnerSubagents(agent: ResolvedAgent): RunnerSubagent[] {
   }));
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function toolErrorResult(message: string): SDKCustomToolResult {
   return {
     content: [{ type: "text", text: message }],