summer-engine 2.6.3 → 2.6.6

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge. Build games by talking.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge. Build games by talking.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -92,7 +92,7 @@
   "interface": {
     "displayName": "Summer",
     "shortDescription": "Superpowers for AI game dev. Build games by talking.",
-    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, a using-summer workflow skill, lifecycle hooks, and a 44-tool MCP bridge for scene editing, asset import, play mode, diagnostics, and generation. File, git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive the engine through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
+    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, a using-summer workflow skill, lifecycle hooks, and a 52-tool MCP bridge for scene editing, asset import, play mode, diagnostics, and generation. File, git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive the engine through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
     "developerName": "Summer Engine",
     "category": "Coding",
     "capabilities": ["Interactive", "Read", "Write"],

package/.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "summer",
   "displayName": "Summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
   "publisher": "summer-engine",
   "homepage": "https://summerengine.com",

package/.factory-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "summer",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "version": "2.5.1",
   "author": {
     "name": "Summer Engine",

package/AGENTS.md

@@ -22,11 +22,12 @@ This file is for any AI agent that loads context from `AGENTS.md` (Codex CLI, Fa
 
 ## MCP tool palette (engine on `localhost:6550`)
 
-44 tools total. Categories:
+52 tools total. Categories:
 
 - Scene: `summer_get_scene_tree`, `summer_open_scene`, `summer_create_scene`, `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_instantiate_scene`, `summer_replace_node`, `summer_select_node`, `summer_inspect_node`, `summer_inspect_resource`, `summer_connect_signal`, `summer_batch`.
 - Diagnostics: `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_clear_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - Runtime: `summer_play`, `summer_stop`, `summer_is_running`.
+- Visual: `summer_screenshot` (capture the editor viewport or running game as an image to verify it).
 - Project: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`, `summer_get_agent_playbook`.
 - Assets: `summer_search_assets`, `summer_list_my_assets`, `summer_get_asset`, `summer_get_asset_download_url`, `summer_import_asset`, `summer_import_asset_by_id`, `summer_import_from_url`, `summer_import_from_url_batch`.
 - Generation: `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_generate_motion`, `summer_check_job`.

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to summer-engine will be documented here. Following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
+## [2.6.6] — 2026-07-15 — "Project-bound engine requests"
+
+### Fixed
+- Every local engine request now carries the engine instance ID, stable project ID, project ID hash, and identity protocol version captured when the CLI connects. This lets compatible engine builds reject stale requests after a project or engine switch instead of acting on the wrong target.
+- An explicit project rebind now refreshes the complete engine and project identity, while keeping the existing project-hash mutation guard and screenshot drift checks.
+- Summer Cloud's engine bridge now binds its save, rescan, and scene reload requests to the project it verified on disk.
+
+### Changed
+- Summer Cloud is documented as an optional Research Preview instead of part of the core local CLI and MCP workflow.
+- Release metadata and the manual npm runbook now pin the public registry and require a clean, reviewed public source checkout.
+
+## [2.6.5] — 2026-07-04 — "Cloud tools don't need the engine"
+
+### Fixed
+- Tool descriptions now say explicitly which tools run in Summer's cloud and work WITHOUT the engine open (`summer_generate_*`, `summer_search_assets`, `summer_list_my_assets`, `summer_get_asset`, `summer_get_asset_download_url`, `summer_check_job`) and which need the engine (imports, scene ops). Agents were misreading a missing `npx summer-engine login` as "MCP requires the engine".
+- The "Summer Engine is not running" error now tells the agent that cloud tools still work without the engine.
+
+## [2.6.4] — 2026-07-03 — "See-Work + project binding" (unpublished, ships with 2.6.5)
+
+### Added
+- MCP session binds to its project; the engine rejects wrong-project writes (`identity_mismatch`) instead of applying them to whatever project is open.
+- Structured per-tool-call stderr logging; agent playbook rewritten around the MCP verification ladder; honest game-capture failure states and identity-stamped reads.
+
+## [2.6.3] — 2026-06-30 — "Agent vision"
+
+### Added
+- `summer_screenshot` MCP tool: capture the editor viewport or the running game as an image the agent sees directly (`target: "viewport" | "game"`, viewport by default). Lets the agent visually verify scene layout, asset placement, scale, framing, and runtime state — the client reads the actual frame, with no description step in between. Total MCP tool surface is now 52.
+
+### Fixed
+- MCP/CLI session now reconnects automatically after a transient engine restart (the engine rotates its api-token and can move its port on relaunch), instead of surfacing as a "disconnected" error.
+
 ## [2.6.0] — 2026-06-10 — "Summer Cloud"
 
 ### Added

package/GEMINI.md

@@ -20,12 +20,13 @@ The single most important skill to know is `summer:using-summer` — it explains
 
 ## MCP tools (when the engine is running on `localhost:6550`)
 
-The `summer-engine` MCP server exposes 44 focused tools. The most important:
+The `summer-engine` MCP server exposes 52 focused tools. The most important:
 
 - **Scene mutation**: `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_replace_node`, `summer_batch`.
 - **Scene inspection**: `summer_get_scene_tree`, `summer_inspect_node`, `summer_inspect_resource`.
 - **Diagnostics**: `summer_get_script_errors` (cheapest), `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - **Run game**: `summer_play`, `summer_stop`, `summer_is_running`.
+- **Visual**: `summer_screenshot` (capture the viewport or running game as an image you can see).
 - **Project**: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`.
 - **Assets**: `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_check_job`.
 

package/README.md

@@ -18,27 +18,11 @@ It just works. Open your agent, say *"let's make an FPS in Summer Engine,"* and
 Three names, one npm package (`summer-engine`):
 
 - **Summer CLI** (`npx -y summer-engine@latest`): installs the engine, signs you in, scaffolds and runs projects, and writes your agent's config. See [www.summerengine.com/cli](https://www.summerengine.com/cli).
-- **Summer MCP**: the local MCP server that gives your agent 44 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
+- **Summer MCP**: the local MCP server that gives your agent 52 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
 - **Summer agent layer**: the game-dev skills, hooks, and plugin manifests that give your AI agent judgment, not just a chat box.
 
 All MIT, all free to use. One paste sets up all three.
 
-## Summer Cloud (new in 2.6.0)
-
-`summer cloud` syncs your whole game project across machines: scenes, scripts, settings, and the big binary assets that never fit in git. Files are stored by content hash, every push becomes a restorable version, and local checkpoints are taken before anything destructive touches your disk.
-
-```bash
-summer cloud init      # bind this project to your account
-summer cloud push      # upload what changed (only missing bytes travel)
-summer cloud pull      # make this machine match the cloud, verified by hash
-summer cloud status    # what differs between here and the cloud
-summer cloud restore   # roll the project back to any version
-```
-
-The same operations are available to agents as MCP tools (`summer_cloud_push`, `summer_cloud_pull`, and friends). See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
-
----
-
 ## Get started: one prompt
 
 Open your AI agent (Claude Code, Cursor, Codex, Copilot, Devin Desktop, etc.) and paste:
@@ -269,13 +253,15 @@ Two pieces, plus the glue.
 
 Skills don't list steps. They encode the **order of operations**: diagnose before editing, scope before building, ask before guessing. [Agent Skills](https://agentskills.io) format, so any conformant tool picks them up.
 
-**MCP bridge.** The `summer-engine` MCP server gives the agent 44 tools that talk to your local engine on `localhost:6550`:
+**MCP bridge.** The `summer-engine` MCP server gives the agent 52 tools that talk to your local engine on `localhost:6550`:
 
 | | |
 |---|---|
 | Scene | `summer_add_node`, `summer_set_prop`, `summer_instantiate_scene`, `summer_replace_node`, `summer_get_scene_tree`, `summer_inspect_node`, `summer_batch` |
 | Diagnostics | `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings` |
 | Runtime | `summer_play`, `summer_stop`, `summer_is_running` |
+| Visual | `summer_screenshot` (see the editor viewport, an offscreen scene render, or the running game) |
+| Interactive | `SimulateInput` / `RunVerification` raw ops via `summer_batch` — drive the running game or run a hidden GDScript probe (engine-build dependent) |
 | Project | `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind` |
 | Assets | `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video` |
 
@@ -285,6 +271,36 @@ File ops, git, shell, and grep already belong to your agent. We don't shadow the
 
 For the full architecture, see [docs/OVERVIEW.md](docs/OVERVIEW.md).
 
+### Using Summer via MCP: the verification loop
+
+There is no single "verify" tool. You **compose** the checks, climbing only as high as the change demands. Call `summer_get_agent_playbook` for the full ladder; the short version:
+
+**1. Does it compile?** After writing a `.gd`, call `summer_get_script_errors res://scripts/player.gd` — no game boot. For a project-wide sweep, `summer_get_diagnostics` (it tells you whether to then read `summer_get_console` / `summer_get_debugger_errors`).
+
+**2. Does it look right?** `summer_screenshot` returns the actual pixels — you see them, no description layer. Pick the target on purpose:
+- `viewport` (default) — the editor's current tab, as it looks now.
+- `scene` — an offscreen render of a scene *file* (`scenePath`). No boot; **static at t=0**. Confesses if the scene has no `Camera3D` (renders grey/black when played) or no light — read those warnings.
+- `game` — a frame from the **running** game (`summer_play` first). Over plain local HTTP this returns an honest failure until the desktop bridge is present; when it fails, drop to `viewport`/`scene` or ask the user.
+
+**3. Does it run?** Compose the loop:
+
+```
+summer_clear_console            # clean slate
+summer_play                     # boot the game (or a specific scene)
+summer_get_debugger_errors      # runtime errors: null refs, missing nodes, physics
+summer_screenshot target:game   # optional: look at the live frame
+summer_stop                     # ALWAYS stop — scene edits are refused while running
+```
+
+**4. Does the interaction work?** To prove input-driven behavior (jump/move/shoot), send a raw op through `summer_batch` (engine-build dependent — a `failure_reason:"unsupported"` comes back verbatim on older builds):
+- `SimulateInput` — inject into the **running** game: `summer_batch ops:[{op:"SimulateInput", type:"action", action:"jump", pressed:true}]`, then re-check screenshot/debugger.
+- `RunVerification` — spawn a hidden, disposable game instance that runs a GDScript probe (press inputs, read state, save frames) and dies, never touching the editor: `summer_batch ops:[{op:"RunVerification", probe_source:"…", max_seconds:20}]` → `{ok, results, frames, out_dir}`.
+- If neither is available on this build, **ask the user to try it** and report what they see — don't fake it.
+
+**Honesty.** Never describe an image you didn't receive; a failed capture is a *result* — report it and climb down (`scene`→`viewport`) or ask the user. Pass structured failures (`failure_reason`, `terminalState`, `identity_mismatch`) through verbatim. `summer_get_project_context` binds the session to the open project; a `projectMismatch` warning on a screenshot means the engine switched projects and the frame may be from the wrong one — rebind before trusting it.
+
+**Debugging the MCP itself.** Set `SUMMER_MCP_DEBUG=1` in the server's environment to log a structured stderr line per tool call (`tool`, `ok`, `durationMs`, `terminalState`, `errorClass`, `failureReason`, `retried`). With the flag off, only failures are logged.
+
 ---
 
 ## The basic workflow
@@ -524,6 +540,24 @@ Skills evolve fast. Two ways to help:
 
 ---
 
+## Research Preview: Summer Cloud
+
+Summer Cloud is an experimental R&D preview. It is optional, it may change or break, and it is **not** the core Summer CLI or MCP workflow. You do not need it to install or run Summer Engine, work with local projects, or use the local MCP server. The stable workflow is the local engine, CLI, MCP bridge, and agent skills described above.
+
+The preview explores content-addressed project sync across machines, including large assets that do not fit comfortably in git:
+
+```bash
+summer cloud init
+summer cloud status
+summer cloud push
+summer cloud pull
+summer cloud restore
+```
+
+Matching `summer_cloud_*` MCP tools are also experimental. Keep an independent backup and do not use this preview as the only recovery path for an important project. See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
+
+---
+
 ## License
 
 MIT for everything in this repo. Summer Engine itself is proprietary. See [What's open and what's not](#whats-open-and-whats-not).

package/dist/lib/api-client.d.ts

@@ -16,12 +16,49 @@ export type EngineSnapshot = {
     bytes?: number;
     error?: string;
     metadata?: Record<string, unknown>;
+    /** Structured failure classifier the engine returns on a game snapshot over
+     *  local HTTP (409 `bridge_required`) — surfaced verbatim so the tool can give
+     *  an honest, actionable message instead of a truncated generic 409 string.
+     *  When P4.4 lands (game snapshots answer 200/202 over HTTP) this simply
+     *  never fires and the tool works. */
+    failureReason?: string;
+    /** Scene-preview confession fields (P4.3). Populated only for target:"scene".
+     *  A scene with no Camera3D renders grey/black when played; the engine reports
+     *  whether it had to synthesize a camera/light so the model can warn honestly. */
+    sceneHasCamera?: boolean;
+    sceneHadLight?: boolean;
+    usedSyntheticCamera?: boolean;
+    /** Set true when the bound projectIdHash no longer matches the engine's live
+     *  health hash at capture time — the frame may be from the WRONG project
+     *  (item 4, client-side drift check). */
+    projectMismatch?: boolean;
+};
+type EngineTargetIdentity = {
+    instanceId?: string;
+    projectId?: string;
+    projectIdHash?: string;
 };
 export declare class EngineApiClient {
     private port;
     private token;
-    constructor(port: number, token: string);
+    private targetIdentity;
+    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string);
     static connect(): Promise<EngineApiClient>;
+    /** The projectIdHash this session is bound to (undefined if none was reported
+     *  at connect — e.g. no project open yet). */
+    getBoundProjectIdHash(): string | undefined;
+    /**
+     * Re-read health and rebind to the currently-open project. Called by
+     * summer_get_project_context so the agent can INTENTIONALLY follow a project
+     * switch (the deliberate escape hatch after an identity_mismatch). Returns the
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
+     */
+    rebind(): Promise<string | undefined>;
+    /** Identity to attach to a MUTATING command's options so the engine can reject
+     *  a wrong-project write. Empty when unbound (engine then skips the check). */
+    private identityOptions;
+    private targetUrl;
     private request;
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
@@ -51,8 +88,34 @@ export declare class EngineApiClient {
     getSelection(): Promise<unknown>;
     private writeSnapshotFile;
     private snapshot;
+    /** Shared: turn an ops/snapshot response envelope into an EngineSnapshot.
+     *  Used by viewport/game snapshots and by scenePreview. */
+    private _parseSnapshotResponse;
+    /**
+     * Probe /api/snapshot/game for the structural 409 `bridge_required` shape
+     * (tool_net_thread.cpp:495-503). Returns a structured failure only when the
+     * engine actually answers 409 with `bridge_required` / `unsupported_transport`;
+     * ANY other status (200/202/other) returns null so the caller proceeds to the
+     * normal queued path — so the moment the engine starts answering over HTTP
+     * (P4.4), game capture just works with no code change here.
+     */
+    private _detectBridgeRequired;
     viewportSnapshot(): Promise<EngineSnapshot>;
     gameSnapshot(): Promise<EngineSnapshot>;
+    /**
+     * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
+     * boot; physics/animations are static). Mirrors the web previewScene op input
+     * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
+     * node_path? } — scene_path optional, engine defaults to the open scene. The
+     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
+     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     */
+    scenePreview(input?: {
+        scenePath?: string;
+        framing?: "auto" | "top" | "front" | "iso";
+        size?: [number, number];
+        nodePath?: string;
+    }): Promise<EngineSnapshot>;
     getPort(): number;
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh
@@ -68,3 +131,4 @@ export declare class EngineApiClient {
      */
     credentialsChanged(): Promise<boolean>;
 }
+export {};

package/dist/lib/api-client.js

@@ -14,6 +14,9 @@ function stringFrom(value) {
 function numberFrom(value) {
     return typeof value === "number" ? value : undefined;
 }
+function boolFrom(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
 function findSnapshotPayload(value) {
     const record = asRecord(value);
     if (!record)
@@ -21,7 +24,8 @@ function findSnapshotPayload(value) {
     if (typeof record.base64 === "string" ||
         typeof record.image_base64 === "string" ||
         record.op === "ViewportSnapshot" ||
-        record.op === "GameSnapshot") {
+        record.op === "GameSnapshot" ||
+        record.op === "ScenePreview") {
         return record;
     }
     if (Array.isArray(record.results)) {
@@ -63,9 +67,19 @@ function withoutImageData(payload) {
 export class EngineApiClient {
     port;
     token;
-    constructor(port, token) {
+    // The engine and project this session is bound to. Every request carries the
+    // identity captured from health so the engine can reject requests after an
+    // in-place project switch or an unexpected instance change. The string form
+    // preserves the pre-2.6.6 constructor contract for existing callers that only
+    // supplied a projectIdHash.
+    targetIdentity;
+    constructor(port, token, targetIdentity = {}) {
         this.port = port;
         this.token = token;
+        this.targetIdentity =
+            typeof targetIdentity === "string"
+                ? { projectIdHash: targetIdentity }
+                : { ...targetIdentity };
     }
     static async connect() {
         const port = await getApiPort();
@@ -77,10 +91,62 @@ export class EngineApiClient {
         if (!health) {
             throw new Error(`Summer Engine is not responding on port ${port}. Make sure it's open.`);
         }
-        return new EngineApiClient(port, token);
+        // Bind to whatever project is open right now. On a genuine engine restart the
+        // token rotates and getClient() rebuilds this client, so a restart naturally
+        // rebinds to the current project. An in-place project switch keeps the same
+        // token, so the cached client retains its original binding and the engine
+        // rejects mismatched mutations until the agent explicitly rebinds.
+        return new EngineApiClient(port, token, {
+            instanceId: health.instanceId,
+            projectId: health.projectId,
+            projectIdHash: health.projectIdHash,
+        });
+    }
+    /** The projectIdHash this session is bound to (undefined if none was reported
+     *  at connect — e.g. no project open yet). */
+    getBoundProjectIdHash() {
+        return this.targetIdentity.projectIdHash;
+    }
+    /**
+     * Re-read health and rebind to the currently-open project. Called by
+     * summer_get_project_context so the agent can INTENTIONALLY follow a project
+     * switch (the deliberate escape hatch after an identity_mismatch). Returns the
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
+     */
+    async rebind() {
+        const health = await checkEngineHealth(this.port);
+        if (health) {
+            this.targetIdentity = {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash: health.projectIdHash,
+            };
+        }
+        return this.targetIdentity.projectIdHash;
+    }
+    /** Identity to attach to a MUTATING command's options so the engine can reject
+     *  a wrong-project write. Empty when unbound (engine then skips the check). */
+    identityOptions() {
+        const projectIdHash = this.targetIdentity.projectIdHash;
+        return projectIdHash ? { projectIdHash } : {};
+    }
+    targetUrl(path) {
+        const url = new URL(path, `http://127.0.0.1:${this.port}`);
+        const { instanceId, projectId, projectIdHash } = this.targetIdentity;
+        if (instanceId)
+            url.searchParams.set("instanceId", instanceId);
+        if (projectId)
+            url.searchParams.set("projectId", projectId);
+        if (projectIdHash)
+            url.searchParams.set("projectIdHash", projectIdHash);
+        if (instanceId && projectId && projectIdHash) {
+            url.searchParams.set("projectIdentityVersion", "1");
+        }
+        return url.toString();
     }
     async request(method, path, body) {
-        const url = `http://127.0.0.1:${this.port}${path}`;
+        const url = this.targetUrl(path);
         const headers = {
             Authorization: `Bearer ${this.token}`,
             "Content-Type": "application/json",
@@ -100,7 +166,7 @@ export class EngineApiClient {
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
     async _fetchRaw(method, path, body, timeoutMs) {
-        return fetch(`http://127.0.0.1:${this.port}${path}`, {
+        return fetch(this.targetUrl(path), {
             method,
             headers: {
                 Authorization: `Bearer ${this.token}`,
@@ -150,7 +216,11 @@ export class EngineApiClient {
         // Ops may include long-running work (ImportFromUrlBatch, GitCommit); the
         // engine keeps it "running" and we poll. 120s budget. Resolves legacy-200 or
         // async-202 (Block E).
-        return this._requestQueued("POST", "/api/ops", { ops, options }, 120_000);
+        // Attach the bound project identity so the engine rejects a write aimed at a
+        // different project (identity_mismatch, atomic — before any op applies).
+        const merged = { ...this.identityOptions(), ...(options ?? {}) };
+        const body = Object.keys(merged).length ? { ops, options: merged } : { ops };
+        return this._requestQueued("POST", "/api/ops", body, 120_000);
     }
     async getSceneState() {
         return this.request("GET", "/api/state/scene");
@@ -174,11 +244,14 @@ export class EngineApiClient {
         // Cold-load on large projects can take 25-40s. 60s budget.
         // The engine reads play params from body.options (tool_net_thread.cpp:503),
         // and the play handler reads options["scene"] — a top-level { scene } is
-        // dropped, so the scene MUST be nested inside options.
-        return this._requestQueued("POST", "/api/play", scene ? { options: { scene } } : {}, 60_000);
+        // dropped, so the scene MUST be nested inside options. The bound identity
+        // rides in the same options dict so play is refused on a mismatched project.
+        const options = { ...this.identityOptions(), ...(scene ? { scene } : {}) };
+        return this._requestQueued("POST", "/api/play", Object.keys(options).length ? { options } : {}, 60_000);
     }
     async stop() {
-        return this._requestQueued("POST", "/api/stop", undefined, 15_000);
+        const options = this.identityOptions();
+        return this._requestQueued("POST", "/api/stop", Object.keys(options).length ? { options } : undefined, 15_000);
     }
     async readFile(path, maxBytes) {
         const params = new URLSearchParams({ path });
@@ -211,6 +284,18 @@ export class EngineApiClient {
         // The terminal result is the apply dict; the image rides as base64 inside it
         // (no raw-binary channel). Legacy/dormant engines answer 200 synchronously
         // with the same payload shape — _requestQueued resolves both.
+        //
+        // Game capture over local HTTP structurally 409s today with a STRUCTURED
+        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`,
+        // tool_net_thread.cpp:495-503). Detect that specific shape and return it
+        // verbatim so the tool can give an honest message — do NOT hardcode "game
+        // always fails": once the engine answers 200/202 (P4.4), the normal path
+        // below just works.
+        if (kind === "game") {
+            const bridge = await this._detectBridgeRequired(`/api/snapshot/${kind}`);
+            if (bridge)
+                return bridge;
+        }
         let response;
         try {
             response = await this._requestQueued("GET", `/api/snapshot/${kind}`, undefined, 60_000);
@@ -218,11 +303,16 @@ export class EngineApiClient {
         catch (err) {
             return { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
+        return this._parseSnapshotResponse(response, kind);
+    }
+    /** Shared: turn an ops/snapshot response envelope into an EngineSnapshot.
+     *  Used by viewport/game snapshots and by scenePreview. */
+    async _parseSnapshotResponse(response, kind) {
         const payload = findSnapshotPayload(response);
         if (!payload) {
             return {
                 ok: false,
-                error: "Snapshot response did not include a viewport/game payload.",
+                error: "Snapshot response did not include an image payload.",
             };
         }
         const base64 = stringFrom(payload.base64) ?? stringFrom(payload.image_base64);
@@ -230,12 +320,34 @@ export class EngineApiClient {
             return {
                 ok: false,
                 error: stringFrom(payload.error) ?? "Snapshot response did not include image data.",
+                failureReason: stringFrom(payload.failure_reason),
+                sceneHasCamera: boolFrom(payload.scene_has_camera),
+                sceneHadLight: boolFrom(payload.scene_had_light),
+                usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
                 metadata: withoutImageData(payload),
             };
         }
         const { format, mime, ext } = snapshotFormat(payload);
         const buffer = Buffer.from(base64, "base64");
         const localPath = await this.writeSnapshotFile(kind, buffer, ext);
+        // Client-side identity drift check (item 4). Current engines validate the
+        // identity query on snapshot reads, but older builds may ignore it. Re-read
+        // health and compare to the bound hash so a frame from a switched project is
+        // still marked as suspect. Best-effort: a failed health read never blocks the
+        // already captured image.
+        let projectMismatch;
+        const boundProjectIdHash = this.targetIdentity.projectIdHash;
+        if (boundProjectIdHash) {
+            try {
+                const health = await checkEngineHealth(this.port);
+                if (health?.projectIdHash && health.projectIdHash !== boundProjectIdHash) {
+                    projectMismatch = true;
+                }
+            }
+            catch {
+                // ignore — never fail a capture on a transient health read
+            }
+        }
         return {
             ok: payload.ok !== false,
             localPath,
@@ -249,15 +361,86 @@ export class EngineApiClient {
             op: stringFrom(payload.op),
             provenance: payload.provenance,
             bytes: buffer.byteLength,
+            sceneHasCamera: boolFrom(payload.scene_has_camera),
+            sceneHadLight: boolFrom(payload.scene_had_light),
+            usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
+            projectMismatch,
             metadata: withoutImageData(payload),
         };
     }
+    /**
+     * Probe /api/snapshot/game for the structural 409 `bridge_required` shape
+     * (tool_net_thread.cpp:495-503). Returns a structured failure only when the
+     * engine actually answers 409 with `bridge_required` / `unsupported_transport`;
+     * ANY other status (200/202/other) returns null so the caller proceeds to the
+     * normal queued path — so the moment the engine starts answering over HTTP
+     * (P4.4), game capture just works with no code change here.
+     */
+    async _detectBridgeRequired(path) {
+        let res;
+        try {
+            res = await this._fetchRaw("GET", path, undefined, 15_000);
+        }
+        catch {
+            // Transport error — let the normal path surface it uniformly.
+            return null;
+        }
+        if (res.status !== 409)
+            return null;
+        const body = (await res.json().catch(() => ({})));
+        const reason = stringFrom(body.failure_reason);
+        const bridge = body.bridge_required === true;
+        if (!bridge && reason !== "unsupported_transport") {
+            // A 409 we don't recognize — surface it as a plain error rather than
+            // silently claiming "bridge required".
+            return {
+                ok: false,
+                error: stringFrom(body.error) ?? "Engine returned 409 for game snapshot.",
+            };
+        }
+        return {
+            ok: false,
+            failureReason: reason ?? "bridge_required",
+            error: stringFrom(body.error) ?? "Game snapshots require the desktop bridge async transport.",
+        };
+    }
     async viewportSnapshot() {
         return this.snapshot("viewport");
     }
     async gameSnapshot() {
         return this.snapshot("game");
     }
+    /**
+     * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
+     * boot; physics/animations are static). Mirrors the web previewScene op input
+     * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
+     * node_path? } — scene_path optional, engine defaults to the open scene. The
+     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
+     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     */
+    async scenePreview(input) {
+        const opInput = { op: "ScenePreview" };
+        const trimmed = input?.scenePath?.trim();
+        if (trimmed && trimmed !== "." && trimmed !== "./")
+            opInput.scene_path = trimmed;
+        if (input?.framing)
+            opInput.framing = input.framing;
+        if (input?.size)
+            opInput.size = input.size;
+        if (input?.nodePath)
+            opInput.node_path = input.nodePath;
+        let response;
+        try {
+            // executeOps stamps the bound identity so a drifted project is rejected
+            // (identity_mismatch) before rendering — ScenePreview reads no game state
+            // but still targets a project's resources.
+            response = await this.executeOps([opInput]);
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+        return this._parseSnapshotResponse(response, "scene");
+    }
     getPort() {
         return this.port;
     }

package/dist/lib/cloud/engine-bridge.js

@@ -50,7 +50,15 @@ async function connectForProject(projectRoot) {
         // rescan; the executor rejects mismatches too, but skip the round trip.
         if (health.projectIdHash && health.projectIdHash !== projectIdHash)
             return null;
-        return { client: new EngineApiClient(port, token), projectIdHash, scene: health.scene };
+        return {
+            client: new EngineApiClient(port, token, {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash,
+            }),
+            projectIdHash,
+            scene: health.scene,
+        };
     }
     catch {
         return null;