wave3d-agent-sdk 0.2.8 → 0.2.9

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.9 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.9 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.9 --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.9 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.9 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.9 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.9";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.4";
 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.',
@@ -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\`.`,
@@ -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(",")}]`;
@@ -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,307 @@ 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 requiredPackage = readStringProperty(data, "requiredPackage");
+  const isCurrentSdkProtocol = protocolVersion === "waveengine-agent-sdk-http-v1";
+  const isLegacyHelperProtocol = protocolVersion === "local-agent-helper-http-v1" && typeof requiredPackage === "string" && requiredPackage.startsWith("wave3d-agent-bridge@");
+  if (!bridgeId || !bridgeId.startsWith("wgbridge_") || !isCurrentSdkProtocol && !isLegacyHelperProtocol) {
+    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|bridge)\b/.test(command);
+}
+function isLegacyBridgePeer(health) {
+  return health.protocolVersion === "local-agent-helper-http-v1";
+}
+async function stopLegacyBridgeLaunchAgent(health) {
+  if (!isLegacyBridgePeer(health) || process.platform !== "darwin") return;
+  const getuid = process.getuid;
+  if (typeof getuid !== "function") return;
+  const uid = getuid();
+  const launchTarget = `gui/${uid}/com.wave3d.agent-bridge`;
+  console.log("[WaveEngine Agent SDK] Stopping legacy wave3d-agent-bridge launch agent before replacement.");
+  try {
+    await execFileAsync("launchctl", ["bootout", launchTarget], {
+      timeout: 2500,
+      maxBuffer: 128 * 1024,
+      windowsHide: true
+    });
+  } catch {
+  }
+  try {
+    await execFileAsync("launchctl", ["remove", "com.wave3d.agent-bridge"], {
+      timeout: 2500,
+      maxBuffer: 128 * 1024,
+      windowsHide: true
+    });
+  } catch {
+  }
+}
+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) {
+  await stopLegacyBridgeLaunchAgent(health);
+  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 +52700,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 +52850,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.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf
+bundleHash: TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf
+zip: wave-engine-sdk-2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
+  "version": "2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
   "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.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
+  "bundleFileName": "wave-engine-sdk-2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf.zip",
+  "bundleHash": "TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-15.2",
-      "promptHash": "S1t3TsiBEK-L5oyOlh3M-2aFvaLyaZ_u"
+      "promptHash": "YyLcFG8-h779ReTOG7GOz4mjgutRtKZw"
     },
     "apiHandbook": {
       "version": "1",
       "contentHash": "edf117cbd2b09857"
     },
     "waveSkillCorpusHash": "nhg-WfsotIdN1pRO41g97bff6RrKujrN",
-    "sdkLookupCorpusHash": "PIjMZyPz-ALuRLJcccp75RQqxQAi3oDV"
+    "sdkLookupCorpusHash": "1DUg8-FDFbzXLOMm12TB3-S_y4c6Z74H"
   },
   "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.9 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."
   },
@@ -51,7 +51,7 @@
       "mediaType": "application/json",
       "role": "lookup-guide",
       "bytes": 1310,
-      "hash": "_bPlWbDd1MsHtcdVNv44Gh_XgmdtIYHw"
+      "hash": "PCkIsr75VpI_nQ4ufjVs-j13jCuh_YUL"
     },
     {
       "path": "skills/wave-skills.jsonl",

package/package.json

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