flowviant 0.125.29 → 0.125.30

package/bin/lib/reviewImage.mjs

@@ -0,0 +1,58 @@
+/** One network-disabled headless canvas normalizes native engine images. */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { chromeFlags, resolveBrowser, sandboxOff } from './shot.mjs';
+import { createCdpClient } from './pinnedCapture.mjs';
+import { childEnv } from './childEnv.mjs';
+
+export async function createReviewImage({ signal, onChild, timeoutMs = 620_000, detached = true, browser = resolveBrowser() } = {}) {
+  if (!browser || browser.viaWindows) throw new Error('Studio viewport review needs native headless Chromium on the daemon host to normalize captured images.');
+  const home = mkdtempSync(join(tmpdir(), 'flowviant-engine-image-'));
+  let process, cdp, closed = false, sessionId;
+  const close = async () => {
+    if (closed) return;
+    closed = true; cdp?.close('Engine image encoder closed.');
+    await process?.close();
+    try { rmSync(home, { recursive: true, force: true }); } catch { /* local cleanup */ }
+  };
+  const send = async (method, params = {}, session) => {
+    let timer;
+    try { return await Promise.race([cdp.send(method, params, session), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Engine image encoding timed out.')), 5000); })]); }
+    catch (error) { await close(); throw error; }
+    finally { clearTimeout(timer); }
+  };
+  try {
+    process = startReviewProcess([browser.bin, ...chromeFlags({ headlessFlag: '--headless=new', noSandbox: sandboxOff(), userDataDir: home, width: 1440, height: 900 }),
+      '--remote-debugging-pipe', '--disable-background-networking', '--disable-sync', '--disable-default-apps', '--proxy-server=http://127.0.0.1:9', '--proxy-bypass-list=<-loopback>', 'about:blank'],
+    { env: { ...childEnv(), HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: home, XDG_DATA_HOME: home, XDG_CACHE_HOME: home }, signal, onChild, timeoutMs, detached, captureStdout: false, stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] });
+    cdp = createCdpClient(process.child.stdio[3], process.child.stdio[4], { maxMessageBytes: 10 * 1024 * 1024 });
+    process.done.then(() => { cdp.close('Engine image encoder exited.'); void close(); });
+    await send('Browser.getVersion');
+    await send('Browser.setDownloadBehavior', { behavior: 'deny' });
+    const { targetInfos } = await send('Target.getTargets');
+    const target = targetInfos.find(t => t.type === 'page');
+    if (!target) throw new Error('No isolated engine image canvas is available.');
+    ({ sessionId } = await send('Target.attachToTarget', { targetId: target.targetId, flatten: true }));
+    await send('Network.enable', {}, sessionId);
+    await send('Network.setBlockedURLs', { urls: ['http://*', 'https://*', 'file://*', 'ws://*', 'wss://*', 'ftp://*'] }, sessionId);
+    return { close, async encode(image) {
+      if (closed) throw new Error('Engine image encoder closed.');
+      if (!image || !['image/png', 'image/jpeg'].includes(image.mimeType) || typeof image.data !== 'string' || image.data.length > 8 * 1024 * 1024 || !/^[A-Za-z0-9+/]+={0,2}$/.test(image.data)) throw new Error('Studio MCP must return one bounded PNG/JPEG image content block.');
+      const encoded = await send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `new Promise((resolve,reject)=>{
+        const image=new Image();image.onerror=()=>reject(new Error('Invalid engine image'));
+        image.onload=()=>{const width=image.naturalWidth,height=image.naturalHeight;
+          if(!width||!height||width>4096||height>4096){reject(new Error('Engine image exceeds pixel bound'));return;}
+          const scale=Math.min(1440/width,900/height),w=width*scale,h=height*scale,left=(1440-w)/2,top=(900-h)/2;
+          const canvas=document.createElement('canvas');canvas.width=1440;canvas.height=900;
+          const context=canvas.getContext('2d');context.fillStyle='#000';context.fillRect(0,0,1440,900);context.drawImage(image,left,top,w,h);
+          resolve({data:canvas.toDataURL('image/jpeg',0.65).split(',')[1],width,height,left,top,w,h});
+        };image.src=${JSON.stringify(`data:${image.mimeType};base64,${image.data}`)};
+      })` }, sessionId);
+      const result = encoded.result?.value;
+      if (encoded.exceptionDetails || !result || result.data.length > 1_000_000) throw new Error('Studio image could not be normalized within the frame bound.');
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}

package/bin/lib/reviewMcpClient.mjs

@@ -0,0 +1,69 @@
+/** Bounded stdio MCP client for an engine bridge, never a model service. */
+import { StringDecoder } from 'node:string_decoder';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+export async function connectReviewMcp({ command, cwd, env, onChild, signal, requestTimeoutMs = 15_000, timeoutMs = 620_000, detached = true }) {
+  const process = startReviewProcess(command, { cwd, env, onChild, signal, timeoutMs, detached, captureStdout: false, stdio: ['pipe', 'pipe', 'pipe'] });
+  const pending = new Map(), decoder = new StringDecoder('utf8');
+  let serial = 0, buffer = '', closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('Studio MCP disconnected.')); }
+    pending.clear(); process.child.stdin.end(); await process.close();
+  };
+  const fail = () => { void close(); };
+  process.done.then(fail);
+  process.child.stdout.on('data', bytes => {
+    if (closed) return;
+    buffer += decoder.write(bytes);
+    if (Buffer.byteLength(buffer) > 10 * 1024 * 1024) { fail(); return; }
+    let newline;
+    while (!closed && (newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line);
+        if (message.jsonrpc !== '2.0') throw new Error('Invalid MCP protocol.');
+        if (message.id != null && message.method) {
+          // This adapter supplies no sampling, elicitation or filesystem roots.
+          process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'This review client does not support server requests.' } }) + '\n');
+        } else {
+          const entry = pending.get(message.id); if (!entry) continue;
+          pending.delete(message.id); clearTimeout(entry.timer);
+          message.error ? entry.reject(new Error(reviewDiagnostic(message.error.message))) : entry.resolve(message.result);
+        }
+      } catch { fail(); }
+    }
+  });
+  const request = (method, params, limit = requestTimeoutMs) => new Promise((resolve, reject) => {
+    if (closed) { reject(new Error('Studio MCP is disconnected.')); return; }
+    const id = ++serial;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Studio MCP ${method} timed out.`)); }, limit);
+    pending.set(id, { resolve, reject, timer });
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => { if (error) fail(); });
+  });
+  try {
+    const hello = await request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'flowviant-runtime-review', version: '1' } });
+    if (!hello?.capabilities?.tools) throw new Error('The configured server exposes no MCP tools.');
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    const tools = []; let cursor;
+    for (let page = 0; page < 8; page++) {
+      const result = await request('tools/list', cursor ? { cursor } : {});
+      if (!Array.isArray(result?.tools) || tools.length + result.tools.length > 500) throw new Error('Studio MCP returned an invalid tool catalog.');
+      tools.push(...result.tools); cursor = result.nextCursor;
+      if (!cursor) break;
+      if (page === 7) throw new Error('Studio MCP tool catalog exceeded its page bound.');
+    }
+    return { tools, close, async call(name, args, limit) {
+      if (!tools.some(tool => tool.name === name)) throw new Error(`Studio MCP does not expose ${name}. Update Studio and enable its built-in MCP server.`);
+      const result = await request('tools/call', { name, arguments: args }, limit);
+      if (result?.isError) throw new Error(reviewDiagnostic((result.content ?? []).filter(c => c.type === 'text').map(c => c.text).join('\n')).slice(0, 1000) || `Studio MCP ${name} failed.`);
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}
+
+export function mcpText(result) {
+  return (result?.content ?? []).filter(c => c.type === 'text' && typeof c.text === 'string').map(c => c.text).join('\n');
+}

package/bin/lib/reviewProcess.mjs

@@ -0,0 +1,51 @@
+/** Own every runtime child and bound its output, cancellation and lifetime. */
+import { spawn } from 'node:child_process';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+export function startReviewProcess(argv, { cwd, env = process.env, display = false, input, signal, onChild = () => () => {}, timeoutMs = 600_000, binary = false, maxBytes = 64 * 1024, stdio, captureStdout = true, detached = true } = {}) {
+  signal?.throwIfAborted();
+  if (workLanesStopped()) throw new Error('The daemon is stopping. Review has not started.');
+  const child = spawn(argv[0], argv.slice(1), { cwd, env: unattendedEnv(env, { display }), detached, stdio: stdio ?? ['pipe', 'pipe', 'pipe'] });
+  let timer, untrack = () => {}, settled = false, total = 0, stdout = [], tail = '', exit;
+  let resolveExit;
+  const done = new Promise(resolve => { resolveExit = resolve; });
+  const finish = result => {
+    if (settled) return;
+    settled = true; exit = result; clearTimeout(timer); signal?.removeEventListener('abort', abort); untrack();
+    killGroup(child);
+    resolveExit({ ...result, output: tail, data: binary ? Buffer.concat(stdout) : undefined });
+  };
+  const terminate = reason => { killGroup(child); child.stdout?.destroy(); child.stderr?.destroy(); finish({ code: null, error: reason }); };
+  const abort = () => terminate('Review was interrupted.');
+  const diagnostics = bytes => { tail = scrub(tail + bytes.toString()).slice(-maxBytes); };
+  child.stdout?.on('data', bytes => {
+    if (!captureStdout) return;
+    if (binary) {
+      total += bytes.length;
+      if (total > maxBytes) { terminate('Review capture exceeded its byte bound.'); return; }
+      stdout.push(bytes);
+    } else diagnostics(bytes);
+  });
+  child.stderr?.on('data', diagnostics);
+  child.once('error', () => finish({ code: null, error: `Could not start ${argv[0]}. Check that it is installed.` }));
+  child.once('close', code => finish({ code }));
+  child.stdin?.on('error', () => {});
+  if (input !== undefined) child.stdin?.end(input);
+  else if (stdio == null) child.stdin?.end();
+  try { untrack = onChild(child) ?? (() => {}); }
+  catch (error) { terminate('The review process could not be tracked.'); throw error; }
+  timer = setTimeout(() => terminate('Review reached its time limit.'), timeoutMs); timer.unref?.();
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  return { child, done, running: () => !settled, result: () => exit, output: () => tail,
+    async close() { terminate('Review stopped.'); await done; } };
+}
+
+export async function reviewExec(argv, options) {
+  const process = startReviewProcess(argv, options);
+  const result = await process.done;
+  if (result.error || result.code !== 0) throw new Error(result.error ?? `Review command exited ${result.code}. ${result.output}`);
+  return result;
+}

package/bin/lib/reviewTargets.mjs

@@ -0,0 +1,50 @@
+/** A reviewed recipe selects workflows; languages do not select viewers. */
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { delimiter, isAbsolute, relative, resolve } from 'node:path';
+import { git } from './git.mjs';
+import { environmentKey } from './reviewEnvironmentConfig.mjs';
+import { robloxConfiguration } from './robloxReview.mjs';
+
+export const REVIEW_RECIPE = '.flowviant/review.json';
+const quiet = { stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 128 * 1024 };
+const nameOk = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,60}$/.test(value);
+const commandOk = value => Array.isArray(value) && value.length > 0 && value.length <= 40 && value.every(v => typeof v === 'string' && v.length > 0 && v.length <= 2000 && !/[\0\r\n]/.test(v));
+
+export function reviewCwd(wt, cwd = '.') {
+  if (typeof cwd !== 'string' || isAbsolute(cwd) || /[\0\r\n\\]/.test(cwd)) throw new Error('Review cwd must be inside this worktree.');
+  const path = realpathSync(resolve(wt, cwd)), rel = relative(realpathSync(wt), path);
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new Error('Review cwd must be inside this worktree.');
+  return path;
+}
+
+export function commandOnPath(command, env = process.env) {
+  const candidates = isAbsolute(command) ? [command] : command.includes('/') || command.includes('\\') ? [] : (env.PATH ?? '').split(delimiter).map(dir => resolve(dir, command));
+  return candidates.find(path => { try { accessSync(path, constants.X_OK); return true; } catch { return false; } }) ?? null;
+}
+
+export function readReviewTargets(root, ref = 'HEAD') {
+  const commit = git(['rev-parse', '--verify', ref], root, quiet);
+  const entry = git(['ls-tree', commit, '--', REVIEW_RECIPE], root, quiet);
+  if (!entry) return { root, commit, targets: {} };
+  if (!/^100(?:644|755) blob /.test(entry)) throw new Error('The review recipe must be a regular tracked file.');
+  let recipe;
+  try { recipe = JSON.parse(git(['show', `${commit}:${REVIEW_RECIPE}`], root, quiet)); }
+  catch { throw new Error('The reviewed review.json is not valid JSON.'); }
+  if (recipe?.version !== 1 || !recipe.targets || typeof recipe.targets !== 'object' || Array.isArray(recipe.targets) || Object.keys(recipe.targets).length > 24) throw new Error('Review recipes need version 1 and at most 24 named targets.');
+  const targets = Object.create(null);
+  for (const [name, target] of Object.entries(recipe.targets)) {
+    if (!nameOk(name) || !target || !['command', 'browser', 'desktop', 'bridge', 'roblox'].includes(target.adapter) || !commandOk(target.command)) throw new Error('Each review target needs a name, supported adapter and command argv.');
+    if (target.adapter === 'roblox') robloxConfiguration(target.configuration);
+    if (target.cwd != null && (typeof target.cwd !== 'string' || target.cwd.length > 500 || isAbsolute(target.cwd) || /[\0\r\n\\]/.test(target.cwd))) throw new Error(`Invalid review cwd for ${name}.`);
+    const timeoutSeconds = target.timeoutSeconds ?? (target.adapter === 'command' ? 120 : 600);
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 600) throw new Error(`Review target ${name} timeoutSeconds must be 1–600.`);
+    if (target.adapter !== 'command' && (typeof target.fixture !== 'string' || target.fixture.trim().length < 12 || target.fixture.length > 2000)) throw new Error(`Review target ${name} needs a disposable fixture description.`);
+    if (target.adapter === 'browser' && (!Number.isInteger(target.port) || target.port < 0 || target.port > 65535 || (target.port === 0 && !target.command.some(arg => arg.includes('${PORT}'))) || (target.hostname != null && target.hostname !== 'localhost') || (target.scheme != null && !['http', 'https'].includes(target.scheme)))) throw new Error(`Review target ${name} needs a valid local port/protocol (port 0 requires a PORT placeholder in command argv).`);
+    if (target.adapter === 'browser' && target.path != null && (typeof target.path !== 'string' || !target.path.startsWith('/') || target.path.startsWith('//') || /[\x00-\x20\\]/.test(target.path) || target.path.length > 2000 || new URL(target.path, 'http://preview.invalid').pathname.startsWith('//'))) throw new Error(`Review target ${name} needs a local path.`);
+    if (target.platforms != null && (!Array.isArray(target.platforms) || target.platforms.length > 3 || target.platforms.some(p => !['linux', 'darwin', 'win32'].includes(p)))) throw new Error(`Review target ${name} platforms must name operating systems.`);
+    if (target.configuration != null && (typeof target.configuration !== 'object' || Array.isArray(target.configuration) || Buffer.byteLength(JSON.stringify(target.configuration)) > 16_000)) throw new Error(`Review target ${name} bridge configuration exceeds its bound.`);
+    if (target.env != null && (!Array.isArray(target.env) || target.env.length > 40 || target.env.some(key => typeof key !== 'string' || !environmentKey(key)))) throw new Error(`Review target ${name} env must name explicitly selected runtime variables.`);
+    targets[name] = { ...target, cwd: target.cwd ?? '.', timeoutSeconds };
+  }
+  return { root: realpathSync(root), commit, targets };
+}

package/bin/lib/robloxReview.mjs

@@ -0,0 +1,234 @@
+/** Studio viewport adapter. All engine operations name one verified fixture. */
+import { readFileSync, realpathSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { connectReviewMcp, mcpText } from './reviewMcpClient.mjs';
+import { createReviewImage } from './reviewImage.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+const MARKER = 'FLOWVIANT_REVIEW_PROBE:';
+const CLIENT_PROBE = `local camera=workspace.CurrentCamera
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({player=game:GetService('Players').LocalPlayer ~= nil,width=camera and camera.ViewportSize.X or 0,height=camera and camera.ViewportSize.Y or 0,session=game:GetAttribute('FlowviantReviewSession')})`;
+const sha = value => createHash('sha256').update(value).digest('hex');
+const normalize = value => value.replace(/\r\n/g, '\n');
+// Decimal byte escapes preserve Unicode without creating hundreds of call
+// arguments (long UTF-8 names can exceed Luau's register limit).
+const luauString = value => '"' + [...Buffer.from(value)].map(byte => '\\' + String(byte).padStart(3, '0')).join('') + '"';
+const pathOk = value => Array.isArray(value) && value.length > 0 && value.length <= 20 && value.every(part => typeof part === 'string' && part.length > 0 && part.length <= 150 && !/[\x00-\x1f]/.test(part));
+
+export function robloxConfiguration(config) {
+  if (!config || typeof config.studioName !== 'string' || config.studioName.length < 1 || config.studioName.length > 250 || /[\x00-\x1f]/.test(config.studioName)) throw new Error('Roblox review needs the exact Studio fixture name (optionally containing ${WORKTREE}).');
+  if (config.startPlay != null && typeof config.startPlay !== 'boolean') throw new Error('Roblox startPlay must be a boolean.');
+  if (!Array.isArray(config.scripts) || config.scripts.length < 1 || config.scripts.length > 40 || config.scripts.some(script => !script || typeof script.file !== 'string' || !script.file || script.file.length > 500 || isAbsolute(script.file) || script.file.split('/').includes('..') || /[\x00-\x1f\\]/.test(script.file) || !/\.(?:lua|luau)$/.test(script.file) || !pathOk(script.path))) throw new Error('Roblox review needs 1–40 Lua/Luau files mapped to explicit Studio instance path segments.');
+  if (new Set(config.scripts.map(s => s.file)).size !== config.scripts.length || new Set(config.scripts.map(s => JSON.stringify(s.path))).size !== config.scripts.length) throw new Error('Roblox source mappings must be unique.');
+  return { studioName: config.studioName, startPlay: config.startPlay ?? true, scripts: config.scripts };
+}
+
+function values(result) {
+  const out = [];
+  const visit = (value, depth = 0) => {
+    if (depth > 5) return;
+    out.push(value);
+    if (typeof value === 'string') { try { visit(JSON.parse(value), depth + 1); } catch { /* ordinary text */ } }
+    else if (value && typeof value === 'object') for (const entry of Object.values(value)) visit(entry, depth + 1);
+  };
+  visit(result.structuredContent); for (const item of result.content ?? []) if (item.type === 'text') visit(item.text);
+  return out;
+}
+
+export function studioPlayState(result) {
+  const states = new Set();
+  const mode = value => {
+    if (typeof value !== 'string') return;
+    if (/^(edit|stopped|stop)$/i.test(value)) states.add('edit');
+    if (/^(play|playing|run|running)$/i.test(value)) states.add('play');
+  };
+  for (const value of values(result)) {
+    if (typeof value === 'string') {
+      const match = /(?:^|\n)\s*(?:current\s+)?(?:studio\s+)?(?:play\s*(?:state|mode)|state|mode)\s*:\s*(Edit|Stopped|Playing|Play|Running|Run)\s*(?:$|\n)/i.exec(value);
+      if (match) mode(match[1]);
+    } else if (value && !Array.isArray(value) && typeof value === 'object') {
+      for (const key of ['playState', 'play_state', 'playMode', 'play_mode', 'state']) mode(value[key]);
+      for (const key of ['isPlaying', 'is_playing', 'isRunning', 'is_running']) if (typeof value[key] === 'boolean') states.add(value[key] ? 'play' : 'edit');
+    }
+  }
+  if (states.size !== 1) throw new Error('Studio did not report an unambiguous supported play state. No play session was changed.');
+  return [...states][0];
+}
+
+function probeValue(result) {
+  for (const value of values(result)) if (typeof value === 'string') {
+    const index = value.indexOf(MARKER);
+    if (index >= 0) { try { return JSON.parse(value.slice(index + MARKER.length)); } catch { /* require a complete probe result */ } }
+  }
+  throw new Error('Studio did not return the complete source-binding probe.');
+}
+
+export function studioProbe(config) {
+  return `local paths={${config.scripts.map(s => `{${s.path.map(luauString).join(',')}}`).join(',')}}
+local sources={}
+local checked=0
+for _,path in ipairs(paths) do
+  local node=game
+  for _,name in ipairs(path) do
+    local found=nil
+    for _,child in ipairs(node:GetChildren()) do
+      checked+=1
+      if checked%500==0 then task.wait() end
+      if child.Name==name then if found then error('Ambiguous review source path') end found=child end
+    end
+    if not found then error('Missing review source path') end
+    node=found
+  end
+  if not node:IsA('LuaSourceContainer') then error('Review source is not a script') end
+  local source=node.Source
+  if #source>131072 then error('Review source exceeds byte bound') end
+  table.insert(sources,source)
+end
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({fixture=game:GetService('ReplicatedStorage'):GetAttribute('FlowviantReviewWorktree'),sources=sources})`;
+}
+
+export async function openRobloxPage({ command, cwd, worktree, configuration, env, signal, onChild, onFrame = () => {}, onChange = () => {}, timeoutMs = 600_000,
+  connect = connectReviewMcp, imageFactory = createReviewImage, frameIntervalMs = 2000, startupWaitMs = 10_000 }) {
+  const config = robloxConfiguration(configuration), wt = realpathSync(worktree), fixture = basename(wt);
+  const expectedName = config.studioName.replaceAll('${WORKTREE}', fixture);
+  let mcp, encoder, studioId, ownedPlay = false, marked = false, closed = false, closePromise, timer, epoch = 0, captureSerial = 0, privateUsed = false, lastImage, queue = Promise.resolve();
+  const session = randomUUID();
+  const sourceHashes = [];
+  const tool = (name, args = {}, limit) => mcp.call(name, { ...args, studio_id: studioId }, limit);
+  const serial = fn => { const result = queue.catch(() => {}).then(fn); queue = result; return result; };
+  const close = () => {
+    if (closePromise) return closePromise;
+    closed = true; epoch++; clearTimeout(timer);
+    closePromise = (async () => {
+      // Only stop a play session this adapter started; never close Studio.
+      try {
+        await queue.catch(() => {});
+        if (ownedPlay && marked) {
+          const current = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }, 4000));
+          if (current.session !== session) ownedPlay = false;
+        }
+        if (ownedPlay) await tool('start_stop_play', { is_start: false }, 8000);
+      }
+      finally { await Promise.allSettled([mcp?.close(), encoder?.close()]); }
+    })();
+    return closePromise;
+  };
+  const capture = async () => {
+    const viewport = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }));
+    if (ownedPlay && marked && viewport.session !== session) { ownedPlay = false; throw new Error('Studio play was replaced outside this review; the replacement session was left alone.'); }
+    if (viewport.player !== true || !(viewport.width > 0 && viewport.height > 0)) throw new Error('No player camera viewport is available in Studio.');
+    const result = await tool('screen_capture', { capture_id: `Flowviant_${epoch}_${++captureSerial}` });
+    const images = (result.content ?? []).filter(c => c.type === 'image');
+    if (images.length !== 1) throw new Error('Studio screen_capture must return one native image content block.');
+    const image = await encoder.encode(images[0]);
+    if (Math.abs((image.width / image.height) / (viewport.width / viewport.height) - 1) > 0.01) throw new Error('Studio capture and player viewport aspect ratios differ; coordinate input cannot be mapped reliably.');
+    return { ...image, inputWidth: viewport.width, inputHeight: viewport.height };
+  };
+  const stream = async () => {
+    const current = epoch;
+    try { const image = await serial(capture); if (!closed && current === epoch) { lastImage = image; onFrame({ type: 'frame', data: image.data, width: 1440, height: 900 }); } }
+    catch (error) { if (!closed && current === epoch) { onChange({ error: reviewDiagnostic(error.message) }); void close().catch(() => {}); } }
+    finally { if (!closed && current === epoch) timer = setTimeout(stream, frameIntervalMs); }
+  };
+  try {
+    signal?.throwIfAborted();
+    // Keep dependencies alive through the outer bridge's 30-second cleanup
+    // grace, including a queued capture plus session-check/stop round trips.
+    mcp = await connect({ command, cwd, env, onChild, timeoutMs: timeoutMs + 35_000, detached: false });
+    for (const required of ['list_roblox_studios', 'get_studio_state', 'execute_luau', 'screen_capture', 'user_mouse_input', 'user_keyboard_input', ...(config.startPlay ? ['start_stop_play'] : [])]) {
+      if (!mcp.tools.some(t => t.name === required)) throw new Error(`Studio MCP is missing ${required}. Update Studio and enable its built-in MCP server.`);
+    }
+    const listed = await mcp.call('list_roblox_studios', {});
+    const studios = values(listed).find(value => value && !Array.isArray(value) && Array.isArray(value.studios))?.studios;
+    if (!studios) throw new Error('Studio MCP did not return a supported Studio instance list.');
+    const selected = studios.filter(studio => studio.name === expectedName && typeof studio.id === 'string');
+    if (selected.length !== 1) throw new Error(`Open exactly one disposable Studio fixture named ${expectedName}. ${selected.length ? 'Several matching instances are connected.' : 'No matching instance is connected.'}`);
+    studioId = selected[0].id;
+    const initial = studioPlayState(await tool('get_studio_state'));
+    if (config.startPlay && initial !== 'edit') throw new Error('This Studio fixture already has a play session. Return it to Edit mode, or configure startPlay:false to watch the existing session.');
+    const loaded = probeValue(await tool('execute_luau', { datamodel_type: 'Edit', code: studioProbe(config) }));
+    if (loaded.fixture !== fixture) throw new Error('Studio fixture is not bound to this worktree. Set the FlowviantReviewWorktree attribute on ReplicatedStorage to the worktree folder name in the disposable fixture.');
+    if (!Array.isArray(loaded.sources) || loaded.sources.length !== config.scripts.length) throw new Error('Studio did not return every mapped source.');
+    for (let index = 0; index < config.scripts.length; index++) {
+      const source = config.scripts[index], file = realpathSync(resolve(wt, source.file)), rel = relative(wt, file);
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new Error('A mapped Studio source escapes the worktree.');
+      const bytes = readFileSync(file); if (bytes.length > 128 * 1024 || typeof loaded.sources[index] !== 'string' || loaded.sources[index].length > 128 * 1024) throw new Error('Mapped Studio sources exceed the per-script bound.');
+      if (normalize(bytes.toString('utf8')) !== normalize(loaded.sources[index])) throw new Error(`Studio has stale/different code for ${source.file}. Sync this worktree into its fixture before review.`);
+      sourceHashes.push({ file: source.file, sha256: sha(normalize(bytes.toString('utf8'))) });
+    }
+    encoder = await imageFactory({ onChild, timeoutMs: timeoutMs + 35_000, detached: false });
+    signal?.throwIfAborted();
+    if (config.startPlay) {
+      if (studioPlayState(await tool('get_studio_state')) !== 'edit') throw new Error('Studio started playing during review setup; that existing session was left alone.');
+      signal?.throwIfAborted(); ownedPlay = true; await tool('start_stop_play', { is_start: true });
+    }
+    signal?.throwIfAborted();
+    if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('Studio did not enter play mode; no gameplay input was enabled.');
+    // Verify Client context rather than treating server-only Run as a player.
+    let player = false;
+    const until = Date.now() + startupWaitMs;
+    do {
+      signal?.throwIfAborted();
+      try {
+        const client = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }, Math.max(1, Math.min(2000, until - Date.now()))));
+        player = client.player === true && client.width > 0 && client.height > 0;
+      } catch { /* Client context can arrive after the play-state transition. */ }
+      if (player || Date.now() >= until) break;
+      await new Promise(resolve => setTimeout(resolve, Math.min(250, until - Date.now())));
+    } while (Date.now() < until);
+    if (!player) throw new Error('No local player was measured in the Studio Client context.');
+    if (ownedPlay) {
+      const receipt = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: `game:SetAttribute('FlowviantReviewSession', '${session}')
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({session=game:GetAttribute('FlowviantReviewSession')})` }));
+      if (receipt.session !== session) throw new Error('Studio did not acknowledge the owned play-session marker.');
+      marked = true;
+    }
+    timer = setTimeout(stream, frameIntervalMs);
+    return { close,
+      async setPrivate(privateInput) { epoch++; clearTimeout(timer); lastImage = null; if (privateInput) privateUsed = true; await queue.catch(() => {}); if (!closed) timer = setTimeout(stream, frameIntervalMs); },
+      async snapshot() {
+        const current = epoch;
+        return serial(async () => {
+          if (closed) throw new Error('Studio review ended.');
+          if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('The Studio play session ended.');
+          const image = await capture();
+          let logs = '';
+          if (!privateUsed && mcp.tools.some(t => t.name === 'get_console_output')) {
+            try { logs = reviewDiagnostic(mcpText(await tool('get_console_output'))).slice(-4000); }
+            catch (error) { logs = `Console unavailable: ${reviewDiagnostic(error.message)}`; }
+          }
+          if (closed || current !== epoch) throw new Error('Studio control changed during capture.');
+          lastImage = image;
+          return { data: image.data, observation: JSON.stringify({ studio: expectedName, sourceHashes, console: privateUsed ? 'Console omitted after private control.' : logs,
+            note: 'Studio viewport observation. Mapped script sources matched at startup; assets and unmapped scripts are unverified. Captures/input do not establish a passing gameplay test. Studio sign-in dialogs require the Windows host.' }), diagnostics: [] };
+        });
+      },
+      async act(input) {
+        return serial(async () => {
+          if (closed) throw new Error('Studio review ended.');
+          if (input.selector || input.type === 'navigate') throw new Error('Studio supports viewport input; browser navigation and DOM selectors do not apply.');
+          if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('The Studio play session ended.');
+          if (ownedPlay && marked) {
+            const current = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }));
+            if (current.session !== session) { ownedPlay = false; throw new Error('Studio play was replaced outside this review; the replacement session was left alone.'); }
+          }
+          const base = { datamodel_type: 'Client' };
+          if (input.type === 'click') {
+            const image = lastImage;
+            if (!image || input.x < image.left || input.y < image.top || input.x >= image.left + image.w || input.y >= image.top + image.h) throw new Error('Click inside the captured Studio viewport.');
+            await tool('user_mouse_input', { ...base, actions: [{ action: 'mouseButtonClick', mouse_button: 'left', x: Math.floor((input.x - image.left) * image.inputWidth / image.w), y: Math.floor((input.y - image.top) * image.inputHeight / image.h) }] });
+          } else if (input.type === 'type') await tool('user_keyboard_input', { ...base, actions: [{ action: 'textInput', text_inputs: input.text }] });
+          else if (input.type === 'key') {
+            const key = ({ Enter: 'Return', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right' })[input.key] ?? input.key;
+            await tool('user_keyboard_input', { ...base, actions: [{ action: 'keyPress', key_code: key }] });
+          } else if (input.type === 'scroll' && input.deltaY !== 0) {
+            if (!lastImage) throw new Error('Observe the Studio viewport before scrolling.');
+            await tool('user_mouse_input', { ...base, actions: Array.from({ length: Math.min(10, Math.ceil(Math.abs(input.deltaY) / 100)) }, () => ({ action: input.deltaY < 0 ? 'scrollUp' : 'scrollDown', x: Math.floor(lastImage.inputWidth / 2), y: Math.floor(lastImage.inputHeight / 2) })) });
+          }
+          else if (!['snapshot', 'scroll'].includes(input.type)) throw new Error('Studio supports viewport input; browser navigation and DOM selectors do not apply.');
+        });
+      },
+    };
+  } catch (error) { await close().catch(() => {}); throw error; }
+}

package/bin/lib/robloxStudioBridge.mjs

@@ -0,0 +1,68 @@
+/** Windows Studio through WSL stdio; no Windows daemon or desktop capture. */
+import { createInterface } from 'node:readline';
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { openBridgePage } from './reviewBridge.mjs';
+import { openRobloxPage, robloxConfiguration } from './robloxReview.mjs';
+import { heldToolArgv } from './heldTool.mjs';
+import { browserAction } from './managedBrowser.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { commandOnPath } from './reviewTargets.mjs';
+
+export function openRobloxStudio({ command, cwd, worktree, configuration, ...options }) {
+  const config = robloxConfiguration(configuration);
+  const name = config.studioName.replaceAll('${WORKTREE}', basename(worktree));
+  const flock = commandOnPath('flock', options.env);
+  if (process.platform !== 'linux' || !flock) throw new Error('The first Studio adapter requires a Linux/WSL daemon with flock and a configured Windows Studio MCP launcher.');
+  const directory = join(homedir(), '.flowviant', 'review-studios'); mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const lock = join(directory, createHash('sha256').update(name).digest('hex') + '.lock');
+  return openBridgePage({ ...options, command: [flock, '-n', '-E', '75', lock, process.execPath, ...heldToolArgv('__roblox-studio-bridge')], cwd, worktree,
+    configuration: { ...config, command, cwd, timeoutMs: options.timeoutMs }, requestTimeoutMs: 60_000, closeGraceMs: 30_000,
+  }).catch(error => {
+    if (/exited \(75\)/.test(error.message)) throw new Error('This Studio fixture is already being reviewed by another local turn. Return or stop that review first.');
+    throw error;
+  });
+}
+
+export async function robloxStudioBridgeMain() {
+  const controller = new AbortController();
+  let page, configuration, worktree, epoch = 0, closing = false, shuttingDown;
+  const send = value => { if (!closing) process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\n'); };
+  const shutdown = () => {
+    if (shuttingDown) return shuttingDown;
+    closing = true; controller.abort();
+    shuttingDown = Promise.resolve().then(() => page?.close()).catch(() => { process.exitCode = 1; });
+    return shuttingDown;
+  };
+  process.stdin.once('end', () => { void shutdown(); }); process.stdin.once('error', () => { void shutdown(); }); process.stdout.once('error', () => { void shutdown(); });
+  process.once('SIGTERM', () => { void shutdown(); process.stdin.destroy(); }); process.once('SIGINT', () => { void shutdown(); process.stdin.destroy(); });
+  try {
+    for await (const line of createInterface({ input: process.stdin })) {
+      if (closing) break;
+      let request;
+      try {
+        if (Buffer.byteLength(line) > 128 * 1024) throw new Error('Studio bridge request exceeds its byte bound.');
+        request = JSON.parse(line);
+        const { id, method, params } = request; let result = {};
+        if (method === 'initialize' && !configuration) {
+          configuration = params.configuration; worktree = params.worktree;
+          if (params.protocol !== 1 || !Array.isArray(configuration?.command) || typeof worktree !== 'string') throw new Error('Invalid Studio bridge initialization.');
+          robloxConfiguration(configuration);
+          result = { protocol: 1, isolation: 'consented-window', privateHandoff: true };
+        } else if (method === 'open' && configuration && !page) {
+          const opened = await openRobloxPage({ command: configuration.command, cwd: configuration.cwd, worktree, configuration, env: process.env, signal: controller.signal, timeoutMs: configuration.timeoutMs,
+            onFrame: frame => send({ method: 'frame', params: { ...frame, epoch } }), onChange: patch => send({ method: 'failure', params: { epoch, message: patch.error } }) });
+          page = opened;
+          // Parent EOF may have arrived while Studio was starting play.
+          if (closing) await opened.close();
+        } else if (method === 'snapshot' && page) result = { ...await page.snapshot(), width: 1440, height: 900, epoch };
+        else if (method === 'act' && page && params.epoch === epoch) await page.act(browserAction(params.input));
+        else if (method === 'privacy' && page) { await page.setPrivate(params.private); epoch = params.epoch; result = { epoch, drained: true }; }
+        else throw new Error('Unsupported or stale Studio bridge operation.');
+        send({ id, result });
+      } catch (error) { send({ id: request?.id, error: { message: reviewDiagnostic(error.message) } }); }
+    }
+  } finally { await shutdown(); }
+}