@vgai/live 0.5.21 → 0.5.23

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

@@ -0,0 +1,158 @@
+/**
+ * `~/.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.
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const EDITOR_SESSIONS_REGISTRY_FILE = join(homedir(), '.vgai', 'editor-sessions.json');
+export function isEditorSessionEntry(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const s = v;
+    const optionalIdentity = (value) => value === undefined || value === null || typeof value === 'string';
+    return ((typeof s['project'] === 'string' || s['project'] === null) &&
+        typeof s['port'] === 'number' &&
+        typeof s['pid'] === 'number' &&
+        typeof s['startedAt'] === 'string' &&
+        optionalIdentity(s['sessionId']) &&
+        optionalIdentity(s['controlSecret']) &&
+        optionalIdentity(s['repositoryId']) &&
+        optionalIdentity(s['worktreeId']) &&
+        optionalIdentity(s['worktreeRoot']) &&
+        optionalIdentity(s['projectRelativePath']) &&
+        optionalIdentity(s['branch']) &&
+        optionalIdentity(s['headCommit']) &&
+        optionalIdentity(s['baseCommit']));
+}
+export function normalizeEditorSessionEntry(session) {
+    return {
+        ...session,
+        sessionId: session.sessionId ?? null,
+        controlSecret: session.controlSecret ?? null,
+        repositoryId: session.repositoryId ?? null,
+        worktreeId: session.worktreeId ?? null,
+        worktreeRoot: session.worktreeRoot ?? null,
+        projectRelativePath: session.projectRelativePath ?? null,
+        branch: session.branch ?? null,
+        headCommit: session.headCommit ?? null,
+        baseCommit: session.baseCommit ?? null,
+    };
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export function readLiveRegisteredSessions() {
+    try {
+        const raw = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, 'utf8'));
+        return Array.isArray(raw)
+            ? raw
+                .filter(isEditorSessionEntry)
+                .map(normalizeEditorSessionEntry)
+                .filter((s) => pidAlive(s.pid))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function servedProjectAnswer(body) {
+    const b = body;
+    return {
+        path: b.project?.path ?? b.serving?.path ?? null,
+        manifestError: b.project ? null : (b.serving?.error ?? null),
+    };
+}
+/** Canonical (realpathed when possible) absolute form of a project path. */
+function canonicalizeProjectPath(p) {
+    const absolute = resolve(p);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
+function portOfUrl(url) {
+    try {
+        const port = new URL(url).port;
+        return port ? Number(port) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 async function resolveRegisteredSession(ctx, transport, options) {
+    const editorUrl = ctx.editorUrl;
+    if (editorUrl !== undefined && transport.probeSessionUrl) {
+        try {
+            const session = await options.withTimeout(transport.probeSessionUrl(editorUrl, options.probeTimeoutMs), options.probeTimeoutMs, 'explicit editor URL probe');
+            if (session)
+                return session;
+        }
+        catch { }
+        return options.notRunning();
+    }
+    let sessions;
+    try {
+        sessions = await options.withTimeout(transport.listSessions(options.discoveryTimeoutMs), options.discoveryTimeoutMs, 'editor session discovery');
+    }
+    catch {
+        return options.notRunning();
+    }
+    if (sessions.length === 0)
+        return options.notRunning();
+    if (editorUrl !== undefined) {
+        const port = portOfUrl(editorUrl);
+        const match = sessions.find((s) => s.port === port);
+        if (!match)
+            return options.notRunning();
+        return { ...match, url: editorUrl.replace(/\/+$/, '') };
+    }
+    if (ctx.projectRoot !== undefined) {
+        const canon = canonicalizeProjectPath(ctx.projectRoot);
+        const match = sessions.find((s) => s.project !== null && canonicalizeProjectPath(s.project) === canon);
+        if (!match)
+            return options.notRunning();
+        return match;
+    }
+    return [...sessions].sort((a, b) => a.port - b.port)[0];
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "type": "module",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.21",
-    "@vgai/sdk": "0.5.21"
+    "@vgai/editor-sdk": "0.5.23",
+    "@vgai/sdk": "0.5.23"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/editor.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 {
@@ -103,11 +103,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(): Promise<string | null> {
     const state = await this.#client.getState();
@@ -133,14 +130,6 @@ export class LiveEditor {
     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?: { seed?: number }): Promise<void> {
     await this.#client.play(opts);
   }

package/src/game-client/bridge-transport.ts

@@ -51,7 +51,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/src/game-client/client.ts

@@ -141,7 +141,7 @@ export class PageTransport implements BridgeTransport {
     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
@@ -651,7 +651,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).
@@ -688,7 +688,7 @@ export class GameClient {
     const start = await this.snapshot();
     let lastTick: number | null = 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)
@@ -770,10 +770,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: CaptureListener): () => void {
     this.#captureListeners.add(listener);
@@ -783,7 +781,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/src/game-client/relay-transport.ts

@@ -102,6 +102,17 @@ export class RelayTransport implements BridgeTransport {
     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.
+   */
   private async postCommand(
     body: Record<string, unknown>,
     timeoutMs: number,
@@ -176,7 +187,7 @@ export 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
@@ -189,7 +200,14 @@ export class RelayTransport implements BridgeTransport {
       // 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(
+      // 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 ' +
@@ -302,7 +320,7 @@ export class RelayTransport implements BridgeTransport {
   }
 
   /**
-   * 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/src/game-client/types.ts

@@ -45,22 +45,22 @@ 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
    *  precedent as `scheduleActionAtTick` above — no client-side convenience
    *  wrapper in `client.ts` (deliberately parked). */
   injectPointerDelta(sourceId: string, delta: { 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/src/game-client/wait-for.ts

@@ -168,7 +168,7 @@ export interface WaitForClock {
 }
 
 // ---------------------------------------------------------------------------
-// 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).
 //
@@ -179,7 +179,7 @@ export interface WaitForClock {
 // 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/src/game.ts

@@ -22,7 +22,7 @@ import { GameClient, RelayTransport } 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/src/index.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/src/recording.ts

@@ -54,17 +54,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/src/session.ts

@@ -54,6 +54,7 @@ import {
   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
@@ -144,16 +145,6 @@ function readProjectSession(projectRoot: string): ProjectSessionHint | null {
  * 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: unknown): { path: string | null; manifestError: string | null } {
-  const b = body as {
-    project?: { path?: string } | null;
-    serving?: { path?: string; error?: string } | null;
-  };
-  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
@@ -168,7 +159,7 @@ async function probeServedProject(
       signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
     });
     if (!response.ok) return undefined;
-    return servedProject(await response.json());
+    return servedProjectAnswer(await response.json());
   } catch {
     return undefined;
   }
@@ -200,6 +191,62 @@ function manifestRefusal(projectRoot: string, manifestError: string): Error {
  * 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: string,
+  canon: string,
+  sessions: readonly EditorSessionInfo[],
+  discoveryFailure: string | null,
+): Error {
+  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: string = process.cwd(),
   deps: SessionResolutionDeps = {},
@@ -239,30 +286,26 @@ export async function resolveSession(
   }
 
   let sessions: EditorSessionInfo[];
+  // 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: string | null = 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);
 

package/src/tools.ts

@@ -31,7 +31,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.
    */