@vgai/editor-sdk 0.5.41 → 0.5.44

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.41",
+  "version": "0.5.44",
   "type": "module",
   "repository": {
     "type": "git",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.41"
+    "@vgai/sdk": "0.5.44"
   },
   "peerDependencies": {
     "@vgai/engine": "*",

package/src/client.ts

@@ -10,12 +10,18 @@ import type {
   AssetPreviewOptions,
   AssetPreviewShotSetDefinition,
   AssetPreviewSource,
+  CaptureDimensions,
+  DocumentCameraPose,
+  DocumentLookOutcome,
+  EditorChromeCapture,
   EditorState,
   EditorView,
+  EditorWorkspaceName,
   GameCapture,
   GameplayRecordingCapture,
   GameplayRecordingOptions,
   GameplayRecordingStarted,
+  GameplayRecordingTimeline,
   HelperVisibility,
   InspectedFieldWrite,
   InspectedHierarchy,
@@ -32,6 +38,9 @@ import type {
   ShadingMode,
   StoryCaptureOptions,
   StoryVariantCapture,
+  StructureOp,
+  StructureOpOptions,
+  StructureOpResult,
   TransformMode,
   TransformSpace,
   Vec3Value,
@@ -114,6 +123,59 @@ const COMMAND_DEADLINE_MS = 150_000;
  */
 const CONSOLE_DRAIN_TIMEOUT_MS = 1_500;
 
+/**
+ * Node's `fetch` collapses EVERY network-layer failure into one two-word
+ * `TypeError: fetch failed`. The real reason — `ECONNREFUSED`, `ECONNRESET`,
+ * `EPIPE`, a DNS miss — lives only on `error.cause` (sometimes two links down,
+ * or inside an `AggregateError`), and nothing prints it unless something walks
+ * the chain. That is the whole reason `project.bake.preview` was observed
+ * failing with a bare "fetch failed" and no way to tell a dead editor from a
+ * momentary one (WORK.md, cold barrel 2026-08-29): the code below used to
+ * rethrow the `TypeError` untouched, on the belief — stated in a comment right
+ * where it happened — that "a connection refused / DNS failure still surfaces
+ * as itself". It does not. This walks the chain so the message can say which.
+ */
+function describeFetchFailure(error: unknown): { code: string; detail: string } {
+  const messages: string[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth < 8; depth++) {
+    if (!(current instanceof Error)) break;
+    if (current.message) messages.push(current.message);
+    const code = (current as { code?: unknown }).code;
+    if (typeof code === 'string' && code !== '') {
+      return { code, detail: messages.join(' <- ') };
+    }
+    const aggregate = (current as { errors?: unknown }).errors;
+    if (Array.isArray(aggregate) && aggregate.length > 0) {
+      const inner = describeFetchFailure(aggregate[0]);
+      return { code: inner.code, detail: [...messages, inner.detail].join(' <- ') };
+    }
+    current = (current as { cause?: unknown }).cause;
+  }
+  return { code: 'UNKNOWN', detail: messages.join(' <- ') || String(error) };
+}
+
+/**
+ * Transport failures where a second attempt is worth making: the connection
+ * itself failed or died, rather than the editor answering something unwelcome.
+ * A dev server that is restarting (any watched source edit restarts it) is
+ * unreachable for a fraction of a second and reachable again after — which is
+ * exactly the "fails, then succeeds unchanged" shape that was reported.
+ */
+const RETRYABLE_TRANSPORT_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'EPIPE',
+  'ETIMEDOUT',
+  'EHOSTUNREACH',
+  'UND_ERR_SOCKET',
+  'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+/** Gap before the one automatic retry — long enough for a dev-server restart's
+ *  listen socket to come back, short enough to stay invisible. */
+const TRANSPORT_RETRY_DELAY_MS = 400;
+
 /** Context accompanying one {@link EditorClient} response observation. */
 export interface EditorEnvelopeObservation {
   /** True only when this body came from the console-ledger endpoint and its
@@ -205,6 +267,9 @@ export class EditorClient {
    * The observer must not throw; anything it raises is swallowed, because a
    * reporting hook may never break the command it is reporting on.
    */
+  private readonly transport:
+    | ((body: Record<string, unknown>) => Promise<Record<string, unknown>>)
+    | null;
   private readonly onEnvelope:
     | ((body: unknown, observation: EditorEnvelopeObservation) => void)
     | null;
@@ -212,6 +277,14 @@ export class EditorClient {
   constructor(opts?: {
     url?: string;
     onEnvelope?: (body: unknown, observation: EditorEnvelopeObservation) => void;
+    /**
+     * An IN-PAGE command channel, for a client that lives inside the editor
+     * page itself on a tier with no editor server (the hosted build's
+     * contribution client). Given, every command goes through it instead of
+     * `POST /__editor/command`, and answers in the route's own body shape
+     * (`{ ok: true, ...data }` / `{ ok: false, error, code? }`).
+     */
+    transport?: (body: Record<string, unknown>) => Promise<Record<string, unknown>>;
   }) {
     if (opts !== undefined && (typeof opts !== 'object' || opts === null || Array.isArray(opts))) {
       throw new TypeError(
@@ -219,7 +292,7 @@ export class EditorClient {
       );
     }
     const unknownOptions = Object.keys(opts ?? {}).filter(
-      (key) => key !== 'url' && key !== 'onEnvelope',
+      (key) => key !== 'url' && key !== 'onEnvelope' && key !== 'transport',
     );
     if (unknownOptions.length > 0) {
       throw new Error(
@@ -228,6 +301,7 @@ export class EditorClient {
     }
     this.baseUrl = (opts?.url ?? DEFAULT_URL).replace(/\/$/, '');
     this.onEnvelope = opts?.onEnvelope ?? null;
+    this.transport = opts?.transport ?? null;
     this.game = {
       state: async (name: string): Promise<unknown> => {
         // `keys` narrows the relay to the one provider asked for, so a panel
@@ -245,28 +319,82 @@ export class EditorClient {
     };
   }
 
+  /**
+   * `retryTransport` opts a command into ONE automatic retry after a transport
+   * failure (see {@link RETRYABLE_TRANSPORT_CODES}). It is deliberately
+   * OPT-IN and off by default: a socket that died after the request was written
+   * cannot prove the editor did not already run the command, so a blanket retry
+   * would risk playing/stopping/writing twice. Read-only relays — the captures —
+   * have no such hazard and turn it on.
+   */
   private async command<T extends object = Record<string, never>>(
     body: Record<string, unknown>,
+    options?: { retryTransport?: boolean },
   ): Promise<T> {
-    let res: Response;
-    try {
-      res = await fetch(`${this.baseUrl}/__editor/command`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(COMMAND_DEADLINE_MS),
-      });
-    } catch (error) {
-      // Only the deadline is reshaped; a connection refused / DNS failure
-      // still surfaces as itself, because those name their own cause.
-      if ((error as { name?: string } | null)?.name !== 'TimeoutError') throw error;
-      throw new EditorCommandError(
-        `The editor at ${this.baseUrl} never answered "${String(body['type'] ?? 'command')}" ` +
-          `within ${Math.round(COMMAND_DEADLINE_MS / 1000)}s — past every server-side budget, so ` +
-          'the server itself is not answering. Check the terminal running `vgai edit`.',
-        undefined,
-        true,
-      );
+    const type = String(body['type'] ?? 'command');
+    if (this.transport) {
+      const answered = (await this.transport(body)) as {
+        ok: boolean;
+        error?: string;
+        code?: string;
+      } & T;
+      if (!answered.ok) {
+        throw new EditorCommandError(
+          answered.error ?? `Editor command "${type}" failed`,
+          answered.code,
+        );
+      }
+      return answered;
+    }
+    const url = `${this.baseUrl}/__editor/command`;
+    const request = JSON.stringify(body);
+    let res: Response | undefined;
+    let retried = false;
+    for (;;) {
+      try {
+        res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: request,
+          signal: AbortSignal.timeout(COMMAND_DEADLINE_MS),
+        });
+        break;
+      } catch (error) {
+        // Only the deadline is reshaped into a "no answer" verdict; everything
+        // else is a TRANSPORT failure, and Node hides its reason behind a bare
+        // `fetch failed` (see `describeFetchFailure`).
+        if ((error as { name?: string } | null)?.name === 'TimeoutError') {
+          throw new EditorCommandError(
+            `The editor at ${this.baseUrl} never answered "${type}" ` +
+              `within ${Math.round(COMMAND_DEADLINE_MS / 1000)}s — past every server-side budget, so ` +
+              'the server itself is not answering. Check the terminal running `vgai edit`.',
+            undefined,
+            true,
+          );
+        }
+        const { code, detail } = describeFetchFailure(error);
+        if (options?.retryTransport === true && !retried && RETRYABLE_TRANSPORT_CODES.has(code)) {
+          retried = true;
+          await new Promise((resolve) => setTimeout(resolve, TRANSPORT_RETRY_DELAY_MS));
+          continue;
+        }
+        throw new EditorCommandError(
+          `POST ${url} ("${type}") never reached the editor: ${code}${detail ? ` (${detail})` : ''}.` +
+            (retried
+              ? ` Retried once after ${TRANSPORT_RETRY_DELAY_MS}ms; it failed the same way.`
+              : '') +
+            (options?.retryTransport === true
+              ? ''
+              : ' Not retried automatically: this command can change editor state, and a socket that' +
+                ' died after the request was written cannot prove the editor did not already run it.') +
+            ' A transport failure means the port stopped answering, not that the editor refused —' +
+            ' the dev server restarts on any watched source edit, and it shuts itself down after an' +
+            ' idle window. Check the terminal running `vgai edit`, and `vgai sessions` for the port' +
+            ' this client resolved.',
+          code,
+          false,
+        );
+      }
     }
     const data = (await this.readJson(res)) as { ok: boolean; error?: string; code?: string } & T;
     if (!data.ok) {
@@ -375,6 +503,40 @@ export class EditorClient {
     await this.command({ type: 'view-preset', preset });
   }
 
+  /**
+   * LOOK AROUND THE OPEN MODEL, visibly. Swings the active Object3D
+   * document's camera — the one on the human's screen — by `azimuth`/
+   * `elevation` radians, animated over `duration` seconds, and resolves when
+   * the move ends. A human drag during the move cancels it where it stands
+   * (`cancelledBy: 'human'`); the promise still resolves.
+   */
+  async orbitDocument(options: {
+    azimuth?: number;
+    elevation?: number;
+    duration?: number;
+  }): Promise<DocumentLookOutcome> {
+    return this.command<DocumentLookOutcome>({ type: 'document-orbit', ...options });
+  }
+
+  /** A slow full revolution around the open document's subject, at a constant rate. */
+  async turntableDocument(options?: {
+    seconds?: number;
+    revolutions?: number;
+  }): Promise<DocumentLookOutcome> {
+    return this.command<DocumentLookOutcome>({ type: 'document-turntable', ...options });
+  }
+
+  /**
+   * Frame the open document's subject (its selection if it has one). `fit`
+   * scales the fitted distance: 1 is the toolbar Frame button's tight fit.
+   */
+  async frameDocument(fit?: number): Promise<DocumentCameraPose> {
+    return this.command<DocumentCameraPose>({
+      type: 'document-frame',
+      ...(fit === undefined ? {} : { fit }),
+    });
+  }
+
   async setCamera(position: Vec3Value, target: Vec3Value, fov?: number): Promise<void> {
     await this.command({
       type: 'set-camera',
@@ -437,6 +599,11 @@ export class EditorClient {
       // re-derives (or softens) it.
       ...(flatness && typeof flatness.dominantFraction === 'number' ? { flatness } : {}),
       ...(data.loopRecoveryFrame === true ? { loopRecoveryFrame: true } : {}),
+      // Same pass-through rule: the recorded-run notice is written where the
+      // pixels are, so nothing here re-derives or softens it.
+      ...(data.recording && typeof data.recording.notice === 'string'
+        ? { recording: data.recording }
+        : {}),
     };
   }
 
@@ -457,6 +624,15 @@ export class EditorClient {
     return this.command<GameplayRecordingCapture>({ type: 'bridge-recording-stop' });
   }
 
+  /** Read the active capture's monotonic media position. This is the only clock
+   * suitable for selecting intervals inside the finalized recording. */
+  async getGameplayRecordingTimeline(): Promise<GameplayRecordingTimeline> {
+    const timeline = await this.command<GameplayRecordingTimeline>({
+      type: 'bridge-recording-timeline',
+    });
+    return { startedAt: timeline.startedAt, elapsedMs: timeline.elapsedMs };
+  }
+
   /**
    * Capture an isolated, deterministic four-view preview through the editor's
    * native Asset Lab. The SDK delegates rendering to the editor; it never
@@ -466,14 +642,22 @@ export class EditorClient {
     source: AssetPreviewSource,
     options: AssetPreviewOptions = {},
   ): Promise<AssetPreviewCapture> {
-    const data = await this.command<AssetPreviewCapture>({
-      type: 'capture-asset-preview',
-      ...source,
-      ...options,
-    });
+    const data = await this.command<AssetPreviewCapture>(
+      {
+        type: 'capture-asset-preview',
+        ...source,
+        ...options,
+      },
+      // Photographing changes nothing, and this is the relay `vgai screenshot
+      // <module>` / `project.bake.preview` rides — the lane where a momentary
+      // transport failure cost a cold agent three probe modules.
+      { retryTransport: true },
+    );
     return {
       width: data.width,
       height: data.height,
+      // Absent from editors that predate orientation reporting.
+      ...(data.orientation ? { orientation: data.orientation } : {}),
       views: data.views,
       contactSheet: data.contactSheet,
     };
@@ -494,12 +678,15 @@ export class EditorClient {
     definition: AssetPreviewShotSetDefinition,
     options: AssetPreviewOptions = {},
   ): Promise<LabeledShotSetCapture> {
-    const data = await this.command<LabeledShotSetCapture>({
-      type: 'capture-asset-preview',
-      ...source,
-      ...options,
-      shotSet: definition,
-    });
+    const data = await this.command<LabeledShotSetCapture>(
+      {
+        type: 'capture-asset-preview',
+        ...source,
+        ...options,
+        shotSet: definition,
+      },
+      { retryTransport: true },
+    );
     return {
       width: data.width,
       height: data.height,
@@ -588,6 +775,13 @@ export class EditorClient {
     await this.command({ type: 'open-asset-tab', path, kind });
   }
 
+  /** SELECT a project asset — the other half of the browser's
+   *  selection-vs-open contract (single click selects and fills the
+   *  Inspector; double click opens a document). */
+  async selectAsset(path: string): Promise<void> {
+    await this.command({ type: 'select-asset', path });
+  }
+
   /** Generate a project-owned native Rapier ragdoll from a rigged model asset. */
   async generateRagdoll(assetPath: string): Promise<RagdollGenerationResult> {
     return this.command<RagdollGenerationResult>({ type: 'generate-ragdoll', assetPath });
@@ -605,6 +799,14 @@ export class EditorClient {
     await this.command({ type: 'toggle-console' });
   }
 
+  /** Switch the editor's NAMED WORKSPACE — the task-named layout memory
+   *  (`game`/`model`/`sculpt`/`texture`/`animate`/`look`). Resolves once the
+   *  dock has finished rebuilding, so a following capture photographs the
+   *  arrangement that was asked for. */
+  async setWorkspace(workspace: EditorWorkspaceName): Promise<void> {
+    await this.command({ type: 'set-workspace', workspace });
+  }
+
   async showBuild(): Promise<void> {
     await this.command({ type: 'show-build' });
   }
@@ -645,6 +847,26 @@ export class EditorClient {
     return data.subject;
   }
 
+  /**
+   * One STRUCTURE op on the authored tree — the hierarchy context menu's own
+   * verbs, on the same helpers, for a caller with no pointer to right-click
+   * with. `id`/`ids` default to the current selection.
+   */
+  async structureOp(op: StructureOp, options: StructureOpOptions = {}): Promise<StructureOpResult> {
+    return this.command<StructureOpResult>({ type: 'structure-op', op, ...options });
+  }
+
+  /** "Extract Component…" — the hierarchy row's action, as a command. Answers
+   *  the action's own sentence, which NAMES the files it created. */
+  async extractComponent(options: { id?: string; name?: string } = {}): Promise<{ hint: string }> {
+    return this.command<{ hint: string }>({ type: 'extract-component', ...options });
+  }
+
+  /** "Fork Component…" — extract's twin: one new file, one callsite retargeted. */
+  async forkComponent(options: { id?: string } = {}): Promise<{ hint: string }> {
+    return this.command<{ hint: string }>({ type: 'fork-component', ...options });
+  }
+
   /**
    * The HIERARCHY PANEL's actual rendered row tree, as data.
    *
@@ -672,6 +894,11 @@ export class EditorClient {
     return data.hierarchy;
   }
 
+  /** Run the Hierarchy panel's own Expand All action. */
+  async expandHierarchyAll(): Promise<void> {
+    await this.command<Record<string, never>>({ type: 'expand-hierarchy-all' });
+  }
+
   /**
    * Write one editable path through the active Inspector's own IO.
    *
@@ -758,11 +985,33 @@ export class EditorClient {
     return data.view;
   }
 
-  /** Capture the active center document exactly as presented to the user. */
-  async captureActiveDocument(size?: number): Promise<ActiveDocumentCapture> {
+  /**
+   * Capture the active center document exactly as presented to the user.
+   *
+   * A number is a SQUARE of that size (the default shape); `{width, height}`
+   * asks for a shaped frame — a video-aspect look that needs no crop. Both are
+   * bounded by the relay budget; see {@link CaptureDimensions}.
+   */
+  /** Photograph the editor PAGE itself — every panel, as the person sees it.
+   *  The sighted door for chrome: skins, workspaces and contributed panels are
+   *  judged through this, never through DOM probes. */
+  async captureEditorChrome(): Promise<EditorChromeCapture> {
+    return this.command<EditorChromeCapture>({ type: 'capture-editor-chrome' });
+  }
+
+  /** With a view, present and capture it in one request so document discovery
+   * cannot retarget the capture between two client calls. */
+  async captureActiveDocument(
+    size?: CaptureDimensions,
+    view?: EditorView,
+  ): Promise<ActiveDocumentCapture> {
     return this.command<ActiveDocumentCapture>({
       type: 'capture-active-document',
-      ...(size === undefined ? {} : { size }),
+      ...(view ? { view } : {}),
+      ...(typeof size === 'number' ? { size } : {}),
+      ...(typeof size === 'object' && size !== null
+        ? { width: size.width, height: size.height }
+        : {}),
     });
   }
 
@@ -778,6 +1027,17 @@ export class EditorClient {
     return this.command<DocumentProbeResult>({ type: 'document-probe', step });
   }
 
+  /**
+   * Run a wire-carried step against the ACTIVE document's published context
+   * (`packages/editor/src/document-context-registry.ts`) — the REPL door over
+   * an open document, in Edit mode. `src` is the step's own `toString()`;
+   * same serialization contract as `page-script` (no closures survive).
+   */
+  async documentScript<T = unknown>(src: string): Promise<T> {
+    const outcome = await this.command<{ result: T }>({ type: 'document-script', src });
+    return outcome.result;
+  }
+
   // --- Display (set semantics) ---
 
   async setGrid(enabled: boolean): Promise<void> {
@@ -827,7 +1087,7 @@ export class EditorClient {
     template: ProjectTemplate = 'default',
     exampleId?: string,
   ): Promise<ProjectInfo> {
-    const res = await fetch(`${this.baseUrl}/__editor/create-project`, {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/create-project`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ name, location, template, ...(exampleId ? { exampleId } : {}) }),
@@ -845,7 +1105,7 @@ export class EditorClient {
   }
 
   async openProject(path: string): Promise<void> {
-    const res = await fetch(`${this.baseUrl}/__editor/open-project`, {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/open-project`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ path }),
@@ -857,14 +1117,14 @@ export class EditorClient {
   }
 
   async getProject(): Promise<ProjectInfo | null> {
-    const res = await fetch(`${this.baseUrl}/__editor/project`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/project`);
     const data = (await this.readJson(res)) as { project: ProjectInfo | null; error?: string };
     if (!res.ok) throw new Error(data.error ?? `Failed to get project: ${res.status}`);
     return data.project;
   }
 
   async listRecentProjects(): Promise<RecentProject[]> {
-    const res = await fetch(`${this.baseUrl}/__editor/recent-projects`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/recent-projects`);
     const data = (await this.readJson(res)) as { projects: RecentProject[]; error?: string };
     if (!res.ok) throw new Error(data.error ?? `Failed to list projects: ${res.status}`);
     return data.projects;
@@ -876,7 +1136,7 @@ export class EditorClient {
    * The editor server loads callable metadata in Node; modules never enter the
    * editor browser merely because they were listed. */
   async listProjectTools(): Promise<ProjectToolCatalog> {
-    const res = await fetch(`${this.baseUrl}/__editor/project-tools`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/project-tools`);
     const body = await this.readJson(res);
     if (!res.ok) throw new Error(`Failed to list project tools: ${res.status}`);
     return body as ProjectToolCatalog;
@@ -889,7 +1149,7 @@ export class EditorClient {
     input: unknown = {},
     options: { confirm?: boolean; instance?: string } = {},
   ): Promise<ProjectToolOutcome> {
-    const res = await fetch(`${this.baseUrl}/__editor/project-tools/run`, {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/project-tools/run`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
@@ -914,7 +1174,7 @@ export class EditorClient {
   /** Read the one project-local generation job ledger. Provider-native
    * request/result shapes remain on their registered operations. */
   async listGenerationJobs(): Promise<GenerationJobsDocument> {
-    const res = await fetch(`${this.baseUrl}/__editor/generations`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/generations`);
     const body = await this.readJson(res);
     if (!res.ok) throw new Error(`Failed to list generation jobs: ${res.status}`);
     return body as GenerationJobsDocument;
@@ -923,9 +1183,12 @@ export class EditorClient {
   /** Forget operational job state. Accepted provenance and project assets
    * are deliberately unaffected. */
   async forgetGenerationJob(id: string): Promise<boolean> {
-    const res = await fetch(`${this.baseUrl}/__editor/generations/${encodeURIComponent(id)}`, {
-      method: 'DELETE',
-    });
+    const res = await this.httpFetch(
+      `${this.baseUrl}/__editor/generations/${encodeURIComponent(id)}`,
+      {
+        method: 'DELETE',
+      },
+    );
     const body = (await this.readJson(res)) as { removed?: boolean; error?: string };
     if (!res.ok) throw new Error(body.error ?? `Failed to forget generation job: ${res.status}`);
     return body.removed === true;
@@ -936,7 +1199,7 @@ export class EditorClient {
   async getLogEntries(): Promise<
     Array<{ t: number; level: string; msg: string; source?: string }>
   > {
-    const res = await fetch(`${this.baseUrl}/__editor/log-entries`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/log-entries`);
     const data = (await this.readJson(res)) as {
       entries: Array<{ t: number; level: string; msg: string; source?: string }>;
     };
@@ -947,7 +1210,7 @@ export class EditorClient {
   // --- State ---
 
   async getState(): Promise<EditorState> {
-    const res = await fetch(`${this.baseUrl}/__editor/state`);
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/state`);
     const state = (await this.readJson(res)) as EditorState;
     if (!res.ok) throw new Error(`Failed to get editor state: ${res.status} ${res.statusText}`);
     return state;
@@ -965,7 +1228,7 @@ export class EditorClient {
    * a thrown error the caller treats as "nothing learned", never a hang.
    */
   async getUnresolvedConsole(opts?: { all?: boolean }): Promise<unknown> {
-    const res = await fetch(
+    const res = await this.httpFetch(
       `${this.baseUrl}/__editor/console${opts?.all === true ? '?all=1' : ''}`,
       { signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS) },
     );
@@ -985,7 +1248,7 @@ export class EditorClient {
     readonly reason: string;
     readonly by: string;
   }): Promise<unknown> {
-    const res = await fetch(`${this.baseUrl}/__editor/console/ack`, {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/console/ack`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(input),
@@ -995,6 +1258,33 @@ export class EditorClient {
     return body;
   }
 
+  /**
+   * `fetch` for this client's plain routes, with the ONE thing Node's `fetch`
+   * will not do: name why it failed.
+   *
+   * `readJson` below already owns "the server answered the wrong thing"; this
+   * owns "nothing answered at all", which used to reach the caller as the bare
+   * `TypeError: fetch failed` with the real code buried on `.cause`. No retry
+   * here — these routes create projects, run tools and acknowledge console
+   * conditions, so repeating one is the caller's decision. The relayed
+   * `command` path above has its own opt-in retry for the read-only captures.
+   */
+  private async httpFetch(url: string, init?: RequestInit): Promise<Response> {
+    try {
+      return await fetch(url, init);
+    } catch (error) {
+      if ((error as { name?: string } | null)?.name === 'TimeoutError') throw error;
+      const { code, detail } = describeFetchFailure(error);
+      throw new EditorCommandError(
+        `${init?.method ?? 'GET'} ${url} never reached the editor: ${code}` +
+          `${detail ? ` (${detail})` : ''}. Nothing answered on that port — check the terminal ` +
+          'running `vgai edit`, and `vgai sessions` for the port this client resolved.',
+        code,
+        false,
+      );
+    }
+  }
+
   /** Parse one JSON body and hand it to {@link onEnvelope}.
    *
    * A command/state envelope carries current counts but not the named set. If
@@ -1033,7 +1323,7 @@ export class EditorClient {
       'unresolvedConsole' in body
     ) {
       try {
-        const consoleRes = await fetch(`${this.baseUrl}/__editor/console`, {
+        const consoleRes = await this.httpFetch(`${this.baseUrl}/__editor/console`, {
           signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS),
         });
         if (consoleRes.ok) {