@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/editor-server.ts

@@ -7,19 +7,43 @@
 
 import { type ChildProcess, execFile, spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { appendFile, mkdir, readdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import type { ServerResponse } from 'node:http';
 import { homedir, platform } from 'node:os';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import chokidar, { type FSWatcher } from 'chokidar';
 import { type ScaffoldTemplate, scaffoldProject } from 'create-vgai-project';
 import type { Request, Response, Router } from 'express';
 import express from 'express';
+import { GAME_MANIFEST_VERSION } from '../../engine/src/manifest/schema';
 import { applyAssetRename } from '../../engine/src/scene/asset-paths';
 import type { SceneFile } from '../../engine/src/scene/scene-types';
+import {
+  assertEditorCompatibility,
+  assertProjectCompatibility,
+  type EditorServerCompatibility,
+  ProjectCompatibilityError,
+} from '../src/editor-compatibility';
+import { parseHarnessChatAction } from '../src/harness-chat-types';
 import { createAssetLibraryRouter } from './asset-library-routes';
 import { canonicalProjectRoot } from './canonical-path';
-import { addClient, broadcast, clientCount, removeClient } from './editor-sse';
+import {
+  addClient,
+  broadcast,
+  clientCount,
+  controllerClientId,
+  removeClient,
+  sendToController,
+  updateClientControlHealth,
+} from './editor-sse';
+import { HarnessChatService } from './harness-chat-service';
+import {
+  discoverProjectOperations,
+  executeProjectOperation,
+  type ProjectModuleLoader,
+} from './project-operations';
+import { classifyValidatableFile, validateProjectFile } from './project-validation';
 import { readProjectView } from './project-view';
 import type { CommandResult } from './server-utils';
 import {
@@ -33,6 +57,7 @@ import {
   isServableFsExtension,
   PACKAGED_NO_MONOREPO_TEMPLATE_ERROR,
   resolveInstalledPackageSrcDir,
+  resolveWatcherPollOptions,
   sanitizeContentDispositionFilename,
   validateManifestWrite,
 } from './server-utils';
@@ -64,8 +89,8 @@ async function loadRecentProjects(): Promise<RecentProject[]> {
     // Filter out projects whose paths no longer exist, populate thumbnails
     const valid: RecentProject[] = [];
     for (const p of projects) {
-      // §1C: a manifest-only folder (no project.json) is still a valid
-      // recent project — readProjectView is the one place this rule lives.
+      // A folder with a valid v2 manifest is a project; readProjectView is
+      // the one place this rule lives.
       const view = await readProjectView(p.path);
       if (!view) continue; // Path no longer exists / neither file describes it — skip
       // Check for thumbnail
@@ -114,6 +139,28 @@ export interface EditorServerOptions {
   serveScripts?: boolean;
   /** Called when a project is opened at runtime — allows the dev server to update Vite's fs.allow. */
   onProjectOpened?: ((projectPath: string) => void) | undefined;
+  /** Dev checkout only: mark this long-running process stale when server-loaded source changes. */
+  watchEngineSource?: boolean | undefined;
+  /** Node-side project-module loader. Vite's ssrLoadModule supplies this in
+   * dev and packaged editors so discoverable project operations can remain
+   * ordinary TypeScript using the project's own dependency graph. */
+  loadProjectModule?: ProjectModuleLoader | undefined;
+}
+
+function readRunningEngineVersion(engineRoot: string): string | null {
+  const candidates = [
+    join(engineRoot, 'packages', 'engine', 'package.json'),
+    join(engineRoot, 'node_modules', '@vgai', 'engine', 'package.json'),
+  ];
+  for (const path of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown };
+      if (typeof parsed.version === 'string') return parsed.version;
+    } catch {
+      // Try the next supported checkout/installed-package layout.
+    }
+  }
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -158,6 +205,14 @@ async function findFiles(dir: string, ext: string): Promise<string[]> {
   return results;
 }
 
+async function unlinkIfPresent(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+
 async function scanDirForHashes(
   dir: string,
   hashCache: Map<string, string>,
@@ -209,12 +264,74 @@ const mimeTypes: Record<string, string> = {
 // Factory
 // ---------------------------------------------------------------------------
 
-export function createEditorServer(options: EditorServerOptions): Router {
+export type EditorServerRouter = Router & { close(): Promise<void> };
+
+export function createEditorServer(options: EditorServerOptions): EditorServerRouter {
   const { engineRoot } = options;
+  const serverStartedAt = new Date().toISOString();
+  const runningEngineVersion = readRunningEngineVersion(engineRoot);
+  let staleSource: { changedPath: string; changedAt: string } | null = null;
+  let engineSourceWatcher: FSWatcher | null = null;
+
+  if (options.watchEngineSource) {
+    const watchedPaths = [
+      join(engineRoot, 'packages', 'editor', 'server'),
+      join(engineRoot, 'packages', 'engine', 'src'),
+      join(engineRoot, 'packages', 'create-vgai-project', 'src'),
+      join(engineRoot, 'vite.config.ts'),
+      join(engineRoot, 'package.json'),
+      join(engineRoot, 'package-lock.json'),
+      join(engineRoot, 'tsconfig.json'),
+      join(engineRoot, 'tsconfig.server.json'),
+      join(engineRoot, 'packages', 'engine', 'package.json'),
+      join(engineRoot, 'packages', 'editor', 'package.json'),
+    ].filter(existsSync);
+    engineSourceWatcher = chokidar.watch(watchedPaths, {
+      ignoreInitial: true,
+      ignored: (watchedPath) => {
+        const name = basename(watchedPath);
+        return name.startsWith('.') || name.endsWith('~') || /\.(?:swp|swo|tmp|temp)$/i.test(name);
+      },
+    });
+    engineSourceWatcher.on('all', (_event, changedPath: string) => {
+      staleSource ??= {
+        changedPath: relative(engineRoot, resolve(changedPath)).split(sep).join('/'),
+        changedAt: new Date().toISOString(),
+      };
+    });
+  }
 
   // Mutable project state — updated by open-project endpoint
   let projectRoot = options.projectPath ?? engineRoot;
   let publicRoot = resolve(projectRoot, 'public');
+  const harnessChat = new HarnessChatService({
+    engineRoot,
+    getProjectRoot: () => projectRoot,
+    onChange: (snapshot) => broadcast('harness-chat', snapshot),
+  });
+
+  const compatibilityIdentity = (): EditorServerCompatibility => ({
+    apiVersion: 1,
+    engineVersion: runningEngineVersion,
+    manifestVersion: GAME_MANIFEST_VERSION,
+    startedAt: serverStartedAt,
+    source: staleSource ? { state: 'restart-required', ...staleSource } : { state: 'current' },
+  });
+
+  // #run2-cold-vite: last time this server served the editor's own INDEX
+  // page (as opposed to an API/SSE/asset request) to a browser. Detected by
+  // response Content-Type rather than by route/path, because the index page
+  // is served by three different mechanisms depending on mode (Vite's dev
+  // middleware at `/` in dev.ts, `express.static` + SPA fallback in
+  // prod.ts, the packaged server's own fallback) and none of those routes
+  // are owned by this file. Exposed on `/__editor/state` so the CLI's
+  // verified-open polling (`waitForVerifiedEditorOpen` in
+  // packages/vgai-cli/src/editor-sessions.ts) can tell "the browser tab
+  // arrived and is loading" apart from "the auto-open never reached a
+  // browser at all" — the distinction a cold Vite dep-optimize on drvfs
+  // needs, since that alone can blow past the old flat 15s timeout on a
+  // project's very first page load.
+  let lastIndexRequestAt: number | null = null;
 
   // ---- File hash cache + move detection ----
   const fileHashCache = new Map<string, string>();
@@ -277,6 +394,7 @@ export function createEditorServer(options: EditorServerOptions): Router {
   // ---- Chokidar watcher ----
   let watcher: FSWatcher | null = null;
   let srcWatcher: FSWatcher | null = null;
+  let manifestWatcher: FSWatcher | null = null;
 
   // Coalesce event bursts (e.g. a git checkout adding several files at once)
   // into one broadcast per event name, trailing ~250ms after the last event.
@@ -293,20 +411,165 @@ export function createEditorServer(options: EditorServerOptions): Router {
     );
   }
 
+  // ---- Validate-on-change (owner decision, GitHub #103) ----
+  //
+  // Hand-editing project files is an accepted authoring path — the
+  // requirement is that invalid output surfaces IMMEDIATELY and OBVIOUSLY
+  // instead of only erroring at next load. `project-validation.ts` owns the
+  // content check (reusing the engine's own Zod parsers, same ones
+  // validate-scenes.ts/validate-manifest.ts run); this section owns
+  // debouncing + the three report surfaces: the terminal, connected editor
+  // tabs (the existing `server-log` SSE event `editor-console.ts` already
+  // listens for — previously unused, since nothing ever broadcast it), and
+  // `/__editor/state`'s `projectValidation` field.
+  //
+  // A file is present in `projectValidation` ONLY while it is currently
+  // failing — a valid write removes its entry entirely ("ok" is represented
+  // by absence, not a stored value), which is what keeps the happy path
+  // silent both on the wire and in the terminal (rule 4: editor-originated
+  // autosaves validate clean by construction and must produce zero noise).
+  interface FileValidationFailure {
+    errors: string[];
+    at: number;
+  }
+  const projectValidation = new Map<string, FileValidationFailure>();
+  const validationDebounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const VALIDATION_DEBOUNCE_MS = 150;
+  const MAX_PRINTED_ERRORS = 5;
+
+  /** Project-relative, forward-slash path — the key `projectValidation` and
+   *  the terminal/SSE messages use. */
+  function relKey(absPath: string): string {
+    return relative(projectRoot, absPath).split(sep).join('/');
+  }
+
+  function printValidationFailure(rel: string, errors: string[]): void {
+    const shown = errors.slice(0, MAX_PRINTED_ERRORS);
+    const rest = errors.length - shown.length;
+    console.error(
+      `\n  \x1b[31m\x1b[1m✖ Invalid project file\x1b[0m \x1b[36m${rel}\x1b[0m\n` +
+        shown.map((e) => `    \x1b[31m•\x1b[0m ${e}`).join('\n') +
+        (rest > 0 ? `\n    … and ${rest} more issue(s)` : '') +
+        '\n',
+    );
+  }
+
+  function printValidationRecovery(rel: string): void {
+    console.log(`  \x1b[32m✓ ${rel} is valid again\x1b[0m`);
+  }
+
+  function validationMessage(rel: string, errors: string[]): string {
+    const shown = errors.slice(0, MAX_PRINTED_ERRORS);
+    const rest = errors.length - shown.length;
+    return (
+      `Invalid project file ${rel}:\n` +
+      shown.map((e) => `  - ${e}`).join('\n') +
+      (rest > 0 ? `\n  … and ${rest} more issue(s)` : '')
+    );
+  }
+
+  /** Run (already-debounced) validation for one absolute path and report the
+   *  result on all three surfaces. Non-validatable paths are a silent no-op
+   *  so callers can invoke this unconditionally from watcher events. */
+  async function runFileValidation(absPath: string): Promise<void> {
+    const kind = classifyValidatableFile(absPath);
+    if (!kind) return;
+    const rel = relKey(absPath);
+    const result = await validateProjectFile(absPath, kind);
+    const wasFailing = projectValidation.has(rel);
+
+    if (result.ok) {
+      if (wasFailing) {
+        projectValidation.delete(rel);
+        printValidationRecovery(rel);
+        broadcast('server-log', { level: 'info', message: `${rel} is valid again` });
+      }
+      // Clean write, never previously failing — the happy-path silence rule:
+      // no terminal line, no broadcast, no state entry.
+      return;
+    }
+
+    projectValidation.set(rel, { errors: result.errors, at: Date.now() });
+    printValidationFailure(rel, result.errors);
+    broadcast('server-log', { level: 'error', message: validationMessage(rel, result.errors) });
+  }
+
+  /** Debounce per absolute file path (~150ms) so a burst of writes to the
+   *  same file (editors/OSes routinely write-then-touch, or write in two
+   *  chunks) triggers exactly one validation pass. */
+  function scheduleFileValidation(absPath: string): void {
+    if (!classifyValidatableFile(absPath)) return;
+    const existing = validationDebounceTimers.get(absPath);
+    if (existing) clearTimeout(existing);
+    validationDebounceTimers.set(
+      absPath,
+      setTimeout(() => {
+        validationDebounceTimers.delete(absPath);
+        void runFileValidation(absPath);
+      }, VALIDATION_DEBOUNCE_MS),
+    );
+  }
+
+  /** A deleted file can no longer be "invalid" — drop any stale entry/timer
+   *  so `projectValidation` doesn't keep reporting a ghost error. */
+  function clearFileValidation(absPath: string): void {
+    const timer = validationDebounceTimers.get(absPath);
+    if (timer) {
+      clearTimeout(timer);
+      validationDebounceTimers.delete(absPath);
+    }
+    projectValidation.delete(relKey(absPath));
+  }
+
+  async function validateSourceTree(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    await Promise.all(
+      entries
+        .filter((entry) => !entry.name.startsWith('.'))
+        .map(async (entry) => {
+          const full = join(dir, entry.name);
+          if (entry.isDirectory()) return validateSourceTree(full);
+          if (entry.isFile()) return runFileValidation(full);
+        }),
+    );
+  }
+
   function startWatcher(): void {
     watcher?.close();
     srcWatcher?.close();
+    manifestWatcher?.close();
     srcWatcher = null;
+    manifestWatcher = null;
     fileHashCache.clear();
     fileSizeCache.clear();
     pendingUnlinks.length = 0;
+    // Validation state is project-scoped — a previous project's failures
+    // must not leak into (or block reporting for) the newly opened one.
+    for (const timer of validationDebounceTimers.values()) clearTimeout(timer);
+    validationDebounceTimers.clear();
+    projectValidation.clear();
 
     // Seed hash cache in background
     scanDirForHashes(publicRoot, fileHashCache, fileSizeCache);
 
+    // #131: on drvfs (WSL /mnt/<drive>) inotify never fires, so without
+    // polling every broadcast below is dead and the editor UI sits stale
+    // until a manual refresh. Auto-detection keys off the PROJECT root and is
+    // skipped in engine-repo mode (projectRoot === engineRoot), where
+    // `public/` includes the vendored-game trees — `VGAI_WATCH_POLL` still
+    // forces it there. Re-derived on every startWatcher() call so a project
+    // switch onto/off a drvfs mount re-decides correctly.
+    const pollOptions = resolveWatcherPollOptions(projectRoot === engineRoot ? null : projectRoot);
+
     watcher = chokidar.watch(publicRoot, {
       ignoreInitial: true,
       ignored: /(^|[/\\])\../, // ignore dotfiles
+      ...pollOptions,
     });
 
     watcher.on('change', async (filePath: string) => {
@@ -330,11 +593,17 @@ export function createEditorServer(options: EditorServerOptions): Router {
           /* file may have been deleted between events */
         }
       }
+
+      // Validate-on-change (#103): a hand-edited (or autosaved) .vscn.json/
+      // .prefab.json content change gets checked against the engine's own
+      // Zod parsers — see the "Validate-on-change" section above.
+      scheduleFileValidation(abs);
     });
 
     watcher.on('unlink', (filePath: string) => {
       const abs = resolve(filePath);
       if (!isPathInside(publicRoot, abs)) return;
+      clearFileValidation(abs);
       const hash = fileHashCache.get(abs);
       const size = fileSizeCache.get(abs);
       if (hash !== undefined && size !== undefined) {
@@ -348,6 +617,9 @@ export function createEditorServer(options: EditorServerOptions): Router {
     watcher.on('add', async (filePath: string) => {
       const abs = resolve(filePath);
       if (!isPathInside(publicRoot, abs)) return;
+      // A brand-new scene/prefab file (not just an edit of an existing one)
+      // deserves the same immediate check.
+      scheduleFileValidation(abs);
 
       try {
         const { hash, size } = await hashAndSize(abs);
@@ -382,30 +654,64 @@ export function createEditorServer(options: EditorServerOptions): Router {
     // packaged/prod (this module is shared by both), and on drvfs
     // (`/mnt/c`, no inotify) via the same `VGAI_WATCH_POLL` env var.
     //
-    // add/unlink ONLY, never `change`: tool-content edits already ride the
-    // existing `vgai:script-update` HMR path, and a data-file `change` event
-    // would echo the DataPanel's own `/__editor/data-file` POST writes back
-    // into a refetch, clobbering in-flight drafts.
+    // Tool/data/story lists use add/unlink. Operation modules also use change:
+    // they are Node-loaded rather than browser-HMR-loaded, so metadata and
+    // implementation edits require a fresh catalog request.
     const srcDir = join(projectRoot, 'src');
     if (projectRoot !== engineRoot && existsSync(srcDir)) {
-      // Same parse as dev.ts's `startProjectPollWatcher` (VGAI_WATCH_POLL=1,
-      // or =<ms> for the interval).
-      const pollRaw = Number(process.env['VGAI_WATCH_POLL']);
+      // #131: same polling decision as the publicRoot watcher above (env
+      // contract matches dev.ts's poller; auto-on for drvfs projects).
       srcWatcher = chokidar.watch(srcDir, {
         ignoreInitial: true,
         ignored: /(^|[/\\])\../, // ignore dotfiles
-        ...(process.env['VGAI_WATCH_POLL']
-          ? { usePolling: true, interval: pollRaw > 1 ? pollRaw : 1000 }
-          : {}),
+        ...pollOptions,
       });
       const onListChange = (filePath: string) => {
         const rel = relative(projectRoot, resolve(filePath)).split(sep).join('/');
         const kind = classifyProjectSrcPath(rel);
-        if (kind === 'tools') broadcastDebounced('tool-files-changed', { path: rel });
-        else if (kind === 'data') broadcastDebounced('data-files-changed', { path: rel });
+        const event = kind
+          ? {
+              tools: 'tool-files-changed',
+              data: 'data-files-changed',
+              stories: 'story-files-changed',
+              operations: 'operation-files-changed',
+            }[kind]
+          : undefined;
+        if (event) broadcastDebounced(event, { path: rel });
       };
       srcWatcher.on('add', onListChange);
       srcWatcher.on('unlink', onListChange);
+      // Tool edits ride Vite HMR and data edits have their own live-value
+      // path. Node-loaded project operations instead need a fresh catalog
+      // read when metadata or implementation changes in place.
+      srcWatcher.on('change', (filePath) => {
+        const rel = relative(projectRoot, resolve(filePath)).split(sep).join('/');
+        if (classifyProjectSrcPath(rel) === 'operations') {
+          broadcastDebounced('operation-files-changed', { path: rel });
+        }
+      });
+      srcWatcher.on('add', (filePath) => scheduleFileValidation(resolve(filePath)));
+      srcWatcher.on('change', (filePath) => scheduleFileValidation(resolve(filePath)));
+      srcWatcher.on('unlink', (filePath) => clearFileValidation(resolve(filePath)));
+      void validateSourceTree(srcDir);
+    }
+
+    // ---- Third watcher: <project>/vgai.game.json (#103 validate-on-change) ----
+    //
+    // The manifest lives at the PROJECT ROOT, outside both `publicRoot` and
+    // `src/` — neither watcher above ever sees it. It's a single fixed-name
+    // file, so this watches that exact path rather than a directory (chokidar
+    // supports watching a not-yet-existing file and reports its later `add`).
+    if (projectRoot !== engineRoot) {
+      const manifestPath = join(projectRoot, 'vgai.game.json');
+      // #131: same polling decision as the watchers above.
+      manifestWatcher = chokidar.watch(manifestPath, {
+        ignoreInitial: true,
+        ...pollOptions,
+      });
+      manifestWatcher.on('add', () => scheduleFileValidation(manifestPath));
+      manifestWatcher.on('change', () => scheduleFileValidation(manifestPath));
+      manifestWatcher.on('unlink', () => clearFileValidation(manifestPath));
     }
   }
 
@@ -428,11 +734,25 @@ export function createEditorServer(options: EditorServerOptions): Router {
 
   // ---- Editor command relay + state ----
   let editorState: Record<string, unknown> = {};
+  const editorStatesByClient = new Map<
+    string,
+    { state: Record<string, unknown>; updatedAt: number }
+  >();
+  // When `editorState` was last POSTed by a browser tab (epoch ms), so a
+  // caller reading a cached snapshot (no live SSE client, `connected: false`
+  // below) can say HOW STALE it is instead of just THAT it's stale. `null`
+  // until the first POST of this server's lifetime (or after a project
+  // switch clears the cache).
+  let editorStateUpdatedAt: number | null = null;
 
   // Pending command results — keyed by requestId, resolved by browser POST
   const pendingCommands = new Map<
     string,
-    { resolve: (result: CommandResult) => void; timer: ReturnType<typeof setTimeout> }
+    {
+      resolve: (result: CommandResult) => void;
+      timer: ReturnType<typeof setTimeout>;
+      controller?: ServerResponse;
+    }
   >();
   const COMMAND_TIMEOUT_MS = 5000;
   // `play` is the one command whose ack is gated on the GAME, not the editor:
@@ -442,11 +762,70 @@ export function createEditorServer(options: EditorServerOptions): Router {
   // "editor connected but did not respond" while play in fact proceeded and
   // succeeded (hit dogfooding a voxel game whose worldgen alone outlives 5s).
   const PLAY_COMMAND_TIMEOUT_MS = 120_000;
+  // `stop`'s ack is gated on teardown the same way play's is gated on setup:
+  // `exitPlayMode()` disposes the whole game (component dispose chain, Rapier
+  // world free, renderer teardown). Under software rendering (SwiftShader on
+  // a headless/CI box) that routinely outlives the generic 5s window — the
+  // command reported "did not respond" while the stop in fact completed
+  // (dogfooded 2026-07-12 on a scaffolded project). 30s is generous for any
+  // teardown while still failing fast relative to play's 120s setup budget.
+  const STOP_COMMAND_TIMEOUT_MS = 30_000;
+  // Asset Lab capture loads a local model, renders four deterministic views,
+  // and encodes five PNGs before acknowledging. Give that bounded local job a
+  // real rendering budget instead of the generic interaction timeout.
+  const ASSET_PREVIEW_COMMAND_TIMEOUT_MS = 30_000;
+
+  /** Fail every in-flight command with one error — used when the last SSE
+   *  client goes away: a reloaded page has no memory of the requestId it was
+   *  supposed to answer, so waiting out the timer only delays the inevitable
+   *  (and mislabels a reload as "editor did not respond"). */
+  function failPendingCommands(error: string): void {
+    for (const [id, pending] of pendingCommands) {
+      clearTimeout(pending.timer);
+      pendingCommands.delete(id);
+      pending.resolve({ ok: false, timedOut: true, error });
+    }
+  }
+
+  function failCommandsOwnedBy(controller: ServerResponse): void {
+    for (const [id, pending] of pendingCommands) {
+      if (pending.controller !== controller) continue;
+      clearTimeout(pending.timer);
+      pendingCommands.delete(id);
+      pending.resolve({
+        ok: false,
+        timedOut: true,
+        error: 'The editor tab controlling this command disconnected before reporting a result.',
+      });
+    }
+  }
 
   // ---- Router ----
-  const router = express.Router();
+  const router = express.Router() as EditorServerRouter;
   router.use(express.json({ limit: '50mb' }));
 
+  // ---- Cold-Vite verified-open signal ----
+  // Stamp `lastIndexRequestAt` for any GET response that turns out to be
+  // genuine HTML (status 2xx, `Content-Type: text/html…`) — that is, purely
+  // observational, via `res.on('finish')`, so it applies no matter which
+  // downstream middleware (Vite, express.static, the SPA fallback) actually
+  // produced the response. API responses are JSON, SSE is
+  // `text/event-stream`, assets carry their own MIME types — none of those
+  // match, so only real page loads stamp.
+  router.use((req: Request, res: Response, next) => {
+    if (req.method === 'GET') {
+      res.on('finish', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          const contentType = res.get('Content-Type');
+          if (contentType?.includes('text/html')) {
+            lastIndexRequestAt = Date.now();
+          }
+        }
+      });
+    }
+    next();
+  });
+
   // ---- CSRF / drive-by protection (S3) ----
   // Mutating /__editor/* routes can write files, switch projects, and run npm
   // builds (RCE). A malicious web page could POST to a locally-bound editor; an
@@ -474,7 +853,7 @@ export function createEditorServer(options: EditorServerOptions): Router {
   );
 
   // ---- Project file serving middleware ----
-  // Serves project.json from root and static files from project's public/
+  // Serves the v2 manifest from root and static files from project's public/
   router.use((req: Request, res: Response, next) => {
     // Only handle non-API requests when a project is open
     if (projectRoot === engineRoot) return next();
@@ -485,24 +864,11 @@ export function createEditorServer(options: EditorServerOptions): Router {
     if (pathname.startsWith('/@')) return next();
     if (pathname.startsWith('/node_modules')) return next();
 
-    // Serve project.json (or its manifest-synthesized compat view — §1C)
-    // from the project root, not public/.
-    if (pathname === '/project.json') {
-      readProjectView(projectRoot)
-        .then((view) => {
-          if (!view) return next();
-          res.json(view);
-        })
-        .catch(() => next());
-      return;
-    }
-
     // Serve the RAW manifest (no view synthesis — the browser-side adapter
     // resolver parses it itself via the pure `@engine/manifest/load` half;
     // T3.3 slice 2 part C) from the project root, not public/. 404s (falls
     // through to `next()`, same as any other missing project-root file) for
-    // legacy `project.json`-only projects — that is what makes the manifest
-    // branch a no-op for them.
+    // folders without a valid manifest.
     if (pathname === '/vgai.game.json') {
       readFile(join(projectRoot, 'vgai.game.json'), 'utf-8')
         .then((raw) => {
@@ -530,6 +896,12 @@ export function createEditorServer(options: EditorServerOptions): Router {
       .catch(() => next());
   });
 
+  // ---- Browser/server compatibility identity ----
+  router.get('/__editor/compatibility', (_req: Request, res: Response) => {
+    res.set('Cache-Control', 'no-store');
+    res.json(compatibilityIdentity());
+  });
+
   // ---- Current project info ----
   router.get('/__editor/project', async (_req: Request, res: Response) => {
     if (projectRoot === engineRoot) {
@@ -570,37 +942,86 @@ export function createEditorServer(options: EditorServerOptions): Router {
       Connection: 'keep-alive',
     });
     res.write(':ok\n\n');
-    addClient(res);
-    req.on('close', () => removeClient(res));
+    const clientId = typeof req.query['clientId'] === 'string' ? req.query['clientId'] : undefined;
+    addClient(res, clientId);
+    req.on('close', () => {
+      removeClient(res);
+      failCommandsOwnedBy(res);
+      // Last tab gone with commands still in flight: nobody left can answer
+      // them (a reload mints a fresh page with no memory of the requestId),
+      // so fail them NOW with the real reason instead of letting the timer
+      // expire into a misleading "editor connected but did not respond".
+      // The classic trigger is a mid-command full page reload — e.g. Vite
+      // discovering/re-optimizing deps on a first play (dogfooded 2026-07-12:
+      // every first `vgai play` on a cold cache burned the full 120s window).
+      if (clientCount() === 0 && pendingCommands.size > 0) {
+        failPendingCommands(
+          'Editor page disconnected while the command was pending — usually a mid-command page ' +
+            'reload (e.g. Vite dep re-optimization on a cold cache) or a closed tab. ' +
+            'Reload the editor tab and retry the command.',
+        );
+      }
+    });
   });
 
-  // ---- Editor command relay ----
-  router.post('/__editor/command', (req: Request, res: Response) => {
-    const body = req.body as Record<string, unknown>;
+  // ---- Coding-harness Chat (Supercode) ----
+  // GET is a complete snapshot; mutations are one explicit action endpoint;
+  // live transcript/runtime changes ride the shared SSE connection above.
+  // Hiding/collapsing the browser panel calls neither route and therefore
+  // never changes ownership of a terminal-driven session.
+  router.get('/__editor/harness-chat', async (_req: Request, res: Response) => {
+    try {
+      res.json(await harnessChat.load(true));
+    } catch (error) {
+      res.status(503).json({ error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+
+  router.post('/__editor/harness-chat/action', async (req: Request, res: Response) => {
+    try {
+      const action = parseHarnessChatAction(req.body);
+      res.json(await harnessChat.act(action));
+    } catch (error) {
+      res.status(400).json({
+        error: error instanceof Error ? error.message : String(error),
+        snapshot: harnessChat.snapshot(),
+      });
+    }
+  });
 
+  // ---- Editor command relay ----
+  /** The relay round trip, extracted (#146) so POST `/__editor/command` and
+   *  the GET poke surface below share ONE implementation: fail fast with no
+   *  connected tab, assign a request id, deliver to the controller tab over
+   *  SSE, and resolve when `/__editor/command-result` reports back (or the
+   *  per-type timeout fires — SC1: a timeout means an editor IS connected
+   *  but did not answer, distinct from the no-editor case). */
+  function relayCommand(body: Record<string, unknown>): Promise<CommandResult> {
     // Fail fast when no editor browser tab holds a live SSE connection. Without
     // this, the command silently waits the full COMMAND_TIMEOUT_MS before a
     // generic timeout — and the caller can't tell "no editor open" from "editor
     // open but the command hung". `clientCount()` is the live SSE-client count,
     // so a 0 here is unambiguous: open the editor in a browser first.
     if (clientCount() === 0) {
-      const { status, body: respBody } = commandResponseFor({
+      return Promise.resolve({
         ok: false,
         timedOut: true,
         error: 'No editor connected — open the editor in a browser tab, then retry.',
       });
-      res.status(status).json(respBody);
-      return;
     }
 
     // Assign a request ID so the browser can report the result back
     const requestId = randomUUID();
     const commandWithId = { ...body, _requestId: requestId };
 
-    // Create a promise that resolves when the browser reports the result.
-    // SC1: a timeout here means an editor IS connected but did not answer in
-    // time (the command hung or threw) — distinct from the no-editor case above.
-    const timeoutMs = body['type'] === 'play' ? PLAY_COMMAND_TIMEOUT_MS : COMMAND_TIMEOUT_MS;
+    const timeoutMs =
+      body['type'] === 'play'
+        ? PLAY_COMMAND_TIMEOUT_MS
+        : body['type'] === 'stop'
+          ? STOP_COMMAND_TIMEOUT_MS
+          : body['type'] === 'capture-asset-preview'
+            ? ASSET_PREVIEW_COMMAND_TIMEOUT_MS
+            : COMMAND_TIMEOUT_MS;
     const resultPromise = new Promise<CommandResult>((resolve) => {
       const timer = setTimeout(() => {
         pendingCommands.delete(requestId);
@@ -613,9 +1034,30 @@ export function createEditorServer(options: EditorServerOptions): Router {
       pendingCommands.set(requestId, { resolve, timer });
     });
 
-    broadcast('editor-command', commandWithId);
+    // Commands mutate editor/game state, so exactly one browser tab owns each
+    // command. Ordinary notifications still broadcast to every tab.
+    const controller = sendToController('editor-command', commandWithId);
+    if (controller) {
+      const pending = pendingCommands.get(requestId);
+      if (pending) pending.controller = controller;
+    } else {
+      const pending = pendingCommands.get(requestId);
+      if (pending) {
+        clearTimeout(pending.timer);
+        pendingCommands.delete(requestId);
+        pending.resolve({
+          ok: false,
+          timedOut: true,
+          error: 'Editor disconnected before the command could be delivered.',
+        });
+      }
+    }
+
+    return resultPromise;
+  }
 
-    resultPromise.then((result) => {
+  router.post('/__editor/command', (req: Request, res: Response) => {
+    relayCommand(req.body as Record<string, unknown>).then((result) => {
       const { status, body } = commandResponseFor(result);
       res.status(status).json(body);
     });
@@ -639,20 +1081,153 @@ export function createEditorServer(options: EditorServerOptions): Router {
   });
 
   // ---- Editor state (browser reports / CLI reads) ----
-  router.get('/__editor/state', (_req: Request, res: Response) => {
+  router.get('/__editor/state', async (_req: Request, res: Response) => {
     // `editorState` is the last snapshot a browser POSTed; it persists even
     // after every tab closes. Stamp the response with the LIVE SSE client count
     // so callers can distinguish "an editor is attached now" from "this is stale
     // cache from a tab that has since gone away".
     const connected = clientCount();
-    res.json({ ...editorState, editorsConnected: connected, connected: connected > 0 });
+    const controlledState = (() => {
+      const clientId = controllerClientId();
+      return clientId ? editorStatesByClient.get(clientId) : undefined;
+    })();
+    const state = controlledState?.state ?? editorState;
+    const stateUpdatedAt = controlledState?.updatedAt ?? editorStateUpdatedAt;
+    // #124: project identity, server-computed exactly like `projectValidation`
+    // below (never part of the browser-POSTed snapshot) — lets a watcher/relay
+    // holding only a port number tell which project that port serves. Mirrors
+    // `/__editor/project`'s own `projectRoot === engineRoot` -> "no project"
+    // convention rather than introducing a new one.
+    const projectOpen = projectRoot !== engineRoot;
+    const view = projectOpen ? await readProjectView(projectRoot) : null;
+    const nameField = view?.['name'];
+    res.json({
+      ...state,
+      editorsConnected: connected,
+      connected: connected > 0,
+      // #run2-cold-vite: null until the FIRST genuine index-page GET this
+      // server has served (see the response-observing middleware above).
+      lastIndexRequestAt,
+      ...(stateUpdatedAt !== null ? { stateUpdatedAt } : {}),
+      // #103: server-computed (never part of the browser-POSTed snapshot
+      // above), so it's always current — a file present here is currently
+      // failing validation; a clean project reports `{}`. `vgai status`
+      // prints this whole object as-is, so no CLI changes were needed to
+      // surface it.
+      projectValidation: Object.fromEntries(projectValidation),
+      projectRoot: projectOpen ? projectRoot : null,
+      projectName: typeof nameField === 'string' ? nameField : null,
+    });
   });
 
   router.post('/__editor/state', (req: Request, res: Response) => {
-    editorState = req.body as Record<string, unknown>;
+    const reported = req.body as Record<string, unknown>;
+    const clientId = typeof reported['_clientId'] === 'string' ? reported['_clientId'] : null;
+    const { _clientId: _ignoredClientId, ...state } = reported;
+    const updatedAt = Date.now();
+    editorState = state;
+    editorStateUpdatedAt = updatedAt;
+    if (clientId) {
+      editorStatesByClient.set(clientId, { state, updatedAt });
+      const pageErrors = state['pageErrors'];
+      const presence = state['presence'];
+      const presenceRecord =
+        presence && typeof presence === 'object' ? (presence as Record<string, unknown>) : null;
+      updateClientControlHealth(clientId, {
+        errorState: Array.isArray(pageErrors)
+          ? pageErrors.length === 0
+            ? 'healthy'
+            : 'errored'
+          : 'unknown',
+        visible: presenceRecord?.['visibility'] === 'visible',
+        focused: presenceRecord?.['focused'] === true,
+        updatedAt,
+      });
+    }
     res.json({ ok: true });
   });
 
+  // ---- #146: the agent poke surface (docs/SHARED-SESSION-SPEC.md §3 rung 2)
+  //
+  // Plain-GET reads for the operations an agent repeats most — check state,
+  // check validation, grab a frame. Deliberately curl-shaped: no JSON body to
+  // quote, terse output, and bulky payloads returned as PATHS inside the
+  // project (never blobs — an agent's context budget is metered, and a
+  // sandboxed agent can read project-internal paths without permission
+  // prompts). Mutations stay on POST `/__editor/command`. The index below is
+  // the wire's self-discovery: arbitrary endpoint names are fine when
+  // queryable, fatal when memorized.
+  router.get('/__vgai', (_req: Request, res: Response) => {
+    res.json({
+      project: projectRoot !== engineRoot ? projectRoot : null,
+      connected: clientCount() > 0,
+      endpoints: {
+        'GET /__vgai': 'this index',
+        'GET /__vgai/state': 'every observable game-state provider (play mode must be running)',
+        'GET /__vgai/state/:provider': 'one provider, e.g. /__vgai/state/gemGame',
+        'GET /__vgai/validation':
+          'validate-on-save results for this project (failing: {} means clean)',
+        'GET /__vgai/screenshot':
+          'capture the live game canvas to <project>/.vgai/captures/<ts>.png and return its path',
+        'POST /__editor/command': 'the full command relay (bridge-call, play, stop, select, …)',
+      },
+    });
+  });
+
+  // The edit→verify loop's other half: after writing a scene/manifest/asset
+  // file, one cheap GET answers "was my last save accepted?" instead of
+  // tailing the (detached) dev-server log. Same server-computed map
+  // `/__editor/state` exposes as `projectValidation`, purpose-shaped.
+  router.get('/__vgai/validation', (_req: Request, res: Response) => {
+    res.json({
+      clean: projectValidation.size === 0,
+      failing: Object.fromEntries(projectValidation),
+    });
+  });
+
+  router.get('/__vgai/state', async (_req: Request, res: Response) => {
+    const result = await relayCommand({ type: 'bridge-call', method: 'stateAll', callArgs: [] });
+    const { status, body } = commandResponseFor(result);
+    res.status(status).json(body);
+  });
+
+  router.get('/__vgai/state/:provider', async (req: Request, res: Response) => {
+    const result = await relayCommand({
+      type: 'bridge-call',
+      method: 'state',
+      callArgs: [req.params['provider']],
+    });
+    const { status, body } = commandResponseFor(result);
+    res.status(status).json(body);
+  });
+
+  // Paths-not-blobs: the page hands back base64 over the relay
+  // (`bridge-screenshot` — a pure "hand back the pixels" primitive), and THIS
+  // side owns the filesystem, so the PNG lands under the project where the
+  // agent's Read tool can open it without leaving the sandbox.
+  router.get('/__vgai/screenshot', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ ok: false, error: 'no project open' });
+      return;
+    }
+    const result = await relayCommand({ type: 'bridge-screenshot' });
+    if (!result.ok) {
+      const { status, body } = commandResponseFor(result);
+      res.status(status).json(body);
+      return;
+    }
+    const base64 = result.data?.['base64'];
+    if (typeof base64 !== 'string') {
+      res.status(500).json({ ok: false, error: 'bridge-screenshot returned no image data' });
+      return;
+    }
+    const capturesDir = join(projectRoot, '.vgai', 'captures');
+    await mkdir(capturesDir, { recursive: true });
+    const file = join(capturesDir, `capture-${new Date().toISOString().replace(/[:.]/g, '-')}.png`);
+    await writeFile(file, Buffer.from(base64, 'base64'));
+    res.json({ ok: true, path: file, relativePath: relative(projectRoot, file) });
+  });
+
   // ---- Asset listing ----
   router.get('/__editor/assets', async (req: Request, res: Response) => {
     const dir = (req.query['dir'] as string) ?? '';
@@ -720,7 +1295,12 @@ export function createEditorServer(options: EditorServerOptions): Router {
 
   // ---- Save file ----
   router.post('/__editor/save-file', async (req: Request, res: Response) => {
-    const body = req.body as { path: string; content: string; encoding?: 'base64' };
+    const body = req.body as {
+      path: string;
+      content?: string;
+      encoding?: 'base64';
+      delete?: boolean;
+    };
     const filePath = body.path ?? '';
 
     if (!filePath || filePath.includes('..')) {
@@ -735,6 +1315,15 @@ export function createEditorServer(options: EditorServerOptions): Router {
     }
 
     try {
+      if (body.delete) {
+        await unlinkIfPresent(absPath);
+        res.json({ ok: true, path: filePath });
+        return;
+      }
+      if (typeof body.content !== 'string') {
+        res.status(400).json({ error: 'Missing content.' });
+        return;
+      }
       await mkdir(dirname(absPath), { recursive: true });
       const data = body.encoding === 'base64' ? Buffer.from(body.content, 'base64') : body.content;
       await writeFile(absPath, data, body.encoding === 'base64' ? undefined : 'utf-8');
@@ -915,7 +1504,7 @@ export function createEditorServer(options: EditorServerOptions): Router {
       // T3.6: shared scaffolder — packages/create-vgai-project/src/scaffold.ts.
       // Same implementation `npx create-vgai-project` and `vgai create` use
       // (copy template, rewrite @vgai/engine file: dep + tsconfig @engine/*
-      // paths/files array + vite alias + index.html title + project.json).
+      // paths/files array + vite alias + index.html title + v2 manifest).
       const result = scaffoldProject({
         name,
         targetDir: projectDir,
@@ -930,7 +1519,7 @@ export function createEditorServer(options: EditorServerOptions): Router {
       // Add to recent projects
       await addToRecentProjects(name, projectDir);
 
-      res.json({ ok: true, path: result.targetDir, config: result.projectConfig });
+      res.json({ ok: true, path: result.targetDir, config: result.manifest });
     } catch (err) {
       res.status(500).json({ error: `Failed to create project: ${err}` });
     }
@@ -1082,20 +1671,37 @@ export function createEditorServer(options: EditorServerOptions): Router {
     // disagree on a symlinked segment).
     const absPath = canonicalProjectRoot(newPath);
 
-    // Read project.json (or synthesize from vgai.game.json — §1C); accepts a
-    // manifest-only folder with no project.json.
+    // Read the v2 game manifest and derive the editor project view.
     const config = await readProjectView(absPath);
     if (!config) {
-      res.status(400).json({ error: `No vgai.game.json or project.json at ${absPath}` });
+      res.status(400).json({ error: `No valid vgai.game.json at ${absPath}` });
       return;
     }
 
+    // Compatibility is enforced by the process that owns the mutable project
+    // state, immediately before activation. The browser also preflights this
+    // for fast feedback, but it cannot make a client-side check atomic and
+    // non-browser API callers must not be able to bypass the contract.
+    try {
+      const compatibility = compatibilityIdentity();
+      assertEditorCompatibility(compatibility);
+      assertProjectCompatibility(config, compatibility);
+    } catch (error) {
+      if (error instanceof ProjectCompatibilityError) {
+        res.status(409).json({ error: error.message, recovery: error.recovery });
+        return;
+      }
+      throw error;
+    }
+
     // Update mutable state
     projectRoot = absPath;
     publicRoot = resolve(absPath, 'public');
 
     // Clear stale editor state from previous project
     editorState = {};
+    editorStateUpdatedAt = null;
+    editorStatesByClient.clear();
 
     // Ensure .vgai/ directory exists
     await mkdir(join(absPath, '.vgai'), { recursive: true });
@@ -1111,6 +1717,15 @@ export function createEditorServer(options: EditorServerOptions): Router {
 
     // Notify all connected editors
     broadcast('project-changed', { path: absPath, config });
+    // Coding sessions are project-scoped. Tear down only editor-owned
+    // Supercode runtime/follower state and rediscover the new folder; this
+    // never touches an independently-running terminal harness process.
+    void harnessChat.setWorkspace().catch((error) => {
+      broadcast('server-log', {
+        level: 'error',
+        message: `Harness Chat could not switch projects: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    });
 
     res.json({ ok: true, config });
   });
@@ -1368,9 +1983,9 @@ export function createEditorServer(options: EditorServerOptions): Router {
     res.json({ files });
   });
 
-  // D1 (spec §2.5): a Data-panel edit writes the `.data.json` IMMEDIATELY —
-  // game-is-the-document; undo is git. D5 RESOLVED here as the spec
-  // recommends: data writes are plain file writes and deliberately BYPASS the
+  // D1 (spec §2.5): a Data-panel edit writes the `.data.json` IMMEDIATELY.
+  // Project History captures exact bytes around this transport. Data writes
+  // deliberately BYPASS the
   // play-mode overlay regime entirely (the overlay is scene-entity-only —
   // `.vgai/overlays/*` via `world-overlay.ts`/`ingest-overlay.ts`; nothing in
   // that path ever touches `src/data/`). A running game picks the write up
@@ -1407,6 +2022,7 @@ export function createEditorServer(options: EditorServerOptions): Router {
     }
     try {
       const absPath = join(projectRoot, relPath);
+      await mkdir(dirname(absPath), { recursive: true });
       await writeFile(absPath, body.content, 'utf-8');
       res.json({ ok: true, path: relPath });
     } catch {
@@ -1414,6 +2030,51 @@ export function createEditorServer(options: EditorServerOptions): Router {
     }
   });
 
+  router.get('/__editor/data-file', async (req: Request, res: Response) => {
+    const relPath = (req.query['path'] as string) ?? '';
+    if (
+      !relPath ||
+      relPath.includes('..') ||
+      !relPath.startsWith('src/data/') ||
+      !relPath.endsWith('.data.json')
+    ) {
+      res.status(400).json({ error: 'Invalid path — expected src/data/**/*.data.json.' });
+      return;
+    }
+    if (projectRoot === engineRoot) {
+      res.status(404).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      res.type('application/json').send(await readFile(join(projectRoot, relPath)));
+    } catch {
+      res.status(404).json({ error: 'Not found.' });
+    }
+  });
+
+  router.delete('/__editor/data-file', async (req: Request, res: Response) => {
+    const relPath = (req.body as { path?: string }).path ?? '';
+    if (
+      !relPath ||
+      relPath.includes('..') ||
+      !relPath.startsWith('src/data/') ||
+      !relPath.endsWith('.data.json')
+    ) {
+      res.status(400).json({ error: 'Invalid path — expected src/data/**/*.data.json.' });
+      return;
+    }
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      await unlinkIfPresent(join(projectRoot, relPath));
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to delete data file.' });
+    }
+  });
+
   // ---- Project tools (W4, docs/DATA-TOOLS-DESIGN.md §3) ----
   //
   // Discovery for the dock's project-tool tabs: every
@@ -1437,6 +2098,108 @@ export function createEditorServer(options: EditorServerOptions): Router {
     });
   });
 
+  // ---- Project operations (docs/PROJECT-OPERATIONS-DESIGN.md) ----
+  //
+  // Unlike project tools, operation modules are loaded on the NODE side.
+  // Merely listing a Node-native asset/map build script must never import it
+  // into the editor browser or make it reachable from a standalone game
+  // bundle. Vite's ssrLoadModule is injected by the owning server and gives
+  // us normal TS transform + project dependency resolution without a second
+  // script runtime.
+  router.get('/__editor/project-operations', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.json({ operations: [], loadErrors: [] });
+      return;
+    }
+    res.json(await discoverProjectOperations(projectRoot, options.loadProjectModule));
+  });
+
+  router.post('/__editor/project-operations/run', async (req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({
+        ok: false,
+        error: { code: 'NO_PROJECT_OPEN', message: 'Open a project before running an operation.' },
+      });
+      return;
+    }
+    const body = req.body as { name?: unknown; input?: unknown; confirm?: unknown };
+    if (typeof body.name !== 'string' || body.name.trim() === '') {
+      res.status(400).json({
+        ok: false,
+        error: { code: 'INVALID_OPERATION_NAME', message: 'Expected a non-empty operation name.' },
+      });
+      return;
+    }
+    const controller = new AbortController();
+    req.once('aborted', () => controller.abort());
+    const result = await executeProjectOperation({
+      projectRoot,
+      loadModule: options.loadProjectModule,
+      name: body.name,
+      input: Object.hasOwn(body, 'input') ? body.input : {},
+      confirmed: body.confirm === true,
+      signal: controller.signal,
+    });
+    // A project command may create an ordinary file anywhere below public/.
+    // The public watcher validates files and detects moves, but it deliberately
+    // does not broadcast every add/change. Tell every editor client to rescan
+    // its Assets view after a successful declared mutation; no generator- or
+    // asset-specific operation contract is needed.
+    if (result.changedProject) broadcast('assets-changed', {});
+    res.status(result.status).json(result.body);
+  });
+
+  // ---- Story discovery (C3, spec §9 — "Add CSF Discovery and Portable
+  // Story Mounting") ----
+  //
+  // Conventional `*.stories.tsx` / `*.stories.ts` files, colocated anywhere
+  // under the project's `src/` (Storybook's own convention — unlike
+  // `src/tools/`/`src/data/`, stories are not confined to one folder). Same
+  // D3 physics as every other editor list here: a live folder scan, never a
+  // cached manifest — add/remove a `*.stories.tsx` and the next refresh sees
+  // it. Paths only: the CSF MODULE itself is loaded client-side through
+  // Vite's `/@fs/` dynamic-import path (`story-discovery.ts`, mirroring
+  // `tool-loader.ts`), so it arrives transpiled with HMR, and the editor
+  // never stores a duplicate story definition — the CSF module stays the one
+  // source of truth (spec §9 C3 "Story source remains the CSF module").
+  //
+  // `previewModulePath` rides along in the same response: the project's
+  // OPTIONAL `.storybook/preview.tsx`/`.ts` (checked with `existsSync`, same
+  // "server tells the truth about disk, client never guesses" contract as
+  // the rest of this route), or `null` when the project has no `.storybook/`
+  // folder — most projects don't. `story-discovery.ts`'s
+  // `loadProjectPreviewAnnotations` used to blind-probe both candidate paths
+  // client-side via `/@fs/` and swallow the import failure; that still
+  // logged a real failed network request for every project without a
+  // preview config (the common case), which is indistinguishable from a
+  // genuine broken-editor error to anything watching the page's network/
+  // console (e.g. `check-vgai-generated-project-p2p.ts`'s browser-proof).
+  // Reporting existence here lets the client only ever import a path that is
+  // actually there.
+  router.get('/__editor/story-files', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.json({ files: [], previewModulePath: null });
+      return;
+    }
+    const srcDir = join(projectRoot, 'src');
+    const [tsxFiles, tsFiles] = await Promise.all([
+      findFiles(srcDir, '.stories.tsx'),
+      findFiles(srcDir, '.stories.ts'),
+    ]);
+    const found = [...tsxFiles, ...tsFiles].filter(
+      (abs) => !abs.includes(`${sep}node_modules${sep}`),
+    );
+    const previewCandidates = ['.storybook/preview.tsx', '.storybook/preview.ts'];
+    const previewModulePath =
+      previewCandidates.find((candidate) => existsSync(join(projectRoot, candidate))) ?? null;
+    res.json({
+      files: found.sort().map((abs) => ({
+        path: relative(projectRoot, abs).split('\\').join('/'),
+      })),
+      previewModulePath,
+    });
+  });
+
   // ---- Manifest write (A4, D8 — the ONE manifest-write verb) ----
   // Unlike every other write route above, this one HARD-CODES its
   // destination: `join(projectRoot, 'vgai.game.json')`, NEVER derived from
@@ -1460,6 +2223,31 @@ export function createEditorServer(options: EditorServerOptions): Router {
     }
   });
 
+  router.get('/__editor/manifest', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(404).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      res.type('application/json').send(await readFile(join(projectRoot, 'vgai.game.json')));
+    } catch {
+      res.status(404).json({ error: 'Not found.' });
+    }
+  });
+
+  router.delete('/__editor/manifest', async (_req: Request, res: Response) => {
+    if (projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      await unlinkIfPresent(join(projectRoot, 'vgai.game.json'));
+      res.json({ ok: true });
+    } catch {
+      res.status(500).json({ error: 'Failed to delete manifest.' });
+    }
+  });
+
   // ---- Play-mode console log persistence ----
   const MAX_LOG_FILES = 20;
   let activeLogFile: string | null = null;
@@ -1533,5 +2321,44 @@ export function createEditorServer(options: EditorServerOptions): Router {
     res.json({ ok: true });
   });
 
+  // ---- #125 item 2: probe lifecycle narration relay ----
+  // `vgai probe` (packages/vgai-cli/src/index.ts's `runProbe`) fires
+  // best-effort lifecycle events at this route so they land in the SAME live
+  // editor console PR #120 wired the `server-log` SSE event into (see
+  // `runFileValidation`'s `broadcast('server-log', …)` calls above) — a human
+  // watching the editor sees "probe: run started (headed)" / "probe: 3/3
+  // specs passed" without tailing a separate terminal. Deliberately dumb:
+  // this is a narration RELAY, not an API — it validates shape, broadcasts,
+  // and gets out of the way; no state is kept here, and a caller with
+  // nothing to say just never POSTs (`vgai probe` skips this entirely when
+  // no live session covers the project).
+  router.post('/__editor/server-log', (req: Request, res: Response) => {
+    const body = req.body as { level?: unknown; message?: unknown };
+    const level = body.level;
+    if (
+      (level !== 'info' && level !== 'warn' && level !== 'error') ||
+      typeof body.message !== 'string'
+    ) {
+      res
+        .status(400)
+        .json({ error: "Expected { level: 'info'|'warn'|'error', message: string }." });
+      return;
+    }
+    broadcast('server-log', { level, message: body.message });
+    res.status(204).end();
+  });
+
+  router.close = async () => {
+    for (const timer of validationDebounceTimers.values()) clearTimeout(timer);
+    validationDebounceTimers.clear();
+    await Promise.all([
+      watcher?.close(),
+      srcWatcher?.close(),
+      manifestWatcher?.close(),
+      engineSourceWatcher?.close(),
+      harnessChat.close(),
+    ]);
+  };
+
   return router;
 }