wave3d-agent-sdk 0.2.8 → 0.2.10

package/README.md

@@ -21,19 +21,19 @@ Vocabulary:
 - Project: user workspace content. Reading a project is not opening/replacing live workspace.
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.8 start
+npx -y wave3d-agent-sdk@0.2.10 start
 ```
 
-After Copy to Agent, restart stale SDK processes with MCP_TOKEN preserved as the local pairing secret. Keep it hidden:
+After Copy to Agent, run the exact start command with MCP_TOKEN preserved as the local pairing secret. Keep it hidden:
 
 ```bash
-WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.8 start
+WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.10 start
 ```
 
 Check SDK build before trusting a running SDK process:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.8 --version
+npx -y wave3d-agent-sdk@0.2.10 --version
 ```
 
 The package bundles the WaveEngine SDK lookup corpus. No normal session needs a separate protected zip download.
@@ -43,12 +43,12 @@ The package bundles the WaveEngine SDK lookup corpus. No normal session needs a
 Wave Studio Copy to Agent defaults same-machine live MCP transport to this SDK:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.8 start
+npx -y wave3d-agent-sdk@0.2.10 start
 ```
 
 Agents choose topology first:
 
-- Same computer as Wave Studio browser: try copied localhost `MCP_URL`, call `self_check_wave_mcp` with copied `expectedVersion` and `expectedBuildHash`, and restart exact SDK command from Copy to Agent if `self_check_wave_mcp` is missing, SDK is stale, tools are missing, or the SDK prints secrets before fallback. If restart happens after Copy to Agent, preserve MCP_TOKEN with `WAVE3D_MCP_TOKEN="$MCP_TOKEN"` so the new SDK process can authorize that local pairing secret. HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; successful Gateway auth or convenience is not a same-machine fallback reason.
+- Same computer as Wave Studio browser: try copied localhost `MCP_URL`, call `self_check_wave_mcp` with copied `expectedVersion` and `expectedBuildHash`, and run the exact SDK command from Copy to Agent if `self_check_wave_mcp` is missing, SDK is stale, tools are missing, or the SDK prints secrets before fallback. Current SDK starts self-heal stale peers on the same localhost port: it reuses a current same-token SDK, replaces verified stale/different-token SDK peers, and refuses to kill non-SDK port owners. If restart happens after Copy to Agent, preserve MCP_TOKEN with `WAVE3D_MCP_TOKEN="$MCP_TOKEN"` so the SDK process can authorize that local pairing secret. HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; successful Gateway auth or convenience is not a same-machine fallback reason.
 - Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to agent machine instead of user browser machine: use `MCP_HTTP_GATEWAY_FALLBACK_URL` directly. Do not start WaveEngine Agent SDK on wrong machine.
 
 Call `get_wave_mcp_health` (aliases: `mcp_health`, `mcp_status`) whenever transport, SDK, or session status is unclear. It reports endpoint kind, SDK version/build, tool catalog hash/count, paired sessions, and WaveEngine SDK Cache state.
@@ -58,13 +58,13 @@ Use `MCP_HTTP_GATEWAY_FALLBACK_URL` only for topology mismatch, remote/sandboxed
 For unfamiliar authoring, use the local SDK tools:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.8 cache search "continuous left rotation"
+npx -y wave3d-agent-sdk@0.2.10 cache search "continuous left rotation"
 ```
 
 `cache refresh` without MCP arguments reinstalls the bundled SDK into `~/.wave3d/agent-cache`:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.8 cache refresh
+npx -y wave3d-agent-sdk@0.2.10 cache refresh
 ```
 
 Old `cache refresh --mcp-url <url> --token <token>` arguments are ignored. Normal users update the npm package; no separate zip download exists.

package/dist/cli.js

@@ -3,10 +3,12 @@
 // src/cli.ts
 import { mkdir as mkdir3, readFile as readFile2, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { existsSync as existsSync2 } from "node:fs";
-import { createHash as createHash5 } from "node:crypto";
+import { execFile } from "node:child_process";
+import { createHash as createHash6 } from "node:crypto";
 import { homedir as homedir2 } from "node:os";
 import path4 from "node:path";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
 import JSZip from "jszip";
 import MiniSearch2 from "minisearch";
 
@@ -35,10 +37,13 @@ function createWaveGenieError(code, message, details) {
 }
 
 // ../../scripts/wavegenie-sdk/auth.ts
-import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 function createWaveGenieBridgeToken() {
   return randomBytes(24).toString("hex");
 }
+function createWaveGenieBridgeTokenFingerprint(token) {
+  return createHash("sha256").update("waveengine-agent-sdk-local-pairing-secret:").update(token).digest("base64url").slice(0, 16);
+}
 function extractWaveGenieBearerToken(authorizationHeader) {
   if (!authorizationHeader) return null;
   const [scheme, ...rest] = authorizationHeader.trim().split(/\s+/);
@@ -42483,8 +42488,8 @@ function normalizeWaveGenieAssetUploadRequest(request) {
 
 // ../../src/lib/waveStudio/aiAssist/bridge/localAgentSdkContract.ts
 var WAVE3D_AGENT_SDK_PACKAGE_NAME = "wave3d-agent-sdk";
-var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.8";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.3";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.10";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260621.1";
 var WAVE3D_AGENT_SDK_PACKAGE_SPEC = `${WAVE3D_AGENT_SDK_PACKAGE_NAME}@${WAVE3D_AGENT_SDK_REQUIRED_VERSION}`;
 var WAVE3D_AGENT_SDK_START_COMMAND = `npx -y ${WAVE3D_AGENT_SDK_PACKAGE_SPEC} start`;
 var WAVE3D_AGENT_SDK_TOKEN_ENV_VAR = "WAVE3D_MCP_TOKEN";
@@ -44390,7 +44395,7 @@ var WAVE_MCP_AGENT_BRIEF = [
   '0-role. Roleplay lock: you are the Wave Studio authoring agent for this session. Stay in that role, follow Wave authoring strategy, use concrete MCP tools, and briefly confirm "Wave Studio authoring role accepted" after onboarding acceptance.',
   "0. Think in skills, act with tools. `studio.*` names are routing families, not callable tool names; call the real MCP tools listed under each family.",
   "0a. Do not invent MCP tool names. After onboarding, call `tools/list` (or read the returned tool catalog) and use concrete names. Common aliases and safe high-confidence typos are tolerated; destructive/write fuzzy matches require an exact follow-up call. There is no `get_wave_current_project`; use `get_wave_session` for current project/session/active-file context.",
-  `0b. Transport rule: choose topology first. Same-machine agent + same Wave Studio browser computer -> use copied \`MCP_URL\` WaveEngine Agent SDK (\`http://127.0.0.1:47231/mcp\`). On localhost, MCP_TOKEN is a local pairing secret, not account/cloud auth. If localhost is refused/unreachable, start exact SDK \`${WAVE3D_AGENT_SDK_START_COMMAND}\` when your runtime allows shell/Node/npm. If SDK is stale, missing tools, printing secrets, or local 401 follows an SDK restart, stop it and restart while preserving MCP_TOKEN as the local pairing secret with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\`; use the current MCP_TOKEN value without printing it. Then recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, do not use HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; convenience, habit, or successful Gateway auth is not a valid fallback reason. Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine -> use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly, where MCP_TOKEN is an HTTP Gateway bearer. Do not start WaveEngine Agent SDK on the wrong machine.`,
+  `0b. Transport rule: choose topology first. Same-machine agent + same Wave Studio browser computer -> use copied \`MCP_URL\` WaveEngine Agent SDK (\`http://127.0.0.1:47231/mcp\`). On localhost, MCP_TOKEN is a local pairing secret, not account/cloud auth. If localhost is refused/unreachable, start exact SDK \`${WAVE3D_AGENT_SDK_START_COMMAND}\` when your runtime allows shell/Node/npm. If SDK is stale, missing tools, printing secrets, or local 401 follows an SDK restart, run the exact token-preserving command \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\`; use the current MCP_TOKEN value without printing it. Current SDK start self-heals verified stale/different-token SDK peers on localhost and refuses to kill non-SDK port owners. Then recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, do not use HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; convenience, habit, or successful Gateway auth is not a valid fallback reason. Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine -> use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly, where MCP_TOKEN is an HTTP Gateway bearer. Do not start WaveEngine Agent SDK on the wrong machine.`,
   "0b-recovery. If connection/session/onboarding/cache/mirror/timeout state is unclear, call `get_wave_mcp_health` (aliases `mcp_health`, `mcp_status`) first for status, then call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` and follow its `nextAction` exactly. Use recovery after `agent_onboarding_required`, `session_not_found`, `command_timeout`, `command_lease_expired`, `workspace_mirror_not_ready`, `hosted_mcp_proxy_failed`, local/HTTP Gateway fallback confusion, or sleeping-tab symptoms. If local HTTP returns 401 but HTTP Gateway accepts the same MCP_TOKEN, update/restart WaveEngine Agent SDK first. If every endpoint returns 401/bridge_auth_invalid before any tool result, ask user for fresh Copy to Agent.",
   `0c. Cache priorities: Priority 1 is active role/context cache. Keep the role, coding guardrails, authoring workflow, full intent taxonomy (${WAVE_MCP_TASK_INTENT_KIND_VALUES.join(", ")}), Studio tool policy, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context as system-prompt-like rules. Priority 2 is WaveEngine SDK Cache. Production HTTP Gateway/local-SDK onboarding must not claim normal cached success until SDK cache is prepared or explicit accept proof passes. If cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, accept degraded fallback explicitly with \`waveEngineSdkFallbackMode:"studio_ops_only"\` plus \`waveEngineSdkUnavailableReason\` plus \`studioOpsOnlyFallbackAccepted:true\`, and warn user HTTP Gateway is Studio-ops-only and skill/API lookup requires local SDK/cache repair. Keep live transport and retrieval cache separate: \`wave3d-agent-sdk start\` is long-running MCP transport; \`wave3d-agent-sdk cache refresh\` reinstalls the package-bundled SDK locally. Never use cache refresh to switch MCP transport, and never treat cache failure as local transport failure. Use SDK Cache for unfamiliar authoring skill/API lookup when Node/npm/local cache are allowed.`,
   '0d. Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway Studio-operation catalog, then adds local SDK lookup/session-discovery extras. Live-session tools run through the paired browser. Local calls wait directly for browser results. Only call `get_wave_command_result` when a tool response actually includes `status:"pending"` and `requestId`; on local it is normally catalog parity only.',
@@ -44416,7 +44421,7 @@ var WAVE_MCP_AGENT_BRIEF = [
   "VFS hashes: simple edit tools auto-resolve the latest mirror `contentHash`; pass `baseHash` only when you already have it or when using advanced `apply_wave_patch`. Always inspect `changedFiles`, `changedPaths`, `partial`, and `skippedOperations` after edits.",
   "VFS modules: scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Put live object ownership in scene-root/feature files, not shared helpers.",
   'VFS HTML sketches: for diagram/chart/doc-sketch requests, create or edit an exact `.html` file with Studio VFS tools. Mermaid renders from `<div class="mermaid">flowchart TD ...</div>` when that HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Do not put Mermaid in markdown fences unless user specifically wants markdown text.',
-  'VFS hot reload ownership: Studio hot reload targets the active/open edited file when safe. Editing `/main.ts` reloads the main graph; editing a scene-root module reloads that root; bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. In multi-file projects, standalone `hot_reload_wave_preview` follows the active Studio editor file, so do not expect it to reload an arbitrary unopened module by path. Put heavy world loading in bootstrap or a coarse world module. If authored UI in `main.ts` changes bootstrap/world-provider state, store the state and call `waveStudio.reloadPreview({ reason })`; do not call `myScene.hotReload(...)` from Studio-authored code because it bypasses Studio VFS/package/source-patch orchestration. For intentional cross-module live entities, the owner module calls `waveStudio.exportEntity("Name", entity)` and importer modules call `waveStudio.importEntity<T>("Name")`; Studio restores the exported baseline and replays active importer overlays during source hot reload. Source execution order is dependency-driven: exporter roots run before importer roots; an exporter root runs before `main.ts` when main imports it; importer overlays run after exporter/main baseline. Entity names must be static string literals, unique, and acyclic or run/hot reload stops before execution. Keep shared helpers pure or parameterized.',
+  'VFS hot reload ownership: Studio hot reload targets the active/open edited file when safe. Editing `/main.ts` reloads the main graph; editing a scene-root module reloads that root; bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. In multi-file projects, standalone `hot_reload_wave_preview` follows the active Studio editor file, so do not expect it to reload an arbitrary unopened module by path. Put heavy world loading in bootstrap or a coarse world module. Static VFS/package/asset-surface changes can be detected from file/package diffs and Studio may upgrade the tier automatically. Runtime-authored UI state changes cannot be inferred from files; if UI in `main.ts` changes bootstrap/world-provider/runtime-envelope state, store the state and call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`. Do not call `myScene.hotReload(...)` from Studio-authored code because it bypasses Studio VFS/package/source-patch orchestration. For intentional cross-module live entities, the owner module calls `waveStudio.exportEntity("Name", entity)` and importer modules call `waveStudio.importEntity<T>("Name")`; Studio restores the exported baseline and replays active importer overlays during source hot reload. Source execution order is dependency-driven: exporter roots run before importer roots; an exporter root runs before `main.ts` when main imports it; importer overlays run after exporter/main baseline. Entity names must be static string literals, unique, and acyclic or run/hot reload stops before execution. Keep shared helpers pure or parameterized.',
   "Assets: when quoting or passing an existing asset, use typed bare refs in main files: `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, etc. Do not paste raw paths or edit Studio-managed generated files just to register assets. If the exact ref is not already visible, call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`) with required `category` from user intent, semantic `query`, and small `limit` before editing code; category-filtered results can still be capped/truncated, so refine query before concluding absence. Use `list_wave_explorer_assets` only for uploaded library metadata, rename/delete, URL, path, size, or display/ref-name management.",
   "Asset authoring facade split: typed refs quote existing assets; `waveMaterial` authors material handles; `assetManager` is only for exact asset-pipeline/generated-asset APIs that a local SDK skill or API lookup names, such as SDF surfaces or surface ribbons. Do not treat `assetManager` as the default creative facade for materials or normal asset arguments.",
   "Material authoring: when creating, configuring, forking, or intentionally editing material handles, route to `wave.material.authoring` and start from `waveMaterial` (`createWater`, `createGrid`, `createSplatMaterial`, `createFromAsset`, `editAsset`). If a material handle later needs runtime sync, `assetManager` may be passed as the sync target; it is still not the authoring root.",
@@ -44441,7 +44446,7 @@ var WAVE_MCP_AUTHORING_GLOBALS_GUIDE = [
   "- Colors/materials/fx helpers: `COLOR`, `PALETTE`, `waveCOLOR`, `waveMaterial`, `shaderUniform`, `waveFx`, `waveFxPresets`, `FxAnchor`, `FxCondition`.",
   "- Controller movement helpers: `waveKinematicActor`, `netKinematicActor`, `KinematicHumanoidMovementState`, `KinematicVehicleMovementState`, and `KinematicFlightMovementState`. Use actor-level `.asHumanoid(...)`, `.asVehicle(...)`, or `.asFlight(...)` for player/controller movement.",
   "- Asset maps: use category-first refs returned by `find_wave_assets_by_category`, commonly `models`, `gaussianSplats`, `animations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `fonts`, `serializedData`, `terrains`, `fx`, and `particles`.",
-  "- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. If authored UI changes bootstrap/world-provider state and needs the Studio preview to rebuild, call `waveStudio.reloadPreview({ reason })`, not `myScene.hotReload(...)`. `assetManager` is available, but use it only when an exact skill/API names an asset-pipeline or generated-asset factory; do not use it as the default facade for existing asset refs or material authoring. Use lower-level `ctx`, `engine`, or `scene` only when existing code or an exact API requires them.",
+  '- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. If authored UI changes bootstrap/world-provider/runtime-envelope state and needs the Studio preview package to rebuild, call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`, not `myScene.hotReload(...)`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`; use the narrowest true reason. `assetManager` is available, but use it only when an exact skill/API names an asset-pipeline or generated-asset factory; do not use it as the default facade for existing asset refs or material authoring. Use lower-level `ctx`, `engine`, or `scene` only when existing code or an exact API requires them.',
   "- Authoring systems/presets: `waveEventBus`, `waveRig`, `waveValueCurve`, `waveValueCurvePresets`, `waveMotionSignal`, `waveParam`, `WaveParam`, `WaveChoice`, `prefabModels`, `effectPrefabs`, and prefab helpers such as `rocketPrefab`.",
   "- Lowercase constructors: `prop`, `marker`, `sphere`, `point`, `cube`, `box`, `cylinder`, `capsule`, `cone`, `torus`, `plane`, `ground`, `line`, `arc`, `path`, and related shape helpers.",
   "- Type names are not import paths. If the handbook shows a type like `TransformVerbMode` or `WaveRateUnit`, look for the matching bare runtime value such as `Animate` or `DegreesPerSecond` before writing code. Transform `Snapshot` calls return a snapshot builder; call `.take()` before passing the pose to `transitionTo(...)`.",
@@ -44478,11 +44483,11 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   "6b. Asset facade split: passing an existing asset uses typed refs such as `models.X`, `textures.X`, `materials.X`, or `audios.X`; material authoring starts from `waveMaterial`; `assetManager` is reserved for exact low-level generated-asset/asset-pipeline APIs named by a local SDK skill or API lookup. Do not use `assetManager` as the default material, asset-ref, or path-surface authoring root.",
   '7. Use category-first asset discovery before referencing uploaded user assets, project aliases, or ambiguous built-in assets. Preferred tool: `find_wave_assets_by_category`; aliases: `list_wave_assets_by_category`, `search_wave_assets_by_category`, tolerant `list_wave_assets`. Choose category from user intent first, then query: `list_wave_assets_by_category({ category:"materials", query:"grass", limit:50 })`. For sound use `audios`, for 3D objects use `models`, for sky/HDR use `hdr`, for cube-map sky/environment use `cubeMaps`, for images use `textures`. Category-filtered responses can still be capped/truncated; absence there is not absence in the library. Only use asset refs returned by this tool. If the current code already contains the exact ref and the user asks for a small pattern-preserving edit, you may reuse that visible ref.',
   "7a. Use `list_wave_explorer_assets` when you need uploaded asset explorer metadata such as path, URL, size, or display/ref name for rename/delete/library work. It is not a fallback for built-in/public code refs and may be empty while `find_wave_assets_by_category` has many usable refs.",
-  "8. Wave Studio automations: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are automatically managed by Wave Studio and are MCP read-only for agents. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too. Edit bootstrap only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, or `stale_api_update_to_latest`. Never edit bootstrap for `asset_manifest_or_loader`, `instrument_registry`, `scene_registry`, or `execution_manifest`; Studio owns those. Do not edit managed files to register/preload assets, wire scenes, execution order, or force bootstrap sync; write user-authored scene code in `main.ts` or feature modules with bare refs like `models.Robot` or `textures.Grass`, then let Studio sync bootstrap/asset/scene/execution wiring. Hot reload is the normal way to see code changes. If the hot-reload path discovers new asset/bootstrap/scene-surface needs, Studio automatically upgrades the reload tier internally (`patchMain`, `preserveScene`, or hard `rebuildScene`). Only the hard rebuild tier performs a full bundled scene run.",
+  '8. Wave Studio automations: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are automatically managed by Wave Studio and are MCP read-only for agents. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too. Edit bootstrap only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, or `stale_api_update_to_latest`. Never edit bootstrap for `asset_manifest_or_loader`, `instrument_registry`, `scene_registry`, or `execution_manifest`; Studio owns those. Do not edit managed files to register/preload assets, wire scenes, execution order, or force bootstrap sync; write user-authored scene code in `main.ts` or feature modules with bare refs like `models.Robot` or `textures.Grass`, then let Studio sync bootstrap/asset/scene/execution wiring. Hot reload is the normal way to see code changes. Static VFS/package/asset-surface changes can be detected from file/package diffs, so Studio may upgrade the reload tier internally (`patchMain`, `preserveScene`, or hard `rebuildScene`). Runtime-authored UI state changes cannot be inferred from files; when UI changes bootstrap/world-provider/runtime-envelope state, call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })` with the narrowest valid invalidation: `bootstrap`, `world-provider`, or `runtime-envelope`. Only the hard rebuild tier performs a full bundled scene run.',
   "9. Use `waveStudio.*` only for Studio host services. Check `waveStudio.capabilities.assetSave` before save/bake calls.",
   '10. Make deterministic file edits through the simplest fitting tool. Default to forgiving `edit_wave_file`: oldText infers exact replace, startLine/endLine infers line replace, `edits:[{startLine,endLine,text}]` or `edits:[{rangeOffset,rangeLength,text}]` performs one-file multi-edit, and path+text/content with no oldText infers whole-file replace. It is the primary simple edit tool and can omit `baseHash`; Studio resolves the latest hosted VFS mirror contentHash and still applies browser-side stale-write checks. Prefer canonical fields: `path` for file path, `text` for line/whole-file content, and `newText` for text replacement; `filePath`, `replacement`, and `content` are accepted as aliases where useful. Use `apply_wave_patch({ operations: [...] })` for multi-file edits, grouped cross-file edits, unified diffs, or full rewrites; a single bare operation is tolerated for mistake recovery but operations:[...] is preferred. Use `create_wave_file`, `rename_wave_file`, and `delete_wave_file` to split projects into `.ts` modules such as `/actors/player.ts`, `/systems/obstacles.ts`, and `/levels/obby.ts` instead of growing one giant `main.ts`; newly created `.ts/.tsx` files are standalone runnable source roots by default, so top-level scene code in them runs on Run/hot reload. Pass `runnable:false` only for pure helper modules that should not execute on their own. These same VFS tools also create `.html` sketch files for diagrams/charts/docs, with Mermaid rendered from `<div class="mermaid">...</div>` when the HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Studio hot reload targets the active/open edited file when safe: `/main.ts` reloads the whole main graph, scene-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Standalone `hot_reload_wave_preview` has no target path and follows the currently open/active Studio editor file in multi-file projects. A feature file should own the objects, callbacks, promoted GLB parts, and appearance mutations it wants to iterate on. For intentional live entity reuse across modules, the owner calls `waveStudio.exportEntity("Name", entity)` and importers call `waveStudio.importEntity<T>("Name")`; do not pass live entities through shared helper exports. Use exact VFS paths from `list_wave_files`; read target file before writing. `contentHash` is a cooperative stale-write fingerprint, not a security boundary. For advanced compact `apply_wave_patch` operations, pass the latest full-file `contentHash` as `baseHash`: one `lineEdits`, one `textEdits`, one strict `searchReplace`, or one `unifiedDiff`. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops skip as stale. Scoped `read_wave_file` line ranges do not change the `textEdits` offset base; they do pair naturally with line-based edits. Existing-file `writeFile` requires `baseHash` unless `forceOverwrite: true`; force overwrite is only for intentional stale overwrites.',
   "10a. Always inspect `changedFiles`, `changedPaths`, `partial`, `skippedOperations`, `hotReloadRequested`, `hotReloadSkippedReason`, and `runtimeVerification`; treat skipped operations, no-content-change skips, unscheduled hot reloads, runtime verification errors, and `runtimeVerification.diagnostics.editorErrorCount > 0` as work still needing attention.",
-  "11. After the final code edit, default to hot reload. Prefer `awaitHotReload: true` on the edit tool when you want one MCP response with edit result + hot reload + bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` also wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. That hot-reload request may internally upgrade from `patchMain` to `preserveScene` or hard `rebuildScene` when assets/bootstrap/scene surface changed; do not manually force bootstrap sync. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. `pause_wave_preview` and `resume_wave_preview` are direct preview controls mirroring the toolbar pause/resume buttons.",
+  '11. After the final code edit, default to hot reload. Prefer `awaitHotReload: true` on the edit tool when you want one MCP response with edit result + hot reload + bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` also wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. That hot-reload request may internally upgrade from `patchMain` to `preserveScene` or hard `rebuildScene` when assets/bootstrap/scene surface changed; do not manually force bootstrap sync. Runtime-authored UI that changes bootstrap/world-provider/runtime-envelope state must call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })` because Studio cannot infer that from static file diffs. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. `pause_wave_preview` and `resume_wave_preview` are direct preview controls mirroring the toolbar pause/resume buttons.',
   '12. After run/hot reload, use returned `runtimeVerification` when present; otherwise call `get_wave_runtime_diagnostics` repeatedly until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`. Use `previewExecutionPhase` to distinguish Studio preparing work from the preview iframe executing it. `isRunning` is only the Studio scheduling flag, not the final runtime completion gate. If the edit/runtime tool returned `requestedAt` or `runtimeActionRequestedAt`, ignore diagnostics whose `lastRuntimeOutcomeAt` is older than that timestamp. Treat `latestError` as current only when `lastRuntimeOutcome` is `error`; older error lines can remain in returned logs as history. Treat `editorErrorCount > 0` as blocking Monaco/linter/compile failure and read `editorDiagnostics` before claiming success, even when `lastRuntimeOutcome` is `success`. If `lastRuntimeOutcome` is `success` and `editorErrorCount` is 0, verify visually with `capture_wave_screenshot({ resolution: "L" })` or structurally with `get_wave_runtime_entity_snapshot({ variableName, filePath? })` instead of declaring failure from old log text. Same-machine screenshots usually return `localPath`; hosted screenshots return exact field `dataBase64`, not `imageBase64`.',
   "12a. Marker waypoint workflow: when the human asks to use preview marking tools such as `clickToMark()`, route with `marker.use` plus the code/project intent, then call `list_wave_runtime_markers`. Treat marker records as runtime observation data, write marker `worldPosition`/`worldRotation` into the appropriate path/waypoint/placement code, hot reload, and verify with screenshot or marker re-read. One marker read may happen before routing only when needed to decide the code intent. Use path/placement skills only when current code does not reveal the marker-to-code pattern.",
   `13. To use locally generated assets in code, prefer \`create_wave_asset_upload\` for local files when available: pass assetKind from the Wave Studio upload policy SSOT (${getWaveStudioBridgeAssetUploadKindHelpText()}), stat the file first, pass exact byte size, get \`uploadUrl\` + \`uploadHeaders\`, upload raw bytes with plain HTTP PUT using every returned header exactly, keep \`clientToken\`/\`uploadHeaders.Authorization\` out of logs, call \`get_wave_asset_upload_status\` until \`receivedBytes === sizeBytes\`, then call \`commit_wave_asset_upload\` with the same uploadId, assetKind, filename, contentType, and sizeBytes from the create response. No local Python, Vercel package, or Blob SDK is required. On hosted MCP this uses hosted temporary object storage; on same-machine local MCP it uses the local SDK as temporary staging. If direct upload is unavailable, use \`stage_wave_asset_upload_chunk\` plus \`commit_wave_asset_chunk_upload\`: omit uploadId only for chunkIndex 0, then reuse the returned uploadId for every later chunk and for commit. Use \`upload_wave_asset\` with exactly one of \`dataBase64\` or \`dataUrl\` only for small inline assets. If staging is abandoned before commit, call \`abort_wave_asset_upload\` with the uploadId. Do not abort after commit returns pending or completed; the Studio browser cleans committed staging after execution. Hosted MCP cannot read local filesystem paths through inline upload. All flows stage bytes outside the command queue, cap staged bytes at 300 MB, and return \`asset.bareRef\`, for example \`textures.Albedo\`, \`cubeMaps.Studio\`, \`materials.Wood\`, \`audios.Click\`, \`models.Robot\`, \`animations.Run\`, \`fonts.Title\`, or \`serializedData.Config\`. If the name already exists, the upload result returns \`skipped: true\` and the existing asset. Staged chunks/blobs are also swept lazily after about 24 hours. Model-family uploads enable meshoptimizer by default unless \`useMeshoptimizer\` is false.`,
@@ -44633,7 +44638,7 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "- MCP names: HTTP Gateway = Next/Vercel endpoint for remote/sandbox Studio operations; WaveEngine Agent SDK = same-machine live MCP transport from long-running `wave3d-agent-sdk start`; WaveEngine SDK Cache = package-bundled local skill/API docs retrieval; VFS Mirror = HTTP Gateway workspace snapshot. Do not confuse these modules. On same machine, HTTP Gateway is degraded fallback only after SDK cannot run/update/adopt; do not choose it because it is already reachable or easier.",
   "- MCP recovery: when connection/session/onboarding/cache/mirror/timeout state is unclear, call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` first and follow its returned `nextAction`. This is the explicit recovery path for sleeping tabs, local/HTTP Gateway confusion, mirror-not-ready, onboarding-required, command timeout/lease expiry, and hosted proxy/cache failures.",
   '- Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway Studio-operation catalog, then adds local SDK lookup/session-discovery extras. Direct local live-session tools include VFS edits, assets/uploads, project save/open/new/read/share, preview run/hot reload/pause/resume, diagnostics, performance, screenshots, entity snapshots, and runtime markers. Local browser-backed calls wait directly for browser results. Only call `get_wave_command_result` if a tool returns `status:"pending"` plus `requestId`; on local it normally exists only for catalog parity and reports no local pending-command queue.',
-  `- MCP topology: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints secrets; after restart recheck /health and tools/list. If restart happens after Copy-to-Agent, preserve MCP_TOKEN with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it, otherwise the new SDK may be healthy but unable to authorize the copied local pairing secret. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly; starting WaveEngine Agent SDK there binds localhost beside the agent, not beside the user browser. Stale SDK/cache are not reasons to use HTTP Gateway fallback; wrong-machine localhost is a topology mismatch.`,
+  `- MCP topology: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints secrets; after restart recheck /health and tools/list. If restart happens after Copy-to-Agent, preserve MCP_TOKEN with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it, otherwise the SDK may be healthy but unable to authorize the copied local pairing secret. Current SDK start reuses a current same-token peer, replaces verified stale/different-token SDK peers on localhost, and refuses to kill non-SDK port owners. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly; starting WaveEngine Agent SDK there binds localhost beside the agent, not beside the user browser. Stale SDK/cache are not reasons to use HTTP Gateway fallback; wrong-machine localhost is a topology mismatch.`,
   `- MCP cache priorities: Priority 1 is active role/context cache: keep role, guardrails, authoring workflow, asset/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context. Priority 2 is WaveEngine SDK Cache: production HTTP Gateway/local-SDK onboarding must not claim normal cached success until SDK cache is prepared or accept proof passes. If accept returns \`wave_engine_sdk_cache_not_ready\`, update/restart \`wave3d-agent-sdk\` or run \`${WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE}\`, then retry accept. If local cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly accept degraded fallback with \`waveEngineSdkFallbackMode:"studio_ops_only"\`, a valid \`waveEngineSdkUnavailableReason\`, and \`studioOpsOnlyFallbackAccepted:true\`; warn user HTTP Gateway is Studio-ops-only and skill/API lookup requires local SDK/cache repair. This cache command reinstalls the package-bundled SDK locally; it is not WaveEngine Agent SDK transport. Never run it to switch MCP transport; never treat cache failure as local transport failure.`,
   "- Main-file globals include `myScene`, `assetManager`, `waveEngine`, `waveStudio`, and direct asset maps such as `models`, `gaussianSplats`, `textures`, `materials`, `animations`, `audios`, `hdr`, `cubeMaps`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`. Availability is not endorsement: choose the intent-owned facade/skill before using a global.",
   `- Bare authoring globals: common examples include ${WAVE_AUTHORING_COMMON_GLOBAL_EXAMPLES_TEXT}, \`waveMaterial\`, \`waveFx\`, \`waveValueCurve\`, and \`waveParam\`. Use them directly in \`main.ts\`; do not import or namespace-qualify them. If the task is unfamiliar, retrieve the relevant local-SDK \`wave.*\` skill first; for the full generated exact-global surface, call local-SDK \`query_wave_api\`.`,
@@ -44659,7 +44664,7 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "- `waveStudio.saveFor3dPrinting(target, options?)`: save export-friendly model.",
   "- `waveStudio.saveMaterial(request)`: save authored material asset.",
   "- `waveStudio.bakeTerrainMaterial(request)`: bake terrain material textures.",
-  "- `waveStudio.reloadPreview({ reason? })`: request the Wave Studio toolbar-style reload path from authored code. Use this when a UI authored in `main.ts` changes Studio/bootstrap-backed state such as active city/world provider and must re-run the Studio preview package. Do not call `myScene.hotReload(...)` from Studio-authored code for this; that bypasses Studio VFS/package/source-patch orchestration.",
+  '- `waveStudio.reloadPreview({ reason?, invalidates? })`: request the Wave Studio toolbar-style reload path from authored code. Use `invalidates: ["world-provider"]` when UI authored in `main.ts` changes Studio/bootstrap-backed runtime state such as active city/world provider and must rebuild the Studio preview package. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`; use the narrowest true reason. Do not call `myScene.hotReload(...)` from Studio-authored code for this; that bypasses Studio VFS/package/source-patch orchestration.',
   "- `waveStudio.exportEntity(name, entity)`: declare a live entity owned by the current source module for intentional modular reuse. `name` must be a static string literal and unique across runnable roots.",
   "- `waveStudio.importEntity<T>(name)`: import an exported live entity into the current source module; Studio restores the exporter baseline and prunes/replays importer callbacks/overlays during source hot reload. Studio orders source roots by export/import dependencies: exporter before importer; exporter before `main.ts` if main imports it; overlay importers after exporter/main baseline. Missing, duplicate, dynamic, or cyclic entity names stop run/hot reload before execution.",
   '- MCP command result rule: poll `get_wave_command_result({ requestId })` only when the previous tool response includes `status:"pending"` plus `requestId`. HTTP Gateway browser-backed tools may return pending and need that poll. WaveEngine Agent SDK browser-backed tools wait directly and return final results; its `get_wave_command_result` is a catalog-parity no-op unless a pending result was explicitly returned.',
@@ -44677,7 +44682,7 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "- `get_wave_coding_guardrails`: call after onboarding acceptance; returns policy, file context, tool catalog, and recipes.",
   '- `get_wave_mcp_health` (aliases `mcp_health`, `mcp_status`): read-only self diagnostic for endpoint kind, SDK version/build, tool catalog hash/count, onboarding, session/VFS, and WaveEngine SDK Cache state. Use when the agent asks "am I local/cloud/current/cached?" or any MCP state is unclear.',
   "- `get_wave_tool_map`: stable complete concrete MCP tool menu grouped by family plus policy flags. Use only when `tools/list` feels truncated or unclear.",
-  `- Transport topology rule: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints secrets; after Copy-to-Agent, restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it so the copied local pairing secret still works. After restart recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; never use it because it is familiar, already authenticated, or avoids SDK repair. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Stale SDK/cache are local setup issues, not fallback triggers; wrong-machine localhost is a topology mismatch.`,
+  `- Transport topology rule: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints secrets; after Copy-to-Agent, restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it so the copied local pairing secret still works. Current SDK start self-heals localhost SDK peers: reuse current same-token, replace verified stale/different-token SDK, refuse non-SDK port owners. After restart recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; never use it because it is familiar, already authenticated, or avoids SDK repair. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Stale SDK/cache are local setup issues, not fallback triggers; wrong-machine localhost is a topology mismatch.`,
   "- `recover_wave_connection`: direct Observe recovery tool. Call after onboarding required, session missing, command timeout/lease expired, mirror not ready, hosted proxy/cache failure, local/HTTP Gateway confusion, or sleeping-tab symptoms. It returns exact next action: re-onboard, get session, wake tab, update/restart SDK, wait mirror, retry, use HTTP Gateway fallback, or ask fresh Copy to Agent.",
   '- WaveEngine SDK Cache: normal skill/API lookup lives inside the local `wave3d-agent-sdk` SDK package. Update/restart SDK when SDK is stale or missing. HTTP Gateway is Studio-ops-only and does not provide cloud skill/API lookup. If local SDK cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly accept degraded fallback with `waveEngineSdkFallbackMode:"studio_ops_only"`, a valid `waveEngineSdkUnavailableReason`, and `studioOpsOnlyFallbackAccepted:true`; warn user skill/API lookup requires local SDK repair. This is retrieval cache, not WaveEngine Agent SDK transport. Never treat SDK cache failure as local transport failure. Keep Priority 1 role, guardrails, workflow, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context.',
   "- Work-mode rule: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose routes through `start_wave_task`; General avoids Wave tools. Operate tools include run/hot reload, save/share, VFS create/rename/delete exact files, asset upload/rename/delete exact assets, new project, project rename, and open project by exact projectId.",
@@ -44849,7 +44854,7 @@ var LOCAL_MCP_AGENT_ONBOARDING_PROMPT = [
   `The WaveEngine Agent SDK answers skill/API/guardrail tools from the bundled WaveEngine SDK Cache. The SDK ships inside \`wave3d-agent-sdk\`; \`start\`, \`cache status\`, and \`cache search\` auto-prepare it locally. During \`accept_wave_agent_onboarding\`, production/HTTP-Gateway pairings must verify this local SDK cache before normal success. If missing, stale, or unverified, accept returns \`wave_engine_sdk_cache_not_ready\`; update/restart the exact SDK package or run the local bundled repair command \`${WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE}\`, then retry accept. If the agent is sandboxed, has no filesystem/Node/npm, or user refuses local SDK/cache, explicitly accept degraded Studio-ops-only fallback with \`waveEngineSdkFallbackMode:"studio_ops_only"\`, a valid \`waveEngineSdkUnavailableReason\`, and \`studioOpsOnlyFallbackAccepted:true\`; warn user HTTP Gateway can still do VFS/assets/project/preview/capture, but exact API lookup is unavailable until local SDK works. Keep the exact SDK command in active context as \`waveEngineSdkCacheCommandCached\`. Use local skill onion retrieval: \`list_wave_skill_families\` -> choose family ids -> \`query_wave_skills\` with \`families\`/\`familyId\` -> \`get_wave_skill\` -> \`query_wave_api\` only for exact signature/global/value uncertainty. HTTP Gateway is not an API lookup fallback.`,
   "",
   "Mandatory phased handshake:",
-  `Phase 0 WaveEngine Agent SDK preflight is not optional. Do these phases in order before user work: 1 initialize endpoint; 2 call \`self_check_wave_mcp\` with the exact \`expectedVersion\` and \`expectedBuildHash\` from Copy-to-Agent; hard-stop if stale/hardStop is true or tool count/hash looks missing, then restart SDK while preserving the copied MCP_TOKEN/local pairing secret with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden; same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt, never because Gateway is familiar/easier; 2a when status is unclear, call \`get_wave_mcp_health\`/\`mcp_status\` to read endpoint/SDK/tool/SDK/session state; 3 call \`get_wave_agent_onboarding\` and cache Priority 1 rules in active context; 4 call \`accept_wave_agent_onboarding\` with acceptedRole true, current promptVersion/promptHash, all required cachedSections, full intentKindsCached list, exact waveEngineSdkCacheCommandCached template, and every context-cache confirmation true; if it returns \`wave_engine_sdk_cache_not_ready\`, update/restart SDK or run the bundled SDK repair command and retry accept; if local SDK cannot work, explicitly accept Studio-ops-only fallback and do not do unfamiliar API authoring; 5 call \`tools/list\` and prefer concrete tool names from the returned catalog; 6 call \`get_wave_session\`; 7 call \`list_wave_files\`; 8 if the tool menu is unclear, call \`get_wave_tool_map\`. Observe tools such as file reads, assets, diagnostics, screenshots, snapshots, performance, and markers stay open. Operate tools such as run preview, hot reload, save/share/rename/open/new project, VFS create/rename/delete, and asset upload/rename/delete are direct Studio commands when the user asks for that operation. Author/Diagnose tools such as \`query_wave_api\`, \`edit_wave_file\`, \`apply_wave_patch\`, and code behavior changes use \`start_wave_task\`. After startup, report phase status briefly. If a required phase fails or any later MCP state is unclear, call \`get_wave_mcp_health\` for state and \`recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })\` for nextAction before asking user for a fresh copy; do not skip ahead.`,
+  `Phase 0 WaveEngine Agent SDK preflight is not optional. Do these phases in order before user work: 1 initialize endpoint; 2 call \`self_check_wave_mcp\` with the exact \`expectedVersion\` and \`expectedBuildHash\` from Copy-to-Agent; hard-stop if stale/hardStop is true or tool count/hash looks missing, then run the SDK while preserving the copied MCP_TOKEN/local pairing secret with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden; current SDK start reuses a current same-token peer, replaces verified stale/different-token SDK peers on localhost, and refuses to kill non-SDK port owners; same-machine HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt, never because Gateway is familiar/easier; 2a when status is unclear, call \`get_wave_mcp_health\`/\`mcp_status\` to read endpoint/SDK/tool/SDK/session state; 3 call \`get_wave_agent_onboarding\` and cache Priority 1 rules in active context; 4 call \`accept_wave_agent_onboarding\` with acceptedRole true, current promptVersion/promptHash, all required cachedSections, full intentKindsCached list, exact waveEngineSdkCacheCommandCached template, and every context-cache confirmation true; if it returns \`wave_engine_sdk_cache_not_ready\`, update/restart SDK or run the bundled SDK repair command and retry accept; if local SDK cannot work, explicitly accept Studio-ops-only fallback and do not do unfamiliar API authoring; 5 call \`tools/list\` and prefer concrete tool names from the returned catalog; 6 call \`get_wave_session\`; 7 call \`list_wave_files\`; 8 if the tool menu is unclear, call \`get_wave_tool_map\`. Observe tools such as file reads, assets, diagnostics, screenshots, snapshots, performance, and markers stay open. Operate tools such as run preview, hot reload, save/share/rename/open/new project, VFS create/rename/delete, and asset upload/rename/delete are direct Studio commands when the user asks for that operation. Author/Diagnose tools such as \`query_wave_api\`, \`edit_wave_file\`, \`apply_wave_patch\`, and code behavior changes use \`start_wave_task\`. After startup, report phase status briefly. If a required phase fails or any later MCP state is unclear, call \`get_wave_mcp_health\` for state and \`recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })\` for nextAction before asking user for a fresh copy; do not skip ahead.`,
   "Tool-name tolerance: concrete names from tools/list remain preferred. Common aliases and safe high-confidence typos are tolerated. Destructive/write fuzzy matches return did-you-mean instead of executing.",
   "Glossary: WaveEngine Agent SDK = same-machine live MCP transport plus bundled SDK lookup; Local Pairing Secret = MCP_TOKEN on localhost, not account/cloud auth; HTTP Gateway Bearer = MCP_TOKEN on HTTP Gateway; WaveEngine SDK Cache = package-bundled public docs/API/skill retrieval; MCP Session = browser pairing state; VFS Mirror = HTTP Gateway read/edit hash snapshot; Project = user workspace content. Do not merge these concepts.",
   "",
@@ -44877,7 +44882,7 @@ var LOCAL_MCP_AGENT_ONBOARDING_PROMPT = [
 ].join("\n");
 
 // ../../scripts/wavegenie-sdk/mcp/referenceTools.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -45262,7 +45267,7 @@ function isLocalCorpusManifest(value) {
   return isRecord2(value) && typeof value.version === "string" && (typeof value.formatVersion === "undefined" || typeof value.formatVersion === "string") && typeof value.cacheKey === "string" && typeof value.bundleFileName === "string" && typeof value.bundleHash === "string" && (typeof value.generatedAt === "undefined" || typeof value.generatedAt === "string") && (typeof value.sourceVersions === "undefined" || isRecord2(value.sourceVersions)) && Array.isArray(value.files) && value.files.every(isLocalCorpusFileManifestEntry);
 }
 function corpusFileHash(content) {
-  return createHash("sha256").update(JSON.stringify(content)).digest("base64url").slice(0, 32);
+  return createHash2("sha256").update(JSON.stringify(content)).digest("base64url").slice(0, 32);
 }
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map((item) => stableJson(item)).join(",")}]`;
@@ -46194,7 +46199,7 @@ var HOT_RELOAD_UNSAFE_SCENE_EVENT_CALLBACKS = /* @__PURE__ */ new Map([
   ["once", "myScene.once(...) is scene-scoped, but an unfired one-shot handler can survive preserve-scene hotreload. Use Wave-owned input/entity callbacks, or wait for a scoped Wave scene-event authoring API."]
 ]);
 var HOT_RELOAD_FORBIDDEN_STUDIO_SCENE_METHODS = /* @__PURE__ */ new Map([
-  ["hotReload", 'Studio-authored code must not call myScene.hotReload(...). Use waveStudio.reloadPreview({ reason: "..." }) so Wave Studio can flush VFS, rebuild the project package/bootstrap, sync assets, choose the correct reload tier, and return diagnostics.']
+  ["hotReload", 'Studio-authored code must not call myScene.hotReload(...). Use waveStudio.reloadPreview({ reason: "...", invalidates: ["world-provider"] }) when authored UI changes bootstrap/world-provider/runtime-envelope state so Wave Studio can flush VFS, rebuild the project package/bootstrap, sync assets, choose the correct reload tier, and return diagnostics.']
 ]);
 var HOT_RELOAD_UNSAFE_CONSTRUCTORS = /* @__PURE__ */ new Map([
   ["Promise", "new Promise(...) is not hotreload-safe because it creates unmanaged callback closures. Use awaitable Wave APIs instead."],
@@ -47429,7 +47434,7 @@ async function handleVfsTool(input) {
 }
 
 // ../../scripts/wavegenie-sdk/mcp/toolDefinitions.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 
 // ../../src/lib/waveStudio/authoring/workspace/vfs/vfsImportAnalysis.ts
 var VFS_CODE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
@@ -49764,7 +49769,7 @@ function getLocalToolCatalogHash() {
     description: definition.description,
     inputSchema: definition.inputSchema
   })).sort((left, right) => left.name.localeCompare(right.name));
-  return createHash2("sha256").update(JSON.stringify(tools)).digest("base64url").slice(0, 24);
+  return createHash3("sha256").update(JSON.stringify(tools)).digest("base64url").slice(0, 24);
 }
 
 // ../../scripts/wavegenie-sdk/mcp.ts
@@ -49963,7 +49968,7 @@ function localConnectionRecoveryResult(args, context) {
     nextAction = "Wave Studio tab is paired but not actively polling commands, or browser-backed command timed out. Ask user to focus/wake the tab and verify MCP is live; retry the same tool once on the same local endpoint and MCP_TOKEN pairing secret.";
     nextTool = failedTool || "get_wave_session";
     requiresUserAction = true;
-    steps.push(`If SDK /health is down before pairing, start \`${WAVE3D_AGENT_SDK_START_COMMAND}\`; after Copy-to-Agent, restart stale SDK with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden. If /health is OK and version matches Copy to Agent, do not restart SDK first.`);
+    steps.push(`If SDK /health is down before pairing, start \`${WAVE3D_AGENT_SDK_START_COMMAND}\`; after Copy-to-Agent, run \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden. Current SDK start self-heals verified stale/different-token SDK peers and refuses non-SDK port owners. If /health is OK and version/token match Copy to Agent, do not restart SDK first.`);
   } else if (lastErrorCode === "session_write_not_allowed" || selectedSession?.accessMode !== "readwrite") {
     state = "write_access_not_ready";
     nextAction = "Read tools can continue. For write/run/hot reload, user must make the Studio MCP session read-write/adopt WaveEngine Agent SDK, then retry same local endpoint and MCP_TOKEN pairing secret or paste fresh Copy to Agent if the secret changed.";
@@ -50023,7 +50028,7 @@ function localConnectionRecoveryResult(args, context) {
     steps,
     hardStopRules: [
       "Local HTTP refused/unreachable before MCP response: start WaveEngine Agent SDK, retry localhost for up to 10 seconds.",
-      "Local HTTP 401/bridge_auth_invalid: if HTTP Gateway accepts the same MCP_TOKEN, SDK is stale/not adopted: restart exact WaveEngine Agent SDK so it adopts MCP_TOKEN as the local pairing secret, then retry local. If every endpoint rejects MCP_TOKEN, ask user for fresh Copy to Agent.",
+      "Local HTTP 401/bridge_auth_invalid: if HTTP Gateway accepts the same MCP_TOKEN, SDK is stale/not adopted: run the exact token-preserving WaveEngine Agent SDK command so it adopts MCP_TOKEN as the local pairing secret, then retry local. If every endpoint rejects MCP_TOKEN, ask user for fresh Copy to Agent.",
       "No paired session or stale command poll: wake/reopen Wave Studio tab; keep same local endpoint and MCP_TOKEN pairing secret first.",
       "WaveEngine SDK Cache failure is not live transport failure."
     ]
@@ -51378,7 +51383,7 @@ async function handleWaveGenieMcpRequest(request, context) {
 }
 
 // ../../scripts/wavegenie-sdk/sessionRegistry.ts
-import { createHash as createHash3, randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
+import { createHash as createHash4, randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
 function createSessionId() {
   return `wgb_${randomUUID2()}`;
 }
@@ -51386,7 +51391,7 @@ function nowIso2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function hashAgentToken(token) {
-  return createHash3("sha256").update(token).digest("hex");
+  return createHash4("sha256").update(token).digest("hex");
 }
 function tokenHashMatches(left, right) {
   const leftBuffer = Buffer.from(left, "hex");
@@ -51520,7 +51525,7 @@ var WaveGenieBridgeSessionRegistry = class {
 };
 
 // ../../scripts/wavegenie-sdk/assetStaging.ts
-import { createHash as createHash4, randomBytes as randomBytes2, randomUUID as randomUUID3 } from "node:crypto";
+import { createHash as createHash5, randomBytes as randomBytes2, randomUUID as randomUUID3 } from "node:crypto";
 import { createWriteStream } from "node:fs";
 import { mkdir as mkdir2, rm, writeFile as writeFile2 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
@@ -51537,7 +51542,7 @@ function createSecret() {
   return randomBytes2(24).toString("base64url");
 }
 function hashPathPart(value) {
-  return createHash4("sha256").update(value).digest("hex").slice(0, 20);
+  return createHash5("sha256").update(value).digest("hex").slice(0, 20);
 }
 function decodeBase64(dataBase64) {
   const normalized = dataBase64.trim();
@@ -51997,8 +52002,10 @@ async function startWaveEngineAgentSdkServer(options = {}) {
           bridgeId,
           version: MCP_SERVER_VERSION,
           packageVersion: MCP_SERVER_VERSION,
+          processId: process.pid,
           protocolVersion: "waveengine-agent-sdk-http-v1",
           buildHash: WAVE3D_AGENT_SDK_REQUIRED_BUILD,
+          tokenFingerprint: createWaveGenieBridgeTokenFingerprint(token),
           requiredPackage: WAVE3D_AGENT_SDK_PACKAGE_SPEC,
           requiredVersion: WAVE3D_AGENT_SDK_REQUIRED_VERSION,
           requiredBuildHash: WAVE3D_AGENT_SDK_REQUIRED_BUILD,
@@ -52285,6 +52292,7 @@ var BUNDLED_SDK_DIR_NAME = "sdk";
 var MAX_CORPUS_ZIP_BYTES2 = 50 * 1024 * 1024;
 var MAX_CORPUS_EXTRACTED_BYTES2 = 100 * 1024 * 1024;
 var MAX_CORPUS_FILE_COUNT = 5e3;
+var execFileAsync = promisify(execFile);
 function parseArgs(argv) {
   const flags = /* @__PURE__ */ new Map();
   const positionals = [];
@@ -52382,6 +52390,277 @@ function requireSafePathSegment(value, label) {
 function isRecord4(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function formatLoopbackHttpUrl(host, port, pathname) {
+  const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `http://${urlHost}:${port}${pathname}`;
+}
+function readNumberProperty(record, name) {
+  const value = record[name];
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function readStringProperty(record, name) {
+  const value = record[name];
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readLocalSdkPeerHealth(value) {
+  if (!isRecord4(value)) return null;
+  const data = isRecord4(value.data) ? value.data : value;
+  const bridgeId = readStringProperty(data, "bridgeId");
+  const protocolVersion = readStringProperty(data, "protocolVersion");
+  const isCurrentSdkProtocol = protocolVersion === "waveengine-agent-sdk-http-v1";
+  if (!bridgeId || !bridgeId.startsWith("wgbridge_") || !isCurrentSdkProtocol) {
+    return null;
+  }
+  return {
+    bridgeId,
+    packageVersion: readStringProperty(data, "packageVersion"),
+    protocolVersion,
+    buildHash: readStringProperty(data, "buildHash"),
+    processId: readNumberProperty(data, "processId"),
+    tokenFingerprint: readStringProperty(data, "tokenFingerprint")
+  };
+}
+function parseProcessIds(output) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const match of output.matchAll(/\b\d+\b/g)) {
+    const pid = Number(match[0]);
+    if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) ids.add(pid);
+  }
+  return [...ids];
+}
+async function execProcessIdCommand(command, args) {
+  try {
+    const { stdout } = await execFileAsync(command, args, {
+      timeout: 2500,
+      maxBuffer: 128 * 1024,
+      windowsHide: true
+    });
+    return parseProcessIds(stdout);
+  } catch {
+    return [];
+  }
+}
+async function findListenerProcessIds(port) {
+  if (process.platform === "win32") {
+    return execProcessIdCommand("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `(Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess | Sort-Object -Unique) -join "
+"`
+    ]);
+  }
+  return execProcessIdCommand("lsof", ["-nP", `-tiTCP:${port}`, "-sTCP:LISTEN"]);
+}
+async function readProcessInfo(pid) {
+  if (pid === process.pid) return null;
+  try {
+    if (process.platform === "win32") {
+      const { stdout: stdout2 } = await execFileAsync("powershell.exe", [
+        "-NoProfile",
+        "-Command",
+        `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" | Select-Object ProcessId,ParentProcessId,CommandLine | ConvertTo-Json -Compress)`
+      ], {
+        timeout: 2500,
+        maxBuffer: 128 * 1024,
+        windowsHide: true
+      });
+      const parsed = JSON.parse(stdout2);
+      if (!isRecord4(parsed)) return null;
+      const parsedPid = readNumberProperty(parsed, "ProcessId");
+      const parentPid = readNumberProperty(parsed, "ParentProcessId");
+      const command = readStringProperty(parsed, "CommandLine");
+      if (!parsedPid || !parentPid || !command) return null;
+      return { pid: parsedPid, parentPid, command };
+    }
+    const { stdout } = await execFileAsync("ps", [
+      "-o",
+      "pid=",
+      "-o",
+      "ppid=",
+      "-o",
+      "command=",
+      "-p",
+      String(pid)
+    ], {
+      timeout: 2500,
+      maxBuffer: 128 * 1024,
+      windowsHide: true
+    });
+    const match = stdout.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+    if (!match) return null;
+    return {
+      pid: Number(match[1]),
+      parentPid: Number(match[2]),
+      command: match[3]
+    };
+  } catch {
+    return null;
+  }
+}
+async function findChildProcessIds(parentPid) {
+  if (parentPid <= 0 || parentPid === process.pid) return [];
+  if (process.platform === "win32") {
+    return execProcessIdCommand("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `(Get-CimInstance Win32_Process -Filter "ParentProcessId = ${parentPid}" | Select-Object -ExpandProperty ProcessId | Sort-Object -Unique) -join "
+"`
+    ]);
+  }
+  try {
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=", "-o", "ppid="], {
+      timeout: 2500,
+      maxBuffer: 512 * 1024,
+      windowsHide: true
+    });
+    const ids = [];
+    for (const line of stdout.split("\n")) {
+      const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+      if (!match) continue;
+      const pid = Number(match[1]);
+      const ppid = Number(match[2]);
+      if (ppid === parentPid && pid !== process.pid) ids.push(pid);
+    }
+    return ids;
+  } catch {
+    return [];
+  }
+}
+function isWaveEngineAgentProcessCommand(command) {
+  return /\bwave3d-agent-sdk\b/.test(command);
+}
+async function collectVerifiedSdkPeerProcessIds(seedPids) {
+  const targetPids = /* @__PURE__ */ new Set();
+  const parentPids = /* @__PURE__ */ new Set();
+  for (const seedPid of seedPids) {
+    if (seedPid <= 0 || seedPid === process.pid) continue;
+    targetPids.add(seedPid);
+    const processInfo = await readProcessInfo(seedPid);
+    if (!processInfo) continue;
+    if (isWaveEngineAgentProcessCommand(processInfo.command)) {
+      for (const childPid of await findChildProcessIds(processInfo.pid)) targetPids.add(childPid);
+    }
+    if (processInfo.parentPid > 1 && processInfo.parentPid !== process.pid) {
+      const parentInfo = await readProcessInfo(processInfo.parentPid);
+      if (parentInfo && isWaveEngineAgentProcessCommand(parentInfo.command)) {
+        parentPids.add(parentInfo.pid);
+        for (const childPid of await findChildProcessIds(parentInfo.pid)) targetPids.add(childPid);
+      }
+    }
+  }
+  for (const parentPid of parentPids) targetPids.delete(parentPid);
+  return [...parentPids, ...targetPids].filter((pid) => pid !== process.pid);
+}
+async function readLocalSdkPeerProbe(host, port) {
+  const healthUrl = formatLoopbackHttpUrl(host, port, "/health");
+  let response;
+  try {
+    response = await fetch(healthUrl, { signal: AbortSignal.timeout(1500) });
+  } catch {
+    return { kind: "none" };
+  }
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch {
+    return {
+      kind: "non-sdk",
+      message: `Port ${port} is occupied by an HTTP server, but /health did not return JSON.`
+    };
+  }
+  const health = readLocalSdkPeerHealth(parsed);
+  if (!health) {
+    return {
+      kind: "non-sdk",
+      message: `Port ${port} is occupied, but /health is not a WaveEngine Agent SDK health response.`
+    };
+  }
+  return { kind: "sdk", health };
+}
+function isCurrentSdkPeer(health) {
+  return health.packageVersion === WAVE3D_AGENT_SDK_REQUIRED_VERSION && health.buildHash === WAVE3D_AGENT_SDK_REQUIRED_BUILD;
+}
+function shouldReplaceCurrentSdkPeer(health, token) {
+  if (!isCurrentSdkPeer(health)) return true;
+  if (!token) return false;
+  const expectedFingerprint = createWaveGenieBridgeTokenFingerprint(token);
+  return health.tokenFingerprint !== expectedFingerprint;
+}
+async function waitForSdkPeerExit(pids, deadlineMs) {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    const alive = pids.some((pid) => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    if (!alive) return true;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return false;
+}
+async function waitForSdkPeerPortRelease(port, deadlineMs) {
+  const deadline = Date.now() + deadlineMs;
+  while (Date.now() < deadline) {
+    const listenerPids = await findListenerProcessIds(port);
+    if (listenerPids.every((pid) => pid === process.pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return false;
+}
+async function terminateVerifiedSdkPeer(health, port) {
+  const seedPids = /* @__PURE__ */ new Set();
+  if (health.processId && health.processId !== process.pid) seedPids.add(health.processId);
+  for (const pid of await findListenerProcessIds(port)) seedPids.add(pid);
+  if (seedPids.size === 0) {
+    if (await waitForSdkPeerPortRelease(port, 250)) return;
+    throw new Error(`WaveEngine Agent SDK peer on port ${port} is stale, but no listener PID could be found.`);
+  }
+  let targetPids = await collectVerifiedSdkPeerProcessIds([...seedPids]);
+  if (targetPids.length === 0) {
+    throw new Error("Refusing to terminate current SDK process.");
+  }
+  for (const pid of targetPids) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+    }
+  }
+  const exitedAfterTerm = await waitForSdkPeerExit(targetPids, 2500);
+  if (exitedAfterTerm && await waitForSdkPeerPortRelease(port, 1500)) return;
+  targetPids = await collectVerifiedSdkPeerProcessIds(await findListenerProcessIds(port));
+  for (const pid of targetPids) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+    }
+  }
+  const exitedAfterKill = await waitForSdkPeerExit(targetPids, 2500);
+  if (!exitedAfterKill || !await waitForSdkPeerPortRelease(port, 1500)) {
+    throw new Error(`WaveEngine Agent SDK peer on port ${port} did not exit after termination.`);
+  }
+}
+async function prepareLocalSdkPeerForStart(input) {
+  if (!isLoopbackHost(input.host)) return false;
+  if (input.allowNetwork) return false;
+  const probe = await readLocalSdkPeerProbe(input.host, input.port);
+  if (probe.kind === "none") return false;
+  if (probe.kind === "non-sdk") {
+    throw new Error(`${probe.message} Refusing to kill a non-SDK process.`);
+  }
+  if (!shouldReplaceCurrentSdkPeer(probe.health, input.token)) {
+    console.log(`[WaveEngine Agent SDK] Existing SDK on ${formatLoopbackHttpUrl(input.host, input.port, "")} is current; reusing it.`);
+    console.log("[WaveEngine Agent SDK] If a new Copy-to-Agent token fails later, restart with WAVE3D_MCP_TOKEN from that copy.");
+    return true;
+  }
+  const reason = isCurrentSdkPeer(probe.health) ? "local pairing secret does not match this start request" : `stale version/build (${probe.health.packageVersion ?? "unknown"} ${probe.health.buildHash ?? "unknown"})`;
+  console.log(`[WaveEngine Agent SDK] Replacing existing SDK on port ${input.port}: ${reason}.`);
+  await terminateVerifiedSdkPeer(probe.health, input.port);
+  return false;
+}
 function isCorpusFileManifestEntry(value) {
   if (!isRecord4(value)) return false;
   return typeof value.path === "string" && typeof value.mediaType === "string" && typeof value.role === "string" && typeof value.bytes === "number" && Number.isFinite(value.bytes) && Number.isInteger(value.bytes) && value.bytes >= 0 && typeof value.hash === "string";
@@ -52391,7 +52670,7 @@ function isCorpusManifest(value) {
   return typeof value.version === "string" && (typeof value.formatVersion === "undefined" || typeof value.formatVersion === "string") && typeof value.cacheKey === "string" && typeof value.bundleFileName === "string" && typeof value.bundleHash === "string" && (typeof value.generatedAt === "undefined" || typeof value.generatedAt === "string") && (typeof value.sourceVersions === "undefined" || isRecord4(value.sourceVersions)) && Array.isArray(value.files) && value.files.every(isCorpusFileManifestEntry);
 }
 function corpusFileHash2(content) {
-  return createHash5("sha256").update(JSON.stringify(content)).digest("base64url").slice(0, 32);
+  return createHash6("sha256").update(JSON.stringify(content)).digest("base64url").slice(0, 32);
 }
 function stableJson2(value) {
   if (Array.isArray(value)) return `[${value.map((item) => stableJson2(item)).join(",")}]`;
@@ -52541,14 +52820,24 @@ function printUsage() {
 }
 async function commandStart(options) {
   const host = readStringFlag(options, "host") ?? DEFAULT_HOST2;
-  assertSafeListenHost(host, readBooleanFlag(options, "allow-network"));
+  const port = readNumberFlag(options, "port") ?? DEFAULT_PORT2;
+  const token = readStringFlag(options, "token") ?? process.env.WAVE3D_MCP_TOKEN ?? process.env.WAVESTUDIO_MCP_TOKEN;
+  const allowNetwork = readBooleanFlag(options, "allow-network");
+  assertSafeListenHost(host, allowNetwork);
   await ensureBundledSdkCache(options).catch((error) => {
     console.warn(`[WaveEngine Agent SDK] Bundled WaveEngine SDK cache prepare failed: ${error instanceof Error ? error.message : String(error)}`);
   });
+  const reusedExistingPeer = await prepareLocalSdkPeerForStart({
+    host,
+    port,
+    token,
+    allowNetwork
+  });
+  if (reusedExistingPeer) return;
   const handle = await startWaveEngineAgentSdkServer({
     host,
-    port: readNumberFlag(options, "port") ?? DEFAULT_PORT2,
-    token: readStringFlag(options, "token") ?? process.env.WAVE3D_MCP_TOKEN ?? process.env.WAVESTUDIO_MCP_TOKEN,
+    port,
+    token,
     sessionTtlMs: readNumberFlag(options, "session-ttl-ms")
   });
   console.log(`[WaveEngine Agent SDK] sdkId=${handle.bridgeId}`);

package/dist/sdk/README.md

@@ -3,6 +3,6 @@
 Bundled public-safe WaveEngine SDK lookup cache for wave3d-agent-sdk.
 Generated from sanitized public API/skill corpus during package build.
 
-cacheKey: 2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg
-bundleHash: p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg
-zip: wave-engine-sdk-2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg.zip
+cacheKey: 2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf
+bundleHash: fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf
+zip: wave-engine-sdk-2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
+  "version": "2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
   "formatVersion": "2026-06-17.1",
-  "cacheKey": "2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
-  "bundleFileName": "wave-engine-sdk-2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg.zip",
-  "bundleHash": "p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
+  "cacheKey": "2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
+  "bundleFileName": "wave-engine-sdk-2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf.zip",
+  "bundleHash": "fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-15.2",
-      "promptHash": "S1t3TsiBEK-L5oyOlh3M-2aFvaLyaZ_u"
+      "promptHash": "XmQbudg8ys8LmiXVENo3zVyngwfWfTD7"
     },
     "apiHandbook": {
       "version": "1",
       "contentHash": "edf117cbd2b09857"
     },
     "waveSkillCorpusHash": "nhg-WfsotIdN1pRO41g97bff6RrKujrN",
-    "sdkLookupCorpusHash": "PIjMZyPz-ALuRLJcccp75RQqxQAi3oDV"
+    "sdkLookupCorpusHash": "cIY-jnbSR_-b2nlQgJwVDT7ffQyZ372l"
   },
   "cacheContract": {
     "llmContextCacheOnly": [
@@ -35,7 +35,7 @@
       "searchDocuments"
     ],
     "rule": "Priority 1 always-on sections must stay in LLM chat/system context. The WaveEngine SDK local cache is public-safe retrieval data, never the only memory for core policy.",
-    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.8 cache refresh",
+    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.10 cache refresh",
     "refreshRule": "When using WaveEngine SDK local cache, compare cacheKey, bundleHash, and sourceVersions before trusting local lookup. If any value differs, update the SDK package or reinstall its bundled SDK cache and rebuild local indexes. Do not fetch a remote SDK zip.",
     "onlineFallback": "HTTP Gateway does not provide cloud API lookup. If local Node/npm or cache is refused/unavailable, use only concrete Studio operations and already-known code; repair the local WaveEngine SDK before unfamiliar API authoring."
   },
@@ -50,8 +50,8 @@
       "path": "cache-policy.json",
       "mediaType": "application/json",
       "role": "lookup-guide",
-      "bytes": 1310,
-      "hash": "_bPlWbDd1MsHtcdVNv44Gh_XgmdtIYHw"
+      "bytes": 1311,
+      "hash": "cKZ5cpwWvIcymqtgXmCcrFyPK5pMUCKm"
     },
     {
       "path": "skills/wave-skills.jsonl",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave3d-agent-sdk",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "WaveEngine Agent SDK for same-machine Wave Studio MCP plus bundled WaveEngine lookup.",
   "type": "module",
   "license": "UNLICENSED",