virtualmatter 0.6.2 → 0.6.4

package/README.md

@@ -44,6 +44,11 @@ was stopped), your copy stays put and the remote version lands next to it as
 `<name>.remote-conflict`. Merge, save, and it pushes. Edits made while sync
 was stopped go out when it starts again.
 
+Large voxel and terrain files (several GB is normal) are streamed to disk,
+never loaded into memory. Sync does not push a file over 8 MB, the most the
+world accepts in one write. It warns once and leaves that file as it is on
+both sides.
+
 `make`, `pull` and `sync` print the world's editor link ending in `?chat=closed`.
 Open it in any browser to watch changes land live - no install needed.
 
@@ -121,8 +126,8 @@ deploying it.
 | `pull [target] [dir]` | Mirror a world's file tree. `target` is any link to the world (or your website) or a framing id, and always resolves to the world's editor; omitted, it uses this folder's world or your only one. |
 | `sync [dir]` | Watch + two-way sync with the live session. Ctrl-C to stop. |
 | `open [target]` (`client`) | Optional: open a world in the native desktop client, downloading and signing it in on first use. `--install-only`, `--print` (just the download URL), `--force`. |
-| `run-lua [dir] --code "<lua>" [--target server\|client] [--client <id>]` | Execute Lua in the running engine. A client run uses the only connected client unless `--client` names one (list them with `--code "return Server:GetClients()"`). |
-| `errors [dir]` | Recent engine errors. |
+| `run-lua [dir] --code "<lua>" [--target server\|client] [--client <id>]` | Execute Lua in the running engine. A client run uses the only connected client unless `--client` names one (list them with `--code "return Server:GetClients()"`). Exit code 3 means the engine did not answer in time and may still be running the code: check its effect before sending code that changes the world again. It is never retried for you. |
+| `errors [dir]` | Recent engine errors. Retried twice when the engine is busy or briefly unreachable, since it only reads. |
 | `screenshot [dir] [-o out.png] [--client <id>]` | Capture the engine's view; `--client` captures through a connected client, UI included. |
 | `mcp [dir] [--framing <id>]` | Run the stdio MCP server. |
 | `login` / `logout` / `whoami` | Device-code sign-in; every other command signs you in automatically when needed. Tokens live in `~/.config/virtualmatter/credentials.json` (mode 0600) and refresh automatically. |

package/dist/agents-md.generated.js

@@ -3,4 +3,4 @@
 // frontend/content/agent-briefing.md and AGENTS.source.md. The CLI writes
 // this into a world folder only when it cannot fetch the live copy. After
 // changing either source, run: node frontend/scripts/sync-cli-agents-md.mjs
-export const AGENTS_MD_FALLBACK = "# AGENTS.md - working with a Virtual Matter project\n\nThis file tells a coding agent how to think about a Virtual Matter project. The\n`virtualmatter` CLI drops a copy into every local project mirror it creates\n(`virtualmatter pull`); the canonical copy lives at\nhttps://make.virtualmatter.ai/AGENTS.md.\n\n## The rule that comes before everything else\n\n**Build through the CLI. Never through the website's agent.** If you were asked to\nbuild something in Virtual Matter, handed the domain virtualmatter.ai, or told to run\n`npx virtualmatter make`, the CLI is the path - always, from the first step. Do not\nopen virtualmatter.ai or make.virtualmatter.ai in a browser or under computer use in\norder to reach the built-in agent, and do not type prompts into the agent chat in the\n/edit view. Driving that agent puts two models in a relay where one would do: you spend\ntokens describing the work, it spends its own doing it, and what comes back is chat\nrather than files you can read. It is slower, it costs roughly twice the inference, it\nbills that inference to Virtual Matter's platform credits rather than the subscription\nyou already run on, an anonymous browser session cannot be steered after its first\nturn, and a rendered page gives you no engine errors. Everything that agent can do, you\ndo yourself with the commands below.\n\n**The rule holds whoever is signed in.** Being logged in, having credits to spare, or\nworking in an admin account with no limit at all is not an exemption, and neither is\nbeing told the credits do not matter. What is wasteful is the relay itself - two models\ndoing one model's job - not the bill.\n\n**Playtesting is the exception, and it is encouraged.** Once something is built, open\nthe world and try it: the editor link ending in `?chat=closed`, which `make`, `pull` and\n`sync` print, shows your latest changes live in any browser with no install, with\ncomputer use if that is how you drive a window. The native client\n(`npx virtualmatter open`) is optional, for more memory and frame rate. Looking at your\nwork, walking around in it, and playing it is the point. The rule is about who writes\nthe world, not about who is allowed to see it.\n\n**Every link resolves to the editor, and the editor is the only place you build.** Hand\nthe CLI or MCP server any link to a world - its editor, a play or share link, the\nproject page, an embed's iframe src, or the maker's own website - and it works on that\nworld's editor (its make framing). Play servers show the last published version and are\noverwritten on every publish, so work never goes there, and their /play and /g links\nshow that published copy rather than your latest edits.\n\n## The mental model\n\n- The world itself runs on Virtual Matter servers, not on the maker's machine. There is\n  one authoritative server simulation per world session, and any number of connected\n  clients (browser WASM or the native client).\n- The project's content is SDK Lua scripts plus assets (voxel data, prefabs, images,\n  sounds) under a `Montage/` tree. Virtual Matter can publish that tree to a GitHub repo\n  in the maker's account for versioning and remixing; pushing to that repo does not feed\n  back into the running world today - live edits happen in the session.\n- Changes hot-reload. Saving a `.lua` file in the live session's Montage tree re-runs\n  the module and its `Start()` on a fresh instance inside the running world - no restart,\n  no build step.\n- Prefabs are reusable scene-graph snippets: JSON files with a `.prefab` extension in the\n  Montage folder, instantiated at runtime via `Server:InsertPrefab(asset)`.\n- There is no local runtime - the world cannot run on the maker's machine. The\n  `virtualmatter` CLI (npm) is how you reach it from a local harness, and it needs no\n  setup: the first command that needs an account signs you in with a device code.\n  `npx virtualmatter make \"My world\"` makes a world and mirrors its Montage tree\n  into `./my-world`; `npx virtualmatter pull <any Virtual Matter link>` mirrors an\n  existing one (/edit, /play, /g, /p, /projects links all work, with or without a\n  readable slug); `npx virtualmatter list` shows your worlds; `npx virtualmatter sync`\n  live-pushes saves into the running session (which hot-reloads them);\n  `npx virtualmatter run-lua` / `errors` / `screenshot` drive the engine;\n  `npx virtualmatter open` optionally opens the world in the native desktop client,\n  downloaded and signed in on first use; and `npx virtualmatter mcp` serves\n  all of it over MCP. A mirrored folder carries `.mcp.json` and `.cursor/mcp.json`\n  (so Claude Code and Cursor register the MCP server on their own), this file, and a\n  `CLAUDE.md` that imports it. Folders from virtualmatter 0.5.0 on also carry\n  `.codex/config.toml`, which Codex loads once you trust the folder; with an older\n  CLI, or if Codex does not list the server, register it once with\n  `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. In Claude Code outside a\n  mirrored folder, use `claude mcp add virtualmatter -- npx -y virtualmatter mcp`. The\n  server works before a world\n  is selected (`list_projects`, `create_project`, `select_project`), then exposes\n  `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`,\n  `capture_screenshot`, `open_native_client`, and `world_info`.\n- Work through the CLI, not the website - see the rule above. Prompting the built-in\n  agent to do your building is the one thing to avoid; opening the world to play it is\n  not.\n- Seeing your work: `virtualmatter screenshot` shoots a default overview of the world\n  origin, `--target <object>` frames one object by name or id, and `--at x,y,z --rot\n  yaw,pitch,roll` places the camera exactly. Y is up and -Z is forward, and the\n  rotation really is yaw first: yaw 0 faces -Z, pitch -90 looks straight down, pitch 0\n  is the horizon. The MCP `capture_screenshot`\n  tool takes the same arguments. Verify a change with a screenshot plus `errors` rather\n  than assuming a write worked.\n- The mirrored folder's AGENTS.md is this guide followed by the engine SDK's own agent guide\n  (the AGENTS.md that lives in every Montage tree and inside the desktop client's\n  Data/Sdk/Montage/). The engine guide assumes an in-session agent driving the engine\n  through `atomo`; the merged file maps each `atomo` step to the CLI or MCP equivalent, and\n  the `Skills/*.md` references it points at are in the folder. The SDK's own tooling\n  (`atomo`, `vm_auth.py`, the agent-log hooks) is not mirrored: it only works inside a\n  session. Sandboxed agents need network access for every CLI command.\n\n## Reference\n\nThe same facts as terse lists, for quick lookup.\n\n### Project model\n- A project (\"montage\") is one voxel world hosted with Virtual Matter.\n- A project has framings: \"make\" framings (editing sessions) and \"play\"\n  framings (public play sessions). A framing is a running session slot\n  on a voxel host.\n- Project content = SDK Lua scripts + assets under a Montage/ tree.\n  Edits made in the live session hot-reload into the running world.\n  The tree can be published to a maker-owned GitHub repo.\n\n### URL shapes (make.virtualmatter.ai)\n- /new                 builder for people: create a world from a prompt\n                       (also at https://virtualmatter.ai/); coding agents\n                       use npx virtualmatter make instead\n- /edit/<framing-id>   maker session: live world + agent chat. The chat is\n                       for people; a coding agent builds with the CLI and\n                       never prompts it\n                       (also /edit/<slug>-<framing-id>; the CLI accepts both)\n- /play/<framing-id>   play session for a specific framing\n- /g/<id>              share URL resolver: 302s to a live session\n\n### APIs (unauthenticated)\n- GET https://make.virtualmatter.ai/api/v1/public/native-clients\n  JSON: { iteration, clients: [{ platform, kind, variant, url, filename,\n  file_size, branch, commit, match }] } - per-platform native client\n  installers (kind \"download\") or store links (kind \"store\", iOS).\n  Windows and Linux list two downloads each: variant \"installer\" /\n  \"flatpak\" for people, and \"portable\" / \"tarball\", the file tree the\n  CLI installs.\n\n### CLI + MCP (npm package \"virtualmatter\", Node >= 20)\n- npx virtualmatter make \"<name>\"     make a world, mirror it into ./<slug>\n- npx virtualmatter pull <link>       mirror an existing world (any link shape)\n- npx virtualmatter list              your worlds with framing ids + URLs\n- npx virtualmatter sync              live-push saves into the running world\n- npx virtualmatter open              optional: open it in the native client\n- npx virtualmatter mcp               stdio MCP server (list_projects,\n  create_project, select_project, list_files, read_file, write_file,\n  run_lua, get_engine_errors, capture_screenshot, open_native_client,\n  world_info)\n- Sign-in happens on first use (device code); no separate login step.\n- These commands are the whole build path. Never prompt the built-in\n  agent on the site to do the work; a browser or the native client is\n  for playtesting what you built.\n- Any link to a world (editor, play or share link, project page, embed,\n  or the maker's own website) resolves to its editor, the only place\n  the CLI and MCP server work. Play servers show the last published\n  version and are overwritten on publish.\n- Watch changes land live at the editor link ending in ?chat=closed,\n  in any browser, no install. The native client is optional.\n- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and\n  CLAUDE.md, so Claude Code and Cursor register the server on their own.\n- Codex: folders from 0.5.0 on carry .codex/config.toml, loaded once the\n  folder is trusted; otherwise register the server once:\n  codex mcp add virtualmatter -- npx -y virtualmatter mcp\n\n## SDK Lua cheat sheet\n\nThe scripting language is Lua 5.4, sandboxed: `os`, `io`, `require`, `package`,\n`dofile`, `loadfile`, `loadstring` are nil. `math`, `string`, `table`, `coroutine`\nremain. No `os.time` - use `Time.time` (sim time), `Time.frame`, or\n`AE:GetDebugTime()` (wall clock).\n\n### Script shape\n\nEvery persistent behavior is a `.lua` file in the Montage tree returning a `self` table:\n\n```lua\nlocal self = {}\nfunction self:Start() end\nfunction self:Update(deltaTime) end\nreturn self\n```\n\nAttach to an object with `obj:AddScript(\"My Folder/Example.lua\", sync)` - the path is\nrelative to the Montage root; `sync = true` replicates the script to clients.\n`obj:FindScript(\"Example\")` returns the live instance.\n\n### Server / client split\n\nThe same script runs on the server and (when synced) on every client. Branch with\n`self.onServer` / `self.onClient`:\n\n```lua\nfunction self:Update(dt)\n    if self.onClient then return end  -- voxel edits are server-only\n    -- authoritative logic here\nend\n```\n\nNothing replicates automatically: set `syncToClients = true` on the script or\nVoxelData component, and use `util:makeNetworkedTable(self, { hp = 100 })` for\nproperties that should sync (server writes, clients read, deltas only).\n`obj.pos` / `obj.rot` do not auto-sync - replicate them yourself.\n\n### RPC\n\n```lua\nself:RPC(\"serverDoSomething\", pos, dir)   -- on a client: goes to the server\nfunction self:serverDoSomething(pos, dir, clientID)  -- clientID auto-appended\n    assert(self.onServer)\nend\n```\n\nOn the server, `self:RPC(...)` fans out to all clients. Reliable, FIFO per direction.\nRequires `self.component.syncToClients = true`.\n\n### Scene and objects (server)\n\n```lua\nlocal ob = Scene:CreateObject(\"Name\")\nob.save = true\nob:AddScript(\"Path/Script.lua\")\nScene:GetObjectByName(\"Name\")\nScene:CloneObject(ob)                 -- prefer over rebuilding\nob.active = false                     -- prefer over destroy\nob:AddTag(\"Enemy\"); FindObjectsWithTag(\"Enemy\")  -- tags are runtime-only state\n```\n\n### Voxel editing (server only, async)\n\n```lua\nVox:Add(Sphere(pos, 2)):Color(1, 0, 0):Run()\nVox:Add(Box(Vec3(0, -1, 0), Vec3(20, 2, 20))):ForceStatic():Run()\n```\n\nShapes: `Box(center, fullSize)`, `Sphere(center, r)`, `Capsule(p1, p2, r)`,\n`Cylinder(p1, p2, r1[, r2])`. `Run()` is async - chain `:OnFinished(fn)` before\n`:Run()` to read post-commit state. Big edits stall the frame for every client;\nkeep in-game edits small and infrequent.\n\n### Input (event-driven, client input reaches the server)\n\n```lua\nself.component.syncToClients = true\nevents.keyDown.addListener(self, function(key, from) self.keys[key] = true end)\nevents.keyUp.addListener(self, function(key, from) self.keys[key] = false end)\n```\n\nPlayer-driven movement must be client-predicted - never gate the player's own\nfeedback on the server round-trip.\n\n### Physics\n\n```lua\nlocal rb = obj:AddComponent(\"RigidBody\")\nrb:AddImpulse(Vec3(0, 50, 0), obj.pos)\nrb.velocity; rb.mass; rb.gravityScale\n```\n\n### Time and diagnostics\n\n```lua\nTime.dt; Time.time; Time.frame; Time.timeScale\nAE:GetLogValue(\"Raycasts\")        -- engine counters, e.g. raycasts this frame\nAE:GetAssets()                    -- list all assets (APIs take Assets, not paths)\n```\n\n### UI (client-side HUD)\n\nBuild screen UI with the MUI builder: `UI:AddPanel|AddButton|AddLabel|AddSlider|...`\nchained with `:Set{...}`; flexbox-like row-wrap layout.\n\n## Conventions\n\n- Coordinates: Y is up, -Z is forward, X is right.\n- Script files are named in capital case with spaces (`Character Controller.lua`).\n- Check whether a script is already attached before adding it - duplicates run twice.\n- The server is for authority (world edits, spawns, state); clients are for feel\n  (prediction, FX, UI).\n\n## Embed or build a world for an existing website\n\nFor a shared project link, fetch `/api/v1/public/embed?target=<encoded-link>`\nand follow `/embed-guide.md`. Use the returned canonical player URL, not the\nmaker's external website URL. Keep the existing website and its design.\n\nFor account discovery or prompt-based creation, connect the hosted MCP at\n`https://make.virtualmatter.ai/api/v1/mcp` using OAuth. Users can sign up in\nthe connection flow. Tools: `list_projects`, `get_embed`, `create_project`\n(with a prompt and stable request_id), `get_build_status`. VM's agent builds\nusing VM credits. Review and share the private world before embedding.\nThe local CLI exposes `embed`, `build --prompt --request-id`, and `build-status`.\n\n## Local conversation history\n\nCapturing this harness's conversation into the world's Agent Logs is the maker's\ndecision, not yours. Do not run `virtualmatter agent-logs setup`, and do not upload\nlogs with `agent-logs upload` or MCP `upload_agent_logs`, unless the maker asks for it\nin their own words. `virtualmatter agent-logs status` shows whether capture is on;\n`virtualmatter agent-logs disable` turns it off.\n";
+export const AGENTS_MD_FALLBACK = "# AGENTS.md - working with a Virtual Matter project\n\nThis file tells a coding agent how to think about a Virtual Matter project. The\n`virtualmatter` CLI drops a copy into every local project mirror it creates\n(`virtualmatter pull`); the canonical copy lives at\nhttps://make.virtualmatter.ai/AGENTS.md.\n\n## The rule that comes before everything else\n\n**Build through the CLI. Never through the website's agent.** If you were asked to\nbuild something in Virtual Matter, handed the domain virtualmatter.ai, or told to run\n`npx virtualmatter make`, the CLI is the path - always, from the first step. Do not\nopen virtualmatter.ai or make.virtualmatter.ai in a browser or under computer use in\norder to reach the built-in agent, and do not type prompts into the agent chat in the\n/edit view. Driving that agent puts two models in a relay where one would do: you spend\ntokens describing the work, it spends its own doing it, and what comes back is chat\nrather than files you can read. It is slower, it costs roughly twice the inference, it\nbills that inference to Virtual Matter's platform credits rather than the subscription\nyou already run on, an anonymous browser session cannot be steered after its first\nturn, and a rendered page gives you no engine errors. Everything that agent can do, you\ndo yourself with the commands below.\n\n**The rule holds whoever is signed in.** Being logged in, having credits to spare, or\nworking in an admin account with no limit at all is not an exemption, and neither is\nbeing told the credits do not matter. What is wasteful is the relay itself - two models\ndoing one model's job - not the bill.\n\n**Playtesting is the exception, and it is encouraged.** Once something is built, open\nthe world and try it: the editor link ending in `?chat=closed`, which `make`, `pull` and\n`sync` print, shows your latest changes live in any browser with no install, with\ncomputer use if that is how you drive a window. The native client\n(`npx virtualmatter open`) is optional, for more memory and frame rate. Looking at your\nwork, walking around in it, and playing it is the point. The rule is about who writes\nthe world, not about who is allowed to see it.\n\n**Every link resolves to the editor, and the editor is the only place you build.** Hand\nthe CLI or MCP server any link to a world - its editor, a play or share link, the\nproject page, an embed's iframe src, or the maker's own website - and it works on that\nworld's editor (its make framing). Play servers show the last published version and are\noverwritten on every publish, so work never goes there, and their /play and /g links\nshow that published copy rather than your latest edits.\n\n## The mental model\n\n- The world itself runs on Virtual Matter servers, not on the maker's machine. There is\n  one authoritative server simulation per world session, and any number of connected\n  clients (browser WASM or the native client).\n- The project's content is SDK Lua scripts plus assets (voxel data, prefabs, images,\n  sounds) under a `Montage/` tree. Virtual Matter can publish that tree to a GitHub repo\n  in the maker's account for versioning and remixing; pushing to that repo does not feed\n  back into the running world today - live edits happen in the session.\n- Changes hot-reload. Saving a `.lua` file in the live session's Montage tree re-runs\n  the module and its `Start()` on a fresh instance inside the running world - no restart,\n  no build step.\n- Prefabs are reusable scene-graph snippets: JSON files with a `.prefab` extension in the\n  Montage folder, instantiated at runtime via `Server:InsertPrefab(asset)`.\n- There is no local runtime - the world cannot run on the maker's machine. The\n  `virtualmatter` CLI (npm) is how you reach it from a local harness, and it needs no\n  setup: the first command that needs an account signs you in with a device code.\n  `npx virtualmatter make \"My world\"` makes a world and mirrors its Montage tree\n  into `./my-world`; `npx virtualmatter pull <any Virtual Matter link>` mirrors an\n  existing one (/edit, /play, /g, /p, /projects links all work, with or without a\n  readable slug); `npx virtualmatter list` shows your worlds; `npx virtualmatter sync`\n  live-pushes saves into the running session (which hot-reloads them);\n  `npx virtualmatter run-lua` / `errors` / `screenshot` drive the engine;\n  `npx virtualmatter open` optionally opens the world in the native desktop client,\n  downloaded and signed in on first use; and `npx virtualmatter mcp` serves\n  all of it over MCP. A mirrored folder carries `.mcp.json` and `.cursor/mcp.json`\n  (so Claude Code and Cursor register the MCP server on their own), this file, and a\n  `CLAUDE.md` that imports it. Folders from virtualmatter 0.5.0 on also carry\n  `.codex/config.toml`, which Codex loads once you trust the folder; with an older\n  CLI, or if Codex does not list the server, register it once with\n  `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. In Claude Code outside a\n  mirrored folder, use `claude mcp add virtualmatter -- npx -y virtualmatter mcp`. The\n  server works before a world\n  is selected (`list_projects`, `create_project`, `select_project`), then exposes\n  `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`,\n  `capture_screenshot`, `open_native_client`, and `world_info`.\n- Work through the CLI, not the website - see the rule above. Prompting the built-in\n  agent to do your building is the one thing to avoid; opening the world to play it is\n  not.\n- Seeing your work: `virtualmatter screenshot` shoots a default overview of the world\n  origin, `--target <object>` frames one object by name or id, and `--at x,y,z --rot\n  yaw,pitch,roll` places the camera exactly. Y is up and -Z is forward, and the\n  rotation really is yaw first: yaw 0 faces -Z, pitch -90 looks straight down, pitch 0\n  is the horizon. The MCP `capture_screenshot`\n  tool takes the same arguments. Verify a change with a screenshot plus `errors` rather\n  than assuming a write worked.\n- A `run-lua` that fails with HTTP 504 (`run-lua timed out`, exit code 3 from CLI\n  0.6.4 on; the MCP `run_lua` tool returns the same text) reached the engine, which\n  may still be running it. Do not send code that changes the world again: check its\n  effect first, by reading back what it sets or taking a screenshot. Any other\n  failure never reached the engine and is safe to retry.\n- The mirrored folder's AGENTS.md is this guide followed by the engine SDK's own agent guide\n  (the AGENTS.md that lives in every Montage tree and inside the desktop client's\n  Data/Sdk/Montage/). The engine guide assumes an in-session agent driving the engine\n  through `atomo`; the merged file maps each `atomo` step to the CLI or MCP equivalent, and\n  the `Skills/*.md` references it points at are in the folder. The SDK's own tooling\n  (`atomo`, `vm_auth.py`, the agent-log hooks) is not mirrored: it only works inside a\n  session. Sandboxed agents need network access for every CLI command.\n\n## Reference\n\nThe same facts as terse lists, for quick lookup.\n\n### Project model\n- A project (\"montage\") is one voxel world hosted with Virtual Matter.\n- A project has framings: \"make\" framings (editing sessions) and \"play\"\n  framings (public play sessions). A framing is a running session slot\n  on a voxel host.\n- Project content = SDK Lua scripts + assets under a Montage/ tree.\n  Edits made in the live session hot-reload into the running world.\n  The tree can be published to a maker-owned GitHub repo.\n\n### URL shapes (make.virtualmatter.ai)\n- /new                 builder for people: create a world from a prompt\n                       (also at https://virtualmatter.ai/); coding agents\n                       use npx virtualmatter make instead\n- /edit/<framing-id>   maker session: live world + agent chat. The chat is\n                       for people; a coding agent builds with the CLI and\n                       never prompts it\n                       (also /edit/<slug>-<framing-id>; the CLI accepts both)\n- /play/<framing-id>   play session for a specific framing\n- /g/<id>              share URL resolver: 302s to a live session\n\n### APIs (unauthenticated)\n- GET https://make.virtualmatter.ai/api/v1/public/native-clients\n  JSON: { iteration, clients: [{ platform, kind, variant, url, filename,\n  file_size, branch, commit, match }] } - per-platform native client\n  installers (kind \"download\") or store links (kind \"store\", iOS).\n  Windows and Linux list two downloads each: variant \"installer\" /\n  \"flatpak\" for people, and \"portable\" / \"tarball\", the file tree the\n  CLI installs.\n\n### CLI + MCP (npm package \"virtualmatter\", Node >= 20)\n- npx virtualmatter make \"<name>\"     make a world, mirror it into ./<slug>\n- npx virtualmatter pull <link>       mirror an existing world (any link shape)\n- npx virtualmatter list              your worlds with framing ids + URLs\n- npx virtualmatter sync              live-push saves into the running world\n- npx virtualmatter open              optional: open it in the native client\n- npx virtualmatter mcp               stdio MCP server (list_projects,\n  create_project, select_project, list_files, read_file, write_file,\n  run_lua, get_engine_errors, capture_screenshot, open_native_client,\n  world_info)\n- Sign-in happens on first use (device code); no separate login step.\n- These commands are the whole build path. Never prompt the built-in\n  agent on the site to do the work; a browser or the native client is\n  for playtesting what you built.\n- Any link to a world (editor, play or share link, project page, embed,\n  or the maker's own website) resolves to its editor, the only place\n  the CLI and MCP server work. Play servers show the last published\n  version and are overwritten on publish.\n- Watch changes land live at the editor link ending in ?chat=closed,\n  in any browser, no install. The native client is optional.\n- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and\n  CLAUDE.md, so Claude Code and Cursor register the server on their own.\n- Codex: folders from 0.5.0 on carry .codex/config.toml, loaded once the\n  folder is trusted; otherwise register the server once:\n  codex mcp add virtualmatter -- npx -y virtualmatter mcp\n\n## SDK Lua cheat sheet\n\nThe scripting language is Lua 5.4, sandboxed: `os`, `io`, `require`, `package`,\n`dofile`, `loadfile`, `loadstring` are nil. `math`, `string`, `table`, `coroutine`\nremain. No `os.time` - use `Time.time` (sim time), `Time.frame`, or\n`AE:GetDebugTime()` (wall clock).\n\n### Script shape\n\nEvery persistent behavior is a `.lua` file in the Montage tree returning a `self` table:\n\n```lua\nlocal self = {}\nfunction self:Start() end\nfunction self:Update(deltaTime) end\nreturn self\n```\n\nAttach to an object with `obj:AddScript(\"My Folder/Example.lua\", sync)` - the path is\nrelative to the Montage root; `sync = true` replicates the script to clients.\n`obj:FindScript(\"Example\")` returns the live instance.\n\n### Server / client split\n\nThe same script runs on the server and (when synced) on every client. Branch with\n`self.onServer` / `self.onClient`:\n\n```lua\nfunction self:Update(dt)\n    if self.onClient then return end  -- voxel edits are server-only\n    -- authoritative logic here\nend\n```\n\nNothing replicates automatically: set `syncToClients = true` on the script or\nVoxelData component, and use `util:makeNetworkedTable(self, { hp = 100 })` for\nproperties that should sync (server writes, clients read, deltas only).\n`obj.pos` / `obj.rot` do not auto-sync - replicate them yourself.\n\n### RPC\n\n```lua\nself:RPC(\"serverDoSomething\", pos, dir)   -- on a client: goes to the server\nfunction self:serverDoSomething(pos, dir, clientID)  -- clientID auto-appended\n    assert(self.onServer)\nend\n```\n\nOn the server, `self:RPC(...)` fans out to all clients. Reliable, FIFO per direction.\nRequires `self.component.syncToClients = true`.\n\n### Scene and objects (server)\n\n```lua\nlocal ob = Scene:CreateObject(\"Name\")\nob.save = true\nob:AddScript(\"Path/Script.lua\")\nScene:GetObjectByName(\"Name\")\nScene:CloneObject(ob)                 -- prefer over rebuilding\nob.active = false                     -- prefer over destroy\nob:AddTag(\"Enemy\"); FindObjectsWithTag(\"Enemy\")  -- tags are runtime-only state\n```\n\n### Voxel editing (server only, async)\n\n```lua\nVox:Add(Sphere(pos, 2)):Color(1, 0, 0):Run()\nVox:Add(Box(Vec3(0, -1, 0), Vec3(20, 2, 20))):ForceStatic():Run()\n```\n\nShapes: `Box(center, fullSize)`, `Sphere(center, r)`, `Capsule(p1, p2, r)`,\n`Cylinder(p1, p2, r1[, r2])`. `Run()` is async - chain `:OnFinished(fn)` before\n`:Run()` to read post-commit state. Big edits stall the frame for every client;\nkeep in-game edits small and infrequent.\n\n### Input (event-driven, client input reaches the server)\n\n```lua\nself.component.syncToClients = true\nevents.keyDown.addListener(self, function(key, from) self.keys[key] = true end)\nevents.keyUp.addListener(self, function(key, from) self.keys[key] = false end)\n```\n\nPlayer-driven movement must be client-predicted - never gate the player's own\nfeedback on the server round-trip.\n\n### Physics\n\n```lua\nlocal rb = obj:AddComponent(\"RigidBody\")\nrb:AddImpulse(Vec3(0, 50, 0), obj.pos)\nrb.velocity; rb.mass; rb.gravityScale\n```\n\n### Time and diagnostics\n\n```lua\nTime.dt; Time.time; Time.frame; Time.timeScale\nAE:GetLogValue(\"Raycasts\")        -- engine counters, e.g. raycasts this frame\nAE:GetAssets()                    -- list all assets (APIs take Assets, not paths)\n```\n\n### UI (client-side HUD)\n\nBuild screen UI with the MUI builder: `UI:AddPanel|AddButton|AddLabel|AddSlider|...`\nchained with `:Set{...}`; flexbox-like row-wrap layout.\n\n## Conventions\n\n- Coordinates: Y is up, -Z is forward, X is right.\n- Script files are named in capital case with spaces (`Character Controller.lua`).\n- Check whether a script is already attached before adding it - duplicates run twice.\n- The server is for authority (world edits, spawns, state); clients are for feel\n  (prediction, FX, UI).\n\n## Embed or build a world for an existing website\n\nFor a shared project link, fetch `/api/v1/public/embed?target=<encoded-link>`\nand follow `/embed-guide.md`. Use the returned canonical player URL, not the\nmaker's external website URL. Keep the existing website and its design.\n\nFor account discovery or prompt-based creation, connect the hosted MCP at\n`https://make.virtualmatter.ai/api/v1/mcp` using OAuth. Users can sign up in\nthe connection flow. Tools: `list_projects`, `get_embed`, `create_project`\n(with a prompt and stable request_id), `get_build_status`. VM's agent builds\nusing VM credits. Review and share the private world before embedding.\nThe local CLI exposes `embed`, `build --prompt --request-id`, and `build-status`.\n\n## Local conversation history\n\nCapturing this harness's conversation into the world's Agent Logs is the maker's\ndecision, not yours. Do not run `virtualmatter agent-logs setup`, and do not upload\nlogs with `agent-logs upload` or MCP `upload_agent_logs`, unless the maker asks for it\nin their own words. `virtualmatter agent-logs status` shows whether capture is on;\n`virtualmatter agent-logs disable` turns it off.\n";

package/dist/files.js

@@ -2,7 +2,25 @@
  * Client for the session file + engine API served at
  * https://<voxel_host>/s/<session_id>/api/montage/<framing_id>/...
  */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { authorizedFetch } from "./api.js";
+/**
+ * The session API's per-write cap (session-agent server/api/files.py
+ * MAX_WRITE_BYTES). A bigger PUT is answered 413, so sync skips such files
+ * up front instead of reading gigabytes of voxel data just to be refused.
+ */
+export const MAX_WRITE_BYTES = 8 * 1024 * 1024;
+/**
+ * Largest body `get()` reads into memory. Node refuses a Buffer past
+ * 2^31-1 bytes, and worlds do carry multi-GB voxel/terrain files - Rooftop
+ * Rumble's 2.7 GB one crashed every pull. Anything that writes a file to
+ * disk uses `download()`, which streams and has no limit.
+ */
+export const MAX_BUFFERED_BYTES = 256 * 1024 * 1024;
 /**
  * The reason an engine call failed, read out of the response body.
  *
@@ -12,23 +30,42 @@ import { authorizedFetch } from "./api.js";
  * browser instead. Falls back to the status when the body says nothing.
  */
 export async function engineErrorMessage(res, what) {
-    let detail = "";
+    const detail = await errorDetail(res);
+    return `${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`;
+}
+async function errorDetail(res) {
     try {
         const body = (await res.json());
         const d = body.detail;
         if (typeof d === "string")
-            detail = d;
-        else if (d && typeof d === "object" && typeof d.message === "string") {
-            detail = d.message;
+            return d;
+        if (d && typeof d === "object" && typeof d.message === "string") {
+            return d.message;
         }
-        else if (d)
-            detail = JSON.stringify(d);
+        return d ? JSON.stringify(d) : "";
     }
     catch {
-        /* non-JSON body */
+        return ""; // non-JSON body, e.g. a proxy's own 504 page
     }
-    return `${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`;
 }
+/**
+ * The engine did not answer an engine call in time (HTTP 504). The session
+ * relay answers 504 `engine_timeout` only when the call reached the engine,
+ * so for run-lua the snippet may still be running: resending it can run a
+ * mutation twice. Nothing retries it, and the CLI exits with
+ * ENGINE_TIMEOUT_EXIT_CODE so a script can tell it from a plain failure.
+ */
+export class EngineTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EngineTimeoutError";
+    }
+}
+export const ENGINE_TIMEOUT_EXIT_CODE = 3;
+const RUN_LUA_TIMEOUT = "The engine did not answer in time; it may still be running this Lua. Do not resend code that changes the world: check its effect first.";
+/** How long `engineErrors` waits before each retry of a 503/504; it only reads. */
+const READ_RETRY_DELAYS_MS = [1_000, 3_000];
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class ConflictError extends Error {
     filePath;
     constructor(filePath) {
@@ -37,6 +74,10 @@ export class ConflictError extends Error {
         this.name = "ConflictError";
     }
 }
+function tooBigToBuffer(filePath, size, limit) {
+    const mb = (n) => `${Math.round(n / (1024 * 1024))} MB`;
+    return `${filePath} is ${mb(size)}, too large to read into memory (limit ${mb(limit)}). It is in the folder \`virtualmatter pull\` mirrored - read it from disk.`;
+}
 function encodePath(p) {
     return p.split("/").map(encodeURIComponent).join("/");
 }
@@ -58,14 +99,49 @@ export function normalizeEtag(v) {
         s = s.slice(1, -1);
     return s;
 }
+/**
+ * Write a response body to `destAbs` without holding it in memory, hashing
+ * it on the way. Lands in a temp file beside the target and is renamed into
+ * place, so the target is either the old file or the whole new one - never a
+ * truncated half that a later sync would push back as an edit.
+ */
+export async function streamToFile(res, destAbs) {
+    fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+    const tmp = `${destAbs}.vmdownload-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    const hasher = crypto.createHash("sha256");
+    let size = 0;
+    const tap = new Transform({
+        transform(chunk, _enc, cb) {
+            hasher.update(chunk);
+            size += chunk.length;
+            cb(null, chunk);
+        },
+    });
+    try {
+        const source = res.body
+            ? Readable.fromWeb(res.body)
+            : Readable.from([]);
+        await pipeline(source, tap, fs.createWriteStream(tmp));
+        fs.renameSync(tmp, destAbs);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    return { hash: hasher.digest("hex"), size };
+}
 export class FilesClient {
     sessionBase;
     framingId;
     fetchFn;
-    constructor(sessionBase, framingId, fetchFn = fetch) {
+    maxBufferedBytes;
+    sleep;
+    constructor(sessionBase, framingId, fetchFn = fetch, maxBufferedBytes = MAX_BUFFERED_BYTES, sleep = defaultSleep) {
         this.sessionBase = sessionBase;
         this.framingId = framingId;
         this.fetchFn = fetchFn;
+        this.maxBufferedBytes = maxBufferedBytes;
+        this.sleep = sleep;
     }
     get apiRoot() {
         return `${this.sessionBase}/api/montage/${encodeURIComponent(this.framingId)}`;
@@ -87,8 +163,30 @@ export class FilesClient {
         const res = await authorizedFetch(`${this.apiRoot}/files/content/${encodePath(filePath)}`, {}, this.fetchFn);
         if (!res.ok)
             throw new Error(`Downloading ${filePath} failed: HTTP ${res.status}`);
-        const bytes = Buffer.from(await res.arrayBuffer());
-        return { bytes, etag: normalizeEtag(res.headers.get("ETag")) };
+        const declared = Number(res.headers.get("Content-Length"));
+        if (Number.isFinite(declared) && declared > this.maxBufferedBytes) {
+            await res.body?.cancel();
+            throw new Error(tooBigToBuffer(filePath, declared, this.maxBufferedBytes));
+        }
+        // No (or a lying) Content-Length: count as it arrives and stop at the limit.
+        const chunks = [];
+        let size = 0;
+        if (res.body) {
+            for await (const chunk of Readable.fromWeb(res.body)) {
+                size += chunk.length;
+                if (size > this.maxBufferedBytes)
+                    throw new Error(tooBigToBuffer(filePath, size, this.maxBufferedBytes));
+                chunks.push(chunk);
+            }
+        }
+        return { bytes: Buffer.concat(chunks, size), etag: normalizeEtag(res.headers.get("ETag")) };
+    }
+    async download(filePath, destAbs) {
+        const res = await authorizedFetch(`${this.apiRoot}/files/content/${encodePath(filePath)}`, {}, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`Downloading ${filePath} failed: HTTP ${res.status}`);
+        const { hash, size } = await streamToFile(res, destAbs);
+        return { etag: normalizeEtag(res.headers.get("ETag")), hash, size };
     }
     async put(filePath, body, opts) {
         const headers = { "Content-Type": "application/octet-stream" };
@@ -121,6 +219,11 @@ export class FilesClient {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload),
         }, this.fetchFn);
+        if (res.status === 504) {
+            // Never retried: the engine may still be running the snippet.
+            const detail = (await errorDetail(res)) || RUN_LUA_TIMEOUT;
+            throw new EngineTimeoutError(`run-lua timed out: HTTP 504 - ${detail}`);
+        }
         if (!res.ok)
             throw new Error(await engineErrorMessage(res, "run-lua"));
         // Server envelope: {output: <text>} - the engine bridge's text
@@ -129,11 +232,24 @@ export class FilesClient {
         return body.output;
     }
     async engineErrors() {
-        const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
-        if (!res.ok)
-            throw new Error(await engineErrorMessage(res, "Fetching engine errors"));
-        const body = (await res.json());
-        return body.output;
+        // Reading the error buffer changes nothing, so a busy (504) or briefly
+        // unreachable (503) engine is worth another try.
+        for (let attempt = 0;; attempt++) {
+            const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
+            if (res.ok) {
+                const body = (await res.json());
+                return body.output;
+            }
+            const retryable = res.status === 503 || res.status === 504;
+            const delay = READ_RETRY_DELAYS_MS[attempt];
+            if (retryable && delay !== undefined) {
+                await res.body?.cancel();
+                await this.sleep(delay);
+                continue;
+            }
+            const message = await engineErrorMessage(res, "Fetching engine errors");
+            throw res.status === 504 ? new EngineTimeoutError(message) : new Error(message);
+        }
     }
     async screenshot(opts = {}) {
         const body = {};

package/dist/index.js

@@ -9,7 +9,7 @@ import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, save
 import { openInBrowser } from "./browser.js";
 import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
 import { apiBase, packageVersion } from "./config.js";
-import { FilesClient } from "./files.js";
+import { ENGINE_TIMEOUT_EXIT_CODE, EngineTimeoutError, FilesClient } from "./files.js";
 import { runMcpServer } from "./mcp.js";
 import { pullCommand } from "./pull.js";
 import { NeedsChoiceError, formatProjectList, makeFramingOf, resolveImplicitTarget, resolveTarget, } from "./resolve.js";
@@ -42,9 +42,15 @@ program
     "install. The native client (`virtualmatter open`) is optional, for more memory",
     "and frame rate.",
 ].join("\n"));
-function fail(message) {
+function fail(message, code = 1) {
     console.error(message);
-    process.exit(1);
+    process.exit(code);
+}
+/** Exit with the failure's own code: an engine timeout is not a plain failure. */
+function failWith(err) {
+    if (err instanceof EngineTimeoutError)
+        fail(err.message, ENGINE_TIMEOUT_EXIT_CODE);
+    fail(err instanceof Error ? err.message : String(err));
 }
 /** The device-code sign-in, shared by `login` and the automatic first-use sign-in. */
 async function signIn() {
@@ -76,10 +82,10 @@ async function run(fn) {
                 return;
             }
             catch (again) {
-                fail(again instanceof Error ? again.message : String(again));
+                failWith(again);
             }
         }
-        fail(err instanceof Error ? err.message : String(err));
+        failWith(err);
     }
 }
 /** Resolve a session-scoped FilesClient from a synced dir's state file. */
@@ -115,6 +121,14 @@ function slugFor(name) {
 }
 function reportPull(result, dest, watchUrl) {
     console.log(`Pulled ${result.fileCount} files into ${dest}.`);
+    if (result.failed.length > 0) {
+        // Reported, not fatal: the folder and its state file are usable, and the
+        // first `sync` retries whatever is missing.
+        console.error(`${result.failed.length} file(s) could not be downloaded (\`virtualmatter sync\` will retry them):`);
+        for (const f of result.failed)
+            console.error(`  ${f.path}: ${f.error}`);
+        process.exitCode = 1;
+    }
     const files = result.agentFiles;
     if (files && files.written.length > 0) {
         console.log(`Wrote ${files.written.join(", ")} so Claude Code, Codex, and Cursor find their way around.`);
@@ -296,7 +310,7 @@ program
 }));
 program
     .command("run-lua")
-    .description("Execute Lua in the running engine")
+    .description("Execute Lua in the running engine. Exit code 3 means the engine did not answer in time and may still be running the code: check its effect before sending it again")
     .argument("[dir]", "a synced folder", ".")
     .requiredOption("--code <lua>", "Lua source to execute")
     .option("--target <target>", "server or client", "server")

package/dist/mcp.js

@@ -195,7 +195,7 @@ export async function runMcpServer(dir, framingFlag) {
         let pulled = null;
         if (pull_to) {
             const result = await pullCommand(framingId, pull_to);
-            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+            pulled = { dir: result.dir, file_count: result.fileCount, failed: result.failed, agent_files: result.agentFiles };
         }
         return textResult(JSON.stringify({ ...projectSummary(project), selected: true, pulled }, null, 2));
     });
@@ -211,7 +211,7 @@ export async function runMcpServer(dir, framingFlag) {
         let pulled = null;
         if (pull_to) {
             const result = await pullCommand(resolved.framingId, pull_to);
-            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+            pulled = { dir: result.dir, file_count: result.fileCount, failed: result.failed, agent_files: result.agentFiles };
         }
         return textResult(JSON.stringify({
             framing_id: resolved.framingId,
@@ -249,7 +249,7 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify({ ok: true, path: filePath, etag }));
     });
     server.registerTool("run_lua", {
-        description: "Execute a Lua snippet in the running Virtual Matter engine and return its result. target \"server\" (default) runs in the server-side Lua state where game logic lives; \"client\" runs in a connected client (someone must have the world open) - that is where UI, input and the camera live. With several clients connected, pass client_id; list them with target server and code 'return Server:GetClients()'. Use this to inspect live state, call engine APIs, or nudge the scene without editing files.",
+        description: "Execute a Lua snippet in the running Virtual Matter engine and return its result. target \"server\" (default) runs in the server-side Lua state where game logic lives; \"client\" runs in a connected client (someone must have the world open) - that is where UI, input and the camera live. With several clients connected, pass client_id; list them with target server and code 'return Server:GetClients()'. Use this to inspect live state, call engine APIs, or nudge the scene without editing files. If it fails with \"run-lua timed out\", the engine may still be running the snippet: check its effect before sending code that changes the world again.",
         inputSchema: {
             code: z.string().describe("Lua source to execute"),
             target: z

package/dist/pull.js

@@ -5,7 +5,7 @@ import { resolveEditSession, sessionBaseUrl } from "./api.js";
 import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
-import { recordLocal, saveState } from "./state.js";
+import { adoptLocal, saveState } from "./state.js";
 export { fetchAgentsMd } from "./agentfiles.js";
 export { AGENTS_MD_FALLBACK } from "./agents-md.generated.js";
 /** Download workers per pull. The tree is ~1000 small files; sequential
@@ -52,6 +52,7 @@ export async function pullTree(client, dir, framingId) {
     const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
     const state = { framing_id: framingId, etags: {}, local: {} };
     const progress = makeProgress(remote.length);
+    const failed = [];
     let next = 0;
     const worker = async () => {
         for (;;) {
@@ -59,20 +60,26 @@ export async function pullTree(client, dir, framingId) {
             if (index >= remote.length)
                 return;
             const file = remote[index];
-            const { bytes, etag } = await client.get(file.path);
-            const absPath = path.join(dir, file.path);
-            fs.mkdirSync(path.dirname(absPath), { recursive: true });
-            fs.writeFileSync(absPath, bytes);
-            state.etags[file.path] = etag ?? file.etag;
-            // what the disk holds now, so the first sync can tell local edits apart
-            recordLocal(state, dir, file.path, bytes);
+            try {
+                // streamed to disk: a multi-GB voxel file must not pass through a Buffer
+                const { etag, hash } = await client.download(file.path, path.join(dir, file.path));
+                state.etags[file.path] = etag ?? file.etag;
+                // what the disk holds now, so the first sync can tell local edits apart
+                adoptLocal(state, dir, file.path, hash);
+            }
+            catch (err) {
+                // One bad file must not cost the other thousand, nor the state file:
+                // without it the folder cannot sync at all. A file left out here has
+                // no etag, so the first `sync` pulls it again.
+                failed.push({ path: file.path, error: err instanceof Error ? err.message : String(err) });
+            }
             progress.tick(file.path);
         }
     };
     await Promise.all(Array.from({ length: Math.min(PULL_CONCURRENCY, remote.length) }, () => worker()));
     progress.done();
     saveState(dir, state);
-    return { dir, framingId, fileCount: remote.length };
+    return { dir, framingId, fileCount: remote.length - failed.length, failed };
 }
 export async function pullCommand(framingId, dir) {
     console.log(`Resolving session for framing ${framingId} (this can cold-start one) ...`);

package/dist/state.js

@@ -34,6 +34,27 @@ export function requireState(dir) {
 export function sha256Hex(bytes) {
     return crypto.createHash("sha256").update(bytes).digest("hex");
 }
+/**
+ * sha256 of a file read in chunks. `readFileSync` cannot load a file past
+ * 2 GiB at all, and multi-GB voxel files are normal in a world.
+ */
+export function hashFileSync(abs) {
+    const hasher = crypto.createHash("sha256");
+    const buf = Buffer.allocUnsafe(1024 * 1024);
+    const fd = fs.openSync(abs, "r");
+    try {
+        for (;;) {
+            const n = fs.readSync(fd, buf, 0, buf.length, null);
+            if (n === 0)
+                break;
+            hasher.update(buf.subarray(0, n));
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return hasher.digest("hex");
+}
 /**
  * Record a file whose content hash is already known to match its last sync,
  * from a stat alone. How a state file from before `local` records existed
@@ -69,7 +90,7 @@ export function localHash(state, dir, relPath) {
     const rec = state.local?.[relPath];
     if (rec && rec.size === st.size && rec.mtime_ms === st.mtimeMs)
         return rec.hash;
-    return sha256Hex(fs.readFileSync(abs));
+    return hashFileSync(abs);
 }
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 /**

package/dist/sync.js

@@ -14,7 +14,7 @@ import { startLogSync } from "./agent-logs.js";
  */
 import fs from "node:fs";
 import path from "node:path";
-import { ConflictError } from "./files.js";
+import { ConflictError, MAX_WRITE_BYTES } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { loadState, adoptLocal, localHash, recordLocal, saveState, sha256Hex, syncedHash, } from "./state.js";
 const consoleLogger = {
@@ -34,6 +34,8 @@ export class SyncEngine {
     selfWrites = new Map();
     /** State changed without being written yet (see flush). */
     dirty = false;
+    /** relPath -> "size:mtime" of an oversized file already warned about, so the scan does not repeat it every few seconds. */
+    tooBigWarned = new Map();
     constructor(client, dir, state, opts = {}) {
         this.client = client;
         this.dir = dir;
@@ -102,13 +104,12 @@ export class SyncEngine {
         this.persist();
     }
     async pullFile(relPath, etag) {
-        const { bytes, etag: gotEtag } = await this.client.get(relPath);
-        const absPath = this.abs(relPath);
-        fs.mkdirSync(path.dirname(absPath), { recursive: true });
         this.recordSelfWrite(relPath);
-        fs.writeFileSync(absPath, bytes);
+        // streamed: voxel and terrain files run to several GB
+        const { etag: gotEtag, hash } = await this.client.download(relPath, this.abs(relPath));
+        this.recordSelfWrite(relPath); // the rename is the write the watcher sees; restart the grace from it
         this.state.etags[relPath] = gotEtag ?? etag;
-        recordLocal(this.state, this.dir, relPath, bytes);
+        adoptLocal(this.state, this.dir, relPath, hash);
         this.persist();
     }
     /**
@@ -119,10 +120,8 @@ export class SyncEngine {
      */
     async writeConflict(relPath, remoteEtag) {
         try {
-            const { bytes, etag } = await this.client.get(relPath);
             const conflictPath = this.abs(relPath) + CONFLICT_SUFFIX;
-            fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
-            fs.writeFileSync(conflictPath, bytes);
+            const { etag } = await this.client.download(relPath, conflictPath);
             const e = etag ?? remoteEtag;
             if (e)
                 this.state.etags[relPath] = e;
@@ -253,6 +252,8 @@ export class SyncEngine {
     }
     /** Push the local file. Returns false when there was nothing to send or it became a conflict. */
     async pushFile(relPath, opts) {
+        if (this.tooBigToPush(relPath))
+            return false;
         const body = fs.readFileSync(this.abs(relPath));
         const known = this.state.etags[relPath];
         // unchanged since the last sync: nothing to send (a touch, or the
@@ -276,6 +277,32 @@ export class SyncEngine {
             throw err;
         }
     }
+    /**
+     * Over the session API's write cap: the server would answer 413, so do not
+     * read the file at all (a multi-GB read would also exhaust memory). Warned
+     * once per version of the file. The file stays as it is on both sides.
+     */
+    tooBigToPush(relPath) {
+        let st;
+        try {
+            st = fs.statSync(this.abs(relPath));
+        }
+        catch {
+            return false;
+        }
+        if (st.size <= MAX_WRITE_BYTES) {
+            this.tooBigWarned.delete(relPath);
+            return false;
+        }
+        const key = `${st.size}:${st.mtimeMs}`;
+        if (this.tooBigWarned.get(relPath) !== key) {
+            this.tooBigWarned.set(relPath, key);
+            const mb = (n) => `${(n / (1024 * 1024)).toFixed(1)} MB`;
+            this.log.warn(`not pushing ${relPath} (${mb(st.size)}): the world accepts at most ${mb(MAX_WRITE_BYTES)} per file. ` +
+                `Edit large voxel/terrain data in the engine instead; it is left unchanged in the world.`);
+        }
+        return true;
+    }
     /** Watcher callback for a local add/change. */
     async handleLocalChange(relPath) {
         const norm = relPath.replace(/\\/g, "/");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",