@lifeaitools/clauth 1.30.23 → 1.30.24

package/cli/studio-debug.js

@@ -1,1095 +1,1095 @@
-import crypto from "crypto";
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { spawn } from "child_process";
-import ts from "typescript";
-
-const DEFAULT_POLL_TIMEOUT = 600_000;
-const MAX_POLL_TIMEOUT = 600_000;
-const MAX_EVENT_QUEUE = 100;
-const MAX_SNIPPET = 2_000;
-const STYLE_WRITE_EXTENSIONS = new Set([".css", ".scss", ".sass", ".less", ".html", ".jsx", ".tsx"]);
-const TEXT_WRITE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".html", ".md", ".txt", ".css", ".scss"]);
-
-const APP_TARGETS = {
-  studio_test: {
-    appSlug: "studio_test",
-    brandSlug: "studio_test",
-    packageName: "@regen/studio",
-    command: "pnpm --filter @regen/studio dev",
-    url: "http://localhost:3011/editor/local-test-target",
-  },
-  "studio-test": {
-    appSlug: "studio_test",
-    brandSlug: "studio_test",
-    packageName: "@regen/studio",
-    command: "pnpm --filter @regen/studio dev",
-    url: "http://localhost:3011/editor/local-test-target",
-  },
-  prt: {
-    appSlug: "prt",
-    brandSlug: "prt",
-    packageName: "@regen/prt-portal",
-    command: "pnpm --filter @regen/prt-portal dev",
-    url: "http://localhost:3006",
-  },
-  "prt-portal": {
-    appSlug: "prt",
-    brandSlug: "prt",
-    packageName: "@regen/prt-portal",
-    command: "pnpm --filter @regen/prt-portal dev",
-    url: "http://localhost:3006",
-  },
-};
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-const EDITOR_SETTINGS_FILENAME = ".studio-editor-settings.json";
-
-/**
- * Editable-prompts settings file — every Claude prompt built here has a default
- * baked into code; this loads the SAME-SHAPED override from
- * `<repoRoot>/.studio-editor-settings.json` if present (same file/shape
- * agent-pool.js's buildFullSystemPrompt() reads, different field). Read fresh
- * on every dispatch (no caching) so an edit takes effect on the next edit sent,
- * no daemon restart needed. Never throws.
- */
-function loadEditorSettings(repoRoot) {
-  if (!repoRoot) return {};
-  try {
-    const settingsPath = path.join(repoRoot, EDITOR_SETTINGS_FILENAME);
-    if (!fs.existsSync(settingsPath)) return {};
-    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch (e) {
-    console.error(`[studio-debug] ${EDITOR_SETTINGS_FILENAME} malformed, using code default edit prompt: ${e.message}`);
-    return {};
-  }
-}
-
-/**
- * Build the per-edit dispatch prompt. Editable: set `editPromptTemplate` in
- * `<repoRoot>/.studio-editor-settings.json` to override the whole template —
- * tokens {targetFile} {purpose} {appSlug} {brandSlug} {repoRoot} {devUrl}
- * {mode} {selector} {currentText} {newText} {notes} are substituted (each
- * resolves to "" when the underlying value is absent, same as the default).
- */
-function buildEditPrompt(session, event) {
-  const repoRoot = (session.repoRoot || session.cwd || "").replace(/\\/g, "/");
-  const targetFile = event.file
-    ? `TARGET FILE: ${event.file}`
-    : `TARGET FILE: unknown — locate it from Selector "${event.selector || "unknown"}"${event.component ? ` (component: ${event.component})` : ""} in the repo below before editing anything.`;
-  const tokens = {
-    targetFile,
-    purpose: event.instruction || "Make the requested edit.",
-    appSlug: session.appSlug || "",
-    brandSlug: session.brandSlug || "",
-    repoRoot,
-    devUrl: session.devUrl || "unknown",
-    mode: event.mode || "direct_edit",
-    selector: event.selector || "unknown",
-    currentText: event.textSnippet || "",
-    newText: event.textEdit?.newText || "",
-    notes: event.notes || "",
-  };
-
-  const settings = loadEditorSettings(repoRoot);
-  if (typeof settings.editPromptTemplate === "string" && settings.editPromptTemplate.trim()) {
-    return Object.entries(tokens).reduce(
-      (text, [key, value]) => text.replaceAll(`{${key}}`, value),
-      settings.editPromptTemplate,
-    );
-  }
-
-  return [
-    `You are a Studio local-debug agent. Make ONE source edit to the codebase.`,
-    ``,
-    // Explicit file + purpose, stated up front and unmissable — required even when
-    // no deterministic file hint exists, so a warm session's first turn is never
-    // vague about what it's touching or why.
-    tokens.targetFile,
-    `PURPOSE: ${tokens.purpose}`,
-    ``,
-    `App: ${tokens.appSlug} (brand: ${tokens.brandSlug})`,
-    `Repo: ${tokens.repoRoot}`,
-    `Dev URL: ${tokens.devUrl}`,
-    ``,
-    `Edit event:`,
-    `  Mode: ${tokens.mode}`,
-    `  Selector: ${tokens.selector}`,
-    tokens.currentText ? `  Current text: "${tokens.currentText}"` : "",
-    tokens.newText ? `  New text: "${tokens.newText}"` : "",
-    tokens.notes ? `  Notes: ${tokens.notes}` : "",
-    ``,
-    `Do not edit any file other than the one this edit targets.`,
-    `After editing, output a JSON object: {"status":"done","message":"<what you did>","filesChanged":["<path>"]}`,
-  ].filter(Boolean).join("\n");
-}
-
-/**
- * Build the prompt for a `mode:"chat"` event — a genuine conversational turn, not a
- * source edit. Deliberately does NOT reuse buildEditPrompt(): that template's "Make ONE
- * source edit" instruction plus the {"status","message","filesChanged"} JSON-output
- * contract make no sense for a question like "what does this page do?" and produced
- * broken chat replies (the agent trying to force a conversational answer into an edit
- * JSON shape, or refusing because there was no real target file to edit). Editable via
- * `<repoRoot>/.studio-editor-settings.json`'s `chatPromptTemplate` field (same token set
- * as `editPromptTemplate`, same substitution rule).
- */
-function buildChatPrompt(session, event) {
-  const repoRoot = (session.repoRoot || session.cwd || "").replace(/\\/g, "/");
-  const tokens = {
-    purpose: event.instruction || "",
-    appSlug: session.appSlug || "",
-    brandSlug: session.brandSlug || "",
-    repoRoot,
-    devUrl: session.devUrl || "unknown",
-  };
-
-  const settings = loadEditorSettings(repoRoot);
-  if (typeof settings.chatPromptTemplate === "string" && settings.chatPromptTemplate.trim()) {
-    return Object.entries(tokens).reduce(
-      (text, [key, value]) => text.replaceAll(`{${key}}`, value),
-      settings.chatPromptTemplate,
-    );
-  }
-
-  return [
-    `You are a Studio local-debug chat assistant helping someone edit the "${tokens.appSlug}" app (brand: ${tokens.brandSlug}).`,
-    `Repo: ${tokens.repoRoot}`,
-    `Dev URL: ${tokens.devUrl}`,
-    ``,
-    `This is a conversational turn, not a source-edit dispatch — answer the question or`,
-    `discuss the request in plain text. Only touch files if the person explicitly asks`,
-    `you to make a change; if you do, describe what you changed in your reply.`,
-    `Reply in plain prose — do NOT wrap your answer in the edit-dispatch JSON contract.`,
-    ``,
-    tokens.purpose,
-  ].filter(Boolean).join("\n");
-}
-
-/**
- * Persist an editable-prompts settings patch to `<repoRoot>/.studio-editor-settings.json`,
- * merging with whatever is already on disk. Only `systemPrompt`, `editPromptTemplate`, and
- * `chatPromptTemplate` are recognized fields — the same keys loadEditorSettings()/buildEditPrompt() (this
- * file) and buildFullSystemPrompt()/buildStudioEditorSystemPrompt() (agent-pool.js) read.
- * Empty-string values clear that field back to the code default rather than persisting "".
- */
-function saveEditorSettings(repoRoot, patch) {
-  if (!repoRoot) throw new Error("repoRoot required");
-  const settingsPath = path.join(repoRoot, EDITOR_SETTINGS_FILENAME);
-  const current = loadEditorSettings(repoRoot);
-  const next = { ...current };
-  for (const key of ["systemPrompt", "editPromptTemplate", "chatPromptTemplate"]) {
-    if (!(key in patch)) continue;
-    const value = typeof patch[key] === "string" ? patch[key].trim() : "";
-    if (value) next[key] = value;
-    else delete next[key];
-  }
-  fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + "\n", "utf8");
-  return next;
-}
-
-function safeString(value, max = MAX_SNIPPET) {
-  if (typeof value !== "string") return value;
-  return value.length > max ? value.slice(0, max) : value;
-}
-
-function normalizeEvent(session, body) {
-  const type = body.type || body.mode || "direct_edit";
-  const id = body.id || `evt_${crypto.randomUUID()}`;
-  const target = body.target && typeof body.target === "object" ? { ...body.target } : {};
-  if (typeof target.textSnippet === "string") target.textSnippet = safeString(target.textSnippet, 500);
-  if (typeof target.outerHTMLSnippet === "string") target.outerHTMLSnippet = safeString(target.outerHTMLSnippet, MAX_SNIPPET);
-  if (typeof target.outerHTML === "string" && !target.outerHTMLSnippet) {
-    target.outerHTMLSnippet = safeString(target.outerHTML, MAX_SNIPPET);
-    delete target.outerHTML;
-  }
-
-  return {
-    type,
-    id,
-    mode: body.mode || type,
-    sessionId: session.sessionId,
-    brandSlug: session.brandSlug,
-    appSlug: session.appSlug,
-    target,
-    reference: body.reference || null,
-    instruction: safeString(body.instruction || body.prompt || "", 4_000),
-    createdAt: nowIso(),
-  };
-}
-
-function readBody(req, maxBytes = 128 * 1024) {
-  return new Promise((resolve, reject) => {
-    let data = "";
-    req.on("data", chunk => {
-      data += chunk;
-      if (data.length > maxBytes) reject(new Error("Body too large"));
-    });
-    req.on("end", () => {
-      if (!data.trim()) return resolve({});
-      try {
-        resolve(JSON.parse(data));
-      } catch {
-        reject(new Error("Invalid JSON"));
-      }
-    });
-    req.on("error", reject);
-  });
-}
-
-function writeJson(res, status, data, cors) {
-  res.writeHead(status, { "Content-Type": "application/json", ...cors });
-  res.end(JSON.stringify(data));
-}
-
-function resolveSourceFile(session, file, allowedExtensions = STYLE_WRITE_EXTENSIONS) {
-  if (!file || typeof file !== "string") return null;
-  const root = path.resolve(session.repoRoot || session.cwd || process.cwd());
-  const candidate = path.isAbsolute(file) ? path.resolve(file) : path.resolve(root, file);
-  const rel = path.relative(root, candidate);
-  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
-  if (!allowedExtensions.has(path.extname(candidate).toLowerCase())) return null;
-  return { root, path: candidate, relativePath: rel.replace(/\\/g, "/") };
-}
-
-function applyTextRangeEdit(sourceText, textEdit) {
-  const source = textEdit.source;
-  if (!source || !source.range || typeof source.range.start !== "number" || typeof source.range.end !== "number") {
-    throw new Error("text-write requires source.range.start and source.range.end.");
-  }
-  const { start, end } = source.range;
-  if (start < 0 || end < start || end > sourceText.length) {
-    throw new Error(`text-write source range [${start}, ${end}] is out of bounds (file length: ${sourceText.length}).`);
-  }
-  if (textEdit.oldText !== undefined) {
-    const oldSlice = sourceText.slice(start, end);
-    if (oldSlice !== textEdit.oldText) {
-      throw new Error(`text-write oldText mismatch at [${start}, ${end}]: expected "${String(textEdit.oldText).slice(0, 80)}", found "${oldSlice.slice(0, 80)}".`);
-    }
-  }
-  return `${sourceText.slice(0, start)}${textEdit.newText}${sourceText.slice(end)}`;
-}
-
-function escapeRegExp(value) {
-  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function applyCssTextEdit(source, property, value, lineNumber = null) {
-  const propertyPattern = new RegExp(`(${escapeRegExp(property)}\\s*:\\s*)([^;\\n]+)(\\s*;?)`);
-  if (Number.isInteger(lineNumber) && lineNumber > 0) {
-    const lines = source.split(/\r?\n/);
-    const index = Math.min(lines.length - 1, lineNumber - 1);
-    const windowStart = Math.max(0, index - 8);
-    const windowEnd = Math.min(lines.length - 1, index + 8);
-    for (let i = windowStart; i <= windowEnd; i += 1) {
-      if (propertyPattern.test(lines[i])) {
-        lines[i] = lines[i].replace(propertyPattern, `$1${value}$3`);
-        return { content: lines.join("\n"), strategy: "replace-near-line" };
-      }
-    }
-    const anchor = lines[index] ?? "";
-    const indent = anchor.match(/^\s*/)?.[0] ?? "";
-    lines.splice(index + 1, 0, `${indent}${property}: ${value};`);
-    return { content: lines.join("\n"), strategy: "insert-near-line" };
-  }
-  const replaced = source.replace(propertyPattern, `$1${value}$3`);
-  if (replaced !== source) return { content: replaced, strategy: "replace-first" };
-  throw new Error(`CSS property "${property}" was not found and no source line was provided.`);
-}
-
-function applyJsxStyleEdit(source, property, value, lineNumber = null) {
-  const lines = source.split(/\r?\n/);
-  const targetIndex = Number.isInteger(lineNumber) && lineNumber > 0 ? Math.min(lines.length - 1, lineNumber - 1) : -1;
-  const windowStart = targetIndex >= 0 ? Math.max(0, targetIndex - 8) : 0;
-  const windowEnd = targetIndex >= 0 ? Math.min(lines.length - 1, targetIndex + 8) : lines.length - 1;
-  const camel = property.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-  const quoted = JSON.stringify(value);
-  const propPattern = new RegExp(`(${camel}\\s*:\\s*)(["'\`])([^"'\`]+)(\\2)`);
-
-  for (let i = windowStart; i <= windowEnd; i += 1) {
-    if (propPattern.test(lines[i])) {
-      lines[i] = lines[i].replace(propPattern, `$1${quoted}`);
-      return { content: lines.join("\n"), strategy: "replace-js-style-near-line" };
-    }
-  }
-
-  for (let i = windowStart; i <= windowEnd; i += 1) {
-    if (lines[i].includes("style={{")) {
-      lines[i] = lines[i].replace("style={{", `style={{ ${camel}: ${quoted},`);
-      return { content: lines.join("\n"), strategy: "insert-js-style-near-line" };
-    }
-  }
-
-  throw new Error(`No inline style object for "${property}" was found near the selected source line.`);
-}
-
-// Syntax-check extensions we know how to parse with the TS compiler. Non-TS/JS
-// source (e.g. plain .css, .md) is skipped — there is nothing meaningful for
-// ts.transpileModule to validate there.
-const SYNTAX_CHECK_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
-
-// Same pattern already proven in
-// packages/studio-local-debug/src/integration/editor-coverage-matrix.test.ts
-// (syntaxDiagnosticsLikeEditor) and returned by apps/studio's accept-adapter.ts
-// as `syntaxDiagnostics`. Kept identical here so results are directly comparable.
-function syntaxDiagnosticsFor(source, fileName) {
-  const output = ts.transpileModule(source, {
-    fileName,
-    reportDiagnostics: true,
-    compilerOptions: {
-      jsx: ts.JsxEmit.Preserve,
-      target: ts.ScriptTarget.ESNext,
-      module: ts.ModuleKind.ESNext,
-    },
-  });
-  return output.diagnostics || [];
-}
-
-function formatDiagnostic(diagnostic) {
-  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
-  if (diagnostic.file && typeof diagnostic.start === "number") {
-    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
-    return `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`;
-  }
-  return message;
-}
-
-/**
- * Read each changed file (relative to the session repo root) and run a TS
- * syntax check. Returns { ok, diagnostics } — diagnostics is a flat array of
- * human-readable strings, empty when every checkable file is syntax-clean.
- * Files outside SYNTAX_CHECK_EXTENSIONS, or that no longer exist on disk, are
- * skipped (not treated as failures) — this check validates parseability, not
- * file presence.
- */
-function checkFilesSyntax(session, filesChanged) {
-  const diagnostics = [];
-  const root = path.resolve(session.repoRoot || session.cwd || process.cwd());
-  for (const file of Array.isArray(filesChanged) ? filesChanged : []) {
-    if (!file || typeof file !== "string") continue;
-    const ext = path.extname(file).toLowerCase();
-    if (!SYNTAX_CHECK_EXTENSIONS.has(ext)) continue;
-    const candidate = path.isAbsolute(file) ? path.resolve(file) : path.resolve(root, file);
-    let source;
-    try {
-      source = fs.readFileSync(candidate, "utf8");
-    } catch (err) {
-      // A referenced file that no longer exists is itself suspicious, but the
-      // agent may have renamed/moved it deliberately as part of the edit —
-      // treat as unable-to-verify, not a hard syntax failure.
-      continue;
-    }
-    const fileDiagnostics = syntaxDiagnosticsFor(source, candidate);
-    for (const d of fileDiagnostics) {
-      diagnostics.push(`${file}: ${formatDiagnostic(d)}`);
-    }
-  }
-  return { ok: diagnostics.length === 0, diagnostics };
-}
-
-/**
- * Best-effort collection of the file(s) an event referenced, used as a
- * fallback filesChanged set when the agent's JSON reply fails to parse (or
- * omits filesChanged) — so a malformed-but-plausible-looking agent response
- * still gets its target file(s) syntax-checked instead of slipping through
- * ungated.
- */
-function filesReferencedByEvent(event) {
-  const files = new Set();
-  const add = (f) => {
-    if (typeof f === "string" && f.trim()) files.add(f.trim());
-  };
-  add(event?.file);
-  add(event?.target?.file);
-  add(event?.textEdit?.source?.file);
-  add(event?.styleEdit?.source?.file);
-  return [...files];
-}
-
-async function isUrlReachable(url) {
-  try {
-    const response = await fetch(url, {
-      method: "GET",
-      signal: AbortSignal.timeout(1_500),
-    });
-    return response.status < 500;
-  } catch {
-    return false;
-  }
-}
-
-function resolveTarget(input = {}) {
-  const slug = String(input.appSlug || input.brandSlug || "prt").toLowerCase();
-  const configured = APP_TARGETS[slug];
-  // No registration required IF the caller supplies an explicit devUrl/devCommand —
-  // an arbitrary appSlug with an explicit target is a legitimate ad-hoc session. But
-  // an unknown slug with NO explicit override has nothing to resolve to at all.
-  if (!configured && !input.devUrl && !input.devCommand) {
-    return {
-      error: "unknown_app",
-      message: `Unknown appSlug "${slug}" — not registered in APP_TARGETS and no devUrl/devCommand override was provided.`,
-    };
-  }
-
-  const base = configured || {
-    appSlug: slug,
-    brandSlug: input.brandSlug || slug,
-    command: input.devCommand,
-    url: input.devUrl,
-  };
-
-  return {
-    appSlug: input.appSlug || base.appSlug,
-    brandSlug: input.brandSlug || base.brandSlug || input.appSlug || base.appSlug,
-    command: input.devCommand || base.command,
-    url: input.devUrl || base.url,
-    cwd: input.cwd || input.repoRoot || process.cwd(),
-  };
-}
-
-/**
- * A reachable HTTP server is not necessarily a genuine Next.js DEV server the editor
- * can attach HMR-based live edits to — it could be a production build (no HMR at all)
- * or a dev server sitting behind an auth gate the editor can't get past. Probe the
- * webpack-hmr path: a redirect (typically to a login page) or an auth-rejection status
- * means source-edit sessions cannot establish the HMR stream this feature depends on.
- */
-async function isGenuineDevServer(url) {
-  try {
-    const response = await fetch(`${url.replace(/\/$/, "")}/_next/webpack-hmr`, {
-      method: "GET",
-      redirect: "manual",
-      signal: AbortSignal.timeout(1_500),
-    });
-    if (response.status >= 300 && response.status < 400) return false;
-    if (response.status === 401 || response.status === 403) return false;
-    return true;
-  } catch {
-    // Network-level errors on a websocket-upgrade path (abrupt close, protocol error)
-    // are expected even for a genuine dev server hit with a plain GET — don't reject
-    // on that basis alone, only on an explicit auth/redirect signal above.
-    return true;
-  }
-}
-
-function splitCommand(command) {
-  if (!command || typeof command !== "string") return null;
-  const parts = command.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
-  return parts.map(part => part.replace(/^"|"$/g, ""));
-}
-
-function startDevProcess(target, logFile) {
-  const parts = splitCommand(target.command);
-  if (!parts || parts.length === 0) {
-    return { started: false, error: "missing_command" };
-  }
-
-  const logDir = path.join(os.tmpdir(), "clauth-studio-debug");
-  fs.mkdirSync(logDir, { recursive: true });
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const outPath = path.join(logDir, `${target.appSlug}-${stamp}.out.log`);
-  const errPath = path.join(logDir, `${target.appSlug}-${stamp}.err.log`);
-  const out = fs.openSync(outPath, "a");
-  const err = fs.openSync(errPath, "a");
-
-  const proc = spawn(parts[0], parts.slice(1), {
-    cwd: target.cwd,
-    env: process.env,
-    stdio: ["ignore", out, err],
-    shell: process.platform === "win32",
-    detached: true,
-    windowsHide: true,
-  });
-  proc.unref();
-  try {
-    fs.appendFileSync(logFile, `[${nowIso()}] studio-debug dev start pid=${proc.pid} command=${target.command}\n`);
-  } catch {}
-
-  return {
-    started: true,
-    pid: proc.pid,
-    command: target.command,
-    url: target.url,
-    stdout: outPath,
-    stderr: errPath,
-    process: proc,
-  };
-}
-
-export class StudioDebugSessionStore {
-  constructor({
-    port = 52437,
-    logFile = path.join(os.tmpdir(), "clauth-serve.log"),
-    dispatchAgent = null,
-    acquireSessionWorker = null,
-    releaseSessionWorker = null,
-  } = {}) {
-    this.port = port;
-    this.logFile = logFile;
-    this.sessions = new Map();
-    this.dispatchAgent = dispatchAgent;
-    // One warm channel per editor session, acquired eagerly at start() and reused for
-    // every dispatch (chat and direct-edit alike) via submitEvent()'s dispatchAgent call
-    // through to session end — never a fresh one-shot process per edit.
-    this.acquireSessionWorker = acquireSessionWorker;
-    this.releaseSessionWorker = releaseSessionWorker;
-  }
-
-  async start(input = {}) {
-    const target = resolveTarget(input);
-    if (target.error) {
-      return { ok: false, error: target.error, message: target.message, status: "error" };
-    }
-
-    const shouldLaunch = input.launchDevServer !== false;
-    const reachable = await isUrlReachable(target.url);
-    if (reachable && !(await isGenuineDevServer(target.url))) {
-      return {
-        ok: false,
-        error: "non_dev_server",
-        message: `${target.url} is reachable but its Next dev HMR stream is not accessible (redirected or auth-gated) — source-edit sessions require a genuine, reachable Next.js dev server.`,
-        status: "error",
-      };
-    }
-    const launch = reachable
-      ? { started: false, command: target.command, url: target.url, alreadyRunning: true }
-      : shouldLaunch
-        ? startDevProcess(target, this.logFile)
-        : { started: false, command: target.command, url: target.url, skipped: true };
-
-    const sessionId = input.sessionId || `studio-${crypto.randomUUID()}`;
-    const token = crypto.randomBytes(24).toString("base64url");
-    const session = {
-      sessionId,
-      token,
-      brandSlug: target.brandSlug,
-      appSlug: target.appSlug,
-      repoRoot: input.repoRoot || target.cwd,
-      cwd: target.cwd,
-      devCommand: target.command,
-      devUrl: target.url,
-      modeDefault: input.modeDefault || "direct_edit",
-      agentModel: typeof input.agentModel === "string" && input.agentModel.trim() ? input.agentModel.trim() : null,
-      warmAgent: input.warmAgent !== false,
-      status: "waiting_for_agent",
-      createdAt: nowIso(),
-      updatedAt: nowIso(),
-      stopped: false,
-      events: [],
-      replies: [],
-      pendingPolls: [],
-      launch,
-    };
-    this.sessions.set(sessionId, session);
-
-    const relayBaseUrl = `http://127.0.0.1:${this.port}/studio/debug/${sessionId}`;
-    const claudeBaseUrl = `http://127.0.0.1:${this.port}/studio/claude/${sessionId}`;
-    const pollCommand = `node scripts/studio-debug-poll.mjs --session ${sessionId} --token ${token} --relay ${claudeBaseUrl}`;
-
-    // When dispatchAgent is wired, events dispatch directly — no polling agent needed.
-    if (this.dispatchAgent) {
-      session.status = "waiting_for_event";
-    }
-
-    // Acquire this session's warm channel now, at session start — not lazily on the
-    // first edit. Every subsequent dispatchAgent call for this sessionId (chat or
-    // direct-edit) reuses the same pinned worker. Best-effort: a warm-pool exhaustion
-    // here does not fail session start, dispatchToSession() will surface it per-turn.
-    if (session.warmAgent && this.acquireSessionWorker) {
-      try { this.acquireSessionWorker(sessionId, session.agentModel, session.repoRoot || session.cwd); } catch { /* best-effort */ }
-    }
-
-    return {
-      ok: true,
-      sessionId,
-      token,
-      devUrl: target.url,
-      relayBaseUrl,
-      status: session.status,
-      agentMode: session.warmAgent ? "warm" : "disabled",
-      launch: {
-        started: !!launch.started,
-        alreadyRunning: !!launch.alreadyRunning,
-        command: launch.command,
-        url: launch.url,
-        pid: launch.pid || null,
-      },
-      pollCommand,
-      claudeBaseUrl,
-    };
-  }
-
-  get(sessionId) {
-    return this.sessions.get(sessionId) || null;
-  }
-
-  authenticate(sessionId, token) {
-    const session = this.get(sessionId);
-    if (!session) return { error: "not_found" };
-    if (session.token !== token) return { error: "unauthorized" };
-    return { session };
-  }
-
-  submitEvent(sessionId, body) {
-    const auth = this.authenticate(sessionId, body.token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    if (!session.warmAgent) {
-      return {
-        error: "agent_disabled",
-        message: "This direct-write session does not allow agent-dispatched events.",
-      };
-    }
-    const event = normalizeEvent(session, body);
-
-    session.updatedAt = nowIso();
-    session.status = "event_pending";
-
-    // If a dispatchAgent handler exists, spawn a full headless Claude agent.
-    if (this.dispatchAgent) {
-      // Stash images from the event body so the dispatcher can write them to tmp
-      if (Array.isArray(body.images) && body.images.length > 0) {
-        session._pendingImages = body.images;
-      }
-
-      // A chat turn is conversational, not a source-edit dispatch: use buildChatPrompt()
-      // (plain prose, no "make ONE source edit" instruction, no edit-JSON output contract)
-      // and skip the syntax-check-and-retry loop below entirely — there's no edited file
-      // to check, and the agent's raw reply text IS the message, not something to parse
-      // as JSON. Previously every chat message reused buildEditPrompt(), so the agent was
-      // told to edit a file and reply in {"status","message","filesChanged"} JSON for what
-      // was just a question — see submitEvent's mode branch below for the corresponding fix.
-      if (event.mode === "chat") {
-        const chatPrompt = buildChatPrompt(session, event);
-        this.dispatchAgent(event.id, session.token, null, session, chatPrompt)
-          .then((result) => {
-            const message = String(result?.package ?? "").trim() || "(no reply)";
-            session.replies.push({
-              eventId: event.id,
-              status: result?.ok === false ? "error" : "done",
-              message,
-              filesChanged: [],
-              diagnostics: [],
-              createdAt: nowIso(),
-            });
-            session.status = result?.ok === false ? "error" : "done";
-            session.updatedAt = nowIso();
-          })
-          .catch((err) => {
-            session.replies.push({
-              eventId: event.id,
-              status: "error",
-              message: `Chat dispatch failed: ${err?.message || "unknown error"}`,
-              filesChanged: [],
-              diagnostics: [],
-              createdAt: nowIso(),
-            });
-            session.status = "error";
-            session.updatedAt = nowIso();
-          });
-        return { ok: true, eventId: event.id, status: session.status };
-      }
-
-      const prompt = buildEditPrompt(session, event);
-
-      const fallbackFiles = filesReferencedByEvent(event);
-
-      const parseAgentResult = (result) => {
-        // BUG FIX (2026-07-02): AgentPool.dispatchToSession()/dispatch() resolve with
-        // `result.package` (the agent's raw final-text response, see agent-pool.js:629
-        // `package: (text || "").trim()`) -- NOT `result.stdout` or `result.output`,
-        // neither of which exist on this result shape. Reading the wrong fields meant
-        // JSON.parse("") always threw, parsed silently stayed {}, and EVERY dispatch
-        // reported status:"done" / filesChanged:[] regardless of what the agent
-        // actually did -- the syntax-check-and-retry loop below was checking an empty
-        // file list every single time and never catching anything.
-        const rawText = String(result?.package ?? "").trim();
-        let parsed = {};
-        try {
-          parsed = JSON.parse(rawText);
-        } catch {
-          // Agents don't always emit pure JSON despite instructions -- a trailing/leading
-          // sentence around the JSON object is common. Try to recover the LAST {...}
-          // block in the text before giving up (never throws further).
-          const match = rawText.match(/\{[\s\S]*\}/);
-          if (match) {
-            try { parsed = JSON.parse(match[0]); } catch { /* give up, use defaults below */ }
-          }
-        }
-        const filesChanged = Array.isArray(parsed.filesChanged) && parsed.filesChanged.length > 0
-          ? parsed.filesChanged
-          : fallbackFiles;
-        return {
-          status: parsed.status || "done",
-          message: parsed.message || rawText.slice(0, 500) || "Agent completed",
-          filesChanged,
-        };
-      };
-
-      // D1/D2 (studio-editor-v1-auto-escalation.md): after the dispatched agent
-      // reports back, verify the file(s) it touched still parse before trusting
-      // "status":"done". A malformed agent JSON reply (bare try/catch above)
-      // must NOT bypass this — filesChanged falls back to whatever the original
-      // event referenced so even an unparseable reply still gets checked.
-      // On a syntax failure, re-dispatch exactly once with the diagnostic
-      // appended; a second failure (or a second dispatch error) is a hard stop
-      // to status "error" with diagnostics attached — never a silent accept,
-      // never an unbounded retry loop.
-      this.dispatchAgent(event.id, session.token, null, session, prompt)
-        .then(async (result) => {
-          const attempt1 = parseAgentResult(result);
-          const check1 = checkFilesSyntax(session, attempt1.filesChanged);
-
-          if (check1.ok) {
-            session.replies.push({
-              eventId: event.id,
-              status: attempt1.status,
-              message: attempt1.message,
-              filesChanged: attempt1.filesChanged,
-              diagnostics: [],
-              createdAt: nowIso(),
-            });
-            session.status = "done";
-            session.updatedAt = nowIso();
-            return;
-          }
-
-          const retryPrompt = [
-            prompt,
-            ``,
-            `Your previous edit broke the file's syntax. Diagnostic: ${check1.diagnostics.join("; ")}.`,
-            `Fix the file so it is syntactically valid, preserving your intended change.`,
-          ].join("\n");
-
-          let attempt2Result;
-          try {
-            attempt2Result = await this.dispatchAgent(event.id, session.token, null, session, retryPrompt);
-          } catch {
-            session.replies.push({
-              eventId: event.id,
-              status: "error",
-              message: "Agent retry dispatch failed after syntax check failure",
-              filesChanged: attempt1.filesChanged,
-              diagnostics: check1.diagnostics,
-              createdAt: nowIso(),
-            });
-            session.status = "error";
-            session.updatedAt = nowIso();
-            return;
-          }
-
-          const attempt2 = parseAgentResult(attempt2Result);
-          const check2 = checkFilesSyntax(session, attempt2.filesChanged);
-
-          if (check2.ok) {
-            session.replies.push({
-              eventId: event.id,
-              status: attempt2.status,
-              message: attempt2.message,
-              filesChanged: attempt2.filesChanged,
-              diagnostics: [],
-              createdAt: nowIso(),
-            });
-            session.status = "done";
-            session.updatedAt = nowIso();
-            return;
-          }
-
-          session.replies.push({
-            eventId: event.id,
-            status: "error",
-            message: `Agent edit failed syntax check after retry: ${check2.diagnostics.join("; ")}`,
-            filesChanged: attempt2.filesChanged,
-            diagnostics: check2.diagnostics,
-            createdAt: nowIso(),
-          });
-          session.status = "error";
-          session.updatedAt = nowIso();
-        })
-        .catch(() => {
-          session.replies.push({
-            eventId: event.id,
-            status: "error",
-            message: "Agent dispatch failed",
-            filesChanged: [],
-            diagnostics: [],
-            createdAt: nowIso(),
-          });
-          session.status = "error";
-          session.updatedAt = nowIso();
-        });
-
-      return { ok: true, eventId: event.id, status: session.status };
-    }
-
-    // Legacy path: queue for a polling agent
-    if (session.pendingPolls.length > 0) {
-      const poll = session.pendingPolls.shift();
-      poll(event);
-    } else {
-      session.events.push(event);
-      if (session.events.length > MAX_EVENT_QUEUE) session.events.shift();
-    }
-    return { ok: true, eventId: event.id, status: session.status };
-  }
-
-  poll(sessionId, token, timeoutMs = DEFAULT_POLL_TIMEOUT) {
-    const auth = this.authenticate(sessionId, token);
-    if (auth.error) return Promise.resolve(auth);
-    const session = auth.session;
-    if (session.events.length > 0) {
-      session.status = "agent_received";
-      session.updatedAt = nowIso();
-      return Promise.resolve(session.events.shift());
-    }
-    if (session.stopped) return Promise.resolve({ type: "stopped" });
-
-    const timeout = Math.min(Math.max(Number(timeoutMs) || DEFAULT_POLL_TIMEOUT, 1), MAX_POLL_TIMEOUT);
-    session.status = "waiting_for_event";
-    session.updatedAt = nowIso();
-
-    return new Promise(resolve => {
-      const timer = setTimeout(() => {
-        session.pendingPolls = session.pendingPolls.filter(fn => fn !== finish);
-        resolve({ type: "timeout" });
-      }, timeout);
-      const finish = event => {
-        clearTimeout(timer);
-        session.status = "agent_received";
-        session.updatedAt = nowIso();
-        resolve(event);
-      };
-      session.pendingPolls.push(finish);
-    });
-  }
-
-  reply(sessionId, body) {
-    const auth = this.authenticate(sessionId, body.token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    const reply = {
-      eventId: body.eventId,
-      status: body.status || body.type || "done",
-      message: body.message || "",
-      filesChanged: Array.isArray(body.filesChanged)
-        ? body.filesChanged
-        : body.file
-          ? [body.file]
-          : [],
-      createdAt: nowIso(),
-    };
-    session.replies.push(reply);
-    session.status = reply.status === "done" ? "done" : reply.status;
-    session.updatedAt = nowIso();
-    return { ok: true, status: session.status, reply };
-  }
-
-  writeText(sessionId, body) {
-    const auth = this.authenticate(sessionId, body.token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    const textEdit = body.textEdit && typeof body.textEdit === "object" ? body.textEdit : {};
-    const source = textEdit.source && typeof textEdit.source === "object" ? textEdit.source : {};
-    const file = source.file || textEdit.file || body.file;
-    const fileInfo = resolveSourceFile(session, file, TEXT_WRITE_EXTENSIONS);
-    if (!fileInfo) {
-      return { error: "invalid_source", message: `text-write requires a source file inside the debug session repo (got: ${file || "(none)"}).` };
-    }
-    if (typeof textEdit.newText !== "string") {
-      return { error: "invalid_body", message: "text-write requires textEdit.newText." };
-    }
-    try {
-      const original = fs.readFileSync(fileInfo.path, "utf8");
-      const updated = applyTextRangeEdit(original, { ...textEdit, source });
-      fs.writeFileSync(fileInfo.path, updated, "utf8");
-      const reply = {
-        eventId: body.id || `text_${crypto.randomUUID()}`,
-        status: "done",
-        message: `Direct text write (source_replace [${source.range?.start}, ${source.range?.end}])`,
-        filesChanged: [fileInfo.relativePath],
-        createdAt: nowIso(),
-      };
-      session.replies.push(reply);
-      session.status = "done";
-      session.updatedAt = nowIso();
-      return { ok: true, status: "done", eventId: reply.eventId, filesChanged: reply.filesChanged };
-    } catch (err) {
-      return { error: "text_write_failed", message: err instanceof Error ? err.message : String(err) };
-    }
-  }
-
-  writeStyle(sessionId, body) {
-    const auth = this.authenticate(sessionId, body.token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    const styleEdit = body.styleEdit && typeof body.styleEdit === "object" ? body.styleEdit : {};
-    const deltas = Array.isArray(styleEdit.deltas) ? styleEdit.deltas : [];
-    const source = styleEdit.source && typeof styleEdit.source === "object" ? styleEdit.source : {};
-    const fileInfo = resolveSourceFile(session, source.file || body.file);
-    if (!fileInfo) return { error: "invalid_source", message: "style-write requires a source file inside the debug session repo." };
-    if (deltas.length !== 1) return { error: "invalid_delta", message: "style-write currently accepts exactly one deterministic CSS delta." };
-
-    const delta = deltas[0] || {};
-    if (typeof delta.property !== "string" || typeof delta.value !== "string") {
-      return { error: "invalid_delta", message: "style-write requires string property and value." };
-    }
-
-    try {
-      const original = fs.readFileSync(fileInfo.path, "utf8");
-      const ext = path.extname(fileInfo.path).toLowerCase();
-      const result = ext === ".jsx" || ext === ".tsx"
-        ? applyJsxStyleEdit(original, delta.property, delta.value, source.line || body.line || null)
-        : applyCssTextEdit(original, delta.property, delta.value, source.line || body.line || null);
-      fs.writeFileSync(fileInfo.path, result.content, "utf8");
-      const reply = {
-        eventId: body.id || `style_${crypto.randomUUID()}`,
-        status: "done",
-        message: `Direct style write (${result.strategy})`,
-        filesChanged: [fileInfo.relativePath],
-        createdAt: nowIso(),
-      };
-      session.replies.push(reply);
-      session.status = "done";
-      session.updatedAt = nowIso();
-      return { ok: true, status: "done", eventId: reply.eventId, filesChanged: reply.filesChanged, strategy: result.strategy };
-    } catch (err) {
-      return { error: "style_write_failed", message: err instanceof Error ? err.message : String(err) };
-    }
-  }
-
-  status(sessionId, token) {
-    const auth = this.authenticate(sessionId, token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    return {
-      ok: true,
-      sessionId: session.sessionId,
-      brandSlug: session.brandSlug,
-      appSlug: session.appSlug,
-      devUrl: session.devUrl,
-      status: session.status,
-      createdAt: session.createdAt,
-      updatedAt: session.updatedAt,
-      pendingEvents: session.events.length,
-      pendingPolls: session.pendingPolls.length,
-      replies: session.replies,
-      launch: {
-        started: !!session.launch?.started,
-        alreadyRunning: !!session.launch?.alreadyRunning,
-        command: session.launch?.command || session.devCommand,
-        url: session.launch?.url || session.devUrl,
-        pid: session.launch?.pid || null,
-      },
-    };
-  }
-
-  stop(sessionId, token) {
-    const auth = this.authenticate(sessionId, token);
-    if (auth.error) return auth;
-    const session = auth.session;
-    session.stopped = true;
-    session.status = "stopped";
-    session.updatedAt = nowIso();
-    if (session.launch?.process && !session.launch.process.killed) {
-      try {
-        session.launch.process.kill();
-      } catch {}
-    }
-    for (const poll of session.pendingPolls.splice(0)) poll({ type: "stopped" });
-    this.sessions.delete(sessionId);
-    if (this.releaseSessionWorker) {
-      try { this.releaseSessionWorker(sessionId); } catch { /* best-effort */ }
-    }
-    return { ok: true, status: "stopped", sessionId };
-  }
-}
-
-export function createStudioDebugRuntime(options) {
-  const store = new StudioDebugSessionStore(options);
-
-  async function handle(req, res, url, cors) {
-    const reqPath = url.pathname;
-    const method = req.method;
-
-    if (method === "POST" && reqPath === "/studio/debug/start") {
-      try {
-        const body = await readBody(req);
-        const result = await store.start(body);
-        return writeJson(res, result.ok ? 200 : 400, result, cors);
-      } catch (err) {
-        return writeJson(res, 400, { ok: false, error: err.message }, cors);
-      }
-    }
-
-    // Editable-prompts settings — the UI for .studio-editor-settings.json (loadEditorSettings()
-    // above / buildFullSystemPrompt()+buildStudioEditorSystemPrompt() in agent-pool.js). GET
-    // returns what's on disk (empty object if never set); POST merges a partial patch.
-    if (reqPath === "/studio/editor-settings") {
-      const repoRoot = url.searchParams.get("repoRoot");
-      if (!repoRoot) return writeJson(res, 400, { ok: false, error: "repoRoot query param required" }, cors);
-      if (method === "GET") {
-        return writeJson(res, 200, { ok: true, settings: loadEditorSettings(repoRoot) }, cors);
-      }
-      if (method === "POST") {
-        try {
-          const patch = await readBody(req);
-          const settings = saveEditorSettings(repoRoot, patch || {});
-          return writeJson(res, 200, { ok: true, settings }, cors);
-        } catch (err) {
-          return writeJson(res, 400, { ok: false, error: err.message }, cors);
-        }
-      }
-      return writeJson(res, 405, { ok: false, error: "method not allowed" }, cors);
-    }
-
-    const debugMatch = reqPath.match(/^\/studio\/debug\/([^/]+)\/(events|style-write|text-write|status|stop)$/);
-    const claudeMatch = reqPath.match(/^\/studio\/claude\/([^/]+)\/(poll|reply|status)$/);
-    if (!debugMatch && !claudeMatch) return false;
-    const [, sessionId, action] = debugMatch || claudeMatch;
-
-    try {
-      if (method === "POST" && action === "events") {
-        const result = store.submitEvent(sessionId, await readBody(req));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
-      }
-      if (method === "POST" && action === "style-write") {
-        const result = store.writeStyle(sessionId, await readBody(req));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 400 : 200, result, cors);
-      }
-      if (method === "POST" && action === "text-write") {
-        const result = store.writeText(sessionId, await readBody(req));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 400 : 200, result, cors);
-      }
-      if (method === "GET" && action === "poll") {
-        const result = await store.poll(sessionId, url.searchParams.get("token"), url.searchParams.get("timeout"));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
-      }
-      if (method === "POST" && action === "reply") {
-        const result = store.reply(sessionId, await readBody(req));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
-      }
-      if (method === "GET" && action === "status") {
-        const result = store.status(sessionId, url.searchParams.get("token"));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
-      }
-      if (method === "POST" && action === "stop") {
-        const body = await readBody(req);
-        const result = store.stop(sessionId, body.token || url.searchParams.get("token"));
-        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
-      }
-      return writeJson(res, 405, { ok: false, error: "method_not_allowed" }, cors);
-    } catch (err) {
-      return writeJson(res, 400, { ok: false, error: err.message }, cors);
-    }
-  }
-
-  return { store, handle };
-}
-
-export const studioDebugTargets = APP_TARGETS;
-export { buildEditPrompt, buildChatPrompt, loadEditorSettings };
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawn } from "child_process";
+import ts from "typescript";
+
+const DEFAULT_POLL_TIMEOUT = 600_000;
+const MAX_POLL_TIMEOUT = 600_000;
+const MAX_EVENT_QUEUE = 100;
+const MAX_SNIPPET = 2_000;
+const STYLE_WRITE_EXTENSIONS = new Set([".css", ".scss", ".sass", ".less", ".html", ".jsx", ".tsx"]);
+const TEXT_WRITE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".html", ".md", ".txt", ".css", ".scss"]);
+
+const APP_TARGETS = {
+  studio_test: {
+    appSlug: "studio_test",
+    brandSlug: "studio_test",
+    packageName: "@regen/studio",
+    command: "pnpm --filter @regen/studio dev",
+    url: "http://localhost:3011/editor/local-test-target",
+  },
+  "studio-test": {
+    appSlug: "studio_test",
+    brandSlug: "studio_test",
+    packageName: "@regen/studio",
+    command: "pnpm --filter @regen/studio dev",
+    url: "http://localhost:3011/editor/local-test-target",
+  },
+  prt: {
+    appSlug: "prt",
+    brandSlug: "prt",
+    packageName: "@regen/prt-portal",
+    command: "pnpm --filter @regen/prt-portal dev",
+    url: "http://localhost:3006",
+  },
+  "prt-portal": {
+    appSlug: "prt",
+    brandSlug: "prt",
+    packageName: "@regen/prt-portal",
+    command: "pnpm --filter @regen/prt-portal dev",
+    url: "http://localhost:3006",
+  },
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+const EDITOR_SETTINGS_FILENAME = ".studio-editor-settings.json";
+
+/**
+ * Editable-prompts settings file — every Claude prompt built here has a default
+ * baked into code; this loads the SAME-SHAPED override from
+ * `<repoRoot>/.studio-editor-settings.json` if present (same file/shape
+ * agent-pool.js's buildFullSystemPrompt() reads, different field). Read fresh
+ * on every dispatch (no caching) so an edit takes effect on the next edit sent,
+ * no daemon restart needed. Never throws.
+ */
+function loadEditorSettings(repoRoot) {
+  if (!repoRoot) return {};
+  try {
+    const settingsPath = path.join(repoRoot, EDITOR_SETTINGS_FILENAME);
+    if (!fs.existsSync(settingsPath)) return {};
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (e) {
+    console.error(`[studio-debug] ${EDITOR_SETTINGS_FILENAME} malformed, using code default edit prompt: ${e.message}`);
+    return {};
+  }
+}
+
+/**
+ * Build the per-edit dispatch prompt. Editable: set `editPromptTemplate` in
+ * `<repoRoot>/.studio-editor-settings.json` to override the whole template —
+ * tokens {targetFile} {purpose} {appSlug} {brandSlug} {repoRoot} {devUrl}
+ * {mode} {selector} {currentText} {newText} {notes} are substituted (each
+ * resolves to "" when the underlying value is absent, same as the default).
+ */
+function buildEditPrompt(session, event) {
+  const repoRoot = (session.repoRoot || session.cwd || "").replace(/\\/g, "/");
+  const targetFile = event.file
+    ? `TARGET FILE: ${event.file}`
+    : `TARGET FILE: unknown — locate it from Selector "${event.selector || "unknown"}"${event.component ? ` (component: ${event.component})` : ""} in the repo below before editing anything.`;
+  const tokens = {
+    targetFile,
+    purpose: event.instruction || "Make the requested edit.",
+    appSlug: session.appSlug || "",
+    brandSlug: session.brandSlug || "",
+    repoRoot,
+    devUrl: session.devUrl || "unknown",
+    mode: event.mode || "direct_edit",
+    selector: event.selector || "unknown",
+    currentText: event.textSnippet || "",
+    newText: event.textEdit?.newText || "",
+    notes: event.notes || "",
+  };
+
+  const settings = loadEditorSettings(repoRoot);
+  if (typeof settings.editPromptTemplate === "string" && settings.editPromptTemplate.trim()) {
+    return Object.entries(tokens).reduce(
+      (text, [key, value]) => text.replaceAll(`{${key}}`, value),
+      settings.editPromptTemplate,
+    );
+  }
+
+  return [
+    `You are a Studio local-debug agent. Make ONE source edit to the codebase.`,
+    ``,
+    // Explicit file + purpose, stated up front and unmissable — required even when
+    // no deterministic file hint exists, so a warm session's first turn is never
+    // vague about what it's touching or why.
+    tokens.targetFile,
+    `PURPOSE: ${tokens.purpose}`,
+    ``,
+    `App: ${tokens.appSlug} (brand: ${tokens.brandSlug})`,
+    `Repo: ${tokens.repoRoot}`,
+    `Dev URL: ${tokens.devUrl}`,
+    ``,
+    `Edit event:`,
+    `  Mode: ${tokens.mode}`,
+    `  Selector: ${tokens.selector}`,
+    tokens.currentText ? `  Current text: "${tokens.currentText}"` : "",
+    tokens.newText ? `  New text: "${tokens.newText}"` : "",
+    tokens.notes ? `  Notes: ${tokens.notes}` : "",
+    ``,
+    `Do not edit any file other than the one this edit targets.`,
+    `After editing, output a JSON object: {"status":"done","message":"<what you did>","filesChanged":["<path>"]}`,
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Build the prompt for a `mode:"chat"` event — a genuine conversational turn, not a
+ * source edit. Deliberately does NOT reuse buildEditPrompt(): that template's "Make ONE
+ * source edit" instruction plus the {"status","message","filesChanged"} JSON-output
+ * contract make no sense for a question like "what does this page do?" and produced
+ * broken chat replies (the agent trying to force a conversational answer into an edit
+ * JSON shape, or refusing because there was no real target file to edit). Editable via
+ * `<repoRoot>/.studio-editor-settings.json`'s `chatPromptTemplate` field (same token set
+ * as `editPromptTemplate`, same substitution rule).
+ */
+function buildChatPrompt(session, event) {
+  const repoRoot = (session.repoRoot || session.cwd || "").replace(/\\/g, "/");
+  const tokens = {
+    purpose: event.instruction || "",
+    appSlug: session.appSlug || "",
+    brandSlug: session.brandSlug || "",
+    repoRoot,
+    devUrl: session.devUrl || "unknown",
+  };
+
+  const settings = loadEditorSettings(repoRoot);
+  if (typeof settings.chatPromptTemplate === "string" && settings.chatPromptTemplate.trim()) {
+    return Object.entries(tokens).reduce(
+      (text, [key, value]) => text.replaceAll(`{${key}}`, value),
+      settings.chatPromptTemplate,
+    );
+  }
+
+  return [
+    `You are a Studio local-debug chat assistant helping someone edit the "${tokens.appSlug}" app (brand: ${tokens.brandSlug}).`,
+    `Repo: ${tokens.repoRoot}`,
+    `Dev URL: ${tokens.devUrl}`,
+    ``,
+    `This is a conversational turn, not a source-edit dispatch — answer the question or`,
+    `discuss the request in plain text. Only touch files if the person explicitly asks`,
+    `you to make a change; if you do, describe what you changed in your reply.`,
+    `Reply in plain prose — do NOT wrap your answer in the edit-dispatch JSON contract.`,
+    ``,
+    tokens.purpose,
+  ].filter(Boolean).join("\n");
+}
+
+/**
+ * Persist an editable-prompts settings patch to `<repoRoot>/.studio-editor-settings.json`,
+ * merging with whatever is already on disk. Only `systemPrompt`, `editPromptTemplate`, and
+ * `chatPromptTemplate` are recognized fields — the same keys loadEditorSettings()/buildEditPrompt() (this
+ * file) and buildFullSystemPrompt()/buildStudioEditorSystemPrompt() (agent-pool.js) read.
+ * Empty-string values clear that field back to the code default rather than persisting "".
+ */
+function saveEditorSettings(repoRoot, patch) {
+  if (!repoRoot) throw new Error("repoRoot required");
+  const settingsPath = path.join(repoRoot, EDITOR_SETTINGS_FILENAME);
+  const current = loadEditorSettings(repoRoot);
+  const next = { ...current };
+  for (const key of ["systemPrompt", "editPromptTemplate", "chatPromptTemplate"]) {
+    if (!(key in patch)) continue;
+    const value = typeof patch[key] === "string" ? patch[key].trim() : "";
+    if (value) next[key] = value;
+    else delete next[key];
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + "\n", "utf8");
+  return next;
+}
+
+function safeString(value, max = MAX_SNIPPET) {
+  if (typeof value !== "string") return value;
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+function normalizeEvent(session, body) {
+  const type = body.type || body.mode || "direct_edit";
+  const id = body.id || `evt_${crypto.randomUUID()}`;
+  const target = body.target && typeof body.target === "object" ? { ...body.target } : {};
+  if (typeof target.textSnippet === "string") target.textSnippet = safeString(target.textSnippet, 500);
+  if (typeof target.outerHTMLSnippet === "string") target.outerHTMLSnippet = safeString(target.outerHTMLSnippet, MAX_SNIPPET);
+  if (typeof target.outerHTML === "string" && !target.outerHTMLSnippet) {
+    target.outerHTMLSnippet = safeString(target.outerHTML, MAX_SNIPPET);
+    delete target.outerHTML;
+  }
+
+  return {
+    type,
+    id,
+    mode: body.mode || type,
+    sessionId: session.sessionId,
+    brandSlug: session.brandSlug,
+    appSlug: session.appSlug,
+    target,
+    reference: body.reference || null,
+    instruction: safeString(body.instruction || body.prompt || "", 4_000),
+    createdAt: nowIso(),
+  };
+}
+
+function readBody(req, maxBytes = 128 * 1024) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", chunk => {
+      data += chunk;
+      if (data.length > maxBytes) reject(new Error("Body too large"));
+    });
+    req.on("end", () => {
+      if (!data.trim()) return resolve({});
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        reject(new Error("Invalid JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function writeJson(res, status, data, cors) {
+  res.writeHead(status, { "Content-Type": "application/json", ...cors });
+  res.end(JSON.stringify(data));
+}
+
+function resolveSourceFile(session, file, allowedExtensions = STYLE_WRITE_EXTENSIONS) {
+  if (!file || typeof file !== "string") return null;
+  const root = path.resolve(session.repoRoot || session.cwd || process.cwd());
+  const candidate = path.isAbsolute(file) ? path.resolve(file) : path.resolve(root, file);
+  const rel = path.relative(root, candidate);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  if (!allowedExtensions.has(path.extname(candidate).toLowerCase())) return null;
+  return { root, path: candidate, relativePath: rel.replace(/\\/g, "/") };
+}
+
+function applyTextRangeEdit(sourceText, textEdit) {
+  const source = textEdit.source;
+  if (!source || !source.range || typeof source.range.start !== "number" || typeof source.range.end !== "number") {
+    throw new Error("text-write requires source.range.start and source.range.end.");
+  }
+  const { start, end } = source.range;
+  if (start < 0 || end < start || end > sourceText.length) {
+    throw new Error(`text-write source range [${start}, ${end}] is out of bounds (file length: ${sourceText.length}).`);
+  }
+  if (textEdit.oldText !== undefined) {
+    const oldSlice = sourceText.slice(start, end);
+    if (oldSlice !== textEdit.oldText) {
+      throw new Error(`text-write oldText mismatch at [${start}, ${end}]: expected "${String(textEdit.oldText).slice(0, 80)}", found "${oldSlice.slice(0, 80)}".`);
+    }
+  }
+  return `${sourceText.slice(0, start)}${textEdit.newText}${sourceText.slice(end)}`;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function applyCssTextEdit(source, property, value, lineNumber = null) {
+  const propertyPattern = new RegExp(`(${escapeRegExp(property)}\\s*:\\s*)([^;\\n]+)(\\s*;?)`);
+  if (Number.isInteger(lineNumber) && lineNumber > 0) {
+    const lines = source.split(/\r?\n/);
+    const index = Math.min(lines.length - 1, lineNumber - 1);
+    const windowStart = Math.max(0, index - 8);
+    const windowEnd = Math.min(lines.length - 1, index + 8);
+    for (let i = windowStart; i <= windowEnd; i += 1) {
+      if (propertyPattern.test(lines[i])) {
+        lines[i] = lines[i].replace(propertyPattern, `$1${value}$3`);
+        return { content: lines.join("\n"), strategy: "replace-near-line" };
+      }
+    }
+    const anchor = lines[index] ?? "";
+    const indent = anchor.match(/^\s*/)?.[0] ?? "";
+    lines.splice(index + 1, 0, `${indent}${property}: ${value};`);
+    return { content: lines.join("\n"), strategy: "insert-near-line" };
+  }
+  const replaced = source.replace(propertyPattern, `$1${value}$3`);
+  if (replaced !== source) return { content: replaced, strategy: "replace-first" };
+  throw new Error(`CSS property "${property}" was not found and no source line was provided.`);
+}
+
+function applyJsxStyleEdit(source, property, value, lineNumber = null) {
+  const lines = source.split(/\r?\n/);
+  const targetIndex = Number.isInteger(lineNumber) && lineNumber > 0 ? Math.min(lines.length - 1, lineNumber - 1) : -1;
+  const windowStart = targetIndex >= 0 ? Math.max(0, targetIndex - 8) : 0;
+  const windowEnd = targetIndex >= 0 ? Math.min(lines.length - 1, targetIndex + 8) : lines.length - 1;
+  const camel = property.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  const quoted = JSON.stringify(value);
+  const propPattern = new RegExp(`(${camel}\\s*:\\s*)(["'\`])([^"'\`]+)(\\2)`);
+
+  for (let i = windowStart; i <= windowEnd; i += 1) {
+    if (propPattern.test(lines[i])) {
+      lines[i] = lines[i].replace(propPattern, `$1${quoted}`);
+      return { content: lines.join("\n"), strategy: "replace-js-style-near-line" };
+    }
+  }
+
+  for (let i = windowStart; i <= windowEnd; i += 1) {
+    if (lines[i].includes("style={{")) {
+      lines[i] = lines[i].replace("style={{", `style={{ ${camel}: ${quoted},`);
+      return { content: lines.join("\n"), strategy: "insert-js-style-near-line" };
+    }
+  }
+
+  throw new Error(`No inline style object for "${property}" was found near the selected source line.`);
+}
+
+// Syntax-check extensions we know how to parse with the TS compiler. Non-TS/JS
+// source (e.g. plain .css, .md) is skipped — there is nothing meaningful for
+// ts.transpileModule to validate there.
+const SYNTAX_CHECK_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+
+// Same pattern already proven in
+// packages/studio-local-debug/src/integration/editor-coverage-matrix.test.ts
+// (syntaxDiagnosticsLikeEditor) and returned by apps/studio's accept-adapter.ts
+// as `syntaxDiagnostics`. Kept identical here so results are directly comparable.
+function syntaxDiagnosticsFor(source, fileName) {
+  const output = ts.transpileModule(source, {
+    fileName,
+    reportDiagnostics: true,
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ESNext,
+      module: ts.ModuleKind.ESNext,
+    },
+  });
+  return output.diagnostics || [];
+}
+
+function formatDiagnostic(diagnostic) {
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+  if (diagnostic.file && typeof diagnostic.start === "number") {
+    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+    return `${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`;
+  }
+  return message;
+}
+
+/**
+ * Read each changed file (relative to the session repo root) and run a TS
+ * syntax check. Returns { ok, diagnostics } — diagnostics is a flat array of
+ * human-readable strings, empty when every checkable file is syntax-clean.
+ * Files outside SYNTAX_CHECK_EXTENSIONS, or that no longer exist on disk, are
+ * skipped (not treated as failures) — this check validates parseability, not
+ * file presence.
+ */
+function checkFilesSyntax(session, filesChanged) {
+  const diagnostics = [];
+  const root = path.resolve(session.repoRoot || session.cwd || process.cwd());
+  for (const file of Array.isArray(filesChanged) ? filesChanged : []) {
+    if (!file || typeof file !== "string") continue;
+    const ext = path.extname(file).toLowerCase();
+    if (!SYNTAX_CHECK_EXTENSIONS.has(ext)) continue;
+    const candidate = path.isAbsolute(file) ? path.resolve(file) : path.resolve(root, file);
+    let source;
+    try {
+      source = fs.readFileSync(candidate, "utf8");
+    } catch (err) {
+      // A referenced file that no longer exists is itself suspicious, but the
+      // agent may have renamed/moved it deliberately as part of the edit —
+      // treat as unable-to-verify, not a hard syntax failure.
+      continue;
+    }
+    const fileDiagnostics = syntaxDiagnosticsFor(source, candidate);
+    for (const d of fileDiagnostics) {
+      diagnostics.push(`${file}: ${formatDiagnostic(d)}`);
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
+
+/**
+ * Best-effort collection of the file(s) an event referenced, used as a
+ * fallback filesChanged set when the agent's JSON reply fails to parse (or
+ * omits filesChanged) — so a malformed-but-plausible-looking agent response
+ * still gets its target file(s) syntax-checked instead of slipping through
+ * ungated.
+ */
+function filesReferencedByEvent(event) {
+  const files = new Set();
+  const add = (f) => {
+    if (typeof f === "string" && f.trim()) files.add(f.trim());
+  };
+  add(event?.file);
+  add(event?.target?.file);
+  add(event?.textEdit?.source?.file);
+  add(event?.styleEdit?.source?.file);
+  return [...files];
+}
+
+async function isUrlReachable(url) {
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      signal: AbortSignal.timeout(1_500),
+    });
+    return response.status < 500;
+  } catch {
+    return false;
+  }
+}
+
+function resolveTarget(input = {}) {
+  const slug = String(input.appSlug || input.brandSlug || "prt").toLowerCase();
+  const configured = APP_TARGETS[slug];
+  // No registration required IF the caller supplies an explicit devUrl/devCommand —
+  // an arbitrary appSlug with an explicit target is a legitimate ad-hoc session. But
+  // an unknown slug with NO explicit override has nothing to resolve to at all.
+  if (!configured && !input.devUrl && !input.devCommand) {
+    return {
+      error: "unknown_app",
+      message: `Unknown appSlug "${slug}" — not registered in APP_TARGETS and no devUrl/devCommand override was provided.`,
+    };
+  }
+
+  const base = configured || {
+    appSlug: slug,
+    brandSlug: input.brandSlug || slug,
+    command: input.devCommand,
+    url: input.devUrl,
+  };
+
+  return {
+    appSlug: input.appSlug || base.appSlug,
+    brandSlug: input.brandSlug || base.brandSlug || input.appSlug || base.appSlug,
+    command: input.devCommand || base.command,
+    url: input.devUrl || base.url,
+    cwd: input.cwd || input.repoRoot || process.cwd(),
+  };
+}
+
+/**
+ * A reachable HTTP server is not necessarily a genuine Next.js DEV server the editor
+ * can attach HMR-based live edits to — it could be a production build (no HMR at all)
+ * or a dev server sitting behind an auth gate the editor can't get past. Probe the
+ * webpack-hmr path: a redirect (typically to a login page) or an auth-rejection status
+ * means source-edit sessions cannot establish the HMR stream this feature depends on.
+ */
+async function isGenuineDevServer(url) {
+  try {
+    const response = await fetch(`${url.replace(/\/$/, "")}/_next/webpack-hmr`, {
+      method: "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(1_500),
+    });
+    if (response.status >= 300 && response.status < 400) return false;
+    if (response.status === 401 || response.status === 403) return false;
+    return true;
+  } catch {
+    // Network-level errors on a websocket-upgrade path (abrupt close, protocol error)
+    // are expected even for a genuine dev server hit with a plain GET — don't reject
+    // on that basis alone, only on an explicit auth/redirect signal above.
+    return true;
+  }
+}
+
+function splitCommand(command) {
+  if (!command || typeof command !== "string") return null;
+  const parts = command.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+  return parts.map(part => part.replace(/^"|"$/g, ""));
+}
+
+function startDevProcess(target, logFile) {
+  const parts = splitCommand(target.command);
+  if (!parts || parts.length === 0) {
+    return { started: false, error: "missing_command" };
+  }
+
+  const logDir = path.join(os.tmpdir(), "clauth-studio-debug");
+  fs.mkdirSync(logDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const outPath = path.join(logDir, `${target.appSlug}-${stamp}.out.log`);
+  const errPath = path.join(logDir, `${target.appSlug}-${stamp}.err.log`);
+  const out = fs.openSync(outPath, "a");
+  const err = fs.openSync(errPath, "a");
+
+  const proc = spawn(parts[0], parts.slice(1), {
+    cwd: target.cwd,
+    env: process.env,
+    stdio: ["ignore", out, err],
+    shell: process.platform === "win32",
+    detached: true,
+    windowsHide: true,
+  });
+  proc.unref();
+  try {
+    fs.appendFileSync(logFile, `[${nowIso()}] studio-debug dev start pid=${proc.pid} command=${target.command}\n`);
+  } catch {}
+
+  return {
+    started: true,
+    pid: proc.pid,
+    command: target.command,
+    url: target.url,
+    stdout: outPath,
+    stderr: errPath,
+    process: proc,
+  };
+}
+
+export class StudioDebugSessionStore {
+  constructor({
+    port = 52437,
+    logFile = path.join(os.tmpdir(), "clauth-serve.log"),
+    dispatchAgent = null,
+    acquireSessionWorker = null,
+    releaseSessionWorker = null,
+  } = {}) {
+    this.port = port;
+    this.logFile = logFile;
+    this.sessions = new Map();
+    this.dispatchAgent = dispatchAgent;
+    // One warm channel per editor session, acquired eagerly at start() and reused for
+    // every dispatch (chat and direct-edit alike) via submitEvent()'s dispatchAgent call
+    // through to session end — never a fresh one-shot process per edit.
+    this.acquireSessionWorker = acquireSessionWorker;
+    this.releaseSessionWorker = releaseSessionWorker;
+  }
+
+  async start(input = {}) {
+    const target = resolveTarget(input);
+    if (target.error) {
+      return { ok: false, error: target.error, message: target.message, status: "error" };
+    }
+
+    const shouldLaunch = input.launchDevServer !== false;
+    const reachable = await isUrlReachable(target.url);
+    if (reachable && !(await isGenuineDevServer(target.url))) {
+      return {
+        ok: false,
+        error: "non_dev_server",
+        message: `${target.url} is reachable but its Next dev HMR stream is not accessible (redirected or auth-gated) — source-edit sessions require a genuine, reachable Next.js dev server.`,
+        status: "error",
+      };
+    }
+    const launch = reachable
+      ? { started: false, command: target.command, url: target.url, alreadyRunning: true }
+      : shouldLaunch
+        ? startDevProcess(target, this.logFile)
+        : { started: false, command: target.command, url: target.url, skipped: true };
+
+    const sessionId = input.sessionId || `studio-${crypto.randomUUID()}`;
+    const token = crypto.randomBytes(24).toString("base64url");
+    const session = {
+      sessionId,
+      token,
+      brandSlug: target.brandSlug,
+      appSlug: target.appSlug,
+      repoRoot: input.repoRoot || target.cwd,
+      cwd: target.cwd,
+      devCommand: target.command,
+      devUrl: target.url,
+      modeDefault: input.modeDefault || "direct_edit",
+      agentModel: typeof input.agentModel === "string" && input.agentModel.trim() ? input.agentModel.trim() : null,
+      warmAgent: input.warmAgent !== false,
+      status: "waiting_for_agent",
+      createdAt: nowIso(),
+      updatedAt: nowIso(),
+      stopped: false,
+      events: [],
+      replies: [],
+      pendingPolls: [],
+      launch,
+    };
+    this.sessions.set(sessionId, session);
+
+    const relayBaseUrl = `http://127.0.0.1:${this.port}/studio/debug/${sessionId}`;
+    const claudeBaseUrl = `http://127.0.0.1:${this.port}/studio/claude/${sessionId}`;
+    const pollCommand = `node scripts/studio-debug-poll.mjs --session ${sessionId} --token ${token} --relay ${claudeBaseUrl}`;
+
+    // When dispatchAgent is wired, events dispatch directly — no polling agent needed.
+    if (this.dispatchAgent) {
+      session.status = "waiting_for_event";
+    }
+
+    // Acquire this session's warm channel now, at session start — not lazily on the
+    // first edit. Every subsequent dispatchAgent call for this sessionId (chat or
+    // direct-edit) reuses the same pinned worker. Best-effort: a warm-pool exhaustion
+    // here does not fail session start, dispatchToSession() will surface it per-turn.
+    if (session.warmAgent && this.acquireSessionWorker) {
+      try { this.acquireSessionWorker(sessionId, session.agentModel, session.repoRoot || session.cwd); } catch { /* best-effort */ }
+    }
+
+    return {
+      ok: true,
+      sessionId,
+      token,
+      devUrl: target.url,
+      relayBaseUrl,
+      status: session.status,
+      agentMode: session.warmAgent ? "warm" : "disabled",
+      launch: {
+        started: !!launch.started,
+        alreadyRunning: !!launch.alreadyRunning,
+        command: launch.command,
+        url: launch.url,
+        pid: launch.pid || null,
+      },
+      pollCommand,
+      claudeBaseUrl,
+    };
+  }
+
+  get(sessionId) {
+    return this.sessions.get(sessionId) || null;
+  }
+
+  authenticate(sessionId, token) {
+    const session = this.get(sessionId);
+    if (!session) return { error: "not_found" };
+    if (session.token !== token) return { error: "unauthorized" };
+    return { session };
+  }
+
+  submitEvent(sessionId, body) {
+    const auth = this.authenticate(sessionId, body.token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    if (!session.warmAgent) {
+      return {
+        error: "agent_disabled",
+        message: "This direct-write session does not allow agent-dispatched events.",
+      };
+    }
+    const event = normalizeEvent(session, body);
+
+    session.updatedAt = nowIso();
+    session.status = "event_pending";
+
+    // If a dispatchAgent handler exists, spawn a full headless Claude agent.
+    if (this.dispatchAgent) {
+      // Stash images from the event body so the dispatcher can write them to tmp
+      if (Array.isArray(body.images) && body.images.length > 0) {
+        session._pendingImages = body.images;
+      }
+
+      // A chat turn is conversational, not a source-edit dispatch: use buildChatPrompt()
+      // (plain prose, no "make ONE source edit" instruction, no edit-JSON output contract)
+      // and skip the syntax-check-and-retry loop below entirely — there's no edited file
+      // to check, and the agent's raw reply text IS the message, not something to parse
+      // as JSON. Previously every chat message reused buildEditPrompt(), so the agent was
+      // told to edit a file and reply in {"status","message","filesChanged"} JSON for what
+      // was just a question — see submitEvent's mode branch below for the corresponding fix.
+      if (event.mode === "chat") {
+        const chatPrompt = buildChatPrompt(session, event);
+        this.dispatchAgent(event.id, session.token, null, session, chatPrompt)
+          .then((result) => {
+            const message = String(result?.package ?? "").trim() || "(no reply)";
+            session.replies.push({
+              eventId: event.id,
+              status: result?.ok === false ? "error" : "done",
+              message,
+              filesChanged: [],
+              diagnostics: [],
+              createdAt: nowIso(),
+            });
+            session.status = result?.ok === false ? "error" : "done";
+            session.updatedAt = nowIso();
+          })
+          .catch((err) => {
+            session.replies.push({
+              eventId: event.id,
+              status: "error",
+              message: `Chat dispatch failed: ${err?.message || "unknown error"}`,
+              filesChanged: [],
+              diagnostics: [],
+              createdAt: nowIso(),
+            });
+            session.status = "error";
+            session.updatedAt = nowIso();
+          });
+        return { ok: true, eventId: event.id, status: session.status };
+      }
+
+      const prompt = buildEditPrompt(session, event);
+
+      const fallbackFiles = filesReferencedByEvent(event);
+
+      const parseAgentResult = (result) => {
+        // BUG FIX (2026-07-02): AgentPool.dispatchToSession()/dispatch() resolve with
+        // `result.package` (the agent's raw final-text response, see agent-pool.js:629
+        // `package: (text || "").trim()`) -- NOT `result.stdout` or `result.output`,
+        // neither of which exist on this result shape. Reading the wrong fields meant
+        // JSON.parse("") always threw, parsed silently stayed {}, and EVERY dispatch
+        // reported status:"done" / filesChanged:[] regardless of what the agent
+        // actually did -- the syntax-check-and-retry loop below was checking an empty
+        // file list every single time and never catching anything.
+        const rawText = String(result?.package ?? "").trim();
+        let parsed = {};
+        try {
+          parsed = JSON.parse(rawText);
+        } catch {
+          // Agents don't always emit pure JSON despite instructions -- a trailing/leading
+          // sentence around the JSON object is common. Try to recover the LAST {...}
+          // block in the text before giving up (never throws further).
+          const match = rawText.match(/\{[\s\S]*\}/);
+          if (match) {
+            try { parsed = JSON.parse(match[0]); } catch { /* give up, use defaults below */ }
+          }
+        }
+        const filesChanged = Array.isArray(parsed.filesChanged) && parsed.filesChanged.length > 0
+          ? parsed.filesChanged
+          : fallbackFiles;
+        return {
+          status: parsed.status || "done",
+          message: parsed.message || rawText.slice(0, 500) || "Agent completed",
+          filesChanged,
+        };
+      };
+
+      // D1/D2 (studio-editor-v1-auto-escalation.md): after the dispatched agent
+      // reports back, verify the file(s) it touched still parse before trusting
+      // "status":"done". A malformed agent JSON reply (bare try/catch above)
+      // must NOT bypass this — filesChanged falls back to whatever the original
+      // event referenced so even an unparseable reply still gets checked.
+      // On a syntax failure, re-dispatch exactly once with the diagnostic
+      // appended; a second failure (or a second dispatch error) is a hard stop
+      // to status "error" with diagnostics attached — never a silent accept,
+      // never an unbounded retry loop.
+      this.dispatchAgent(event.id, session.token, null, session, prompt)
+        .then(async (result) => {
+          const attempt1 = parseAgentResult(result);
+          const check1 = checkFilesSyntax(session, attempt1.filesChanged);
+
+          if (check1.ok) {
+            session.replies.push({
+              eventId: event.id,
+              status: attempt1.status,
+              message: attempt1.message,
+              filesChanged: attempt1.filesChanged,
+              diagnostics: [],
+              createdAt: nowIso(),
+            });
+            session.status = "done";
+            session.updatedAt = nowIso();
+            return;
+          }
+
+          const retryPrompt = [
+            prompt,
+            ``,
+            `Your previous edit broke the file's syntax. Diagnostic: ${check1.diagnostics.join("; ")}.`,
+            `Fix the file so it is syntactically valid, preserving your intended change.`,
+          ].join("\n");
+
+          let attempt2Result;
+          try {
+            attempt2Result = await this.dispatchAgent(event.id, session.token, null, session, retryPrompt);
+          } catch {
+            session.replies.push({
+              eventId: event.id,
+              status: "error",
+              message: "Agent retry dispatch failed after syntax check failure",
+              filesChanged: attempt1.filesChanged,
+              diagnostics: check1.diagnostics,
+              createdAt: nowIso(),
+            });
+            session.status = "error";
+            session.updatedAt = nowIso();
+            return;
+          }
+
+          const attempt2 = parseAgentResult(attempt2Result);
+          const check2 = checkFilesSyntax(session, attempt2.filesChanged);
+
+          if (check2.ok) {
+            session.replies.push({
+              eventId: event.id,
+              status: attempt2.status,
+              message: attempt2.message,
+              filesChanged: attempt2.filesChanged,
+              diagnostics: [],
+              createdAt: nowIso(),
+            });
+            session.status = "done";
+            session.updatedAt = nowIso();
+            return;
+          }
+
+          session.replies.push({
+            eventId: event.id,
+            status: "error",
+            message: `Agent edit failed syntax check after retry: ${check2.diagnostics.join("; ")}`,
+            filesChanged: attempt2.filesChanged,
+            diagnostics: check2.diagnostics,
+            createdAt: nowIso(),
+          });
+          session.status = "error";
+          session.updatedAt = nowIso();
+        })
+        .catch(() => {
+          session.replies.push({
+            eventId: event.id,
+            status: "error",
+            message: "Agent dispatch failed",
+            filesChanged: [],
+            diagnostics: [],
+            createdAt: nowIso(),
+          });
+          session.status = "error";
+          session.updatedAt = nowIso();
+        });
+
+      return { ok: true, eventId: event.id, status: session.status };
+    }
+
+    // Legacy path: queue for a polling agent
+    if (session.pendingPolls.length > 0) {
+      const poll = session.pendingPolls.shift();
+      poll(event);
+    } else {
+      session.events.push(event);
+      if (session.events.length > MAX_EVENT_QUEUE) session.events.shift();
+    }
+    return { ok: true, eventId: event.id, status: session.status };
+  }
+
+  poll(sessionId, token, timeoutMs = DEFAULT_POLL_TIMEOUT) {
+    const auth = this.authenticate(sessionId, token);
+    if (auth.error) return Promise.resolve(auth);
+    const session = auth.session;
+    if (session.events.length > 0) {
+      session.status = "agent_received";
+      session.updatedAt = nowIso();
+      return Promise.resolve(session.events.shift());
+    }
+    if (session.stopped) return Promise.resolve({ type: "stopped" });
+
+    const timeout = Math.min(Math.max(Number(timeoutMs) || DEFAULT_POLL_TIMEOUT, 1), MAX_POLL_TIMEOUT);
+    session.status = "waiting_for_event";
+    session.updatedAt = nowIso();
+
+    return new Promise(resolve => {
+      const timer = setTimeout(() => {
+        session.pendingPolls = session.pendingPolls.filter(fn => fn !== finish);
+        resolve({ type: "timeout" });
+      }, timeout);
+      const finish = event => {
+        clearTimeout(timer);
+        session.status = "agent_received";
+        session.updatedAt = nowIso();
+        resolve(event);
+      };
+      session.pendingPolls.push(finish);
+    });
+  }
+
+  reply(sessionId, body) {
+    const auth = this.authenticate(sessionId, body.token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    const reply = {
+      eventId: body.eventId,
+      status: body.status || body.type || "done",
+      message: body.message || "",
+      filesChanged: Array.isArray(body.filesChanged)
+        ? body.filesChanged
+        : body.file
+          ? [body.file]
+          : [],
+      createdAt: nowIso(),
+    };
+    session.replies.push(reply);
+    session.status = reply.status === "done" ? "done" : reply.status;
+    session.updatedAt = nowIso();
+    return { ok: true, status: session.status, reply };
+  }
+
+  writeText(sessionId, body) {
+    const auth = this.authenticate(sessionId, body.token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    const textEdit = body.textEdit && typeof body.textEdit === "object" ? body.textEdit : {};
+    const source = textEdit.source && typeof textEdit.source === "object" ? textEdit.source : {};
+    const file = source.file || textEdit.file || body.file;
+    const fileInfo = resolveSourceFile(session, file, TEXT_WRITE_EXTENSIONS);
+    if (!fileInfo) {
+      return { error: "invalid_source", message: `text-write requires a source file inside the debug session repo (got: ${file || "(none)"}).` };
+    }
+    if (typeof textEdit.newText !== "string") {
+      return { error: "invalid_body", message: "text-write requires textEdit.newText." };
+    }
+    try {
+      const original = fs.readFileSync(fileInfo.path, "utf8");
+      const updated = applyTextRangeEdit(original, { ...textEdit, source });
+      fs.writeFileSync(fileInfo.path, updated, "utf8");
+      const reply = {
+        eventId: body.id || `text_${crypto.randomUUID()}`,
+        status: "done",
+        message: `Direct text write (source_replace [${source.range?.start}, ${source.range?.end}])`,
+        filesChanged: [fileInfo.relativePath],
+        createdAt: nowIso(),
+      };
+      session.replies.push(reply);
+      session.status = "done";
+      session.updatedAt = nowIso();
+      return { ok: true, status: "done", eventId: reply.eventId, filesChanged: reply.filesChanged };
+    } catch (err) {
+      return { error: "text_write_failed", message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  writeStyle(sessionId, body) {
+    const auth = this.authenticate(sessionId, body.token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    const styleEdit = body.styleEdit && typeof body.styleEdit === "object" ? body.styleEdit : {};
+    const deltas = Array.isArray(styleEdit.deltas) ? styleEdit.deltas : [];
+    const source = styleEdit.source && typeof styleEdit.source === "object" ? styleEdit.source : {};
+    const fileInfo = resolveSourceFile(session, source.file || body.file);
+    if (!fileInfo) return { error: "invalid_source", message: "style-write requires a source file inside the debug session repo." };
+    if (deltas.length !== 1) return { error: "invalid_delta", message: "style-write currently accepts exactly one deterministic CSS delta." };
+
+    const delta = deltas[0] || {};
+    if (typeof delta.property !== "string" || typeof delta.value !== "string") {
+      return { error: "invalid_delta", message: "style-write requires string property and value." };
+    }
+
+    try {
+      const original = fs.readFileSync(fileInfo.path, "utf8");
+      const ext = path.extname(fileInfo.path).toLowerCase();
+      const result = ext === ".jsx" || ext === ".tsx"
+        ? applyJsxStyleEdit(original, delta.property, delta.value, source.line || body.line || null)
+        : applyCssTextEdit(original, delta.property, delta.value, source.line || body.line || null);
+      fs.writeFileSync(fileInfo.path, result.content, "utf8");
+      const reply = {
+        eventId: body.id || `style_${crypto.randomUUID()}`,
+        status: "done",
+        message: `Direct style write (${result.strategy})`,
+        filesChanged: [fileInfo.relativePath],
+        createdAt: nowIso(),
+      };
+      session.replies.push(reply);
+      session.status = "done";
+      session.updatedAt = nowIso();
+      return { ok: true, status: "done", eventId: reply.eventId, filesChanged: reply.filesChanged, strategy: result.strategy };
+    } catch (err) {
+      return { error: "style_write_failed", message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  status(sessionId, token) {
+    const auth = this.authenticate(sessionId, token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    return {
+      ok: true,
+      sessionId: session.sessionId,
+      brandSlug: session.brandSlug,
+      appSlug: session.appSlug,
+      devUrl: session.devUrl,
+      status: session.status,
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+      pendingEvents: session.events.length,
+      pendingPolls: session.pendingPolls.length,
+      replies: session.replies,
+      launch: {
+        started: !!session.launch?.started,
+        alreadyRunning: !!session.launch?.alreadyRunning,
+        command: session.launch?.command || session.devCommand,
+        url: session.launch?.url || session.devUrl,
+        pid: session.launch?.pid || null,
+      },
+    };
+  }
+
+  stop(sessionId, token) {
+    const auth = this.authenticate(sessionId, token);
+    if (auth.error) return auth;
+    const session = auth.session;
+    session.stopped = true;
+    session.status = "stopped";
+    session.updatedAt = nowIso();
+    if (session.launch?.process && !session.launch.process.killed) {
+      try {
+        session.launch.process.kill();
+      } catch {}
+    }
+    for (const poll of session.pendingPolls.splice(0)) poll({ type: "stopped" });
+    this.sessions.delete(sessionId);
+    if (this.releaseSessionWorker) {
+      try { this.releaseSessionWorker(sessionId); } catch { /* best-effort */ }
+    }
+    return { ok: true, status: "stopped", sessionId };
+  }
+}
+
+export function createStudioDebugRuntime(options) {
+  const store = new StudioDebugSessionStore(options);
+
+  async function handle(req, res, url, cors) {
+    const reqPath = url.pathname;
+    const method = req.method;
+
+    if (method === "POST" && reqPath === "/studio/debug/start") {
+      try {
+        const body = await readBody(req);
+        const result = await store.start(body);
+        return writeJson(res, result.ok ? 200 : 400, result, cors);
+      } catch (err) {
+        return writeJson(res, 400, { ok: false, error: err.message }, cors);
+      }
+    }
+
+    // Editable-prompts settings — the UI for .studio-editor-settings.json (loadEditorSettings()
+    // above / buildFullSystemPrompt()+buildStudioEditorSystemPrompt() in agent-pool.js). GET
+    // returns what's on disk (empty object if never set); POST merges a partial patch.
+    if (reqPath === "/studio/editor-settings") {
+      const repoRoot = url.searchParams.get("repoRoot");
+      if (!repoRoot) return writeJson(res, 400, { ok: false, error: "repoRoot query param required" }, cors);
+      if (method === "GET") {
+        return writeJson(res, 200, { ok: true, settings: loadEditorSettings(repoRoot) }, cors);
+      }
+      if (method === "POST") {
+        try {
+          const patch = await readBody(req);
+          const settings = saveEditorSettings(repoRoot, patch || {});
+          return writeJson(res, 200, { ok: true, settings }, cors);
+        } catch (err) {
+          return writeJson(res, 400, { ok: false, error: err.message }, cors);
+        }
+      }
+      return writeJson(res, 405, { ok: false, error: "method not allowed" }, cors);
+    }
+
+    const debugMatch = reqPath.match(/^\/studio\/debug\/([^/]+)\/(events|style-write|text-write|status|stop)$/);
+    const claudeMatch = reqPath.match(/^\/studio\/claude\/([^/]+)\/(poll|reply|status)$/);
+    if (!debugMatch && !claudeMatch) return false;
+    const [, sessionId, action] = debugMatch || claudeMatch;
+
+    try {
+      if (method === "POST" && action === "events") {
+        const result = store.submitEvent(sessionId, await readBody(req));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
+      }
+      if (method === "POST" && action === "style-write") {
+        const result = store.writeStyle(sessionId, await readBody(req));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 400 : 200, result, cors);
+      }
+      if (method === "POST" && action === "text-write") {
+        const result = store.writeText(sessionId, await readBody(req));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 400 : 200, result, cors);
+      }
+      if (method === "GET" && action === "poll") {
+        const result = await store.poll(sessionId, url.searchParams.get("token"), url.searchParams.get("timeout"));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
+      }
+      if (method === "POST" && action === "reply") {
+        const result = store.reply(sessionId, await readBody(req));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
+      }
+      if (method === "GET" && action === "status") {
+        const result = store.status(sessionId, url.searchParams.get("token"));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
+      }
+      if (method === "POST" && action === "stop") {
+        const body = await readBody(req);
+        const result = store.stop(sessionId, body.token || url.searchParams.get("token"));
+        return writeJson(res, result.error === "unauthorized" ? 401 : result.error ? 404 : 200, result, cors);
+      }
+      return writeJson(res, 405, { ok: false, error: "method_not_allowed" }, cors);
+    } catch (err) {
+      return writeJson(res, 400, { ok: false, error: err.message }, cors);
+    }
+  }
+
+  return { store, handle };
+}
+
+export const studioDebugTargets = APP_TARGETS;
+export { buildEditPrompt, buildChatPrompt, loadEditorSettings };