@frockbot/plugin-fly-sprite 0.3.15 → 0.3.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-fly-sprite",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,16 +25,16 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/computer-core": "0.3.15",
-    "@frockbot/computer-host-protocol": "0.3.15",
-    "@frockbot/computer-host-runtime": "0.3.15",
-    "@frockbot/kernel-contracts": "0.3.15",
-    "@frockbot/plugin-computer": "0.3.15",
+    "@frockbot/computer-core": "0.3.17",
+    "@frockbot/computer-host-protocol": "0.3.17",
+    "@frockbot/computer-host-runtime": "0.3.17",
+    "@frockbot/kernel-contracts": "0.3.17",
+    "@frockbot/plugin-computer": "0.3.17",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.3.15",
-    "@frockbot/workspace-store": "0.3.15",
+    "@frockbot/plugin-testkit": "0.3.17",
+    "@frockbot/workspace-store": "0.3.17",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "typescript": "^7.0.2"

package/src/provider.ts

@@ -12,6 +12,7 @@ import {
   type ComputerHandle,
   type ComputerIdentityV1,
   type ComputerOperationOptions,
+  type ComputerRootSyncOptionsV1,
   type ComputerProvider,
   type ComputerSyncHostV1,
   type ComputerSyncReasonV1,
@@ -254,7 +255,7 @@ class FlySpriteComputerSync implements ComputerSyncV1 {
   async reconcileRoot(
     root: WorkspaceRootV1,
     _reason: ComputerSyncReasonV1,
-    options?: ComputerOperationOptions,
+    options?: ComputerRootSyncOptionsV1,
   ): Promise<ComputerSyncSummaryV1> {
     if (options?.signal?.aborted) {
       return computerSyncSummaryV1("skipped", "the Turn was cancelled");
@@ -267,7 +268,7 @@ class FlySpriteComputerSync implements ComputerSyncV1 {
       );
     }
     try {
-      const report = await this.sync.syncRoot(root);
+      const report = await this.sync.syncRoot(root, options?.requiredPaths);
       return summarize({
         roots: [report],
         conflicts: report.conflicts,
@@ -299,15 +300,35 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
     pick: (root: WorkspaceSyncReportV1["roots"][number]) => number,
   ) => report.roots.reduce((sum, root) => sum + pick(root), 0);
   const failed = report.failures[0];
+  const ignored = total((root) => root.ignored);
+  const omitted = total((root) => root.omitted);
+  const detail: string[] = [];
+  if (ignored > 0) {
+    detail.push(
+      `Excluded ${ignored} reproducible Workspace ${ignored === 1 ? "item" : "items"} from sync.`,
+    );
+  }
+  if (omitted > 0) {
+    detail.push(
+      `Omitted ${omitted} manifest ${omitted === 1 ? "entry" : "entries"} at the sync safety limit.`,
+    );
+  }
+  if (failed) {
+    detail.push(
+      `${report.failures.length} sync ${report.failures.length === 1 ? "operation" : "operations"} failed: ${failed.status}: ${failed.reason}.`,
+    );
+  }
   const summary: ComputerSyncSummaryV1 = {
     // Every root failing is `unavailable` — the usual shape of a paused
-    // Sprite. A partial failure is still an `ok` run that says what it missed.
+    // Sprite. Any partial failure or bounded exclusion is truthfully degraded.
     status:
       report.failures.length > 0 &&
       report.roots.every((root) => root.failures.length > 0)
         ? "unavailable"
-        : "ok",
-    detail: failed ? `${failed.status}: ${failed.reason}`.slice(0, 512) : "",
+        : report.failures.length > 0 || ignored > 0 || omitted > 0
+          ? "degraded"
+          : "ok",
+    detail: detail.join(" ").slice(0, 512),
     pulled: total((root) => root.pulled.length),
     pushed: total((root) => root.pushed.length),
     restored: total((root) => root.restored.length),
@@ -315,6 +336,8 @@ function summarize(report: WorkspaceSyncReportV1): ComputerSyncSummaryV1 {
       (root) => root.removedOnComputer.length + root.removedInStore.length,
     ),
     adopted: total((root) => root.adopted.length),
+    ignored,
+    omitted,
     conflicts: report.conflicts.length,
     failures: report.failures.length,
   };

package/src/sync.test.ts

@@ -22,6 +22,11 @@ import { FLY_WORKSPACE_LAYOUT, FlySpriteComputerProvider } from "./provider.ts";
 import {
   createFlySpriteSyncV1,
   declaredWorkspaceRootsV1,
+  FlySpriteSyncSurface,
+  isWorkspaceSyncIgnoredPathV1,
+  WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1,
+  WORKSPACE_SYNC_MANIFEST_MAX_BYTES_V1,
+  WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1,
   type WorkspaceSyncReportV1,
 } from "./sync.ts";
 import { WORKSPACE_EMPTY_SHA256 } from "./workspace.ts";
@@ -84,6 +89,10 @@ class FakeSyncSprite {
   readonly files = new Map<string, Uint8Array>();
   /** Set to fail every storage call, as a paused Sprite does. */
   paused = false;
+  /** Simulates the shared host truncating an oversized storage response. */
+  maxScanOutputBytes?: number;
+  /** The exact remote Bash document, for syntax validation. */
+  lastScanScript?: string;
   /** Drops the next sidecar write, as a pause between store and Computer does. */
   dropNextMaterialize = false;
 
@@ -92,7 +101,19 @@ class FakeSyncSprite {
     // A paused Sprite answers nothing, and the host reports the failed exit;
     // the provider turns that into `Sprite storage operation failed: …`.
     if (this.paused) return { exitCode: 1, stderr: "Sprite is paused" };
-    return { stdout: this.interpret(script) };
+    if (script.includes("append_manifest")) this.lastScanScript = script;
+    const stdout = this.interpret(script);
+    if (
+      script.includes("append_manifest") &&
+      this.maxScanOutputBytes !== undefined &&
+      stdout.length > this.maxScanOutputBytes
+    ) {
+      return {
+        stdout: stdout.slice(0, this.maxScanOutputBytes),
+        outputTruncated: true,
+      };
+    }
+    return { stdout };
   };
 
   /** Writes a file the way a shell command on the Computer would: no sidecar. */
@@ -118,7 +139,16 @@ class FakeSyncSprite {
   private interpret(shell: string): string {
     const root = quoted(shell, "ROOT");
     const relative = quoted(shell, "REL");
-    if (shell.includes('printf "F\\t')) return this.scan(root ?? "");
+    if (shell.includes("append_manifest") && shell.includes("sha256sum")) {
+      const encoded = quoted(shell, "REQUIRED_PATHS") ?? "W10=";
+      const required = new Set<string>(
+        Buffer.from(encoded, "base64")
+          .toString("utf8")
+          .split("\n")
+          .filter(Boolean),
+      );
+      return this.scan(root ?? "", required);
+    }
     if (root && relative) {
       if (shell.includes("__SYNCED__")) {
         if (this.dropNextMaterialize) {
@@ -160,14 +190,39 @@ class FakeSyncSprite {
       : `${decoder.decode(bytes)}\n`;
   }
 
-  private scan(root: string): string {
+  private scan(root: string, required: ReadonlySet<string>): string {
     const rows: string[] = [];
+    const ignoredDirectories = new Set<string>();
+    const requiredIgnoredDirectories = new Set(
+      [...required].map((path) => {
+        const segments = path.split("/");
+        const index = segments.findIndex((segment) =>
+          (WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1 as readonly string[]).includes(
+            segment,
+          ),
+        );
+        return segments.slice(0, index + 1).join("/");
+      }),
+    );
     const generations = `${root}/.frockbot-generations/`;
     const graves = `${root}/.frockbot-sync/tombstones/`;
     for (const [path, bytes] of [...this.files].sort()) {
       if (!path.startsWith(`${root}/`)) continue;
       const relative = path.slice(root.length + 1);
       if (relative.startsWith(".frockbot-")) continue;
+      if (isWorkspaceSyncIgnoredPathV1(relative) && !required.has(relative)) {
+        const segments = relative.split("/");
+        const index = segments.findIndex((segment) =>
+          (WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1 as readonly string[]).includes(
+            segment,
+          ),
+        );
+        const ignoredRoot = segments.slice(0, index + 1).join("/");
+        if (!requiredIgnoredDirectories.has(ignoredRoot)) {
+          ignoredDirectories.add(ignoredRoot);
+        }
+        continue;
+      }
       const meta = this.files.get(`${generations}${relative}`);
       rows.push(
         [
@@ -181,10 +236,13 @@ class FakeSyncSprite {
     }
     for (const [path, bytes] of [...this.files].sort()) {
       if (path.startsWith(graves)) {
+        const relative = path.slice(graves.length);
+        if (isWorkspaceSyncIgnoredPathV1(relative) && !required.has(relative))
+          continue;
         rows.push(
           [
             "T",
-            Buffer.from(path.slice(graves.length)).toString("base64"),
+            Buffer.from(relative).toString("base64"),
             Buffer.from(bytes).toString("base64"),
           ].join("\t"),
         );
@@ -192,6 +250,8 @@ class FakeSyncSprite {
       }
       if (!path.startsWith(generations)) continue;
       const relative = path.slice(generations.length);
+      if (isWorkspaceSyncIgnoredPathV1(relative) && !required.has(relative))
+        continue;
       if (this.files.has(`${root}/${relative}`)) continue;
       rows.push(
         [
@@ -201,7 +261,22 @@ class FakeSyncSprite {
         ].join("\t"),
       );
     }
-    return rows.length ? `${rows.join("\n")}\n` : "";
+    const bounded: string[] = [];
+    let bytes = 0;
+    let omitted = 0;
+    for (const row of rows) {
+      const rowBytes = Buffer.byteLength(`${row}\n`);
+      if (
+        bounded.length >= WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1 ||
+        bytes + rowBytes > WORKSPACE_SYNC_MANIFEST_MAX_BYTES_V1
+      ) {
+        omitted += 1;
+        continue;
+      }
+      bounded.push(row);
+      bytes += rowBytes;
+    }
+    return `${bounded.length ? `${bounded.join("\n")}\n` : ""}X\t${ignoredDirectories.size}\t${omitted}\n`;
   }
 
   private materialize(root: string, relative: string, shell: string): string {
@@ -631,6 +706,78 @@ describe("the durable-root sync, Computer to store", () => {
 });
 
 describe("the durable-root sync, Package-declared roots", () => {
+  test("ignores reproducible dependency, VCS, cache, and build directories", () => {
+    for (const directory of WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1) {
+      expect(
+        isWorkspaceSyncIgnoredPathV1(`to-dos/${directory}/nested/file.js`),
+      ).toBe(true);
+    }
+    expect(isWorkspaceSyncIgnoredPathV1("to-dos/src/build-result.ts")).toBe(
+      false,
+    );
+    expect(isWorkspaceSyncIgnoredPathV1("to-dos/.gitignore")).toBe(false);
+  });
+
+  test("bounds a source-only manifest and reports every omitted row", async () => {
+    const sprite = new FakeSyncSprite();
+    const surface = new FlySpriteSyncSurface({
+      computer: attach(sprite).bot(BOT),
+      layout: FLY_WORKSPACE_LAYOUT,
+      userId: USER,
+      botDirectoryKey: computerBotKey,
+    });
+    for (
+      let index = 0;
+      index < WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1 + 100;
+      index += 1
+    ) {
+      sprite.shellWrite(
+        MOUNTS.appletSource,
+        `to-dos/src/file-${index.toString().padStart(4, "0")}.ts`,
+        `export const value${index} = ${index};`,
+      );
+    }
+
+    const outcome = await surface.scan(appletSourceRoot);
+
+    if (outcome.status !== "ok") throw new Error(outcome.reason);
+    expect(outcome.scan.entries).toHaveLength(
+      WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1,
+    );
+    expect(outcome.scan.ignored).toBe(0);
+    expect(outcome.scan.omitted).toBe(100);
+  });
+
+  test("emits valid Bash with exact required build paths", async () => {
+    const sprite = new FakeSyncSprite();
+    const surface = new FlySpriteSyncSurface({
+      computer: attach(sprite).bot(BOT),
+      layout: FLY_WORKSPACE_LAYOUT,
+      userId: USER,
+      botDirectoryKey: computerBotKey,
+    });
+
+    await surface.scan(appletSourceRoot, [
+      "todo/dist/server.js",
+      "todo/dist/ui.html",
+      "todo/dist/manifest.json",
+      "todo/dist/it's-$(not-a-command).js",
+    ]);
+
+    expect(sprite.lastScanScript).toBeString();
+    const process = Bun.spawn(["bash", "-n"], {
+      stdin: new Blob([sprite.lastScanScript!]),
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    const [exitCode, stderr] = await Promise.all([
+      process.exited,
+      new Response(process.stderr).text(),
+    ]);
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+  });
+
   // Constitution — Computer and Workspace: "durable roots, declared by the
   // Computer Package's Workspace layout **and by Package manifests**". The
   // layout half was always here; a `package-declared` root reaches the sync
@@ -643,10 +790,9 @@ describe("the durable-root sync, Package-declared roots", () => {
   });
 
   test("a declared root round-trips: store to Computer, and a shell write back", async () => {
-    // ADR 0022 decision 7: this is the root Applet source lives in, and both
-    // directions matter — the Bot edits source the store holds, and `applet
-    // build` writes `dist/` with a shell that a publish then reads from the
-    // store.
+    // ADR 0022 decision 7: this is the root Applet source lives in, and source
+    // edits still move in both directions while reproducible build trees do
+    // not enter the ordinary whole-Workspace manifest.
     const { sprite, store, sync, roots } = harness({
       packageRoots: [APPLET_SOURCE_PACKAGE_ROOT],
     });
@@ -667,25 +813,103 @@ describe("the durable-root sync, Package-declared roots", () => {
       "export class TodoApplet {}",
     );
 
-    // `applet build` is an ordinary shell write on the Computer.
+    // An ordinary shell source edit on the Computer is mirrored back.
     sprite.shellWrite(
       MOUNTS.appletSource,
-      `${appletId}/dist/server.js`,
-      "export class A{}",
+      `${appletId}/server.ts`,
+      "export class TodoApplet { health() {} }",
     );
     const pushed = await sync();
 
     const built = await store.read({
       root: appletSourceRoot,
-      path: `${appletId}/dist/server.js`,
+      path: `${appletId}/server.ts`,
     });
     if (built.status !== "ok") throw new Error(built.reason);
-    expect(decoder.decode(built.file.bytes)).toBe("export class A{}");
+    expect(decoder.decode(built.file.bytes)).toBe(
+      "export class TodoApplet { health() {} }",
+    );
     // A shell wrote it, so nothing claims to know which Bot did: the artifact
-    // is data the publish reads, never provenance.
+    // is data, never provenance.
     expect(built.file.generation.writer).toEqual({ kind: "unattributed" });
     expect(pushed.failures).toEqual([]);
   });
+
+  test("a large node_modules tree cannot prevent Applet source from syncing", async () => {
+    const { sprite, store, sync } = harness({
+      packageRoots: [APPLET_SOURCE_PACKAGE_ROOT],
+    });
+    const appletId = "to-dos";
+    sprite.maxScanOutputBytes = 10_000;
+    sprite.shellWrite(
+      MOUNTS.appletSource,
+      `${appletId}/server.ts`,
+      "export class TodoApplet {}",
+    );
+    for (let index = 0; index < 200; index += 1) {
+      sprite.shellWrite(
+        MOUNTS.appletSource,
+        `${appletId}/node_modules/dependency-${index}/package.json`,
+        JSON.stringify({ name: `dependency-${index}` }),
+      );
+    }
+
+    const report = await sync();
+
+    expect(report.failures).toEqual([]);
+    expect(report.roots.at(-1)).toMatchObject({ ignored: 1, omitted: 0 });
+    const source = await store.read({
+      root: appletSourceRoot,
+      path: `${appletId}/server.ts`,
+    });
+    if (source.status !== "ok") throw new Error(source.reason);
+    expect(decoder.decode(source.file.bytes)).toBe(
+      "export class TodoApplet {}",
+    );
+    expect(
+      await store.read({
+        root: appletSourceRoot,
+        path: `${appletId}/node_modules/dependency-0/package.json`,
+      }),
+    ).toMatchObject({ status: "not-found" });
+  });
+
+  test("an empty replacement Computer restores source but not legacy project dependencies", async () => {
+    const { sprite, store, sync } = harness({
+      packageRoots: [APPLET_SOURCE_PACKAGE_ROOT],
+    });
+    const appletId = "pub-user-1.0123456789abcdef0123456789abcdef";
+    await writeToStore(
+      store,
+      appletSourceRoot,
+      `${appletId}/server.ts`,
+      "export class TodoApplet {}",
+      BOT_WRITER,
+    );
+    // A pre-policy generation stays in object storage for audit/recovery, but
+    // a new Computer must not materialize it back into the project.
+    await writeToStore(
+      store,
+      appletSourceRoot,
+      `${appletId}/node_modules/dependency/package.json`,
+      '{"name":"dependency"}',
+      BOT_WRITER,
+    );
+
+    const report = await sync();
+
+    expect(sprite.text(`${MOUNTS.appletSource}/${appletId}/server.ts`)).toBe(
+      "export class TodoApplet {}",
+    );
+    expect(
+      sprite.text(
+        `${MOUNTS.appletSource}/${appletId}/node_modules/dependency/package.json`,
+      ),
+    ).toBeUndefined();
+    expect(
+      report.roots.find((item) => item.root.kind === "package-declared"),
+    ).toMatchObject({ pulled: [`${appletId}/server.ts`], ignored: 1 });
+  });
 });
 
 describe("the durable-root sync, conflicts", () => {
@@ -1108,6 +1332,34 @@ describe("the durable-root sync on the Computer handle", () => {
     }
   });
 
+  test("reports a bounded dependency exclusion as degraded while source still syncs", async () => {
+    const { sprite, open } = providerHarness([APPLET_SOURCE_PACKAGE_ROOT]);
+    const handle = await open();
+    sprite.shellWrite(
+      MOUNTS.appletSource,
+      "todo/src/index.ts",
+      "export const todo = true;",
+    );
+    sprite.shellWrite(
+      MOUNTS.appletSource,
+      "todo/node_modules/dependency/package.json",
+      '{"name":"dependency"}',
+    );
+
+    const summary = await handle.sync!.reconcile("turn-end");
+
+    expect(summary).toMatchObject({
+      status: "degraded",
+      pushed: 1,
+      ignored: 1,
+      omitted: 0,
+      failures: 0,
+    });
+    expect(summary.detail).toBe(
+      "Excluded 1 reproducible Workspace item from sync.",
+    );
+  });
+
   // The sync-now seam of ADR 0022 decision 7, provider side: an Applet publish
   // needs the bytes `applet build` left on the Computer to be in the store
   // before it reads them, and it needs that for one root, not the Workspace.
@@ -1127,6 +1379,7 @@ describe("the durable-root sync on the Computer handle", () => {
     const summary = await handle.sync!.reconcileRoot!(
       appletSourceRoot,
       "publish",
+      { requiredPaths: [`${appletId}/dist/server.js`] },
     );
 
     expect(summary.status).toBe("ok");

package/src/sync.ts

@@ -116,6 +116,44 @@ const EFFECT_NOTE_KIND = "effects";
 const MAX_STORE_PAGES = 100;
 const STORE_PAGE_LIMIT = 500;
 
+/**
+ * Reproducible dependency, cache, VCS, and build trees never enter a durable
+ * Workspace manifest. Names are matched as path segments at any depth, so one
+ * policy covers a project nested inside a Package-declared root.
+ */
+export const WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1 = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  "target",
+  "coverage",
+  ".cache",
+  ".parcel-cache",
+  ".turbo",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  ".vite",
+  ".pnpm-store",
+] as const;
+
+/** Leaves headroom below `runStorageForAgent`'s 500 KB response ceiling. */
+export const WORKSPACE_SYNC_MANIFEST_MAX_BYTES_V1 = 400_000;
+/** Bounds work and rows even when unusually short paths fit under the bytes. */
+export const WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1 = 2_000;
+
+const ignoredDirectoryNames = new Set<string>(
+  WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1,
+);
+
+/** True when a Workspace-relative path belongs to a reproducible tree. */
+export function isWorkspaceSyncIgnoredPathV1(path: string): boolean {
+  return path.split("/").some((segment) => ignoredDirectoryNames.has(segment));
+}
+
 function failure(
   status: WorkspaceFailureV1["status"],
   reason: string,
@@ -162,6 +200,10 @@ export interface ComputerSyncRemovalV1 {
 export interface ComputerSyncScanV1 {
   entries: ComputerSyncEntryV1[];
   removed: ComputerSyncRemovalV1[];
+  /** Reproducible directories or already-stored paths excluded by policy. */
+  ignored: number;
+  /** Rows omitted after the manifest hit its entry or byte ceiling. */
+  omitted: number;
 }
 
 export type ComputerSyncOutcomeV1 = { status: "ok" } | WorkspaceFailureV1;
@@ -183,7 +225,10 @@ export type ComputerSyncNoteOutcomeV1 =
  */
 export interface ComputerSyncSurfaceV1 {
   /** Every file and every recorded removal under one durable root. */
-  scan(root: WorkspaceRootV1): Promise<ComputerSyncScanOutcomeV1>;
+  scan(
+    root: WorkspaceRootV1,
+    requiredPaths?: readonly string[],
+  ): Promise<ComputerSyncScanOutcomeV1>;
   read(
     root: WorkspaceRootV1,
     path: string,
@@ -261,6 +306,10 @@ export interface WorkspaceSyncRootReportV1 {
   removedInStore: string[];
   /** Pushes a previous run had already applied, adopted rather than repeated. */
   adopted: string[];
+  /** Reproducible directories and store entries excluded by policy. */
+  ignored: number;
+  /** Computer manifest rows omitted at the hard bound. */
+  omitted: number;
   conflicts: WorkspaceSyncConflictV1[];
   failures: WorkspaceSyncFailureV1[];
 }
@@ -293,7 +342,10 @@ export interface WorkspaceRootSyncOptionsV1 {
 export interface WorkspaceRootSyncV1 {
   /** Reconciles every declared root. */
   sync(): Promise<WorkspaceSyncReportV1>;
-  syncRoot(root: WorkspaceRootV1): Promise<WorkspaceSyncRootReportV1>;
+  syncRoot(
+    root: WorkspaceRootV1,
+    requiredPaths?: readonly string[],
+  ): Promise<WorkspaceSyncRootReportV1>;
   /**
    * The on-Sprite watcher's change signal. A caller runs the sync on wake and
    * whenever this changes, rather than scanning every root every Turn.
@@ -332,6 +384,8 @@ function emptyReport(root: WorkspaceRootV1): WorkspaceSyncRootReportV1 {
     removedOnComputer: [],
     removedInStore: [],
     adopted: [],
+    ignored: 0,
+    omitted: 0,
     conflicts: [],
     failures: [],
   };
@@ -363,18 +417,24 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
     };
   }
 
-  async syncRoot(root: WorkspaceRootV1): Promise<WorkspaceSyncRootReportV1> {
+  async syncRoot(
+    root: WorkspaceRootV1,
+    requiredPaths: readonly string[] = [],
+  ): Promise<WorkspaceSyncRootReportV1> {
     const report = emptyReport(root);
-    const scanned = await this.options.computer.scan(root);
+    const scanned = await this.options.computer.scan(root, requiredPaths);
     if (isFailure(scanned)) {
       report.failures.push({ ...scanned, root });
       return report;
     }
-    const stored = await this.listStore(root);
+    report.ignored = scanned.scan.ignored;
+    report.omitted = scanned.scan.omitted;
+    const stored = await this.listStore(root, requiredPaths);
     if (isFailure(stored)) {
       report.failures.push({ ...stored, root });
       return report;
     }
+    report.ignored += stored.ignored;
     const local = new Map(
       scanned.scan.entries.map((entry) => [entry.path, entry] as const),
     );
@@ -458,11 +518,18 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
 
   private async listStore(
     root: WorkspaceRootV1,
+    requiredPaths: readonly string[],
   ): Promise<
-    | { status: "ok"; generations: Map<string, WorkspaceGenerationV1> }
+    | {
+        status: "ok";
+        generations: Map<string, WorkspaceGenerationV1>;
+        ignored: number;
+      }
     | WorkspaceFailureV1
   > {
     const generations = new Map<string, WorkspaceGenerationV1>();
+    const required = new Set(requiredPaths);
+    let ignored = 0;
     let cursor: string | undefined;
     for (let page = 0; page < MAX_STORE_PAGES; page += 1) {
       const listed = await this.options.store.list({
@@ -472,9 +539,16 @@ class WorkspaceRootSync implements WorkspaceRootSyncV1 {
       });
       if (listed.status !== "ok") return listed;
       for (const entry of listed.entries) {
+        if (
+          isWorkspaceSyncIgnoredPathV1(entry.path.path) &&
+          !required.has(entry.path.path)
+        ) {
+          ignored += 1;
+          continue;
+        }
         generations.set(entry.path.path, entry.generation);
       }
-      if (!listed.cursor) return { status: "ok", generations };
+      if (!listed.cursor) return { status: "ok", generations, ignored };
       cursor = listed.cursor;
     }
     return failure("unavailable", "Durable root listing did not terminate");
@@ -888,38 +962,137 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     ).toString("base64");
   }
 
-  async scan(root: WorkspaceRootV1): Promise<ComputerSyncScanOutcomeV1> {
+  async scan(
+    root: WorkspaceRootV1,
+    requiredPaths: readonly string[] = [],
+  ): Promise<ComputerSyncScanOutcomeV1> {
     const mount = this.mount(root);
     if (typeof mount !== "string") return mount;
+    const requiredIgnoredPaths: string[] = [];
+    for (const path of requiredPaths) {
+      const relative = this.relative(path);
+      if (typeof relative !== "string") return relative;
+      if (
+        isWorkspaceSyncIgnoredPathV1(relative) &&
+        !requiredIgnoredPaths.includes(relative)
+      ) {
+        requiredIgnoredPaths.push(relative);
+      }
+    }
+    const requiredIgnoredRoots = [
+      ...new Set(
+        requiredIgnoredPaths.map((path) => {
+          const segments = path.split("/");
+          const index = segments.findIndex((segment) =>
+            ignoredDirectoryNames.has(segment),
+          );
+          return segments.slice(0, index + 1).join("/");
+        }),
+      ),
+    ];
+    const ignoredExpression = WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1.map(
+      (name) => `-name ${shellQuote(name)}`,
+    ).join(" -o ");
     const script = [
+      "set -eu",
       `ROOT=${shellQuote(mount)}`,
+      `REQUIRED_PATHS=${shellQuote(Buffer.from(requiredIgnoredPaths.join("\n")).toString("base64"))}`,
       `mkdir -p "$ROOT" "$ROOT/${WORKSPACE_GENERATIONS_DIR}" "$ROOT/${WORKSPACE_SYNC_DIR}/${SYNC_TOMBSTONES_DIR}"`,
-      `find "$ROOT" -type f ! -path "$ROOT/${WORKSPACE_GENERATIONS_DIR}/*" ! -path "$ROOT/${WORKSPACE_SYNC_DIR}/*" ! -path "$ROOT/.frockbot-locks/*" -print0 | sort -z | while IFS= read -r -d "" FILE; do`,
-      '  REL=${FILE#"$ROOT"/}',
+      "MANIFEST=$(mktemp)",
+      "trap 'rm -f \"$MANIFEST\"' EXIT",
+      "MANIFEST_BYTES=0",
+      "MANIFEST_ENTRIES=0",
+      "OMITTED=0",
+      "IGNORED=0",
+      "SATURATED=0",
+      "append_manifest() {",
+      "  ROW=$1",
+      "  ROW_BYTES=$((${#ROW} + 1))",
+      `  if [ "$MANIFEST_ENTRIES" -ge ${WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1} ] || [ $((MANIFEST_BYTES + ROW_BYTES)) -gt ${WORKSPACE_SYNC_MANIFEST_MAX_BYTES_V1} ]; then`,
+      "    OMITTED=$((OMITTED + 1))",
+      "    SATURATED=1",
+      "    return",
+      "  fi",
+      '  printf \'%s\\n\' "$ROW" >> "$MANIFEST"',
+      "  MANIFEST_BYTES=$((MANIFEST_BYTES + ROW_BYTES))",
+      "  MANIFEST_ENTRIES=$((MANIFEST_ENTRIES + 1))",
+      "}",
+      "ignored_relative() {",
+      '  included_relative "$1" && return 1',
+      '  IFS=/ read -r -a PARTS <<< "$1"',
+      '  for PART in "${PARTS[@]}"; do',
+      `    case "$PART" in ${WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1.map((name) => shellQuote(name)).join("|")}) return 0 ;; esac`,
+      "  done",
+      "  return 1",
+      "}",
+      "included_relative() {",
+      requiredIgnoredPaths.length > 0
+        ? `  case "$1" in ${requiredIgnoredPaths.map((path) => shellQuote(path)).join("|")}) return 0 ;; esac`
+        : "  :",
+      "  return 1",
+      "}",
+      "required_directory() {",
+      requiredIgnoredRoots.length > 0
+        ? `  case "$1" in ${requiredIgnoredRoots.map((path) => shellQuote(path)).join("|")}) return 0 ;; esac`
+        : "  :",
+      "  return 1",
+      "}",
+      // Required artifact files go first: the source manifest may be full,
+      // but an explicit one-root publisher must still receive the exact bytes
+      // it named. They remain subject to the same byte and entry bounds.
+      "while IFS= read -r REL; do",
+      '  [ -n "$REL" ] || continue',
+      '  FILE="$ROOT/$REL"',
+      '  if [ -f "$FILE" ]; then',
       `  META="$ROOT/${WORKSPACE_GENERATIONS_DIR}/$REL"`,
-      '  printf "F\\t%s\\t%s\\t%s\\t%s\\n" "$(printf %s "$REL" | base64 -w0)" "$({ cat "$META" 2>/dev/null || printf \'\'; } | base64 -w0)" "$(sha256sum "$FILE" | cut -d" " -f1)" "$(stat -c %s "$FILE")"',
-      "done",
+      '  printf -v ROW "F\\t%s\\t%s\\t%s\\t%s" "$(printf %s "$REL" | base64 -w0)" "$({ cat "$META" 2>/dev/null || printf \'\'; } | base64 -w0)" "$(sha256sum "$FILE" | cut -d" " -f1)" "$(stat -c %s "$FILE")"',
+      '  append_manifest "$ROW"',
+      "  fi",
+      'done < <(printf %s "$REQUIRED_PATHS" | base64 -d)',
+      // Count pruned directory roots, not every file below them: the count is
+      // useful and bounded work even when a dependency tree holds millions.
+      `while IFS= read -r -d "" DIR; do REL=\${DIR#"$ROOT"/}; required_directory "$REL" || IGNORED=$((IGNORED + 1)); done < <(find "$ROOT" \\( -path "$ROOT/${WORKSPACE_GENERATIONS_DIR}" -o -path "$ROOT/${WORKSPACE_SYNC_DIR}" -o -path "$ROOT/.frockbot-locks" \\) -prune -o -type d \\( ${ignoredExpression} \\) -print0 -prune)`,
       `GRAVES="$ROOT/${WORKSPACE_SYNC_DIR}/${SYNC_TOMBSTONES_DIR}"`,
-      'find "$GRAVES" -type f -print0 | sort -z | while IFS= read -r -d "" FILE; do',
+      'while IFS= read -r -d "" FILE; do',
       '  REL=${FILE#"$GRAVES"/}',
-      '  printf "T\\t%s\\t%s\\n" "$(printf %s "$REL" | base64 -w0)" "$(base64 -w0 "$FILE")"',
-      "done",
+      '  if ignored_relative "$REL"; then IGNORED=$((IGNORED + 1)); continue; fi',
+      '  printf -v ROW "T\\t%s\\t%s" "$(printf %s "$REL" | base64 -w0)" "$(base64 -w0 "$FILE")"',
+      '  append_manifest "$ROW"',
+      'done < <(find "$GRAVES" -type f -print0 | sort -z)',
       `METAS="$ROOT/${WORKSPACE_GENERATIONS_DIR}"`,
-      'find "$METAS" -type f -print0 | sort -z | while IFS= read -r -d "" FILE; do',
+      'while IFS= read -r -d "" FILE; do',
       '  REL=${FILE#"$METAS"/}',
+      '  if ignored_relative "$REL"; then IGNORED=$((IGNORED + 1)); continue; fi',
       '  if [ -f "$ROOT/$REL" ]; then continue; fi',
-      '  printf "S\\t%s\\t%s\\n" "$(printf %s "$REL" | base64 -w0)" "$(base64 -w0 "$FILE")"',
-      "done",
+      '  printf -v ROW "S\\t%s\\t%s" "$(printf %s "$REL" | base64 -w0)" "$(base64 -w0 "$FILE")"',
+      '  append_manifest "$ROW"',
+      'done < <(find "$METAS" -type f -print0 | sort -z)',
+      `while IFS= read -r -d "" FILE; do`,
+      '  REL=${FILE#"$ROOT"/}',
+      '  if [ "$SATURATED" -eq 1 ]; then OMITTED=$((OMITTED + 1)); continue; fi',
+      `  META="$ROOT/${WORKSPACE_GENERATIONS_DIR}/$REL"`,
+      '  printf -v ROW "F\\t%s\\t%s\\t%s\\t%s" "$(printf %s "$REL" | base64 -w0)" "$({ cat "$META" 2>/dev/null || printf \'\'; } | base64 -w0)" "$(sha256sum "$FILE" | cut -d" " -f1)" "$(stat -c %s "$FILE")"',
+      '  append_manifest "$ROW"',
+      `done < <(find "$ROOT" \\( -path "$ROOT/${WORKSPACE_GENERATIONS_DIR}" -o -path "$ROOT/${WORKSPACE_SYNC_DIR}" -o -path "$ROOT/.frockbot-locks" -o -type d \\( ${ignoredExpression} \\) \\) -prune -o -type f -print0 | sort -z)`,
+      'cat "$MANIFEST"',
+      'printf "X\\t%s\\t%s\\n" "$IGNORED" "$OMITTED"',
     ].join("\n");
     const output = await this.run(script);
     if (typeof output !== "string") return output;
     const entries: ComputerSyncEntryV1[] = [];
     const removed = new Map<string, ComputerSyncRemovalV1>();
+    let ignored = 0;
+    let omitted = 0;
     for (const row of output.split("\n")) {
       if (!row.trim()) continue;
       const [tag, encodedPath, second = "", third = "", fourth = ""] =
         row.split("\t");
       if (!encodedPath) continue;
+      if (tag === "X") {
+        ignored = Number(encodedPath);
+        omitted = Number(second);
+        continue;
+      }
       const path = Buffer.from(encodedPath, "base64").toString("utf8");
       const relative = this.relative(path);
       if (typeof relative !== "string") continue;
@@ -955,7 +1128,7 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     }
     return {
       status: "ok",
-      scan: { entries, removed: [...removed.values()] },
+      scan: { entries, removed: [...removed.values()], ignored, omitted },
     };
   }