@cursor/july 0.1.104 → 0.1.105

package/src/internal/hosted-delivery.ts

@@ -358,6 +358,13 @@ export function registerHostedDeliveryRoute(input: {
   flushStartLog?(startLogId: string): Promise<void>;
   /** Snapshot of the process log ring at persist time. */
   snapshotLogs?(): LogRingEntry[];
+  /**
+   * Drop the cached SDK agent handle before the HTTP reply. Hosted v2
+   * hibernates this process as soon as the reply lands; leaving the handle
+   * in memory freezes a dead Connect/HTTP2 session that the next wake
+   * then reuses.
+   */
+  evictSdkSession?(sessionId: string): void;
   /**
    * Wait until guest egress works before authored admission/execution.
    * Defaults to {@link waitForGuestNetworkReady}. Tests inject a stub.
@@ -463,8 +470,18 @@ export function registerHostedDeliveryRoute(input: {
         if (unconsumed !== undefined) {
           return finish(unconsumed);
         }
-        const delivery = parseHostedAdmission(await readJsonObject(request));
+        const rawAdmission = await readJsonObject(request);
+        const delivery = parseHostedAdmission(rawAdmission);
         if (delivery === undefined) {
+          const rawKeys =
+            typeof rawAdmission === "object" &&
+            rawAdmission !== null &&
+            !Array.isArray(rawAdmission)
+              ? Object.keys(rawAdmission as Record<string, unknown>)
+              : [];
+          console.info(
+            `[agent-sdk] hosted admission rejected: envelope failed to parse keys=${JSON.stringify(rawKeys)} hasManagedAutomation=${String(rawKeys.includes("managedAutomation"))}`
+          );
           return finish(
             errorResponse(
               400,
@@ -473,6 +490,9 @@ export function registerHostedDeliveryRoute(input: {
             )
           );
         }
+        console.info(
+          `[agent-sdk] hosted admission received deliveryId=${delivery.deliveryId} channelId=${delivery.channelId} channelKind=${delivery.channelKind} eventType=${delivery.eventType} sessionMode=${delivery.sessionMode} managedAutomation=${delivery.managedAutomation === undefined ? "<absent>" : `automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${delivery.managedAutomation.slackChannels === undefined ? "<absent>" : JSON.stringify(delivery.managedAutomation.slackChannels)}`}`
+        );
         recordHostedManagedAutomation(delivery);
         const channel = input.channels.find(
           (candidate) => candidate.id === delivery.channelId
@@ -624,6 +644,7 @@ export function registerHostedDeliveryRoute(input: {
             sessionId: "",
             turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
           });
+          let sessionId = "";
           try {
             const args = input.buildHandlerArgs(
               admitted.send.channelId,
@@ -635,10 +656,19 @@ export function registerHostedDeliveryRoute(input: {
                 key: admitted.send.mailboxContinuationKey,
               },
             });
+            sessionId = session.id;
             const outcome = await session.waitForCompletion();
             // Failed turns drain too: their record/continuation updates must
             // survive the park just like a finished turn's.
             await input.drainSessionDurability?.(session.id);
+            // Evict before the reply: TAS parks and hibernates this process
+            // as soon as the POST returns. A leftover SDK handle freezes a
+            // dead Connect/HTTP2 session that the next wake then reuses.
+            evictHostedSdkSessions(
+              input.evictSdkSession,
+              session.id,
+              execution.sessionPublicId
+            );
             await writeDiag({
               sessionId: session.id,
               turnStatus: outcome.status,
@@ -671,6 +701,11 @@ export function registerHostedDeliveryRoute(input: {
               },
             };
           } catch (error) {
+            evictHostedSdkSessions(
+              input.evictSdkSession,
+              sessionId,
+              execution.sessionPublicId
+            );
             await writeDiag({
               sessionId: "",
               turnStatus: "error",
@@ -687,6 +722,23 @@ export function registerHostedDeliveryRoute(input: {
   });
 }
 
+function evictHostedSdkSessions(
+  evict: ((sessionId: string) => void) | undefined,
+  ...ids: Array<string | undefined>
+): void {
+  if (evict === undefined) {
+    return;
+  }
+  const seen = new Set<string>();
+  for (const id of ids) {
+    if (id === undefined || id === "" || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    evict(id);
+  }
+}
+
 function hostedErrorForUnfinishedTurn(
   errorMessage: string | undefined
 ): typeof GUEST_CONNECT_STALLED | "turn_failed" {

package/src/internal/hosted-managed-automation.ts

@@ -17,10 +17,36 @@
 
 import type { HostedAdmissionManagedAutomation } from "./hosted-delivery-protocol.js";
 
-const managedAutomationByDelivery = new Map<
-  string,
-  { managedAutomation: HostedAdmissionManagedAutomation; expiresAt: number }
->();
+type ManagedAutomationEntry = {
+  managedAutomation: HostedAdmissionManagedAutomation;
+  expiresAt: number;
+};
+
+/**
+ * Process-wide slot for the table. Hosted engines run the compiled CLI
+ * (`dist/`), which records at admission, while first-party factory agents
+ * relative-import this file from `src/` and read at finalize — two module
+ * instances in one process. A module-local Map would be recorded in one
+ * copy and read from the other (always undefined, so a fork never sees its
+ * Slack channels or MCP servers); the shared symbol keeps one table.
+ */
+const MANAGED_AUTOMATION_TABLE_KEY = Symbol.for(
+  "cursor.agentkit.hostedManagedAutomationByDelivery"
+);
+
+function managedAutomationTable(): Map<string, ManagedAutomationEntry> {
+  const slots = globalThis as unknown as Record<
+    symbol,
+    Map<string, ManagedAutomationEntry> | undefined
+  >;
+  let table = slots[MANAGED_AUTOMATION_TABLE_KEY];
+  if (table === undefined) {
+    table = new Map();
+    slots[MANAGED_AUTOMATION_TABLE_KEY] = table;
+  }
+  return table;
+}
+
 /** Long enough to outlive a slow review run kicked off by the delivery. */
 const MANAGED_AUTOMATION_TTL_MS = 60 * 60_000;
 const MANAGED_AUTOMATION_MAX_ENTRIES = 10_000;
@@ -30,8 +56,12 @@ export function recordHostedManagedAutomation(delivery: {
   managedAutomation?: HostedAdmissionManagedAutomation;
 }): void {
   if (delivery.managedAutomation === undefined) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation not recorded deliveryId=${delivery.deliveryId}: admission envelope carried no managedAutomation slice (non-managed delivery, or the control plane resolved no MCP servers and no Slack channels)`
+    );
     return;
   }
+  const managedAutomationByDelivery = managedAutomationTable();
   const now = Date.now();
   for (const [key, entry] of managedAutomationByDelivery) {
     if (entry.expiresAt <= now) {
@@ -39,12 +69,19 @@ export function recordHostedManagedAutomation(delivery: {
     }
   }
   if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation table full (${String(managedAutomationByDelivery.size)} entries); clearing before recording deliveryId=${delivery.deliveryId}`
+    );
     managedAutomationByDelivery.clear();
   }
   managedAutomationByDelivery.set(delivery.deliveryId, {
     managedAutomation: delivery.managedAutomation,
     expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
   });
+  const slackChannels = delivery.managedAutomation.slackChannels;
+  console.info(
+    `[agent-sdk] hosted managedAutomation recorded deliveryId=${delivery.deliveryId} automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${slackChannels === undefined ? "<absent>" : JSON.stringify(slackChannels)} ttlMs=${String(MANAGED_AUTOMATION_TTL_MS)} tableSize=${String(managedAutomationByDelivery.size)}`
+  );
 }
 
 /**
@@ -55,11 +92,18 @@ export function recordHostedManagedAutomation(delivery: {
 export function getHostedManagedAutomation(
   deliveryId: string
 ): HostedAdmissionManagedAutomation | undefined {
+  const managedAutomationByDelivery = managedAutomationTable();
   const entry = managedAutomationByDelivery.get(deliveryId);
   if (entry === undefined) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation lookup miss deliveryId=${deliveryId}: no entry (never recorded in this process, or evicted) tableSize=${String(managedAutomationByDelivery.size)} knownDeliveryIds=${JSON.stringify([...managedAutomationByDelivery.keys()].slice(0, 10))}`
+    );
     return undefined;
   }
   if (entry.expiresAt <= Date.now()) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation lookup expired deliveryId=${deliveryId} automationUuid=${entry.managedAutomation.automationUuid} expiredMsAgo=${String(Date.now() - entry.expiresAt)}`
+    );
     managedAutomationByDelivery.delete(deliveryId);
     return undefined;
   }
@@ -68,5 +112,5 @@ export function getHostedManagedAutomation(
 
 /** Drop recorded managed-automation slices (tests only). */
 export function resetHostedManagedAutomationForTest(): void {
-  managedAutomationByDelivery.clear();
+  managedAutomationTable().clear();
 }

package/src/internal/init-project.ts

@@ -77,6 +77,7 @@ const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agents-md": { dir: "agents-md" },
   "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
+  "grokbot-agents": { dir: "grokbot-agents" },
   "pr-autofixer": { dir: "pr-autofixer" },
   "security-help": { dir: "security-help" },
   "security-reviewer": { dir: "security-reviewer" },
@@ -711,6 +712,7 @@ export function printInitGuide(): void {
 Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./grokbot --template grokbot-agents    # talk to Grok Bot agents
   npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
   npx ${PACKAGE_NAME} init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
@@ -719,8 +721,9 @@ Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-triage --template triage-jira     # comment on Jira issues
   npx ${PACKAGE_NAME} init ./my-owners --template agentic-owners  # review PRs via owners policies
   npx ${PACKAGE_NAME} init ./pr-autofixer --template pr-autofixer # fix PRs on a cloud VM
-  # TTY asks for GitHub repos. Scripts pass --var:
+  # TTY asks the template's questions. Scripts pass --var:
   #   --var repos=acme/widgets,acme/api
+  #   --var agents="Plan Keeper, Chief of Staff"
   cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):

package/src/internal/sdk-runner.ts

@@ -432,6 +432,25 @@ export class CursorSdkRunner implements AgentRunner {
     return { warmed: true };
   }
 
+  /**
+   * Drop the cached SDK agent for this session, if one is open.
+   *
+   * Hosted v2 parks and hibernates this process as soon as the execution
+   * reply lands on non-interactive channels. A leftover handle still holds
+   * the pre-freeze Connect/HTTP2 session; the next wake then reuses it and
+   * `AgentService/Run` never starts. Call after `waitForCompletion` so the
+   * hibernate snapshot has an empty cache. Slack's interactive hot-window
+   * still reuses handles because that path does not go through hosted
+   * delivery.
+   */
+  evictSession(sessionId: string): void {
+    const cached = this.agents.get(sessionId);
+    if (cached === undefined) {
+      return;
+    }
+    this.evictAgent(sessionId, cached.agent);
+  }
+
   async dispose(): Promise<void> {
     const releases = this.prewarmReleases.splice(0);
     await Promise.allSettled(releases.map((release) => release()));

package/src/internal/server.ts

@@ -918,6 +918,13 @@ export async function startServer(
       ...(accountRefs !== undefined && accountBridge !== undefined
         ? { accountBridge, accountRefs }
         : {}),
+      ...(sdkRunner instanceof CursorSdkRunner
+        ? {
+            evictSdkSession: (sessionId: string) => {
+              sdkRunner.evictSession(sessionId);
+            },
+          }
+        : {}),
     });
     for (const channel of project.channels) {
       const definition = channel.definition;
@@ -1440,6 +1447,12 @@ function mountAgentRoutes(
      * here so the Temporal host can read a stable path after the POST.
      */
     diagStateRoot?: string;
+    /**
+     * Drop the cached SDK agent handle after a hosted turn so hibernate
+     * cannot snapshot a frozen Connect/HTTP2 session. Injected test
+     * runners may omit this.
+     */
+    evictSdkSession?: (sessionId: string) => void;
   }
 ): void {
   const { slug, project, engine, scheduleRunner, reminderRunner } = runtime;
@@ -1523,6 +1536,9 @@ function mountAgentRoutes(
             flushStartLog,
           }),
       snapshotLogs: () => logRing.since(),
+      ...(args.evictSdkSession === undefined
+        ? {}
+        : { evictSdkSession: args.evictSdkSession }),
     });
   }
   // Playground lists/opens Slack (and other channel) sessions across

package/src/internal/session-engine.ts

@@ -202,13 +202,19 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  buildCloudSessionWorkspaceSection,
   buildCloudWorkspaceSection,
   ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
 } from "./workspace.js";
-import { syncWorkspaceToStore } from "./workspace-sync.js";
+import {
+  syncSessionWorkspaceFiles,
+  syncWorkspaceToStore,
+  WorkspaceFileRefusal,
+  wipeSessionWorkspace,
+} from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
@@ -222,6 +228,7 @@ interface CloudStoreTarget {
   mountPath: string;
   skillsPrefix: string;
   workspacePrefix: string;
+  sessionWorkspacePrefix: (sessionId: string) => string;
   label: string;
 }
 
@@ -2254,10 +2261,13 @@ export class SessionEngine {
         await this.baselineDeliveredNudges(record);
         const pendingFiles = record.pendingWorkspaceFiles;
         const pendingImages = record.pendingImages;
-        if (
-          pendingFiles !== undefined &&
-          Object.keys(pendingFiles).length > 0
-        ) {
+        const runtime = resolveSessionRuntime({
+          agentRuntime: agent.runtime,
+          cloudOverride: record.cloudOverride,
+        });
+        const hasPendingFiles =
+          pendingFiles !== undefined && Object.keys(pendingFiles).length > 0;
+        if (hasPendingFiles && runtime !== "cloud") {
           const root = await this.resolveFileSystem({
             sessionId,
             continuationKey: record.continuationKey ?? undefined,
@@ -2267,13 +2277,14 @@ export class SessionEngine {
           await writeWorkspaceFilesToRoot(root, pendingFiles);
         }
         if (
-          (pendingFiles !== undefined &&
-            Object.keys(pendingFiles).length > 0) ||
+          (hasPendingFiles && runtime !== "cloud") ||
           (pendingImages !== undefined && pendingImages.length > 0)
         ) {
           await this.updateRecord(sessionId, (current) => ({
             ...current,
             pendingWorkspaceFiles:
+              hasPendingFiles &&
+              runtime !== "cloud" &&
               current.pendingWorkspaceFiles === pendingFiles
                 ? undefined
                 : current.pendingWorkspaceFiles,
@@ -2441,6 +2452,7 @@ export class SessionEngine {
               data: { message: outcome.errorMessage ?? "task failed" },
             }
       );
+      await this.wipeCloudSessionWorkspace(sessionId);
     } else {
       await this.appendEvent(sessionId, {
         type: "session.waiting",
@@ -2495,6 +2507,68 @@ export class SessionEngine {
     );
   }
 
+  /**
+   * Replace this session's store prefix with the pending `workspaceFiles`.
+   * Undefined when the write did not land; the prompt must not name the
+   * mount, matching ensureCloudWorkspaceSynced.
+   */
+  private async syncCloudSessionWorkspaceFiles(
+    store: CloudStoreTarget,
+    sessionId: string,
+    files: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<{ dir: string; relPaths: string[] } | undefined> {
+    const workspacePrefix = store.sessionWorkspacePrefix(sessionId);
+    try {
+      const relPaths = await syncSessionWorkspaceFiles({
+        sink: store.sink,
+        files,
+        workspacePrefix,
+      });
+      return {
+        dir: `${store.mountPath}/${workspacePrefix}`,
+        relPaths,
+      };
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files sync failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      if (error instanceof WorkspaceFileRefusal) {
+        await this.clearPendingWorkspaceFiles(sessionId, files);
+      }
+      return undefined;
+    }
+  }
+
+  private async wipeCloudSessionWorkspace(sessionId: string): Promise<void> {
+    const store = this.cloudStore();
+    if (store === undefined) {
+      return;
+    }
+    try {
+      await wipeSessionWorkspace({
+        sink: store.sink,
+        workspacePrefix: store.sessionWorkspacePrefix(sessionId),
+      });
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files wipe failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  private async clearPendingWorkspaceFiles(
+    sessionId: string,
+    pending: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingWorkspaceFiles:
+        current.pendingWorkspaceFiles === pending
+          ? undefined
+          : current.pendingWorkspaceFiles,
+    }));
+  }
+
   /**
    * With files authored, every first cloud turn re-copies the authored
    * bytes and the memo only dedupes concurrent first turns. The mount is
@@ -2547,6 +2621,8 @@ export class SessionEngine {
       mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
       skillsPrefix: agentStoreKeys.skillsPrefix(),
       workspacePrefix: agentStoreKeys.workspacePrefix(),
+      sessionWorkspacePrefix: (sessionId: string) =>
+        agentStoreKeys.sessionWorkspacePrefix(sessionId),
       label: "deployment store",
     };
     if (v2Hosting.kind === "cursor-managed") {
@@ -2569,6 +2645,11 @@ export class SessionEngine {
         mountPath: USER_STORE_MOUNT_PATH,
         skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
         workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
+        sessionWorkspacePrefix: (sessionId: string) =>
+          agentStoreKeys.userSessionWorkspacePrefix(
+            this.project.name,
+            sessionId
+          ),
         label: "user store",
       };
     }
@@ -2690,34 +2771,39 @@ export class SessionEngine {
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
-    if (isFirstTurn) {
-      if (runtime === "cloud") {
-        // Cloud VMs have no materialized workspace: ship the full context,
-        // 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, {
+    if (runtime === "cloud") {
+      // Cloud VMs have no materialized workspace: ship the full context,
+      // 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), per-turn workspaceFiles land under
+      // the session prefix, 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 hosted = isCursorHostedFilesAvailable();
+      const store =
+        hosted || isCursorUserStoreFilesAvailable()
+          ? this.cloudStore()
+          : undefined;
+      let preamble = "";
+      const sections: string[] = [];
+      const pending = record.pendingWorkspaceFiles;
+      if (isFirstTurn) {
+        preamble = buildAgentsMdContent(agent, {
           includeScripts: true,
           serverToolsMcpName:
             this.cloudServerToolsConnection === undefined
               ? undefined
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
-        const hosted = isCursorHostedFilesAvailable();
-        // 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) {
+      }
+      if (store !== undefined) {
+        if (isFirstTurn) {
+          // 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 [, seedsSynced] = await Promise.all([
             this.ensureCloudSkillsSynced(store),
             this.ensureCloudWorkspaceSynced(store),
@@ -2725,37 +2811,63 @@ export class SessionEngine {
           // 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)}`;
+            sections.push(
+              buildCloudWorkspaceSection(
+                `${store.mountPath}/${store.workspacePrefix}`
+              )
+            );
           }
         }
-        if (hosted) {
-          sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
+        if (pending !== undefined && Object.keys(pending).length > 0) {
+          const synced = await this.syncCloudSessionWorkspaceFiles(
+            store,
+            record.sessionId,
+            pending
+          );
+          if (synced !== undefined) {
+            sections.push(
+              buildCloudSessionWorkspaceSection(synced.dir, synced.relPaths)
+            );
+            await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+          }
         }
-        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
-        // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-        // reference on-disk paths under the harness cwd. Grokbot turns are
-        // excluded: their instructions ride the request's `instructions`
-        // field into the Sand system prompt instead.
-        const includeScripts = this.hasBorrowedWorkspace(record);
-        const preamble = buildAgentsMdContent(agent, { includeScripts });
-        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+      } else if (pending !== undefined && Object.keys(pending).length > 0) {
+        await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+      }
+      if (isFirstTurn && hosted) {
+        sections.push(buildCloudMemorySection(this.project.name));
       }
+      if (preamble !== "" || sections.length > 0) {
+        turnPrompt = [preamble, ...sections, turnPrompt]
+          .filter((part) => part !== "")
+          .join("\n\n");
+      }
+    } else if (isFirstTurn && 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 (
+      isFirstTurn &&
+      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
+      // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+      // reference on-disk paths under the harness cwd. Grokbot turns are
+      // excluded: their instructions ride the request's `instructions`
+      // field into the Sand system prompt instead.
+      const includeScripts = this.hasBorrowedWorkspace(record);
+      const preamble = buildAgentsMdContent(agent, { includeScripts });
+      turnPrompt = `${preamble}\n\n${turnPrompt}`;
     }
     return {
       sessionId: record.sessionId,

package/src/internal/store-mirror.ts

@@ -1,7 +1,7 @@
 /**
  * Mirror an authored file tree onto an Agent Store prefix. Shared by the
- * skills and workspace seed syncs so both keep the same write-then-sweep
- * discipline and the same path refusals.
+ * skills, workspace seed, and session workspaceFile syncs so they keep the
+ * same write-then-sweep discipline and the same path refusals.
  */
 
 import { posix } from "node:path";