virtualmatter 0.2.0 → 0.4.0

package/README.md

@@ -51,9 +51,17 @@ Poke at the running engine from another terminal:
 ```bash
 npx virtualmatter run-lua --code "return Server.GetInfo()"
 npx virtualmatter errors
-npx virtualmatter screenshot -o shot.png
+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
+                                          # --rot is yaw,pitch,roll
 ```
 
+Work through these commands rather than driving make.virtualmatter.ai in a
+browser. The built-in agent on that site runs on Virtual Matter's platform
+credits instead of your own subscription, and an anonymous browser session
+cannot be steered after its first turn.
+
 ## Hook up a coding agent (MCP)
 
 A folder created by `create` or `pull` already carries `.mcp.json` (Claude
@@ -99,8 +107,81 @@ deploying it.
 - The native client is unpacked under `~/.config/virtualmatter/client/<build>`
   (override with `VIRTUALMATTER_CLIENT_DIR`); each engine build gets its own
   folder, so a newer build never overwrites the one you are running.
-- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, and the
+- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, the
   harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
-  `.cursor/`, `.virtualmatter.json`).
+  `.cursor/`, `.virtualmatter.json`), and the SDK's in-session tooling at the
+  Montage root (`atomo`, `vm_auth.py`, the agent-log hooks) - those only work
+  inside a running session.
+- The pulled `AGENTS.md` is the platform guide followed by the world's own
+  engine SDK guide (its Skills/ table and engine rules), with a header that
+  maps every `atomo` command the engine guide mentions to the CLI or MCP
+  equivalent.
+- Linux: the client is a tarball started through `run.sh`; `open` does that
+  for you. If no window appears, the newest log under
+  `~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/` says why, and
+  the world keeps working in the browser and through every CLI command.
+- Sandboxed agents (Codex, restricted Claude Code) need network access for
+  every command: the platform, the identity server, and the world's host.
 - `pull` may cold-start a session for the framing; the first one can take a
   minute.
+
+## Websites and Lovable
+
+For a shared world, no account or local engine is needed:
+
+```bash
+npx virtualmatter embed 'https://play.virtualmatter.ai/p/world-a1b2c3d4'
+```
+
+The response contains canonical iframe markup, required **host response
+headers**, and verification instructions. Installing this CLI alone cannot
+configure the website's HTTP headers. Read `/embed-guide.md` on the platform.
+
+To ask VM's own agent to build a new world (using your VM credits):
+
+```bash
+npx virtualmatter build 'Lava Arena' --prompt 'Build a multiplayer lava survival arena' --request-id lava-arena-001
+npx virtualmatter build-status <build-id>
+```
+
+Reuse the same request id if the network drops; changing it requests another
+world. Review the world and enable **Share with friends** before embedding.
+An uncertain delivery is never automatically resubmitted.
+
+The local MCP `create_project` also accepts `prompt` plus `request_id`, and
+exposes `get_embed` and `get_build_status`. Without a prompt it retains the
+existing empty-world creation behavior.
+
+In Lovable, add `https://make.virtualmatter.ai/api/v1/mcp` as a custom MCP
+server with OAuth. Sign in or create a VM account, approve the connection,
+and return to Lovable. Then ask “Embed my Lava Arena world” or “Create a
+Virtual Matter lava survival arena and embed it here.” This remote endpoint
+runs on the platform; users do not install or run this CLI for that flow.
+
+## Automatic agent logs
+
+Run `virtualmatter agent-logs setup` once in a project mirror to capture future
+conversations from Codex, Claude Code, Cursor, and an installed Hermes profile.
+Keep `virtualmatter sync` (or `virtualmatter agent-logs watch`) running for
+retry and transcript catch-up. Existing hooks are retained; follow the
+harness's normal hook trust/restart flow. `agent-logs status` shows the queue;
+`agent-logs disable` stops automatic capture.
+
+Any harness can upload public event JSONL with:
+
+```sh
+virtualmatter agent-logs upload conversation.jsonl --harness my-agent --session session-123
+```
+
+Each event needs a stable `event_id`, timezone-bearing `ts`, and `type` (`user`,
+`assistant_text`, `tool_use`, `tool_result`, or `result`). Text events carry
+`text`; tools carry `name`, `input`, `tool_use_id`; results carry `tool_use_id`
+and `result`. Retries deduplicate, existing entries cannot be overwritten, and
+failed batches remain in the project's local `.virtualmatter/agent-logs/`
+outbox. `--format codex` and `--format claude-code` import explicit transcript
+files. MCP exposes the same portable contract as `upload_agent_logs`.
+
+Setup records only this project's future entries. Hidden reasoning, system
+messages, and binary media are excluded. Logs become part of the project's
+history and saved content. The server must have the agent-log API update;
+older servers return 404 and the CLI retains pending entries.

package/dist/agent-logs.js

@@ -0,0 +1,329 @@
+/** Durable project-scoped outbox. No credentials or private transcripts enter the world tree. */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { authorizedFetch, resolveSession, sessionBaseUrl } from "./api.js";
+import { apiBase } from "./config.js";
+import { loadState, requireState } from "./state.js";
+import { convertTranscript, eventSchema, hash, sessionKey, slug, } from "./log-events.js";
+export function projectRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (loadState(dir))
+            return fs.realpathSync(dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export const logDir = (dir) => path.join(dir, ".virtualmatter", "agent-logs");
+export function writeJson(file, obj) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(temp, file);
+}
+export function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export function logConfig(dir) {
+    return readJson(path.join(logDir(dir), "config.json"));
+}
+export function enqueue(dir, harness, session, events) {
+    slug(harness);
+    sessionKey(session);
+    const framing = requireState(dir).framing_id;
+    const indexFile = path.join(logDir(dir), "captured", hash(JSON.stringify([apiBase(), framing, harness, session])) + ".json");
+    const known = Object.assign(Object.create(null), readJson(indexFile) ?? {});
+    const fresh = [];
+    // Validate the entire capture before queueing. Checkpoints contain hashes,
+    // never transcript content. Re-reading a growing transcript while offline
+    // must queue only its new events, not every prefix of the same conversation.
+    for (const raw of events) {
+        const event = eventSchema.parse(raw);
+        const encoded = JSON.stringify(event);
+        if (Buffer.byteLength(encoded) > 256 * 1024)
+            throw new Error("Event exceeds 256 KiB");
+        const digest = hash(encoded);
+        if (Object.hasOwn(known, event.event_id)) {
+            if (known[event.event_id] !== digest)
+                throw new Error("Event ID already captured with different content");
+        }
+        else {
+            fresh.push(event);
+            known[event.event_id] = digest;
+        }
+    }
+    let queued = 0;
+    let batch = [];
+    let size = 0;
+    const commit = () => {
+        if (!batch.length)
+            return;
+        const envelope = {
+            version: 1,
+            api: apiBase(),
+            framing,
+            harness,
+            session,
+            events: batch,
+        };
+        const id = hash(JSON.stringify(envelope));
+        const root = logDir(dir);
+        if (!fs.existsSync(path.join(root, "receipts", id)) &&
+            !fs.existsSync(path.join(root, "pending", id + ".json"))) {
+            writeJson(path.join(root, "pending", id + ".json"), envelope);
+            queued += batch.length;
+        }
+        batch = [];
+        size = 0;
+    };
+    for (const event of fresh) {
+        const bytes = Buffer.byteLength(JSON.stringify(event));
+        if (bytes > 256 * 1024)
+            throw new Error("Event exceeds 256 KiB");
+        if (batch.length >= 250 || size + bytes > 800_000)
+            commit();
+        batch.push(event);
+        size += bytes + 1;
+    }
+    commit();
+    // Queue first, checkpoint second. A crash can cause a safe duplicate retry,
+    // never a checkpoint that skips events which were not durably queued.
+    if (fresh.length)
+        writeJson(indexFile, { ...(readJson(indexFile) ?? {}), ...known });
+    return queued;
+}
+export async function uploadBatch(base, framing, harness, session, events) {
+    const response = await authorizedFetch(`${base}/api/montage/${encodeURIComponent(framing)}/agent-logs/${slug(harness)}/${sessionKey(session)}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok)
+        throw new Error(`Agent-log upload failed: HTTP ${response.status}${response.status === 404 ? " (server may need the agent-log API update)" : ""}`);
+    const result = (await response.json());
+    if (result.accepted + result.duplicates !== events.length)
+        throw new Error("Invalid upload acknowledgement; batch retained");
+    return result;
+}
+export async function flushLogs(dir, send) {
+    const lock = path.join(logDir(dir), "flush.lock");
+    fs.mkdirSync(path.dirname(lock), { recursive: true, mode: 0o700 });
+    // Concurrent hooks share one uploader. A crashed process leaves recoverable
+    // queue files; never discard batches just because a lock was abandoned.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeFileSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            try {
+                return await flushUnlocked(dir, send);
+            }
+            finally {
+                fs.rmSync(lock, { force: true });
+            }
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let pid;
+            try {
+                pid = Number(fs.readFileSync(lock, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            // A just-created, not-yet-written lock also belongs to a live writer.
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                return 0;
+            try {
+                process.kill(pid, 0);
+                return 0;
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    return 0;
+                fs.rmSync(lock, { force: true });
+            }
+        }
+    }
+    return 0;
+}
+async function flushUnlocked(dir, send) {
+    const root = logDir(dir), pending = path.join(root, "pending");
+    if (!fs.existsSync(pending))
+        return 0;
+    const files = fs
+        .readdirSync(pending)
+        .filter((f) => f.endsWith(".json"))
+        .sort((a, b) => fs.statSync(path.join(pending, a)).mtimeMs -
+        fs.statSync(path.join(pending, b)).mtimeMs);
+    if (!files.length)
+        return 0;
+    let base;
+    let sent = 0;
+    for (const name of files) {
+        const file = path.join(pending, name);
+        const e = readJson(file);
+        if (!e)
+            continue; // another flushing process already acknowledged it
+        if (e.version !== 1 ||
+            e.api !== apiBase() ||
+            e.framing !== requireState(dir).framing_id)
+            throw new Error("Outbox belongs to a different project/environment; preserved");
+        try {
+            if (send)
+                await send(e);
+            else {
+                base ??= sessionBaseUrl(await resolveSession(e.framing, { timeoutMs: 30_000 }));
+                await uploadBatch(base, e.framing, e.harness, e.session, e.events);
+            }
+            const receipt = path.join(root, "receipts", name.slice(0, -5));
+            fs.mkdirSync(path.dirname(receipt), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(receipt, "", { mode: 0o600 });
+            fs.rmSync(file, { force: true });
+            sent += e.events.length;
+        }
+        catch (err) {
+            writeJson(path.join(root, "last-error.json"), {
+                ts: new Date().toISOString(),
+                message: String(err),
+            });
+            throw err;
+        }
+    }
+    fs.rmSync(path.join(root, "last-error.json"), { force: true });
+    return sent;
+}
+export function registerSource(dir, source) {
+    slug(source.harness);
+    sessionKey(source.session);
+    const target = path.join(logDir(dir), "sources", hash(source.file) + ".json");
+    if (JSON.stringify(readJson(target)) !== JSON.stringify(source))
+        writeJson(target, source);
+}
+export function captureSource(dir, source, since) {
+    if (!fs.existsSync(source.file))
+        return 0;
+    if (fs.statSync(source.file).size > 128 * 1024 * 1024)
+        throw new Error("Transcript exceeds 128 MiB; split it for explicit upload");
+    const events = convertTranscript(fs.readFileSync(source.file, "utf8"), source.format, true).filter((e) => !since || Date.parse(e.ts) >= Date.parse(since));
+    return enqueue(dir, source.harness, source.session, events);
+}
+/** Discover Codex desktop/CLI sessions by their initial cwd metadata, never by text search. */
+export function discoverCodex(dir, since, home = process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex")) {
+    const root = path.join(home, "sessions"), found = [];
+    const walk = (folder, depth) => {
+        if (depth > 4 || !fs.existsSync(folder))
+            return;
+        for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+            const file = path.join(folder, entry.name);
+            if (entry.isDirectory())
+                walk(file, depth + 1);
+            else if (entry.isFile() &&
+                entry.name.endsWith(".jsonl") &&
+                fs.statSync(file).mtimeMs >= Date.parse(since)) {
+                const fd = fs.openSync(file, "r");
+                let first;
+                try {
+                    const buffer = Buffer.alloc(16384);
+                    first = buffer
+                        .subarray(0, fs.readSync(fd, buffer, 0, buffer.length, 0))
+                        .toString()
+                        .split("\n")[0];
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                try {
+                    const row = JSON.parse(first), p = row.payload;
+                    if (row.type === "session_meta" &&
+                        typeof p?.cwd === "string" &&
+                        projectRoot(p.cwd) === fs.realpathSync(dir)) {
+                        found.push({
+                            file,
+                            format: "codex",
+                            harness: "codex",
+                            session: sessionKey(p.id),
+                        });
+                    }
+                }
+                catch {
+                    /* unrelated/unflushed metadata */
+                }
+            }
+        }
+    };
+    walk(root, 0);
+    return found;
+}
+export async function collectLogs(dir) {
+    const config = logConfig(dir);
+    if (!config?.enabled)
+        return 0;
+    if (config.codexDiscovery)
+        for (const source of discoverCodex(dir, config.since))
+            registerSource(dir, source);
+    const sources = path.join(logDir(dir), "sources");
+    let n = 0;
+    const errors = [];
+    if (fs.existsSync(sources))
+        for (const file of fs
+            .readdirSync(sources)
+            .filter((f) => f.endsWith(".json"))) {
+            try {
+                n += captureSource(dir, readJson(path.join(sources, file)), config.since);
+            }
+            catch (err) {
+                errors.push({ source: file, message: String(err) });
+            }
+        }
+    if (errors.length)
+        writeJson(path.join(logDir(dir), "capture-errors.json"), errors);
+    else
+        fs.rmSync(path.join(logDir(dir), "capture-errors.json"), { force: true });
+    return n;
+}
+/** One non-overlapping retry loop; discovery also catches delayed final transcript writes. */
+export function startLogSync(dir, warn = (s) => console.warn(s)) {
+    let running;
+    let lastError = "";
+    const tick = () => {
+        if (running)
+            return;
+        running = (async () => {
+            try {
+                if (!logConfig(dir)?.enabled)
+                    return;
+                await collectLogs(dir);
+                await flushLogs(dir);
+                lastError = "";
+            }
+            catch (err) {
+                const message = String(err);
+                if (message !== lastError)
+                    warn(`Agent logs queued: ${message}`);
+                lastError = message;
+            }
+        })().finally(() => {
+            running = undefined;
+        });
+    };
+    tick();
+    const interval = setInterval(tick, 5000);
+    return async () => {
+        clearInterval(interval);
+        await running;
+    };
+}

package/dist/agentfiles.js

@@ -14,6 +14,7 @@ export const AGENTS_MD_STUB = `# Working with Virtual Matter
 This folder is a live mirror of a Virtual Matter world's Montage files.
 
 - \`npx virtualmatter sync\` keeps it in sync with the running session.
+- \`npx virtualmatter agent-logs setup\` enables automatic local conversation logs.
 - \`npx virtualmatter run-lua --code "..."\` executes Lua in the engine.
 - \`npx virtualmatter errors\` shows recent engine errors.
 - \`npx virtualmatter screenshot -o shot.png\` captures the current view.
@@ -49,6 +50,48 @@ function mcpServerConfig() {
         args: ["-y", "virtualmatter", "mcp"],
     };
 }
+/**
+ * The SDK's own AGENTS.md ships inside every Montage tree. It is written for
+ * the in-session agent that drives the engine through `atomo`, which only
+ * works against a running engine bridge - so a local harness must not follow
+ * it literally. Its Skills/ table and engine rules are still the best
+ * reference there is, so the pulled AGENTS.md carries BOTH: the platform
+ * guide first, then the engine doc under a header that translates every
+ * `atomo` step into its CLI equivalent.
+ */
+export function composeAgentsMd(platformDoc, engineDoc) {
+    if (!engineDoc || engineDoc.trim().length === 0)
+        return platformDoc;
+    const bridge = `
+
+---
+
+# Engine reference (the world's SDK AGENTS.md)
+
+The section below is the engine SDK's own agent guide, mirrored from this
+world's Montage tree. It assumes an agent running INSIDE a Virtual Matter
+session, where an \`atomo\` command talks to the live engine. Here, on your own
+machine, there is no engine bridge - use the \`virtualmatter\` CLI (or its MCP
+tools) wherever the text says \`atomo\`:
+
+| Engine doc says | Do this instead |
+| --- | --- |
+| \`atomo run-lua '<code>'\` | \`npx virtualmatter run-lua --code '<code>'\` (MCP: \`run_lua\`) |
+| \`atomo run-lua-client ...\` | \`npx virtualmatter run-lua --target client --code '<code>'\` |
+| \`atomo errors\` | \`npx virtualmatter errors\` (MCP: \`get_engine_errors\`) |
+| \`atomo screenshot\` / \`screenshot-at\` / \`screenshot-obj\` | \`npx virtualmatter screenshot -o shot.png\` (MCP: \`capture_screenshot\`); aim the camera with run-lua first if needed |
+| \`atomo prints\` / \`atomo status\` | not available locally; use \`return\` values from run-lua |
+| edit a .lua file, then check \`atomo errors\` | save the file with \`npx virtualmatter sync\` running (or MCP \`write_file\`), then check errors the same way |
+| \`Skills/git-commit.md\` (git add/commit) | skip it - there is no git here; sync IS the persistence |
+| paths under \`/data/persist/Montage/\` | this folder |
+
+Everything else in it - the Skills/ table, the server/client rules, the Lua
+API rules, the mandatory error check after every change - applies as written.
+The \`Skills/\` files it references are in this folder.
+
+`;
+    return platformDoc.trimEnd() + "\n" + bridge + engineDoc.trimStart();
+}
 /** Write the harness files into a pulled folder. */
 export function writeAgentFiles(dir, agentsMd) {
     const written = [];

package/dist/api.js

@@ -151,3 +151,24 @@ export async function fetchNativeClientCatalog(framingId, fetchFn = fetch) {
     const body = (await res.json());
     return { iteration: body.iteration ?? null, clients: body.clients ?? [] };
 }
+/** Website-builder operations share the hosted integration's canonical contract. */
+export async function getEmbed(target, fetchFn = fetch) {
+    const response = await fetchFn(`${apiBase()}/api/v1/public/embed?target=${encodeURIComponent(target)}`);
+    if (!response.ok)
+        throw await readError(response, "Resolving embed (the world must be shared)");
+    return await response.json();
+}
+export async function createWebsiteBuild(input, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input),
+    }, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Starting VM build");
+    return await response.json();
+}
+export async function getWebsiteBuild(buildId, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds/${encodeURIComponent(buildId)}`, {}, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Reading VM build status");
+    return await response.json();
+}

package/dist/files.js

@@ -3,6 +3,32 @@
  * https://<voxel_host>/s/<session_id>/api/montage/<framing_id>/...
  */
 import { authorizedFetch } from "./api.js";
+/**
+ * The reason an engine call failed, read out of the response body.
+ *
+ * The session API answers a refusal with
+ * `{detail: {error, message}}`, and dropping it left callers staring at a
+ * bare "HTTP 502" - which is exactly what sent test agents off to drive a
+ * browser instead. Falls back to the status when the body says nothing.
+ */
+export async function engineErrorMessage(res, what) {
+    let detail = "";
+    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;
+        }
+        else if (d)
+            detail = JSON.stringify(d);
+    }
+    catch {
+        /* non-JSON body */
+    }
+    return `${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`;
+}
 export class ConflictError extends Error {
     filePath;
     constructor(filePath) {
@@ -93,7 +119,7 @@ export class FilesClient {
             body: JSON.stringify({ code, target }),
         }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`run-lua failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "run-lua"));
         // Server envelope: {output: <text>} - the engine bridge's text
         // (result/print/error sections) passed through verbatim.
         const body = (await res.json());
@@ -102,14 +128,36 @@ export class FilesClient {
     async engineErrors() {
         const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Fetching engine errors failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Fetching engine errors"));
         const body = (await res.json());
         return body.output;
     }
-    async screenshot() {
-        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, { method: "POST" }, this.fetchFn);
+    async screenshot(opts = {}) {
+        const body = {};
+        if (opts.target) {
+            body.target_object_id = opts.target;
+            if (opts.distance !== undefined)
+                body.distance = opts.distance;
+        }
+        else if (opts.at || opts.rot) {
+            const [px, py, pz] = opts.at ?? [0, 20, 20];
+            const [rx, ry, rz] = opts.rot ?? [0, -45, 0];
+            Object.assign(body, {
+                camera_pos_x: px,
+                camera_pos_y: py,
+                camera_pos_z: pz,
+                camera_rot_x: rx,
+                camera_rot_y: ry,
+                camera_rot_z: rz,
+            });
+        }
+        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Screenshot failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Screenshot"));
         return Buffer.from(await res.arrayBuffer());
     }
 }

package/dist/ignore.js

@@ -21,5 +21,24 @@ export function isIgnoredPath(relPath) {
         return true;
     if (norm.endsWith(".remote-conflict"))
         return true;
+    // The SDK's in-session harness tooling at the Montage root. `atomo` only
+    // works against a running engine bridge, so mirroring it invites an agent
+    // to try it and fail; the CLI is the local path. Sync leaves them alone in
+    // both directions.
+    if (segments.length === 1 && isSdkHarnessTooling(first))
+        return true;
     return false;
 }
+const SDK_HARNESS_FILES = new Set([
+    "atomo",
+    "atomo.bat",
+    "atomo_cli.py",
+    "vm_auth.py",
+    "agent_log_sync.py",
+    "atomontage.code-workspace",
+]);
+export function isSdkHarnessTooling(name) {
+    if (SDK_HARNESS_FILES.has(name))
+        return true;
+    return /_agent_log_(sync|setup)\.py$/.test(name);
+}