@vgai/live 0.5.21 → 0.5.23

package/dist/{editor.d.ts → vgai-live/src/editor.d.ts}

@@ -1,14 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (Wave 2). Methods are named after the
+ * page }`. Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
  * separate `selectAll`, `showPanel('viewport-play')` rather than
  * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
  * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
- * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
- * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
+ * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
+ * escape hatch: every method goes over the wire.
  */
 import type { ActiveDocumentCapture, AnimationCaptureAction, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, OpenedDocument, PresentedEditorView, RagdollGenerationResult, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
 import { LiveEditorDocument } from './editor-document.js';
@@ -40,11 +40,8 @@ export declare class LiveEditor {
     constructor(client: EditorClient);
     /**
      * The active authoring adapter's persistence destination — where a save would
-     * land (`status().savePath`).
-     *
-     * WO-8: this also took a `path` and OPENED that scene through
-     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
-     * (the `.vscn.json` format is deleted), so only the read remains.
+     * land (`status().savePath`). A read only: a three root has no scene document
+     * to open, and its root is activated instead.
      */
     scene(): Promise<string | null>;
     /**

package/dist/{editor.js → vgai-live/src/editor.js}

@@ -1,14 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (Wave 2). Methods are named after the
+ * page }`. Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
  * separate `selectAll`, `showPanel('viewport-play')` rather than
  * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
  * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
- * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
- * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
+ * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
+ * escape hatch: every method goes over the wire.
  */
 import { LiveEditorDocument } from './editor-document.js';
 import { LiveGameplayRecording } from './recording.js';
@@ -72,11 +72,8 @@ export class LiveEditor {
     }
     /**
      * The active authoring adapter's persistence destination — where a save would
-     * land (`status().savePath`).
-     *
-     * WO-8: this also took a `path` and OPENED that scene through
-     * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
-     * (the `.vscn.json` format is deleted), so only the read remains.
+     * land (`status().savePath`). A read only: a three root has no scene document
+     * to open, and its root is activated instead.
      */
     async scene() {
         const state = await this.#client.getState();
@@ -98,13 +95,6 @@ export class LiveEditor {
     async captureActiveDocument(size) {
         return this.#client.captureActiveDocument(size);
     }
-    /*
-     * `applyDiff` lived here. It dispatched `project.scene.apply`, one of the
-     * twelve `.vscn` document tools deleted with the format, so there is nothing
-     * left for it to call. `ApplyDiffInput` / `ApplyDiffResult` went with it, and
-     * so did `projectRoot` — this was the ONE method that used it (every other
-     * method goes over the wire).
-     */
     async play(opts) {
         await this.#client.play(opts);
     }

package/dist/{game-client → vgai-live/src/game-client}/bridge-transport.d.ts

@@ -52,7 +52,7 @@ export interface BridgeTransport {
      *  blank/corrupt file. */
     screenshot(path: string): Promise<CaptureNotes>;
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal `async (page) => {...}` (`GameClient.page()`,
      * `client.ts`). `src` is `step.toString()`; `step` is the ORIGINAL
      * function, wrapped so its own parameter type is erased to `unknown` (only

package/dist/{game-client → vgai-live/src/game-client}/client.d.ts

@@ -33,7 +33,7 @@ export declare class PageTransport implements BridgeTransport {
      *  (`capture-notes.ts`) exists on this leg. `{}` says that honestly rather
      *  than inventing a clean bill of health. */
     screenshot(path: string): Promise<CaptureNotes>;
-    /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+    /** The ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
      *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
@@ -275,14 +275,12 @@ export declare class GameClient {
      * `events.expect`'s failure path each shoot a frame on their own
      * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
      * observer may shoot one from inside a callback the driver never sees. The
-     * only place that sees ALL of them is here, which is why an autoplay run
-     * stamps its captures by listening rather than by intercepting
-     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
-     * listener).
+     * only place that sees ALL of them is here, which is why a driving tool
+     * stamps its captures by listening rather than by intercepting.
      */
     onCapture(listener: CaptureListener): () => void;
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface
      * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
      * executing Playwright"). Under `PageTransport` this drives the REAL

package/dist/{game-client → vgai-live/src/game-client}/client.js

@@ -111,7 +111,7 @@ export class PageTransport {
         await this.page.screenshot({ path });
         return {};
     }
-    /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+    /** The ONE transport that runs a `game.page()` step against a REAL
      *  Playwright `Page` — no serialization, so `step`'s own closures work
      *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
@@ -529,7 +529,7 @@ export class GameClient {
                 snapshot: () => this.snapshot(),
                 now: () => Date.now(),
                 sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-                // Fixture heartbeat (Wave-6 findings ledger) — real stdout, the
+                // Fixture heartbeat — real stdout, the
                 // same channel a caller watching stdout already treats as
                 // liveness (see wait-for.ts's module doc for the emission
                 // invariant `maybeHeartbeat` enforces).
@@ -565,7 +565,7 @@ export class GameClient {
         const start = await this.snapshot();
         let lastTick = null;
         let stalledPolls = 0;
-        // Fixture heartbeat (Wave-6 findings ledger) — same invariant as
+        // Fixture heartbeat — same invariant as
         // `wait-for.ts`'s `runWaitFor`: a heartbeat requires BOTH 60s of wall
         // silence AND the tick having advanced since the last one emitted, so a
         // genuinely stalled sim clock (caught by `stalledPolls` above, ~30s)
@@ -646,10 +646,8 @@ export class GameClient {
      * `events.expect`'s failure path each shoot a frame on their own
      * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
      * observer may shoot one from inside a callback the driver never sees. The
-     * only place that sees ALL of them is here, which is why an autoplay run
-     * stamps its captures by listening rather than by intercepting
-     * (`src/tools/route-context.ts` in a scaffolded project is the shipped
-     * listener).
+     * only place that sees ALL of them is here, which is why a driving tool
+     * stamps its captures by listening rather than by intercepting.
      */
     onCapture(listener) {
         this.#captureListeners.add(listener);
@@ -658,7 +656,7 @@ export class GameClient {
         };
     }
     /**
-     * Wave-2 "one dialect, full capability" — runs a UI-automation step
+     * One dialect, full capability — runs a UI-automation step
      * written as a literal Playwright `async (page) => {...}` (interface
      * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
      * executing Playwright"). Under `PageTransport` this drives the REAL

package/dist/{game-client → vgai-live/src/game-client}/relay-transport.d.ts

@@ -52,6 +52,17 @@ export declare class RelayTransport implements BridgeTransport {
     private hiddenCache;
     private readonly instance;
     constructor(opts: RelayTransportOptions);
+    /**
+     * Deliberately NOT guarded against a page-fallback answer the way the browser
+     * (`packages/editor/src/editor-server-response.ts`) and the CLI client
+     * (`@vgai/editor-sdk`'s `EditorClient.readJson`) are. Those two can be pointed
+     * at an arbitrary URL — a share tunnel, a static host — where a `200
+     * text/html` for an unserved route is real. This `baseUrl` is
+     * `http://127.0.0.1:<port>` and nothing else, and `session.ts` has already
+     * PROVED that port is this project's editor server (`probeServedProject`, whose
+     * own unparseable-answer path is exactly the refusal): a foreign occupant is
+     * refused there, before any command reaches here.
+     */
     private postCommand;
     /** Maps the relay's wire body back onto the transport-neutral
      *  `BridgeCallOutcome` — `result` on success, `code`/`error`/the rest of
@@ -67,7 +78,7 @@ export declare class RelayTransport implements BridgeTransport {
      *
      * It runs on every leg, not just `call('snapshot')`, because that is where
      * the measured gap was: a bot that drives the game with `hold`/`command` and
-     * reads through them — the shape `npm run playtest` actually has — could run
+     * reads through them could run
      * its entire session against a backgrounded tab and never be told, so a
      * later failure read as a generic relay timeout instead of "your tab is
      * hidden". Returns whether the tab is hidden so `call` can decide whether to
@@ -89,7 +100,7 @@ export declare class RelayTransport implements BridgeTransport {
     bringToFront(): Promise<void>;
     screenshot(path: string): Promise<CaptureNotes>;
     /**
-     * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+     * Ships `src` (`step.toString()`) to the editor dev server's
      * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
      * above), not a `bridge-call` method (see `command-listener.ts`'s
      * `handlePageScript` doc comment for why). `step` itself is unused on this

package/dist/{game-client → vgai-live/src/game-client}/relay-transport.js

@@ -57,6 +57,17 @@ export class RelayTransport {
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.instance = opts.instance;
     }
+    /**
+     * Deliberately NOT guarded against a page-fallback answer the way the browser
+     * (`packages/editor/src/editor-server-response.ts`) and the CLI client
+     * (`@vgai/editor-sdk`'s `EditorClient.readJson`) are. Those two can be pointed
+     * at an arbitrary URL — a share tunnel, a static host — where a `200
+     * text/html` for an unserved route is real. This `baseUrl` is
+     * `http://127.0.0.1:<port>` and nothing else, and `session.ts` has already
+     * PROVED that port is this project's editor server (`probeServedProject`, whose
+     * own unparseable-answer path is exactly the refusal): a foreign occupant is
+     * refused there, before any command reaches here.
+     */
     async postCommand(body, timeoutMs) {
         const res = await fetch(`${this.baseUrl}/__editor/command`, {
             method: 'POST',
@@ -119,7 +130,7 @@ export class RelayTransport {
      *
      * It runs on every leg, not just `call('snapshot')`, because that is where
      * the measured gap was: a bot that drives the game with `hold`/`command` and
-     * reads through them — the shape `npm run playtest` actually has — could run
+     * reads through them could run
      * its entire session against a backgrounded tab and never be told, so a
      * later failure read as a generic relay timeout instead of "your tab is
      * hidden". Returns whether the tab is hidden so `call` can decide whether to
@@ -132,7 +143,14 @@ export class RelayTransport {
             // P21: what was measured, and what this run is doing about it — not a
             // claim about where the tab is. The reading is a `presence` snapshot
             // (`isHidden` below), which ages between the tab's own reports.
-            process.stdout.write('vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
+            // STDERR, not stdout. `vgai status` and every other `--json`-shaped verb
+            // put their PAYLOAD on stdout and every banner on stderr; this notice went
+            // to stdout and prepended a prose sentence to the JSON, so any machine
+            // consumer piping `vgai status` into a parser got a SyntaxError the moment
+            // the tab happened to be hidden — measured while reading the coverage
+            // table on a backgrounded session. A diagnostic that breaks the payload it
+            // annotates is worse than no diagnostic.
+            process.stderr.write('vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
                 'stops its loop while the page reports itself hidden, so this run drives ' +
                 'deterministic runTicks through the session relay instead of wall clock. Sim time ' +
                 'advances either way; `vgai status` prints that reading with its age.\n');
@@ -228,7 +246,7 @@ export class RelayTransport {
         return notes;
     }
     /**
-     * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+     * Ships `src` (`step.toString()`) to the editor dev server's
      * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
      * above), not a `bridge-call` method (see `command-listener.ts`'s
      * `handlePageScript` doc comment for why). `step` itself is unused on this

package/dist/{game-client → vgai-live/src/game-client}/types.d.ts

@@ -41,15 +41,15 @@ export interface DebugBridgeInput {
     setVirtualAction(action: string, value: VirtualActionValue): VirtualActionResult;
     tapVirtualAction(action: string): VirtualActionResult;
     clearVirtualActions(): void;
-    /** D15/T-D15.5 — schedule a virtual actuation for a specific tick, applied
-     *  at the start of that tick's input phase. Declared here (Wave-2
-     *  bridge↔wire coverage-parity gate) for type-shape completeness with
+    /** Schedule a virtual actuation for a specific tick, applied
+     *  at the start of that tick's input phase. Declared here for the
+     *  bridge↔wire coverage-parity gate — type-shape completeness with
      *  `runtime/debug-bridge.ts`'s `VgaiDebugInputHandle` — this package still
      *  exposes no client-side convenience wrapper around it (deliberately
      *  parked; see `GameInput` in `client.ts`), this is pure type-shape
      *  mirroring. */
     scheduleActionAtTick(tick: number, action: string, value: VirtualActionValue): void;
-    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+    /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
      *  `VgaiDebugInputHandle.injectPointerDelta`: accumulates a synthetic
      *  pointer delta for a named test source (sums within a frame, clears each
      *  frame). Declared here for type-shape completeness with the bridge, same
@@ -59,7 +59,7 @@ export interface DebugBridgeInput {
         x: number;
         y: number;
     }): void;
-    /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+    /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
      *  `VgaiDebugInputHandle.injectPointerPosition`: sets a synthetic absolute
      *  pointer position for a named test source (last-write-wins, persists
      *  until changed). Same type-shape-only precedent as `scheduleActionAtTick`. */

package/dist/{game-client → vgai-live/src/game-client}/wait-for.js

@@ -96,7 +96,7 @@ export class WaitForTimeoutError extends Error {
     }
 }
 // ---------------------------------------------------------------------------
-// Fixture heartbeat (Wave-6 findings ledger: "Watchdog sim-awareness / fixture
+// Fixture heartbeat ("Watchdog sim-awareness / fixture
 // heartbeat for long silent tests" — Session C hit exit-5 on the runner's
 // 2x90s stdout-liveness watchdog during a legitimately silent 5-minute test).
 //
@@ -107,7 +107,7 @@ export class WaitForTimeoutError extends Error {
 // advancing test can never false-wedge regardless of duration, no matter how
 // long a single `simSeconds` budget runs.
 //
-// INVARIANT (tested below and in fixture.test.ts): a heartbeat requires BOTH
+// INVARIANT (tested below): a heartbeat requires BOTH
 // (a) >= HEARTBEAT_INTERVAL_MS of wall time since the last heartbeat, AND
 // (b) the tick has ADVANCED since the last heartbeat (not merely since the
 // last poll). Without (b), the poll loop itself — which keeps running

package/dist/{game.d.ts → vgai-live/src/game.d.ts}

@@ -20,7 +20,7 @@ import { GameClient } from './game-client/index.js';
 /** A `GameClient` addressing ONE mounted instance, tagged with the mount `id`
  *  it drives. `id` is the whole point of the handle to a CALLER: it is what
  *  `tools.run(name, args, { instance: handle.id })` passes to scope a
- *  node-hosted tool (e.g. `project.autoplay`) to this seat — the two-seat
+ *  node-hosted tool to this seat — the two-seat
  *  multiplayer verification pattern. Without it the caller has a client it can
  *  drive but no id to hand a tool, so the seat-scoped path silently degrades to
  *  the sole-instance one. */

package/dist/{index.d.ts → vgai-live/src/index.d.ts}

@@ -34,8 +34,8 @@
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
  *
- * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
- * PR #166) — write `step` as a literal `async (page) => {...}` and inline
+ * `page(step)` = `GameClient.page(step)`, the playwright-shim surface —
+ * write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
  * binds to, `step` is shipped to the editor dev server as `step.toString()`
  * and reconstructed there — closures over outer variables do NOT survive that

package/dist/{index.js → vgai-live/src/index.js}

@@ -34,8 +34,8 @@
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
  *
- * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
- * PR #166) — write `step` as a literal `async (page) => {...}` and inline
+ * `page(step)` = `GameClient.page(step)`, the playwright-shim surface —
+ * write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
  * binds to, `step` is shipped to the editor dev server as `step.toString()`
  * and reconstructed there — closures over outer variables do NOT survive that

package/dist/{recording.js → vgai-live/src/recording.js}

@@ -36,17 +36,10 @@ export class LiveGameplayRecording {
             await copyFile(capture.path, path);
         }
         return {
+            ...capture,
+            // The caller's `destination` copy, when there was one — otherwise the
+            // project path the recorder wrote. Spread first so this wins.
             path,
-            startedAt: capture.startedAt,
-            mimeType: capture.mimeType,
-            width: capture.width,
-            height: capture.height,
-            fps: capture.fps,
-            audio: capture.audio,
-            durationMs: capture.durationMs,
-            droppedFrames: capture.droppedFrames,
-            frameErrors: capture.frameErrors,
-            layers: capture.layers,
         };
     }
 }

package/dist/{session.d.ts → vgai-live/src/session.d.ts}

@@ -76,11 +76,4 @@ export interface ProjectSessionHint {
     url: string;
     startedAt: string;
 }
-/**
- * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
- * running `vgai edit` session. Throws a descriptive error (never hangs
- * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
- * silently attaches to an unrelated project's session — see the module doc
- * above) when no vgai.project.json is found, or no live session covers it.
- */
 export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;

package/dist/{session.js → vgai-live/src/session.js}

@@ -47,6 +47,7 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, HttpEditorTransport, withTimeout, } from '@vgai/sdk';
+import { servedProjectAnswer } from '../../vgai-sdk/src/editor/session-registry-format';
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
  * module's doc comment above for why it's duplicated rather than imported).
@@ -106,13 +107,6 @@ function readProjectSession(projectRoot) {
  * but none open this project)" — sending the operator to start an editor that
  * was already running, with the real defect (their own manifest) never named.
  */
-function servedProject(body) {
-    const b = body;
-    return {
-        path: b.project?.path ?? b.serving?.path ?? null,
-        manifestError: b.project ? null : (b.serving?.error ?? null),
-    };
-}
 /**
  * What the server on `port` says it serves — `undefined` when it did not
  * answer at all. One probe: the manifest failure arrives with the path, so
@@ -125,7 +119,7 @@ async function probeServedProject(port) {
         });
         if (!response.ok)
             return undefined;
-        return servedProject(await response.json());
+        return servedProjectAnswer(await response.json());
     }
     catch {
         return undefined;
@@ -154,6 +148,50 @@ function manifestRefusal(projectRoot, manifestError) {
  * silently attaches to an unrelated project's session — see the module doc
  * above) when no vgai.project.json is found, or no live session covers it.
  */
+/**
+ * THE REFUSAL WHEN NOTHING MATCHED — and it says WHICH nothing.
+ *
+ * "No live editor session found … run `vgai edit`" used to be the answer to
+ * four different states, only one of which it described. The other three sent
+ * the operator to start an editor that was already running:
+ *
+ *  - discovery FAILED (a probe timeout under load) — nothing was learned, so
+ *    "no session is running" is not a fact anyone established;
+ *  - the registry was read and is genuinely empty — the one case the old text
+ *    was right about;
+ *  - sessions exist, but every one resolves to a different canonical path. In
+ *    a repo worked through git worktrees this is the ORDINARY miss: two
+ *    checkouts of the same project differ only in a path prefix, and a
+ *    symlinked worktree's `realpath` diverges from the path the caller typed.
+ *    Naming both sides is what makes it a two-second diagnosis instead of a
+ *    hunt.
+ *
+ * Each branch prescribes only what its own state supports.
+ */
+function noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure) {
+    if (discoveryFailure !== null) {
+        return new Error(`@vgai/live: could not READ the editor session registry while looking for ${projectRoot} — ` +
+            `${discoveryFailure}. This is not the answer "no editor is running": the question went ` +
+            'unanswered, so nothing is known about what is live. Retry (a probe can time out while ' +
+            'the box is loaded); if it keeps failing, `vgai sessions` asks the same question directly.');
+    }
+    if (sessions.length === 0) {
+        return new Error(`@vgai/live: the editor session registry is readable and lists NO live sessions, so none ` +
+            `covers ${projectRoot}. @vgai/live only attaches to an already-running session — it ` +
+            'never starts one — so run `vgai edit` in that project first, then retry.');
+    }
+    const listed = sessions
+        .map((s) => `    port ${s.port} → ${s.project === null ? '(no project)' : s.project}`)
+        .join('\n');
+    return new Error(`@vgai/live: ${sessions.length} live editor session(s) are running, but none of them opens ` +
+        `${projectRoot}. @vgai/live never silently attaches to a different project.\n` +
+        `  looking for (resolved): ${canon}\n` +
+        `  live sessions:\n${listed}\n` +
+        '  If one of those is meant to be this project, the two paths differ after resolution — ' +
+        'the usual cause is a git worktree or a symlink, where the session was opened through a ' +
+        'different path to the same files. Run `vgai edit` from THIS path, or use the path the ' +
+        'session lists.');
+}
 export async function resolveSession(projectDir = process.cwd(), deps = {}) {
     const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
     const transport = deps.transport ?? new HttpEditorTransport();
@@ -187,24 +225,23 @@ export async function resolveSession(projectDir = process.cwd(), deps = {}) {
         }
     }
     let sessions;
+    // A FAILED discovery is not an empty one. Collapsing the two into `[]` is
+    // what made this door answer "no live editor session found" — and prescribe
+    // `vgai edit` — for a probe that merely timed out under load, sending the
+    // operator to start an editor that was already running while the real defect
+    // went unnamed. The same collapse the manifest refusal above was added for.
+    let discoveryFailure = null;
     try {
         sessions = await withTimeout(transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS), EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, 'editor session discovery');
     }
-    catch {
+    catch (err) {
         sessions = [];
+        discoveryFailure = err instanceof Error ? err.message : String(err);
     }
     const canon = canonicalPath(projectRoot);
     const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
-    if (!match) {
-        const otherCount = sessions.length;
-        throw new Error(`@vgai/live: no live editor session found for ${projectRoot}. @vgai/live only attaches to ` +
-            'an already-running session — it never starts one — so run `vgai edit` in that project ' +
-            'first, then retry.' +
-            (otherCount > 0
-                ? ` (${otherCount} other live session(s) found, but none open this project — @vgai/live ` +
-                    'never silently attaches to a different project.)'
-                : ''));
-    }
+    if (!match)
+        throw noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure);
     if (match.manifestError != null)
         throw manifestRefusal(projectRoot, match.manifestError);
     return { port: match.port, projectRoot };

package/dist/{tools.d.ts → vgai-live/src/tools.d.ts}

@@ -12,7 +12,7 @@ export declare class LiveTools {
      *
      * `instance` names WHICH mounted instance the tool should drive when several
      * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
-     * and a tool that drives the game (e.g. `project.autoplay`) binds
+     * and a tool that drives the game binds
      * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
      * the tool then targets the sole live instance, exactly as before.
      */

package/dist/{tools.js → vgai-live/src/tools.js}

@@ -19,7 +19,7 @@ export class LiveTools {
      *
      * `instance` names WHICH mounted instance the tool should drive when several
      * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
-     * and a tool that drives the game (e.g. `project.autoplay`) binds
+     * and a tool that drives the game binds
      * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
      * the tool then targets the sole live instance, exactly as before.
      */

package/dist/vgai-sdk/src/editor/session-registry-format.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `~/.vgai/editor-sessions.json` — the ONE spelling of the editor-session
+ * registry contract, and the shared machinery every reader was hand-copying.
+ *
+ * The registry's WRITE half stays with its owner
+ * (`packages/editor/server/session-registry.ts`); this module owns the
+ * FORMAT: the entry shape, the shape guards, the file path, the
+ * liveness-filtered read, the `/__editor/project` answer parser, and the
+ * deterministic session-selection core. It existed as FOUR drifting copies
+ * (server registry, the CLI, and both vgai-sdk transports) held together by
+ * a "the CLI has no editor dependency" premise that had stopped being true —
+ * and the drift was already real: one copy's `/__editor/project` parser
+ * dropped `manifestError`, reporting a degraded session as belonging to no
+ * project.
+ */
+/** One registry entry, exactly as the server's write half records it. */
+export interface EditorSessionEntry {
+    /** Canonical project root currently open, or null when none. */
+    project: string | null;
+    port: number;
+    /** PID of the dev-server process. */
+    pid: number;
+    /** ISO timestamp of server start. */
+    startedAt: string;
+    sessionId: string | null;
+    /** Private loopback control credential — never returned by an editor HTTP
+     *  route; exists only in this user-private registry. */
+    controlSecret?: string | null;
+    repositoryId: string | null;
+    worktreeId: string | null;
+    worktreeRoot: string | null;
+    projectRelativePath: string | null;
+    branch: string | null;
+    headCommit: string | null;
+    baseCommit: string | null;
+}
+export declare const EDITOR_SESSIONS_REGISTRY_FILE: string;
+export declare function isEditorSessionEntry(v: unknown): v is EditorSessionEntry;
+export declare function normalizeEditorSessionEntry(session: EditorSessionEntry): EditorSessionEntry;
+export declare function pidAlive(pid: number): boolean;
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export declare function readLiveRegisteredSessions(): EditorSessionEntry[];
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving.
+ *
+ * `serving` is that server's own statement of "I AM serving this project, I
+ * just cannot describe it" (its manifest is unparseable or fails strict
+ * validation) — added to the route precisely because a bare
+ * `{ project: null }` is indistinguishable from "no project open". Reading
+ * only `project.path` collapses the two, and the cost is that every
+ * project-matched command loses a live session the moment a save breaks its
+ * manifest, reporting it as belonging to no project rather than as this
+ * project's degraded session.
+ */
+export declare function servedProjectAnswer(body: unknown): {
+    path: string | null;
+    manifestError: string | null;
+};
+/**
+ * Deterministic session selection — the ONE precedence order every surface
+ * follows: explicit `ctx.editorUrl` probe > port match against the listing >
+ * `ctx.projectRoot` match > lowest live port > not-running. Generic over the
+ * session shape so the editor and play transports (whose probe results
+ * differ) share the algorithm rather than a copy of it.
+ */
+export declare function resolveRegisteredSession<T extends {
+    port: number;
+    project: string | null;
+    url?: string;
+}>(ctx: {
+    editorUrl?: string | undefined;
+    projectRoot?: string | undefined;
+}, transport: {
+    listSessions(timeoutMs: number): Promise<T[]>;
+    probeSessionUrl?: ((url: string, timeoutMs: number) => Promise<T | null | undefined>) | undefined;
+}, options: {
+    probeTimeoutMs: number;
+    discoveryTimeoutMs: number;
+    withTimeout: <V>(work: Promise<V>, timeoutMs: number, what: string) => Promise<V>;
+    notRunning: () => never;
+}): Promise<T>;