fix: restore preview dependencies after sandbox wake (#202)

## Summary

- Restore disposable pnpm dependencies before a persisted preview or
pnpm-backed process relaunches in a replacement Daytona container.
- Keep the immutable app-builder template on its zero-install fast path
when both manifests match.
- Tighten the FastApply tool contract to consistently produce valid
sparse edits.

## Architecture

Durable Object storage remains the source of truth for process launch
intent and port reservations. On wake or runtime replacement, the Worker
mirrors durable project source onto native sandbox disk, reconciles the
disposable dependency tree, starts the source-sync loop, and then
relaunches the persisted process.

## Decisions Made

| Decision | Choice | Alternatives considered | Reasoning |
|---|---|---|---|
| Dependency recovery | Reconcile with pnpm before every custom process
launch | Trust a `node_modules` presence marker | Presence can be stale
after manifest changes; pnpm is the correctness boundary. |
| Cold-start behavior | Offline-first frozen install with prefer-offline
network fallback | Network-only install | Cached packages restore
quickly while custom dependencies remain recoverable. |
| Template behavior | Compare template package and lock manifests, then
skip install | Always install | The immutable template already has a
baked shared runtime and should remain instant. |
| Edit guidance | Match Morph's exact marker-based contract | Allow
ambiguous sparse edits | Explicit markers prevent accidental deletion
and reduce invalid model calls. |

## Edge Cases Handled

| Scenario | Handling |
|---|---|
| Custom dependencies disappear with a replacement container | Reinstall
from the durable lockfile before process start. |
| Cached package is unavailable offline | Retry through the registry
with bounded network concurrency. |
| Project has no lockfile | Perform a supported prefer-offline install.
|
| Unchanged scaffold uses only baked dependencies | Skip installation
after exact manifest comparison. |
| Sparse edit omits unchanged regions | Schema and tool guidance require
the exact existing-code marker. |

## How to Review

1. Start with `project-sandbox-local-source.ts` for process ordering and
dependency recovery.
2. Check the app-builder and generic process call sites.
3. Review the FastApply descriptions and README update.

## Verification

- [x] `pnpm lint`
- [x] `pnpm typecheck`
- [x] `pnpm turbo build --force`
- [x] `pnpm deadcode`
- [x] `pnpm architecture:check`
- [x] `pnpm turbo skills:build`
- [x] Generated command assertions for ordering, offline fallback,
lockless recovery, and template fast path
- [x] Production explicit FastApply flow reached an atomic
compare-and-swap write
- [ ] Production cold-restore preview QA after Worker deployment and
immutable snapshot promotion

Author: iamjr15

apps/agent-worker/README.md

@@ -158,6 +158,9 @@ content identities rather than unrelated FUSE/native-disk timestamps, performs a
 replacement, and mirrors subsequent writes and deletions within 250 ms, including equal-size and
 shell-based edits. The local source, dependency tree, and build cache are disposable;
 wake and restart reconstruct them from the durable project without changing the Files surface.
+Persisted pnpm-backed preview commands restore a missing sandbox-local dependency tree before the
+server starts, while an unchanged baked app-builder template continues to use the immutable runtime
+without an unnecessary install.
 The immutable sandbox exposes that synchronizer as the root-owned
 `/opt/cheatcode/project-source-sync.py` helper, keeping Worker-to-sandbox command arguments small
 and making the snapshot the source of truth for executable sandbox runtime code.

apps/agent-worker/src/durable-objects/app-builder-local-preview.ts

@@ -1,6 +1,10 @@
 import { shellQuote } from "../sandbox-support";
-import { localProjectProcessCommand } from "./project-sandbox-local-source";
-import { NEXT_RUNTIME_BIN, resolveProjectLocalRuntime } from "./project-sandbox-package-runtime";
+import { localPnpmProjectProcessCommand } from "./project-sandbox-local-source";
+import {
+  NEXT_RUNTIME_BIN,
+  NEXT_TEMPLATE_DIR,
+  resolveProjectLocalRuntime,
+} from "./project-sandbox-package-runtime";
 
 interface LocalPreviewCommandInput {
   port: number;
@@ -25,5 +29,5 @@ export function localNextPreviewCommand(input: LocalPreviewCommandInput): string
   ]
     .map(shellQuote)
     .join(" ");
-  return ["sh", "-lc", localProjectProcessCommand(runtime, nextCommand)];
+  return ["sh", "-lc", localPnpmProjectProcessCommand(runtime, nextCommand, NEXT_TEMPLATE_DIR)];
 }

apps/agent-worker/src/durable-objects/project-sandbox-local-source.ts

@@ -42,17 +42,19 @@ export function localPackageCommand(
 }
 
 /** Runs a long-lived package script on native disk while durable source changes keep flowing in. */
-export function localProjectProcessCommand(
+function localProjectProcessCommand(
   runtime: ProjectLocalRuntime,
   rawCommand: string,
+  prepareCommand?: string,
 ): string {
   const syncOnce = localSourceSyncCommand(runtime, "preview-once");
   const syncLoop = localSourceSyncCommand(runtime, "preview-loop");
   return [
     `${syncOnce} || exit $?`,
+    `cd ${shellQuote(runtime.localCwd)} || exit $?`,
+    ...(prepareCommand ? [`${prepareCommand} || exit $?`] : []),
     `${syncLoop} &`,
     "sync_pid=$!",
-    `cd ${shellQuote(runtime.localCwd)} || exit $?`,
     `${rawCommand} &`,
     "app_pid=$!",
     'terminate() { kill -TERM "$app_pid" "$sync_pid" 2>/dev/null || true; }',
@@ -64,3 +66,29 @@ export function localProjectProcessCommand(
     'exit "$status"',
   ].join("\n");
 }
+
+/** Reconstructs a disposable pnpm tree before a persisted process starts in a new container. */
+export function localPnpmProjectProcessCommand(
+  runtime: ProjectLocalRuntime,
+  rawCommand: string,
+  dependencyTemplateDir?: string,
+): string {
+  return localProjectProcessCommand(
+    runtime,
+    rawCommand,
+    restorePnpmDependenciesCommand(dependencyTemplateDir),
+  );
+}
+
+function restorePnpmDependenciesCommand(dependencyTemplateDir?: string): string {
+  const templateMatch = dependencyTemplateDir
+    ? `(cmp -s package.json ${shellQuote(`${dependencyTemplateDir}/package.json`)} && ` +
+      `cmp -s pnpm-lock.yaml ${shellQuote(`${dependencyTemplateDir}/pnpm-lock.yaml`)})`
+    : "false";
+  const install =
+    "if [ -f pnpm-lock.yaml ]; then " +
+    "pnpm install --frozen-lockfile --offline || " +
+    "pnpm install --frozen-lockfile --prefer-offline --network-concurrency 4; " +
+    "else pnpm install --prefer-offline --network-concurrency 4; fi";
+  return `if [ -f package.json ] && ! ${templateMatch}; then ` + `${install}; fi`;
+}

apps/agent-worker/src/durable-objects/project-sandbox-processes.ts

@@ -8,7 +8,10 @@ import type {
 import type { SandboxConsoleSnapshot } from "@cheatcode/types/api";
 import { sandboxExecProcessName } from "./project-sandbox-audit";
 import { WORKSPACE_DIR } from "./project-sandbox-content-support";
-import { localPackageCommand, localProjectProcessCommand } from "./project-sandbox-local-source";
+import {
+  localPackageCommand,
+  localPnpmProjectProcessCommand,
+} from "./project-sandbox-local-source";
 import { recordSandboxUsageBestEffort } from "./project-sandbox-metering";
 import {
   localizeProjectPackageCommand,
@@ -378,7 +381,7 @@ async function startProcess(
     ? commandToShellString([
         "sh",
         "-lc",
-        localProjectProcessCommand(
+        localPnpmProjectProcessCommand(
           packageRuntime,
           commandToShellString(localizeProjectPackageCommand(packageRuntime, parsed.command)),
         ),

packages/agent-core/src/mastra/tool-defs/code-tools.ts

@@ -156,7 +156,7 @@ export const mastraFsWrite = createTool({
 export const mastraFsApply = createTool({
   id: "fs_apply",
   description:
-    "Apply a focused edit to an existing UTF-8 file under /workspace. Read the file first, then provide only changed code with // ... existing code ... wherever content stays unchanged. Use fs_write for new files, binary files, or intentional complete replacements.",
+    "Edit an existing UTF-8 file under /workspace by showing only the changed lines. Read the file first. ALWAYS use the exact // ... existing code ... marker for every unchanged section; omitting it deletes that section. Preserve indentation, include only enough surrounding context to locate each edit, and batch multiple changes to the same file in one call. Use fs_write only for new files, binary files, or intentional complete replacements.",
   inputSchema: ApplyFileInputSchema,
   outputSchema: ApplyFileOutputSchema,
   execute: async (input, context) => {

packages/agent-core/src/tools/code/files.ts

@@ -56,7 +56,9 @@ export const ApplyFileInputSchema = z.strictObject({
       (value) => value.includes(EXISTING_CODE_MARKER),
       `Sparse edits must include ${EXISTING_CODE_MARKER}`,
     )
-    .describe("Only changed code with // ... existing code ... marking unchanged regions."),
+    .describe(
+      "Only the changed lines, with the exact // ... existing code ... marker for every unchanged region. Preserve indentation and include only enough surrounding context to locate each edit.",
+    ),
 });
 
 export const ApplyFileOutputSchema = z.strictObject({