@frockbot/plugin-fly-sprite 0.3.23 → 0.3.24

package/package.json

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

package/src/computer.test.ts

@@ -1,6 +1,7 @@
 /// <reference types="bun" />
 
 import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
 import type { ComputerConnectionProgressV1 } from "@frockbot/computer-core";
 import { COMPUTER_UNCONFIGURED_MESSAGE_V1 } from "@frockbot/computer-core";
 import { verifyPluginPackage } from "@frockbot/plugin-testkit";
@@ -63,15 +64,18 @@ function computerRunner(script: string): FakeComputerRunV1 {
   }
   if (script.includes('mv "$TMP" "$TARGET"'))
     return { stdout: "__WRITTEN__\n" };
-  if (script.includes('base64 -w0 "$TARGET"')) {
-    // meta, content hash, size, mtime, bytes — the Workspace file shape.
+  if (script.includes('"$TARGET" | base64 -w0')) {
+    // meta, content hash, size, mtime, first chunk — the Workspace file shape.
+    // The digest is the file's real one, because the read proves the chunks it
+    // stitched are one file against exactly this value.
+    const bytes = Buffer.from("remember");
     return {
       stdout: [
         "",
-        "0".repeat(64),
-        "8",
+        createHash("sha256").update(bytes).digest("hex"),
+        String(bytes.byteLength),
         "1700000000",
-        Buffer.from("remember").toString("base64"),
+        bytes.toString("base64"),
         "",
       ].join("\n"),
     };

package/src/computer.ts

@@ -53,7 +53,14 @@ import type {
 export { SLOT_IDLE_SECONDS, WORKSPACE_SYNC_SERVICE };
 
 const MAX_OUTPUT = 30_000;
-const MAX_STORAGE_OUTPUT = 500_000;
+/**
+ * The most a Workspace or sync command may answer with.
+ *
+ * Exported because it is the ceiling those commands are written to stay under,
+ * and a test double that answered past it would prove a read works at a size
+ * the Computer would have refused.
+ */
+export const MAX_STORAGE_OUTPUT = 500_000;
 const EXEC_EXIT_MARKER = "__FROCKBOT_EXIT__";
 /** Largest screenshot this provider will carry back off a Computer. */
 export const SCREENSHOT_MAX_BYTES = 8 * 1024 * 1024;

package/src/sync.test.ts

@@ -25,13 +25,15 @@ import {
   FlySpriteSyncSurface,
   isWorkspaceSyncIgnoredPathV1,
   WORKSPACE_SYNC_IGNORED_DIRECTORIES_V1,
-  WORKSPACE_SYNC_CHUNK_BYTES_V1,
   WORKSPACE_SYNC_MANIFEST_MAX_BYTES_V1,
   WORKSPACE_SYNC_MANIFEST_MAX_ENTRIES_V1,
   WORKSPACE_SYNC_MAX_FILE_BYTES_V1,
   type WorkspaceSyncReportV1,
 } from "./sync.ts";
-import { WORKSPACE_EMPTY_SHA256 } from "./workspace.ts";
+import {
+  WORKSPACE_CHUNK_BYTES_V1,
+  WORKSPACE_EMPTY_SHA256,
+} from "./workspace.ts";
 
 const USER = "owner";
 const BOT = "health";
@@ -219,7 +221,7 @@ class FakeSyncSprite {
     if (bytes.byteLength > WORKSPACE_SYNC_MAX_FILE_BYTES_V1) {
       return "__TOO_LARGE__\n";
     }
-    const head = bytes.subarray(0, WORKSPACE_SYNC_CHUNK_BYTES_V1);
+    const head = bytes.subarray(0, WORKSPACE_CHUNK_BYTES_V1);
     return `${bytes.byteLength}\t${sha256(bytes)}\n${Buffer.from(head).toString("base64")}\n`;
   }
 

package/src/sync.ts

@@ -105,9 +105,12 @@ import {
   SYNC_CONFLICTS_DIR,
   SYNC_STAGING_DIR,
   SYNC_TOMBSTONES_DIR,
+  WORKSPACE_CHUNK_BYTES_V1,
   WORKSPACE_EMPTY_SHA256,
   WORKSPACE_GENERATIONS_DIR,
   WORKSPACE_SYNC_DIR,
+  workspaceChunkOffsetsV1,
+  workspaceStagingNameV1,
 } from "./workspace.js";
 
 /** Where the sync keeps notes that are not scoped to one root. */
@@ -146,17 +149,6 @@ 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;
 
-/**
- * The most file bytes one storage command carries, in either direction.
- *
- * A command's answer travels as base64, so a chunk this size comes back as
- * roughly 350 KB — inside the 500 KB an answer may be — and goes out inside a
- * script well inside the 1 MB a script may be. A file larger than one chunk
- * travels as several commands rather than as one command that would be refused
- * for its size, which is the whole reason the sync reads and writes in chunks.
- */
-export const WORKSPACE_SYNC_CHUNK_BYTES_V1 = 256 * 1024;
-
 /**
  * The largest durable-root file the sync carries between the Computer and the
  * store.
@@ -168,25 +160,6 @@ export const WORKSPACE_SYNC_CHUNK_BYTES_V1 = 256 * 1024;
  */
 export const WORKSPACE_SYNC_MAX_FILE_BYTES_V1 = 4 * 1024 * 1024;
 
-/** Every chunk offset after the first, in bytes, for a file of this size. */
-function chunkOffsets(size: number): number[] {
-  const offsets: number[] = [];
-  for (
-    let offset = WORKSPACE_SYNC_CHUNK_BYTES_V1;
-    offset < size;
-    offset += WORKSPACE_SYNC_CHUNK_BYTES_V1
-  ) {
-    offsets.push(offset);
-  }
-  return offsets;
-}
-
-/** A staging file name that is one path segment whatever the id looks like. */
-function stagingName(generationId: string, kind: string): string {
-  const safe = generationId.replaceAll(/[^A-Za-z0-9._-]/g, "-").slice(0, 128);
-  return `${safe}.${kind}`;
-}
-
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 
 const ignoredDirectoryNames = new Set<string>(
@@ -1205,7 +1178,7 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     const head = await this.run(
       [
         ...prelude,
-        `CHUNK=${WORKSPACE_SYNC_CHUNK_BYTES_V1}`,
+        `CHUNK=${WORKSPACE_CHUNK_BYTES_V1}`,
         'if [ ! -f "$FILE" ]; then echo __MISSING__; exit 0; fi',
         'SIZE=$(stat -c %s "$FILE")',
         `if [ "$SIZE" -gt ${WORKSPACE_SYNC_MAX_FILE_BYTES_V1} ]; then echo __TOO_LARGE__; exit 0; fi`,
@@ -1230,13 +1203,13 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
       return failure("unavailable", "Invalid Fly Workspace sync response");
     }
     const chunks = [Buffer.from(first.trim(), "base64")];
-    for (const offset of chunkOffsets(size)) {
+    for (const offset of workspaceChunkOffsetsV1(size)) {
       const next = await this.run(
         [
           ...prelude,
           // `tail -c +N` counts from one, so the offset is one past the bytes
           // already carried.
-          `tail -c +${offset + 1} "$FILE" | head -c ${WORKSPACE_SYNC_CHUNK_BYTES_V1} | base64 -w0; echo`,
+          `tail -c +${offset + 1} "$FILE" | head -c ${WORKSPACE_CHUNK_BYTES_V1} | base64 -w0; echo`,
         ].join("\n"),
       );
       if (typeof next !== "string") return next;
@@ -1271,17 +1244,14 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     name: string,
     bytes: Uint8Array,
   ): Promise<string | WorkspaceFailureV1 | undefined> {
-    if (bytes.byteLength <= WORKSPACE_SYNC_CHUNK_BYTES_V1) return undefined;
+    if (bytes.byteLength <= WORKSPACE_CHUNK_BYTES_V1) return undefined;
     const staged = `${mount}/${WORKSPACE_SYNC_DIR}/${SYNC_STAGING_DIR}/${name}`;
     for (
       let offset = 0;
       offset < bytes.byteLength;
-      offset += WORKSPACE_SYNC_CHUNK_BYTES_V1
+      offset += WORKSPACE_CHUNK_BYTES_V1
     ) {
-      const chunk = bytes.subarray(
-        offset,
-        offset + WORKSPACE_SYNC_CHUNK_BYTES_V1,
-      );
+      const chunk = bytes.subarray(offset, offset + WORKSPACE_CHUNK_BYTES_V1);
       const output = await this.run(
         [
           "set -eu",
@@ -1315,7 +1285,7 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     if (oversized) return oversized;
     const staged = await this.stage(
       mount,
-      stagingName(generation.generationId, "pull"),
+      workspaceStagingNameV1(generation.generationId, "pull"),
       bytes,
     );
     if (staged && typeof staged !== "string") return staged;
@@ -1462,7 +1432,7 @@ export class FlySpriteSyncSurface implements ComputerSyncSurfaceV1 {
     if (oversized) return oversized;
     const staged = await this.stage(
       mount,
-      stagingName(generation.generationId, "conflict"),
+      workspaceStagingNameV1(generation.generationId, "conflict"),
       bytes,
     );
     if (staged && typeof staged !== "string") return staged;

package/src/workspace.test.ts

@@ -20,10 +20,11 @@ import {
   computerBotKey,
   type ComputerHostFactoryV1,
   FlySpriteComputer,
+  MAX_STORAGE_OUTPUT,
 } from "./computer.ts";
 import { FakeComputerHost, type FakeComputerRunV1 } from "./host-double.ts";
 import { FLY_WORKSPACE_LAYOUT, FlySpriteComputerProvider } from "./provider.ts";
-import { FlyComputerWorkspace } from "./workspace.ts";
+import { FlyComputerWorkspace, WORKSPACE_CHUNK_BYTES_V1 } from "./workspace.ts";
 
 const USER = "owner";
 const BOT = "health";
@@ -69,6 +70,19 @@ function sha256(bytes: Uint8Array): string {
   return createHash("sha256").update(bytes).digest("hex");
 }
 
+/**
+ * Bytes of an exact length whose every chunk differs from every other, so a
+ * chunk carried twice, dropped, or reordered changes the bytes rather than
+ * hiding inside a repeated pattern.
+ */
+function largeBytes(length: number): Uint8Array {
+  let text = "";
+  for (let index = 0; text.length < length; index += 1) {
+    text += `${index}:${"abcdefghijklmnopqrstuvwxyz".repeat(3)}\n`;
+  }
+  return new TextEncoder().encode(text.slice(0, length));
+}
+
 function quoted(shell: string, name: string): string | undefined {
   return new RegExp(`${name}='([^']*)'`).exec(shell)?.[1];
 }
@@ -83,28 +97,39 @@ class FakeWorkspaceDisk {
   offline = false;
   modifiedSeconds = 1_700_000_000;
 
+  /** Every script this disk was handed, in order. */
+  readonly scripts: string[] = [];
+  /** Rewrites the file at this path between two chunk commands of one read. */
+  midReadRewrite?: { path: string; bytes: Uint8Array };
+
   /** The runner the shared host double hands every script to. */
   readonly run = (script: string): FakeComputerRunV1 => {
+    this.scripts.push(script);
     if (this.offline) return { exitCode: 1, stderr: "Sprite is paused" };
+    // The real host's storage surface refuses an answer past this, so a double
+    // that returned one would let a suite prove a read works at a size the
+    // Computer would never have carried.
+    const bounded = (stdout: string): FakeComputerRunV1 =>
+      stdout.length > MAX_STORAGE_OUTPUT
+        ? { stdout: stdout.slice(0, MAX_STORAGE_OUTPUT), outputTruncated: true }
+        : { stdout };
+    if (script.includes("__STAGED__")) {
+      return bounded(this.stageChunk(script));
+    }
     const root = quoted(script, "ROOT");
     const relative = quoted(script, "REL");
     if (!root) return {};
     if (script.includes("__WRITTEN__") && relative) {
-      return { stdout: this.write(`${root}/${relative}`, script) };
+      return bounded(this.write(`${root}/${relative}`, script));
     }
     if (script.includes("__DELETED__") && relative) {
-      return { stdout: this.remove(`${root}/${relative}`, script) };
+      return bounded(this.remove(`${root}/${relative}`, script));
     }
     if (script.includes('find "$ROOT"')) {
-      return { stdout: this.list(root, script) };
+      return bounded(this.list(root, script));
     }
     if (relative) {
-      return {
-        stdout: this.load(
-          `${root}/${relative}`,
-          script.includes('base64 -w0 "$TARGET"'),
-        ),
-      };
+      return bounded(this.load(`${root}/${relative}`, script));
     }
     return {};
   };
@@ -122,14 +147,47 @@ class FakeWorkspaceDisk {
     return /if \[ "\$CURRENT" != '([^']*)' \]/.exec(shell)?.[1] ?? "";
   }
 
-  private write(path: string, shell: string): string {
-    if (this.current(path) !== this.expected(shell)) return "__CONFLICT__\n";
-    const bytes = /printf %s '([^']*)' \| base64 -d > "\$TMP"/.exec(shell)?.[1];
-    const meta = /printf %s '([^']*)' \| base64 -d > "\$MTMP"/.exec(shell)?.[1];
+  /** One appended chunk of a staged file, as the write stages it. */
+  private stageChunk(shell: string): string {
+    const path = quoted(shell, "STAGE") ?? "";
+    const encoded =
+      /printf %s '([^']*)' \| base64 -d >> "\$STAGE"/.exec(shell)?.[1] ?? "";
+    const chunk = Buffer.from(encoded, "base64");
+    const held = shell.includes('rm -f "$STAGE"')
+      ? undefined
+      : this.files.get(path)?.bytes;
     this.files.set(path, {
-      bytes: Uint8Array.from(Buffer.from(bytes ?? "", "base64")),
-      meta,
+      bytes: Uint8Array.from(
+        held ? Buffer.concat([Buffer.from(held), chunk]) : chunk,
+      ),
     });
+    return "__STAGED__\n";
+  }
+
+  private write(path: string, shell: string): string {
+    const stage = quoted(shell, "STAGE");
+    if (this.current(path) !== this.expected(shell)) {
+      if (stage) this.files.delete(stage);
+      return "__CONFLICT__\n";
+    }
+    const meta = /printf %s '([^']*)' \| base64 -d > "\$MTMP"/.exec(shell)?.[1];
+    let bytes: Uint8Array;
+    if (stage) {
+      // The staged bytes are digest-checked exactly as the emitted
+      // `sha256sum` line checks them, so a torn staging file is __CORRUPT__
+      // here for the same reason it would be on the Sprite.
+      const staged = this.files.get(stage)?.bytes ?? new Uint8Array();
+      this.files.delete(stage);
+      const expected = /f1\)" != '([0-9a-f]{64})'/.exec(shell)?.[1];
+      if (expected && sha256(staged) !== expected) return "__CORRUPT__\n";
+      bytes = staged;
+    } else {
+      const inline = /printf %s '([^']*)' \| base64 -d > "\$TMP"/.exec(
+        shell,
+      )?.[1];
+      bytes = Uint8Array.from(Buffer.from(inline ?? "", "base64"));
+    }
+    this.files.set(path, { bytes, meta });
     return "__WRITTEN__\n";
   }
 
@@ -140,7 +198,28 @@ class FakeWorkspaceDisk {
     return "__DELETED__\n";
   }
 
-  private load(path: string, withBytes: boolean): string {
+  /**
+   * The chunked file read: a header of sidecar, digest, size, and mtime with
+   * the first chunk, then one chunk per further command. `head -c` and
+   * `tail -c +N` are the coreutils the Workspace emits; the arithmetic is
+   * theirs, not an approximation.
+   */
+  private load(path: string, shell: string): string {
+    const chunk = /tail -c \+(\d+) "\$TARGET" \| head -c (\d+)/.exec(shell);
+    if (chunk) {
+      // A rewrite between two chunk commands is what makes a read report
+      // rather than stitch, so the double performs one where a test asks.
+      const rewrite = this.midReadRewrite;
+      if (rewrite) {
+        this.midReadRewrite = undefined;
+        this.files.set(rewrite.path, { bytes: rewrite.bytes });
+      }
+      const offset = Number(chunk[1]) - 1;
+      const limit = Number(chunk[2]);
+      const bytes = this.files.get(path)?.bytes;
+      const slice = bytes?.subarray(offset, offset + limit) ?? new Uint8Array();
+      return `${Buffer.from(slice).toString("base64")}\n`;
+    }
     const entry = this.files.get(path);
     if (!entry) return "__MISSING__\n";
     if (entry.bytes.byteLength > WORKSPACE_MAX_FILE_BYTES) {
@@ -152,7 +231,14 @@ class FakeWorkspaceDisk {
       String(entry.bytes.byteLength),
       String(this.modifiedSeconds),
     ];
-    if (withBytes) lines.push(Buffer.from(entry.bytes).toString("base64"));
+    const head = /head -c (\d+) "\$TARGET" \| base64 -w0/.exec(shell);
+    if (head) {
+      lines.push(
+        Buffer.from(entry.bytes.subarray(0, Number(head[1]))).toString(
+          "base64",
+        ),
+      );
+    }
     return `${lines.join("\n")}\n`;
   }
 
@@ -163,6 +249,9 @@ class FakeWorkspaceDisk {
     const rows = [...this.files.entries()]
       .filter(([path]) => path.startsWith(`${root}/`))
       .map(([path, entry]) => [path.slice(root.length + 1), entry] as const)
+      // The emitted `find` prunes the lock, generation, and sync directories,
+      // so a listing never shows a staging file mid-write.
+      .filter(([relative]) => !relative.startsWith(".frockbot-"))
       .filter(
         ([relative]) =>
           !prefix || relative === prefix || relative.startsWith(`${prefix}/`),
@@ -949,3 +1038,171 @@ describe("the Computer's sidecar is a hint; the Durable Object is the authority"
     expect(read.file.generation.writer).toEqual({ kind: "unattributed" });
   });
 });
+
+/**
+ * The Workspace's own per-file rule is what bounds a file; the shape of the
+ * commands that carry it never is.
+ *
+ * A Bot's file tools read and write through this surface, and both directions
+ * used to be one command carrying the whole file as base64: a 470 KB built
+ * Applet page is 627 KB of base64, past what a storage command may answer, so
+ * a Bot could not read a file it had just built. These prove the transport is
+ * no longer the constraint, in both directions, at sizes the Workspace admits.
+ */
+describe("Fly Workspace files past one storage command", () => {
+  const mount = workspaceMountPathV1(
+    FLY_WORKSPACE_LAYOUT,
+    packageRoot,
+    computerBotKey,
+  );
+
+  test("reads a file far larger than one storage command can answer, byte for byte", async () => {
+    const disk = new FakeWorkspaceDisk();
+    const bytes = largeBytes(900 * 1024);
+    disk.files.set(`${mount}/dist/ui.html`, { bytes });
+    const { workspace } = await openWorkspace(BOT, disk);
+
+    const read = await workspace.read({
+      root: packageRoot,
+      path: "dist/ui.html",
+    });
+
+    if (read.status !== "ok") throw new Error(read.reason);
+    expect(read.file.bytes).toEqual(bytes);
+    expect(read.file.generation.contentHash).toBe(sha256(bytes));
+    // The first command answers the size, the digest, and one chunk; the rest
+    // of the file is one command per further chunk.
+    expect(
+      disk.scripts.filter((script) => script.includes("$TARGET")).length,
+    ).toBe(Math.ceil(bytes.byteLength / WORKSPACE_CHUNK_BYTES_V1));
+  });
+
+  test("writes a file far larger than one storage command can carry, byte for byte", async () => {
+    const disk = new FakeWorkspaceDisk();
+    const { workspace } = await openWorkspace(BOT, disk);
+    const bytes = largeBytes(700 * 1024);
+
+    const written = await workspace.write({
+      path: { root: packageRoot, path: "dist/bundle.js" },
+      bytes,
+      writer: BOT_WRITER,
+      expectedGenerationId: null,
+    });
+
+    if (written.status !== "ok") throw new Error(written.reason);
+    expect(written.generation.contentHash).toBe(sha256(bytes));
+    expect(disk.files.get(`${mount}/dist/bundle.js`)?.bytes).toEqual(bytes);
+    // The staging file is gone the moment its bytes are in place, so nothing
+    // half-written is left under a durable root.
+    expect(
+      [...disk.files.keys()].filter((path) => path.includes("/staging/")),
+    ).toEqual([]);
+    const read = await workspace.read({
+      root: packageRoot,
+      path: "dist/bundle.js",
+    });
+    if (read.status !== "ok") throw new Error(read.reason);
+    expect(read.file.bytes).toEqual(bytes);
+  });
+
+  test("a file that fits in one command still takes one command, in each direction", async () => {
+    const disk = new FakeWorkspaceDisk();
+    const { workspace } = await openWorkspace(BOT, disk);
+
+    const written = await workspace.write({
+      path: { root: packageRoot, path: "note.md" },
+      bytes: new TextEncoder().encode("small"),
+      writer: BOT_WRITER,
+      expectedGenerationId: null,
+    });
+    if (written.status !== "ok") throw new Error(written.reason);
+    expect(disk.scripts.filter((script) => script.includes("$STAGE"))).toEqual(
+      [],
+    );
+    expect(
+      disk.scripts.filter((script) => script.includes("__WRITTEN__")),
+    ).toHaveLength(1);
+
+    disk.scripts.length = 0;
+    const read = await workspace.read({ root: packageRoot, path: "note.md" });
+    if (read.status !== "ok") throw new Error(read.reason);
+    expect(new TextDecoder().decode(read.file.bytes)).toBe("small");
+    expect(disk.scripts).toHaveLength(1);
+  });
+
+  test("reports a rewrite between two chunks rather than stitching two versions", async () => {
+    const disk = new FakeWorkspaceDisk();
+    const path = `${mount}/dist/ui.html`;
+    disk.files.set(path, { bytes: largeBytes(900 * 1024) });
+    // A shell on the Computer replaces the file after its size and digest were
+    // answered but before the last chunk arrives.
+    disk.midReadRewrite = { path, bytes: largeBytes(900 * 1024).reverse() };
+    const { workspace } = await openWorkspace(BOT, disk);
+
+    expect(
+      await workspace.read({ root: packageRoot, path: "dist/ui.html" }),
+    ).toMatchObject({
+      status: "unavailable",
+      reason: `"dist/ui.html" changed on the Computer while it was being read`,
+    });
+  });
+
+  // The write used to hold the lock across the whole script, which was fine
+  // while the whole file arrived inside it. Chunks arrive in commands of their
+  // own, and holding the lock across all of them would keep one writer's file
+  // open for as long as its bytes take to travel.
+  test("stages the chunks unlocked and holds the lock only around the final verify-and-rename", async () => {
+    const disk = new FakeWorkspaceDisk();
+    const { workspace } = await openWorkspace(BOT, disk);
+
+    const written = await workspace.write({
+      path: { root: packageRoot, path: "dist/bundle.js" },
+      bytes: largeBytes(700 * 1024),
+      writer: BOT_WRITER,
+      expectedGenerationId: null,
+    });
+
+    if (written.status !== "ok") throw new Error(written.reason);
+    const staging = disk.scripts.filter((script) =>
+      script.includes("__STAGED__"),
+    );
+    expect(staging.length).toBeGreaterThan(1);
+    for (const script of staging) expect(script).not.toContain("flock");
+    const commit = disk.scripts.filter((script) =>
+      script.includes("__WRITTEN__"),
+    );
+    expect(commit).toHaveLength(1);
+    expect(commit[0]).toContain("flock -x 9");
+    // Under the lock: the expected generation, the staged bytes' digest, and
+    // the rename. No file bytes travel inside it.
+    expect(commit[0]).toContain('mv "$STAGE" "$TMP"');
+    expect(commit[0]).not.toContain('base64 -d > "$TMP"');
+    expect(commit[0]!.length).toBeLessThan(WORKSPACE_CHUNK_BYTES_V1);
+  });
+
+  test("refuses a file past the Workspace's own limit in plain words, in each direction", async () => {
+    const disk = new FakeWorkspaceDisk();
+    disk.files.set(`${mount}/huge.bin`, {
+      bytes: new Uint8Array(WORKSPACE_MAX_FILE_BYTES + 1),
+    });
+    const { workspace } = await openWorkspace(BOT, disk);
+
+    expect(
+      await workspace.read({ root: packageRoot, path: "huge.bin" }),
+    ).toMatchObject({
+      status: "refused",
+      reason: `"huge.bin" is past the 1 MB limit on a Workspace file`,
+    });
+    expect(
+      await workspace.write({
+        path: { root: packageRoot, path: "other.bin" },
+        bytes: new Uint8Array(WORKSPACE_MAX_FILE_BYTES + 1),
+        writer: BOT_WRITER,
+        expectedGenerationId: null,
+      }),
+    ).toMatchObject({
+      status: "refused",
+      reason: `"other.bin" is past the 1 MB limit on a Workspace file`,
+    });
+  });
+});

package/src/workspace.ts

@@ -76,6 +76,47 @@ export const SYNC_CONFLICTS_DIR = "conflicts";
  * is moved into place, under `WORKSPACE_SYNC_DIR`.
  */
 export const SYNC_STAGING_DIR = "staging";
+/**
+ * The most file bytes one storage command carries, in either direction.
+ *
+ * A command's answer travels as base64, so a chunk this size comes back as
+ * roughly 350 KB — inside the half megabyte an answer may be — and goes out
+ * inside a script well inside the megabyte a script may be. A file larger than
+ * one chunk travels as several commands rather than as one command that would
+ * be refused for its size, so the Workspace's own per-file rule is what bounds
+ * a file and the shape of the commands never is.
+ */
+export const WORKSPACE_CHUNK_BYTES_V1 = 256 * 1024;
+
+/** Every chunk offset after the first, in bytes, for a file of this size. */
+export function workspaceChunkOffsetsV1(size: number): number[] {
+  const offsets: number[] = [];
+  for (
+    let offset = WORKSPACE_CHUNK_BYTES_V1;
+    offset < size;
+    offset += WORKSPACE_CHUNK_BYTES_V1
+  ) {
+    offsets.push(offset);
+  }
+  return offsets;
+}
+
+/** A staging file name that is one path segment whatever the id looks like. */
+export function workspaceStagingNameV1(
+  generationId: string,
+  kind: string,
+): string {
+  const safe = generationId.replaceAll(/[^A-Za-z0-9._-]/g, "-").slice(0, 128);
+  return `${safe}.${kind}`;
+}
+
+/**
+ * The Workspace's per-file limit as a person reads it. Derived, so it cannot
+ * drift from the rule it describes, and stated in the refusal instead of a
+ * byte count nobody outside this code recognizes.
+ */
+const MAX_FILE_LABEL = `${Math.round(WORKSPACE_MAX_FILE_BYTES / (1024 * 1024))} MB`;
+
 const GENERATIONS_DIR = WORKSPACE_GENERATIONS_DIR;
 const LOCKS_DIR = ".frockbot-locks";
 /** The sha-256 of no bytes; a deletion tombstone's content address. */
@@ -402,10 +443,13 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
     const relative = this.path(path);
     if (typeof relative !== "string") return relative;
     const mount = this.mount(path.root);
-    const script = [
+    const prelude = [
       `ROOT=${shellQuote(mount)}`,
       `REL=${shellQuote(relative)}`,
       'TARGET="$ROOT/$REL"',
+    ];
+    const script = [
+      ...prelude,
       `META="$ROOT/${GENERATIONS_DIR}/$REL"`,
       'if [ ! -f "$TARGET" ]; then echo __MISSING__; exit 0; fi',
       'SIZE=$(stat -c %s "$TARGET")',
@@ -414,7 +458,15 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
       'sha256sum "$TARGET" | cut -d" " -f1',
       'printf "%s\\n" "$SIZE"',
       'stat -c %Y "$TARGET"',
-      withBytes ? 'base64 -w0 "$TARGET"; echo' : "",
+      // The size and the digest come back before any bytes do, so the rest of
+      // the file can be asked for one bounded chunk at a time and the pieces
+      // proven to be one file. A whole file as one base64 answer stopped
+      // working long before a file got large: half a megabyte of built Applet
+      // page is two thirds of a megabyte of answer, which the storage surface
+      // refuses outright rather than truncating.
+      withBytes
+        ? `head -c ${WORKSPACE_CHUNK_BYTES_V1} "$TARGET" | base64 -w0; echo`
+        : "",
     ]
       .filter(Boolean)
       .join("\n");
@@ -425,10 +477,7 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
       return failure("not-found", `No such Workspace file: ${relative}`);
     }
     if (lines[0]?.trim() === "__TOO_LARGE__") {
-      return failure(
-        "refused",
-        `Workspace file exceeds ${WORKSPACE_MAX_FILE_BYTES} bytes`,
-      );
+      return this.tooLarge(relative);
     }
     const [
       meta = "",
@@ -446,15 +495,50 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
       size: Number(size.trim()),
       modifiedSeconds: Number(modified.trim()),
     };
-    const generation = await this.generationOf(path.root, relative, raw);
+    if (!Number.isSafeInteger(raw.size) || raw.size < 0) {
+      return failure("unavailable", "Invalid Fly Workspace file response");
+    }
+    if (!withBytes) {
+      return { generation: await this.generationOf(path.root, relative, raw) };
+    }
+    const chunks = [Buffer.from(encoded.trim(), "base64")];
+    for (const offset of workspaceChunkOffsetsV1(raw.size)) {
+      const next = await this.run(
+        [
+          ...prelude,
+          // `tail -c +N` counts from one, so the offset is one past the bytes
+          // already carried.
+          `tail -c +${offset + 1} "$TARGET" | head -c ${WORKSPACE_CHUNK_BYTES_V1} | base64 -w0; echo`,
+        ].join("\n"),
+        signal,
+      );
+      if (typeof next !== "string") return next;
+      chunks.push(Buffer.from(next.trim(), "base64"));
+    }
+    const bytes = Buffer.concat(chunks);
+    // The digest is the proof the chunks are one file. A file rewritten
+    // between two commands is reported, never stitched together out of two
+    // different versions of itself.
+    if (bytes.byteLength !== raw.size || digest(bytes) !== raw.contentHash) {
+      return failure(
+        "unavailable",
+        `"${relative}" changed on the Computer while it was being read`,
+      );
+    }
     return {
-      generation,
-      ...(withBytes
-        ? { bytes: Uint8Array.from(Buffer.from(encoded.trim(), "base64")) }
-        : {}),
+      generation: await this.generationOf(path.root, relative, raw),
+      bytes: Uint8Array.from(bytes),
     };
   }
 
+  /** The one refusal for a file past the Workspace's own per-file rule. */
+  private tooLarge(relative: string): WorkspaceFailureV1 {
+    return failure(
+      "refused",
+      `"${relative}" is past the ${MAX_FILE_LABEL} limit on a Workspace file`,
+    );
+  }
+
   async read(path: WorkspacePathV1): Promise<WorkspaceReadOutcomeV1> {
     const loaded = await this.load(path, true);
     if ("status" in loaded) return loaded;
@@ -559,6 +643,50 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
     };
   }
 
+  /**
+   * Puts bytes past one command on the Computer under a staging file, chunk by
+   * chunk, and answers where they landed.
+   *
+   * Bytes that fit in one command take no staging file at all — the caller
+   * writes them inline, which is one command and the overwhelmingly common
+   * case. Anything larger is appended chunk by chunk with no lock held, and
+   * the caller's own locked command moves it into place, so a file only ever
+   * appears at its real path complete.
+   */
+  private async stage(
+    mount: string,
+    name: string,
+    bytes: Uint8Array,
+  ): Promise<string | WorkspaceFailureV1 | undefined> {
+    if (bytes.byteLength <= WORKSPACE_CHUNK_BYTES_V1) return undefined;
+    const staged = `${mount}/${WORKSPACE_SYNC_DIR}/${SYNC_STAGING_DIR}/${name}`;
+    for (
+      let offset = 0;
+      offset < bytes.byteLength;
+      offset += WORKSPACE_CHUNK_BYTES_V1
+    ) {
+      const chunk = bytes.subarray(offset, offset + WORKSPACE_CHUNK_BYTES_V1);
+      const output = await this.run(
+        [
+          "set -eu",
+          `STAGE=${shellQuote(staged)}`,
+          'mkdir -p "$(dirname "$STAGE")"',
+          // A staging name is this write's own, so a leftover file under it is
+          // a previous attempt's and never another writer's.
+          ...(offset === 0 ? ['rm -f "$STAGE"'] : []),
+          `printf %s ${shellQuote(Buffer.from(chunk).toString("base64"))} | base64 -d >> "$STAGE"`,
+          'chmod 600 "$STAGE"',
+          "echo __STAGED__",
+        ].join("\n"),
+      );
+      if (typeof output !== "string") return output;
+      if (!output.includes("__STAGED__")) {
+        return failure("unavailable", "Invalid Fly Workspace write response");
+      }
+    }
+    return staged;
+  }
+
   async write(
     request: WorkspaceWriteRequestV1,
   ): Promise<WorkspaceWriteOutcomeV1> {
@@ -567,10 +695,7 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
     const relative = this.path(request.path);
     if (typeof relative !== "string") return relative;
     if (request.bytes.byteLength > WORKSPACE_MAX_FILE_BYTES) {
-      return failure(
-        "refused",
-        `Workspace file exceeds ${WORKSPACE_MAX_FILE_BYTES} bytes`,
-      );
+      return this.tooLarge(relative);
     }
     const writtenAt = new Date();
     // The ledger mints when there is one, so the id this write records is the
@@ -595,12 +720,26 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
       writtenAt: writtenAt.toISOString(),
     };
     const mount = this.mount(request.path.root);
+    // Bytes past one command are staged first, outside the lock: the file
+    // takes several commands to carry, and holding the lock across all of them
+    // would keep one writer's file open for as long as its bytes take to
+    // arrive. The staging name is this write's own minted generation, so two
+    // writers of the same path never share a staging file, and the lock is
+    // taken only for the last command — the one that checks the generation the
+    // writer expected, proves the staged bytes, and renames them into place.
+    const staged = await this.stage(
+      mount,
+      workspaceStagingNameV1(generationId, "write"),
+      request.bytes,
+    );
+    if (staged !== undefined && typeof staged !== "string") return staged;
     const script = [
       "set -eu",
       `ROOT=${shellQuote(mount)}`,
       `REL=${shellQuote(relative)}`,
       'TARGET="$ROOT/$REL"',
       `META="$ROOT/${GENERATIONS_DIR}/$REL"`,
+      ...(staged ? [`STAGE=${shellQuote(staged)}`] : []),
       `mkdir -p "$(dirname "$TARGET")" "$(dirname "$META")" "$ROOT/${LOCKS_DIR}"`,
       'LOCK=$(printf %s "$REL" | sha256sum | cut -d" " -f1)',
       `exec 9>"$ROOT/${LOCKS_DIR}/$LOCK"`,
@@ -608,9 +747,20 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
       "CURRENT=",
       'if [ -f "$TARGET" ] && [ -f "$META" ]; then CURRENT=$(sed -n 1p "$META"); fi',
       'if [ -f "$TARGET" ] && [ ! -f "$META" ]; then CURRENT=__UNRECORDED__; fi',
-      `if [ "$CURRENT" != ${shellQuote(request.expectedGenerationId ?? "")} ]; then echo __CONFLICT__; exit 0; fi`,
+      `if [ "$CURRENT" != ${shellQuote(request.expectedGenerationId ?? "")} ]; then ${staged ? 'rm -f "$STAGE"; ' : ""}echo __CONFLICT__; exit 0; fi`,
+      // A half-written staging file must never become a durable-root file, so
+      // the staged bytes answer for themselves before anything is renamed.
+      ...(staged
+        ? [
+            `if [ "$(sha256sum "$STAGE" | cut -d" " -f1)" != ${shellQuote(generation.contentHash)} ]; then rm -f "$STAGE"; echo __CORRUPT__; exit 0; fi`,
+          ]
+        : []),
       'TMP=$(mktemp "${TARGET}.XXXXXX")',
-      `printf %s ${shellQuote(Buffer.from(request.bytes).toString("base64"))} | base64 -d > "$TMP"`,
+      ...(staged
+        ? ['mv "$STAGE" "$TMP"']
+        : [
+            `printf %s ${shellQuote(Buffer.from(request.bytes).toString("base64"))} | base64 -d > "$TMP"`,
+          ]),
       'chmod 600 "$TMP"',
       'mv "$TMP" "$TARGET"',
       'MTMP=$(mktemp "${META}.XXXXXX")',
@@ -627,6 +777,12 @@ export class FlyWorkspaceFiles implements WorkspaceFilesV1 {
         `Workspace file changed since the writer last saw it: ${relative}`,
       );
     }
+    if (output.includes("__CORRUPT__")) {
+      return failure(
+        "unavailable",
+        `"${relative}" did not reach the Computer intact`,
+      );
+    }
     if (!output.includes("__WRITTEN__")) {
       return failure("unavailable", "Invalid Fly Workspace write response");
     }