virtualmatter 0.6.1 → 0.6.4

package/README.md

@@ -38,9 +38,16 @@ npx virtualmatter pull https://make.virtualmatter.ai/edit/my-world-<framing-id>
 ```
 
 While `sync` runs, saving a Lua script in your editor deploys it - scripts
-hot-reload in the engine. If someone edits the same file in the live session,
-your copy stays put and the remote version lands next to it as
-`<name>.remote-conflict` for you to merge.
+hot-reload in the engine. Sync never overwrites work you have not synced: if
+a file changed both here and in the live session (while sync ran, or while it
+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.
@@ -56,10 +63,12 @@ Poke at the running engine from another terminal:
 
 ```bash
 npx virtualmatter run-lua --code "return Server.GetInfo()"
+npx virtualmatter run-lua --target client --code "return Client:GetID()"   # UI, input, camera
 npx virtualmatter errors
 npx virtualmatter screenshot -o shot.png                  # default overview
 npx virtualmatter screenshot --target "Player" -o p.png   # frame one object
 npx virtualmatter screenshot --at 0,30,40 --rot 0,-35,0    # exact camera
+npx virtualmatter screenshot --client 4 -o ui.png          # what client 4 sees, UI included
                                           # --rot is yaw,pitch,roll
 ```
 
@@ -117,9 +126,9 @@ 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]` | Execute Lua in the running engine. |
-| `errors [dir]` | Recent engine errors. |
-| `screenshot [dir] [-o out.png]` | Capture the engine's current view. |
+| `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\nAfter pulling a project, run `virtualmatter agent-logs setup` once to enable\nfuture chat history capture for local harnesses. It adds Codex, Claude Code,\nCursor, and (when installed) Hermes hooks without replacing existing hooks.\nKeep `virtualmatter sync` or `virtualmatter agent-logs watch` running for retry\nand delayed transcript capture. Follow each harness's normal hook review and\nrestart flow. Use `agent-logs status` to inspect pending uploads and\n`agent-logs disable` to stop capture.\n\nOther harnesses can send portable public event JSONL with\n`virtualmatter agent-logs upload <file> --harness <name> --session <id>`, or use\nMCP `upload_agent_logs`. Supply stable event IDs for retries; omit private\nreasoning, system/developer prompts, credentials, and binary media.\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/client.js

@@ -131,6 +131,38 @@ async function download(url, dest, onProgress, fetchFn = fetch) {
     }
     fs.renameSync(tmp, dest);
 }
+/**
+ * The path of `lsregister`, the tool that edits macOS's database of known apps.
+ * Not on any PATH - it lives inside the LaunchServices framework.
+ */
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+/**
+ * Take this cached client OUT of macOS's app database.
+ *
+ * The cache holds a real .app bundle, and macOS registers every bundle it
+ * sees. Every copy carries the same bundle id, and the "which app opens
+ * virtualmatter:// links" preference is stored per bundle ID, not per path -
+ * so macOS picks among the copies by its own rules, and a cached build from
+ * last week can win over the one in /Applications. That is not hypothetical:
+ * a world link opened a nine-day-old cached client, which then refused to
+ * connect to its own world because the client predated a compatibility fix on
+ * that same release branch.
+ *
+ * The CLI launches this copy by path, so it never needs to be registered.
+ * Unregistering it leaves the user's installed app as the only candidate.
+ * Best-effort by design: this is tidiness, not correctness, and any failure
+ * (another OS, a future layout, a locked database) must not break a launch.
+ */
+export function dropFromLaunchServices(appPath, platform = detectPlatform(), runner = spawnSync) {
+    if (platform !== "macos" || !appPath.endsWith(".app"))
+        return;
+    try {
+        runner(LSREGISTER, ["-u", appPath], { stdio: "ignore" });
+    }
+    catch {
+        /* tidiness only */
+    }
+}
 function run(cmd, args) {
     const res = spawnSync(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
     if (res.error)
@@ -317,6 +349,8 @@ export async function ensureClientInstalled(opts = {}) {
         }
     }
     const installed = { platform, dir, entrypoint, build };
+    // Keep the cache out of the OS's app database (see dropFromLaunchServices).
+    dropFromLaunchServices(entrypoint, platform);
     fs.writeFileSync(path.join(dir, MARKER), JSON.stringify(installed, null, 2) + "\n");
     const pruned = pruneOtherBuilds(dir);
     if (pruned.length)
@@ -350,6 +384,9 @@ export function launchClient(installed, montageUrl) {
         console.error(`Could not launch the client: ${err.message}`);
     });
     child.unref();
+    // Launching re-registers the bundle, so drop it again: the installed app in
+    // /Applications should stay the one that opens world links.
+    dropFromLaunchServices(installed.entrypoint, installed.platform);
 }
 // ---------------------------------------------------------------- sign-in hand-over
 /**

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" };
@@ -112,12 +210,20 @@ export class FilesClient {
             throw new Error(`Deleting ${filePath} failed: HTTP ${res.status}`);
         }
     }
-    async runLua(code, target) {
+    async runLua(code, target, clientId) {
+        const payload = { code, target };
+        if (target === "client" && clientId !== undefined)
+            payload.client_id = clientId;
         const res = await authorizedFetch(`${this.apiRoot}/engine/run-lua`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ code, target }),
+            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
@@ -126,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 = {};
@@ -151,6 +270,8 @@ export class FilesClient {
                 camera_rot_z: rz,
             });
         }
+        if (opts.clientId !== undefined)
+            body.client_id = opts.clientId;
         const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },

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,16 +310,21 @@ 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")
+    .option("--client <id>", "client id for --target client (default: the only connected client; list them with --code 'return Server:GetClients()')")
     .action((dir, opts) => run(async () => {
     if (opts.target !== "server" && opts.target !== "client") {
         fail("--target must be server or client");
     }
+    const clientId = opts.client === undefined ? undefined : clientIdFlag(opts.client);
+    if (clientId !== undefined && opts.target !== "client") {
+        fail("--client needs --target client");
+    }
     const { client } = await clientForDir(path.resolve(dir));
-    const result = await client.runLua(opts.code, opts.target);
+    const result = await client.runLua(opts.code, opts.target, clientId);
     console.log(JSON.stringify({ result }, null, 2));
 }));
 program
@@ -316,6 +335,13 @@ program
     const { client } = await clientForDir(path.resolve(dir));
     console.log(JSON.stringify(await client.engineErrors(), null, 2));
 }));
+/** Parse a --client flag: a positive integer client id. */
+function clientIdFlag(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        fail(`--client takes a client id (a positive integer), got "${value}"`);
+    return n;
+}
 /** Parse an "x,y,z" flag into a numeric triple. */
 function triple(value, flag) {
     const parts = value.split(",").map((p) => Number(p.trim()));
@@ -333,6 +359,7 @@ program
     .option("--rot <yaw,pitch,roll>", "camera rotation in degrees, yaw first (default: 0,-45,0)")
     .option("--target <id-or-name>", "frame this object instead of using a camera pose")
     .option("--distance <meters>", "framing distance for --target (default: from the object's bounds)")
+    .option("--client <id>", "capture through this connected client, UI included; with no --at/--rot/--target it is exactly what that client sees")
     .action((dir, opts) => run(async () => {
     const { client } = await clientForDir(path.resolve(dir));
     const png = await client.screenshot({
@@ -340,6 +367,7 @@ program
         rot: opts.rot ? triple(opts.rot, "--rot") : undefined,
         target: opts.target,
         distance: opts.distance === undefined ? undefined : Number(opts.distance),
+        clientId: opts.client === undefined ? undefined : clientIdFlag(opts.client),
     });
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);

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,17 +249,23 @@ 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 the connected client. 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
                 .enum(["server", "client"])
                 .optional()
                 .describe("Which Lua state to run in (default: server)"),
+            client_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("For target client: which connected client (default: the only one connected)"),
         },
-    }, async ({ code, target }) => {
+    }, async ({ code, target, client_id }) => {
         const client = await ctx.getClient();
-        const result = await client.runLua(code, target ?? "server");
+        const result = await client.runLua(code, target ?? "server", client_id);
         return textResult(JSON.stringify({ result }, null, 2));
     });
     server.registerTool("get_engine_errors", {
@@ -286,13 +292,20 @@ export async function runMcpServer(dir, framingFlag) {
                 .length(3)
                 .optional()
                 .describe("Camera rotation in degrees as [yaw, pitch, roll] - that order. Yaw 0 faces -Z; pitch -90 looks straight down, 0 is the horizon. Default [0, -45, 0] looks down at the origin."),
+            client_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Capture through this connected client, UI (HUD, menus) included - a server capture never shows UI. With no target/at/rot it is exactly what that client sees."),
         },
-    }, async ({ target, at, rot }) => {
+    }, async ({ target, at, rot, client_id }) => {
         const client = await ctx.getClient();
         const png = await client.screenshot({
             target,
             at: at,
             rot: rot,
+            clientId: client_id,
         });
         return {
             content: [

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 { 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
@@ -50,8 +50,9 @@ export async function fetchEngineAgentsMd(client) {
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
     const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
-    const state = { framing_id: framingId, etags: {} };
+    const state = { framing_id: framingId, etags: {}, local: {} };
     const progress = makeProgress(remote.length);
+    const failed = [];
     let next = 0;
     const worker = async () => {
         for (;;) {
@@ -59,18 +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;
+            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

@@ -1,4 +1,5 @@
-/** The .virtualmatter.json state file: framing id + per-file etag bookkeeping. */
+/** The .virtualmatter.json state file: framing id + per-file sync bookkeeping. */
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { STATE_FILE } from "./config.js";
@@ -11,7 +12,7 @@ export function loadState(dir) {
         const parsed = JSON.parse(raw);
         if (typeof parsed.framing_id !== "string")
             return null;
-        return { framing_id: parsed.framing_id, etags: parsed.etags ?? {} };
+        return { framing_id: parsed.framing_id, etags: parsed.etags ?? {}, local: parsed.local ?? {} };
     }
     catch {
         return null;
@@ -30,3 +31,77 @@ export function requireState(dir) {
     }
     return state;
 }
+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
+ * gets upgraded as files are first checked, so the next check is stat-only.
+ */
+export function adoptLocal(state, dir, relPath, hash) {
+    const st = fs.statSync(path.join(dir, relPath));
+    state.local ??= {};
+    state.local[relPath] = { hash, size: st.size, mtime_ms: st.mtimeMs };
+}
+/** Record `bytes` (just written to or read from `relPath`) as the synced local copy. */
+export function recordLocal(state, dir, relPath, bytes) {
+    const st = fs.statSync(path.join(dir, relPath));
+    state.local ??= {};
+    state.local[relPath] = { hash: sha256Hex(bytes), size: st.size, mtime_ms: st.mtimeMs };
+}
+/**
+ * The current content hash of a local file, or null if it does not exist.
+ * Reuses the recorded hash when size and mtime are unchanged, so a start
+ * over a big world does not re-read every voxel file.
+ */
+export function localHash(state, dir, relPath) {
+    const abs = path.join(dir, relPath);
+    let st;
+    try {
+        st = fs.statSync(abs);
+    }
+    catch {
+        return null;
+    }
+    if (!st.isFile())
+        return null;
+    const rec = state.local?.[relPath];
+    if (rec && rec.size === st.size && rec.mtime_ms === st.mtimeMs)
+        return rec.hash;
+    return hashFileSync(abs);
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/**
+ * The content hash of `relPath` as of its last sync, or undefined when
+ * unknown. Falls back to the etag for state files written before `local`
+ * existed - the session API's etags ARE the sha256 of the content.
+ */
+export function syncedHash(state, relPath) {
+    const rec = state.local?.[relPath];
+    if (rec)
+        return rec.hash;
+    const etag = state.etags[relPath];
+    return etag !== undefined && SHA256_HEX.test(etag) ? etag : undefined;
+}

package/dist/sync.js

@@ -1,21 +1,29 @@
 import { startLogSync } from "./agent-logs.js";
 /**
- * The sync hot loop: initial pull of remote changes, watch the local tree
- * and push edits with stored etags, poll the remote listing and pull files
- * whose etag changed remotely. Conflicts (412) never kill the loop - the
- * remote version lands next to yours as <name>.remote-conflict.
+ * The sync hot loop: reconcile both sides at start, watch the local tree and
+ * push edits with stored etags, poll the remote listing and pull files whose
+ * etag changed remotely.
+ *
+ * NEVER OVERWRITE UNSYNCED WORK. Every decision compares each side against
+ * what it looked like at the last sync - the server's etag, and the local
+ * record (content hash) in the state file - so a side that moved while the
+ * other did not is copied across, and a file BOTH sides changed is a
+ * conflict: the local file stays exactly as it is, the remote version lands
+ * next to it as <name>.remote-conflict, and nothing is pushed until you save.
+ * Conflicts never kill the loop.
  */
 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, saveState } from "./state.js";
+import { loadState, adoptLocal, localHash, recordLocal, saveState, sha256Hex, syncedHash, } from "./state.js";
 const consoleLogger = {
     info: (m) => console.log(m),
     warn: (m) => console.warn(m),
 };
 /** How long after our own local write of a pulled file we ignore watcher events for it. */
 const SELF_WRITE_GRACE_MS = 2000;
+export const CONFLICT_SUFFIX = ".remote-conflict";
 export class SyncEngine {
     client;
     dir;
@@ -24,12 +32,17 @@ export class SyncEngine {
     state;
     /** relPath -> timestamp of a write WE made (pull), so the watcher skips it. */
     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;
         this.log = opts.logger ?? consoleLogger;
         this.now = opts.now ?? Date.now;
         this.state = state;
+        this.state.local ??= {};
     }
     get framingId() {
         return this.state.framing_id;
@@ -53,46 +66,170 @@ export class SyncEngine {
         }
         return true;
     }
+    /**
+     * Has the local copy changed since its last sync? `true` also when the
+     * base is unknown but the file exists - "maybe" must be treated as "yes",
+     * or an unknown base is exactly how local work gets pulled over.
+     */
+    localChanged(relPath) {
+        const now = localHash(this.state, this.dir, relPath);
+        if (now === null)
+            return false;
+        const base = syncedHash(this.state, relPath);
+        if (base !== undefined && now === base) {
+            const rec = this.state.local?.[relPath];
+            if (!rec || rec.hash !== now) {
+                // Unchanged, but only known so by reading it (no record yet, or
+                // the mtime moved with the content the same). Record it so the
+                // next check is a stat - the backstop scan runs every few seconds.
+                adoptLocal(this.state, this.dir, relPath, now);
+                this.dirty = true;
+            }
+            else {
+                const st = fs.statSync(this.abs(relPath));
+                if (st.mtimeMs !== rec.mtime_ms || st.size !== rec.size) {
+                    adoptLocal(this.state, this.dir, relPath, now);
+                    this.dirty = true;
+                }
+            }
+            return false;
+        }
+        return true;
+    }
+    /** Record changes made while checking files (adopted records) - batched, one write per pass. */
+    flush() {
+        if (!this.dirty)
+            return;
+        this.dirty = false;
+        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;
+        adoptLocal(this.state, this.dir, relPath, hash);
         this.persist();
     }
     /**
-     * Initial reconcile: pull every remote file that is new or whose etag
-     * changed since the last sync, and push local files the remote has never
-     * seen. Returns counts for logging/tests.
+     * Both sides changed: keep the local file untouched, put the remote copy
+     * beside it, and point the stored etag at the remote version so that the
+     * next deliberate save of the local file is what wins. The local record is
+     * left alone, so the file still reads as locally changed.
+     */
+    async writeConflict(relPath, remoteEtag) {
+        try {
+            const conflictPath = this.abs(relPath) + CONFLICT_SUFFIX;
+            const { etag } = await this.client.download(relPath, conflictPath);
+            const e = etag ?? remoteEtag;
+            if (e)
+                this.state.etags[relPath] = e;
+            this.persist();
+            this.log.warn(`conflict on ${relPath}: it changed both here and in the world. Your file is untouched; ` +
+                `the world's version is saved as ${relPath}${CONFLICT_SUFFIX} - merge, save, and it will push.`);
+        }
+        catch (err) {
+            this.log.warn(`conflict on ${relPath}, and fetching the remote version failed: ${String(err)}`);
+        }
+    }
+    /**
+     * A conflict the user has not resolved yet: the sidecar is still there and
+     * the local file has not been saved since it was written. Such a file is
+     * never pushed automatically - only a save does that.
+     */
+    unresolvedConflict(relPath) {
+        try {
+            const side = fs.statSync(this.abs(relPath) + CONFLICT_SUFFIX);
+            const mine = fs.statSync(this.abs(relPath));
+            return side.mtimeMs >= mine.mtimeMs;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Initial reconcile, per file, against the last sync:
+     *
+     *   local unchanged, remote changed   -> pull
+     *   local changed,   remote unchanged -> push
+     *   both changed (or both new, and different) -> conflict (local kept)
+     *   local only, never synced          -> push (create)
+     *   remote only                       -> pull
+     *
+     * A file deleted locally while sync was off is pulled back rather than
+     * deleted remotely: a start never destroys anything on either side.
      */
     async initialSync() {
         const remote = await this.client.list();
         let pulled = 0;
         let pushed = 0;
-        const remotePaths = new Set();
+        let conflicts = 0;
+        const remoteByPath = new Map();
         for (const file of remote) {
             if (isIgnoredPath(file.path))
                 continue;
-            remotePaths.add(file.path);
+            remoteByPath.set(file.path, file);
             const known = this.state.etags[file.path];
-            const localExists = fs.existsSync(this.abs(file.path));
-            if (known !== file.etag || !localExists) {
+            const current = localHash(this.state, this.dir, file.path);
+            if (current === null) {
                 await this.pullFile(file.path, file.etag);
                 pulled++;
+                continue;
+            }
+            if (current === file.etag) {
+                // same content on both sides (etags are content hashes): just
+                // bring the bookkeeping up to date
+                const rec = this.state.local?.[file.path];
+                if (known !== file.etag || !rec || rec.hash !== current) {
+                    this.state.etags[file.path] = file.etag;
+                    adoptLocal(this.state, this.dir, file.path, current);
+                    this.dirty = true;
+                }
+                continue;
+            }
+            const remoteChanged = known !== file.etag;
+            const localChanged = this.localChanged(file.path);
+            if (!localChanged && remoteChanged) {
+                await this.pullFile(file.path, file.etag);
+                this.log.info(`pulled ${file.path}`);
+                pulled++;
+            }
+            else if (localChanged && !remoteChanged) {
+                if (this.unresolvedConflict(file.path)) {
+                    this.log.warn(`${file.path} still has an unresolved ${file.path}${CONFLICT_SUFFIX} - not pushing it. ` +
+                        `Merge, save the file (or delete the ${CONFLICT_SUFFIX} file), and it will push.`);
+                    continue;
+                }
+                if (await this.pushFile(file.path))
+                    pushed++;
+            }
+            else if (localChanged && remoteChanged) {
+                await this.writeConflict(file.path, file.etag);
+                conflicts++;
             }
         }
-        // Local files the remote has never seen get created remotely.
         for (const relPath of this.walkLocal()) {
-            if (remotePaths.has(relPath))
+            if (remoteByPath.has(relPath))
                 continue;
-            if (this.state.etags[relPath] !== undefined)
-                continue; // was remote once; treat as remote delete, leave local alone
-            await this.pushFile(relPath, { createOnly: true });
-            pushed++;
+            if (this.state.etags[relPath] === undefined) {
+                // never synced: new here, create it remotely
+                if (await this.pushFile(relPath, { createOnly: true }))
+                    pushed++;
+                continue;
+            }
+            // Synced once, gone remotely. Untouched here: leave it (a remote
+            // delete is not ours to undo). Edited here since: that is work, so it
+            // is re-created rather than stranded.
+            if (this.localChanged(relPath)) {
+                this.log.warn(`${relPath} was deleted in the world but edited here - re-creating it.`);
+                delete this.state.etags[relPath];
+                if (await this.pushFile(relPath, { createOnly: true }))
+                    pushed++;
+            }
         }
-        return { pulled, pushed };
+        this.flush();
+        return { pulled, pushed, conflicts };
     }
     *walkLocal(rel = "") {
         const absDir = path.join(this.dir, rel);
@@ -113,41 +250,58 @@ export class SyncEngine {
                 yield relPath;
         }
     }
+    /** 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
+        // watcher and the local scan both reporting the same save)
+        if (known !== undefined && syncedHash(this.state, relPath) === sha256Hex(body))
+            return false;
         const createOnly = opts?.createOnly ?? known === undefined;
         try {
             const etag = await this.client.put(relPath, body, createOnly ? { createOnly: true } : { etag: known });
             this.state.etags[relPath] = etag;
+            recordLocal(this.state, this.dir, relPath, body);
             this.persist();
             this.log.info(`pushed ${relPath}`);
+            return true;
         }
         catch (err) {
             if (err instanceof ConflictError) {
-                await this.handleConflict(relPath);
-                return;
+                await this.writeConflict(relPath);
+                return false;
             }
             throw err;
         }
     }
-    /** 412: fetch the remote version to <name>.remote-conflict, keep the loop alive. */
-    async handleConflict(relPath) {
+    /**
+     * 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 {
-            const { bytes, etag } = await this.client.get(relPath);
-            const conflictPath = this.abs(relPath) + ".remote-conflict";
-            fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
-            fs.writeFileSync(conflictPath, bytes);
-            if (etag)
-                this.state.etags[relPath] = etag;
-            // Deliberately NOT overwriting the local file - the user resolves.
-            this.persist();
-            this.log.warn(`conflict on ${relPath}: the remote copy changed while you edited it. ` +
-                `Remote version saved as ${relPath}.remote-conflict - merge, save, and it will push.`);
+            st = fs.statSync(this.abs(relPath));
         }
-        catch (err) {
-            this.log.warn(`conflict on ${relPath}, and fetching the remote version failed: ${String(err)}`);
+        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) {
@@ -178,12 +332,13 @@ export class SyncEngine {
         try {
             await this.client.delete(norm, known);
             delete this.state.etags[norm];
+            delete this.state.local?.[norm];
             this.persist();
             this.log.info(`deleted ${norm} remotely`);
         }
         catch (err) {
             if (err instanceof ConflictError) {
-                await this.handleConflict(norm);
+                await this.writeConflict(norm);
                 return;
             }
             this.log.warn(`remote delete of ${norm} failed: ${String(err)}`);
@@ -192,7 +347,8 @@ export class SyncEngine {
     /**
      * One remote poll tick: pull files whose remote etag differs from our
      * bookkeeping. Files we just pushed match by etag, so they are skipped
-     * naturally. Returns the pulled paths.
+     * naturally. A file with local changes that have not gone out yet is a
+     * conflict, never a pull. Returns the pulled paths.
      */
     async pollOnce() {
         const remote = await this.client.list();
@@ -200,23 +356,81 @@ export class SyncEngine {
         for (const file of remote) {
             if (isIgnoredPath(file.path))
                 continue;
-            if (this.state.etags[file.path] === file.etag && fs.existsSync(this.abs(file.path)))
+            const exists = fs.existsSync(this.abs(file.path));
+            if (this.state.etags[file.path] === file.etag && exists)
+                continue;
+            if (!exists && this.state.etags[file.path] === file.etag) {
+                // Deleted here, unchanged in the world since the last sync: a delete
+                // the watcher has not delivered yet, not a file to restore. Pulling it
+                // back also marked it as our own write, so the late unlink event was
+                // then ignored and the file came back for good.
+                await this.handleLocalDelete(file.path);
                 continue;
+            }
+            if (exists) {
+                const current = localHash(this.state, this.dir, file.path);
+                if (current === file.etag) {
+                    this.state.etags[file.path] = file.etag;
+                    adoptLocal(this.state, this.dir, file.path, current);
+                    this.persist();
+                    continue;
+                }
+                if (this.localChanged(file.path)) {
+                    // writeConflict points the etag at this remote version, so the
+                    // check at the top of the loop keeps it from firing again
+                    await this.writeConflict(file.path, file.etag);
+                    continue;
+                }
+            }
             await this.pullFile(file.path, file.etag);
             pulled.push(file.path);
             this.log.info(`pulled ${file.path}`);
         }
         return pulled;
     }
+    /**
+     * Backstop for the watcher: push every local file that changed since its
+     * last sync, and create new ones. File-system events get lost (editors
+     * that write in place, network drives, a burst while the queue is busy);
+     * a stat walk every few seconds cannot miss a save. Unchanged files cost a
+     * stat and no read. Returns the pushed paths.
+     */
+    async scanLocal() {
+        const pushed = [];
+        for (const relPath of this.walkLocal()) {
+            if (this.isSelfWrite(relPath))
+                continue;
+            const known = this.state.etags[relPath];
+            if (known !== undefined && !this.localChanged(relPath))
+                continue;
+            if (known !== undefined && this.unresolvedConflict(relPath))
+                continue;
+            try {
+                if (await this.pushFile(relPath))
+                    pushed.push(relPath);
+            }
+            catch (err) {
+                this.log.warn(`push of ${relPath} failed: ${String(err)}`);
+            }
+        }
+        this.flush();
+        return pushed;
+    }
 }
 /** Run the full watch loop until SIGINT. Not unit-tested directly; the decisions above are. */
 export async function runSyncLoop(engine, dir) {
     const { default: chokidar } = await import("chokidar");
-    const { pulled, pushed } = await engine.initialSync();
-    console.log(`initial sync: ${pulled} pulled, ${pushed} pushed. Watching ${dir} ...`);
+    const { pulled, pushed, conflicts } = await engine.initialSync();
+    console.log(`initial sync: ${pulled} pulled, ${pushed} pushed` +
+        (conflicts ? `, ${conflicts} conflict${conflicts === 1 ? "" : "s"} (see above)` : "") +
+        `. Watching ${dir} ...`);
     const stopLogs = startLogSync(dir);
     const watcher = chokidar.watch(dir, {
         ignoreInitial: true,
+        // Wait for a write to settle before reading it. Without this an editor
+        // that rewrites a file in place fired "change" mid-write and the sync
+        // pushed a truncated file.
+        awaitWriteFinish: { stabilityThreshold: 250, pollInterval: 50 },
         ignored: (p) => {
             const rel = path.relative(dir, p).replace(/\\/g, "/");
             return rel.length > 0 && isIgnoredPath(rel);
@@ -231,6 +445,12 @@ export async function runSyncLoop(engine, dir) {
     watcher.on("unlink", (p) => enqueue(() => engine.handleLocalDelete(path.relative(dir, p))));
     const interval = setInterval(() => {
         enqueue(async () => {
+            try {
+                await engine.scanLocal();
+            }
+            catch (err) {
+                console.warn(`local scan failed: ${String(err)}`);
+            }
             try {
                 await engine.pollOnce();
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.6.1",
+  "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",