flowviant 0.125.29 → 0.125.31

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(); }
+}

package/bin/lib/runTurn.mjs

@@ -27,6 +27,7 @@ import { createTurnOutput } from './turnOutput.mjs';
 import { createObservedLines } from './observedLines.mjs';
 import { startTurnDiagnostics } from './turnDiagnostics.mjs';
 import { createClaudeInput } from './claudeInput.mjs';
+import { codexAppArgs, createCodexInput } from './codexInput.mjs';
 import { measuredRuntimeVersion } from './runtimeDetection.mjs';
 import { createTurnSubagents } from './turnSubagents.mjs';
 import { withPublicReference } from './publicReferenceRuntime.mjs';
@@ -79,7 +80,7 @@ const MAX_ARG_BYTES = 128 * 1024;
 
 export function runTurn(opts) {
   if (workLanesStopped()) return never();
-  if ((opts.profile === 'research' || opts.researchIdentity) && ['claude', 'codex'].includes(opts.runtime ?? 'claude'))
+  if (!opts.crossCliChild && (opts.profile === 'research' || opts.researchIdentity) && ['claude', 'codex'].includes(opts.runtime ?? 'claude'))
     return withPublicReference(opts, runProfileTurn);
   return runProfileTurn(opts);
 }
@@ -88,7 +89,7 @@ function runProfileTurn(opts) {
   // A Codex write-up runs over an isolated copy of its worktree
   // (codexResearch.mjs). After the teardown it copies nothing either: the
   // stand-down gate below is asked before the copy, not only before the spawn.
-  if (opts.runtime === 'codex' && opts.profile === 'research')
+  if (!opts.crossCliChild && opts.runtime === 'codex' && opts.profile === 'research')
     return workLanesStopped() ? never() : runIsolatedResearch(opts, prepared => runResearchWithReceipt(prepared, runPlainTurn));
   if (opts.profile === 'research' && opts.researchHandoff)
     return prepareResearchLaunch(opts).then(prepared => runResearchWithReceipt(prepared, runPlainTurn));
@@ -208,6 +209,8 @@ function runPlainTurn(opts) {
       verifiedWorktree: opts.verifiedWorktree === true,
       orchestration: opts.orchestration === true,
       readOnlyCoordination: opts.readOnlyCoordination === true,
+      // A subagent on another CLI's card (crossCliChild.mjs, crossCliPosture.mjs).
+      crossCliChild: opts.crossCliChild === true,
       // The lane's own measurement when it decided to orchestrate, so the
       // hooks and the controller cannot disagree (workAgentTurnExecution.mjs).
       codexVersion: opts.codexVersion ?? measuredRuntimeVersion('codex')?.version,
@@ -303,8 +306,13 @@ function runPlainTurn(opts) {
      * so no throw on the way leaves that file behind: the sweep takes only a
      * dead process's leftovers, and this one names the daemon's own pid.
      */
+    const nativeVersion = opts.codexVersion ?? measuredRuntimeVersion('codex')?.version;
+    // Only a measured native protocol switches transport. Unknown/older CLIs
+    // still receive the original prompt and durable next-turn queue via exec.
+    const appArgs = rt.id === 'codex' && opts.liveMessages && nativeVersion ? codexAppArgs(args, nativeVersion) : null;
+    const codexApp = Boolean(appArgs);
     let transport;
-    try { transport = promptTransport(rt.id, args, stdinText); }
+    try { transport = appArgs ? { args: appArgs, text: null, cleanup() {} } : promptTransport(rt.id, args, stdinText); }
     catch (error) { rt.releaseArgs?.(args); throw error; }
     args.splice(0, args.length, ...transport.args);
     let argsReleased = false;
@@ -403,7 +411,13 @@ function runPlainTurn(opts) {
     const spawnedAt = Date.now();
     let out = '';
     let stdinError = null;
-    const input = rt.liveInput === true && opts.liveMessages ? createClaudeInput(child, { onTaken: opts.liveMessages.onTaken, onContext: opts.onContext ?? null }) : null;
+    const input = codexApp ? createCodexInput(child, { cwd, threadId: resumeThreadId,
+      onTaken: id => { if (!id.startsWith('recovery-')) opts.liveMessages.onTaken(id); },
+      onThread: id => opts.liveMessages.onInit(id),
+      onEvent: event => onLine(JSON.stringify(event), Date.now(), true),
+      onFailure: () => { cliFailed = true; opts.onCliFailure?.(); },
+      onContext: opts.onContext ?? null,
+    }) : !rt.parse && rt.liveInput === true && opts.liveMessages ? createClaudeInput(child, { onTaken: opts.liveMessages.onTaken, onContext: opts.onContext ?? null }) : null;
     // EVERY TURN IS LINE-PARSED (2026-10-10, the audit). Claude's adapter
     // always asks for `--output-format stream-json` and every other runtime
     // brings its own `parse` — for Codex the JSONL stream is the only output
@@ -436,7 +450,7 @@ function runPlainTurn(opts) {
     };
     // The native children this CLI starts, observed (turnSubagents.mjs).
     const natives = createTurnSubagents({ runtime: rt.id, cwd, since: spawnedAt, env: { ...process.env, ...(mcpEnv ?? {}) },
-      owned: opts.orchestration === true, onSubagent: opts.onSubagent, onSpawnResult: opts.onSpawnResult, resumeThreadId,
+      owned: opts.orchestration === true, onSubagent: opts.onSubagent, onWorkflow: opts.onWorkflow, onSpawnResult: opts.onSpawnResult, resumeThreadId, knownSubagents: opts.knownSubagents,
       sinks: { emit, onActivity, onToolEvent, appendText, onDetail: output.detail } });
     let codexThread = rt.id === 'codex' && typeof resumeThreadId === 'string' ? resumeThreadId : null;
     /**
@@ -471,14 +485,18 @@ function runPlainTurn(opts) {
     const taskPlan = new Map();
     /** One line of the child's stdout, in whichever dialect it speaks. */
     let cliFailed = false;
-    const onLine = (line, observedAt) => {
+    const onLine = (line, observedAt, nativeEvent = false) => {
+      if (codexApp && !nativeEvent) {
+        try { input.event(JSON.parse(line)); } catch { /* non-protocol stdout */ }
+        return;
+      }
       const emitObserved = (text, meta) => emit(text, { ...meta, observedAt });
       const toolObserved = (name, input, meta) => onToolEvent(name, input, meta, observedAt);
       try {
         const event = JSON.parse(line);
         const parentEvent = event.parent_tool_use_id == null && !event.isSidechain;
         opts.researchReceipt?.event(event);
-        if (input && parentEvent) {
+        if (input && !codexApp && parentEvent) {
           input.event(event);
           if (event.type === 'system' && event.subtype === 'init' && event.session_id) opts.liveMessages.onInit(event.session_id);
           // A message written just before result may become a second native
@@ -486,6 +504,7 @@ function runPlainTurn(opts) {
           // structured objects joined together; every result still reports spend.
           if (event.type === 'result') out = '';
         }
+        if (codexApp && event.type === 'turn.started') out = '';
         if (parentEvent && ((event.type === 'result' && event.is_error === true) ||
             event.type === 'error' || event.type === 'turn.failed')) {
           cliFailed = true;
@@ -500,7 +519,9 @@ function runPlainTurn(opts) {
       // thread.started). Purely additive: callers that pass no onThreadId —
       // every dispatch path — see zero behavior change.
       if (ev.threadId) {
-        if (rt.id === 'codex') { codexThread = ev.threadId; natives.thread(ev.threadId); }
+        if (rt.id === 'codex') { codexThread = ev.threadId; natives.thread(ev.threadId);
+          if (!input && opts.liveMessages) opts.liveMessages.onTaken(opts.liveMessages.turnId);
+        }
         onThreadId?.(ev.threadId);
       }
       // The runtime's own token count (codex's `turn.completed`) — the same
@@ -657,6 +678,7 @@ function runPlainTurn(opts) {
     if (input) {
       const initial = opts.liveMessages.initialPrompt(prompt, resumeThreadId, resume, opts.liveContinuation === true);
       input.send(opts.liveMessages.initialId || opts.liveMessages.turnId, initial);
+      if (codexApp) input.start();
       opts.liveMessages.connect(input.send);
     }
   });

package/bin/lib/runtimeClaude.mjs

@@ -21,6 +21,7 @@ import { withSettings } from './claudeSettingsArg.mjs';
 import { orchestratorHooks, claudeOrchestrationSafe } from './orchestratorHooks.mjs';
 import { orchestratesPosture } from './orchestratorPrompt.mjs';
 import { versionAtLeast } from './versionOrder.mjs';
+import { crossCliClaudePerm } from './crossCliPosture.mjs';
 
 /** The release the agent lane first measured `--system-prompt-snapshot` on
  *  (decisions.md, 2026-09-24). */
@@ -123,7 +124,7 @@ export const CLAUDE_RUNTIME = {
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ managedBrowser = false, writableDirs = [], prompt, system, model, effort, resume, perm: postureList, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, baseMcp = [], mcpCheckout = null, streamInput = false, orchestration = false, readOnlyCoordination = false, claudeVersion = null }) {
+  args({ managedBrowser = false, writableDirs = [], prompt, system, model, effort, resume, perm: postureList, profile = 'build', mcp = [], resultSchemaArgs = [], adoptResumeId, resumeThreadId, knowledgeDir, vaultDir, agentTools, personalSettings, machineMcp, baseMcp = [], mcpCheckout = null, streamInput = false, orchestration = false, readOnlyCoordination = false, claudeVersion = null, crossCliChild = false, cwd }) {
     // THE CARTOGRAPHER'S FENCE NAMES ITS VAULT (2026-10-10): its one write rule
     // is the vault's absolute path (claudePosture.mjs `wikiPermFor`), so a turn
     // with no vault, or one no rule can name, has no list — refused here in
@@ -195,7 +196,10 @@ export const CLAUDE_RUNTIME = {
     // a research card's list then admits the children its fence denied.
     const readCoordinator = orchestration && readOnlyCoordination && ['consult', 'plan'].includes(profile) && claudeOrchestrationSafe(claudeVersion);
     const gated = readCoordinator || orchestration && orchestratesPosture(profile);
-    const perm = readCoordinator ? withReadOnlyCoordination(postureList) : gated && fenced ? withNativeChildren(postureList) : postureList;
+    // A subagent on another CLI's card runs the build fenced to its worktree,
+    // with no children of its own (crossCliPosture.mjs).
+    const perm = readCoordinator ? withReadOnlyCoordination(postureList) : gated && fenced ? withNativeChildren(postureList)
+      : crossCliChild ? crossCliClaudePerm(postureList, cwd, profile) : postureList;
     if (fenced) a.push(...NO_SETTING_SOURCES);
     // A FENCED POSTURE NAMES ITS OWN MODE (2026-10-10). Its lists fence only
     // under the CLI's `default` mode, where a tool the list does not name is
@@ -205,7 +209,7 @@ export const CLAUDE_RUNTIME = {
     // classifier that may approve what the list never named. So the posture
     // states `default` itself, unless its own list names a mode (plan-mode).
     if (fenced && !perm.includes('--permission-mode')) a.push('--permission-mode', 'default');
-    else if (agentTools) a.push('--setting-sources', 'user');
+    else if (agentTools || crossCliChild) a.push('--setting-sources', 'user');
     // EVERY TURN RENDERS ITS OWN SYSTEM PROMPT (2026-10-19). By default the
     // CLI records a conversation's first system prompt and resends that record
     // on every resume "even when a later launch passes different text" —

package/bin/lib/runtimeCodex.mjs

@@ -19,6 +19,7 @@ import { projectReadBoundary, projectReadFence } from './codexProjectRead.mjs';
 import { versionAtLeast } from './versionOrder.mjs';
 import { codexOrchestratorArgs } from './orchestratorHooks.mjs';
 import { orchestratesPosture } from './orchestratorPrompt.mjs';
+import { CROSS_CLI_TMP_FENCE } from './crossCliPosture.mjs';
 
 /**
  * FLOWVIANT'S OWN TOOLS NEED NO APPROVAL FROM A CHAT NOBODY CAN ANSWER
@@ -215,7 +216,7 @@ export const CODEX_RUNTIME = {
   bin: 'codex',
   install: 'npm i -g @openai/codex',
   login: 'codex login',
-  liveInput: false,
+  liveInput: true,
   /**
    * BUILD AND CONSULT. See `args()` below for how consult is expressed — the
    * short version is that Codex keeps the promise at the kernel rather than in
@@ -281,7 +282,7 @@ export const CODEX_RUNTIME = {
    * limit even when its argv plus environment is far below ARG_MAX. Both exec
    * and exec resume support `-` (verified on Codex 0.160.0, 2026-10-16).
    */
-  args({ managedBrowser = false, streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, verifiedWorktree = false, codexVersion, orchestration = false, readOnlyCoordination = false }) {
+  args({ managedBrowser = false, streamInput = false, writableDirs = [], prompt, system, model, effort, resume, resumeThreadId, profile = 'build', vaultDir, cwd, mcp = [], resultSchemaArgs = [], adoptResumeId, agentTools, personal = null, researchIsolation, knowledgeDir, projectReads, cardTurn = false, verifiedWorktree = false, codexVersion, orchestration = false, readOnlyCoordination = false, crossCliChild = false }) {
     // Adoption resumes a conversation in ITS OWN CLI's store (claude forks,
     // agy moves) — codex has no adoptable store wired yet. Reaching here
     // with an adopt id is a wiring mistake upstream, and it fails loudly on
@@ -319,7 +320,7 @@ export const CODEX_RUNTIME = {
     // the parent's sandbox (2026-10-19, orchestratorPrompt.mjs).
     const gated = orchestration && (orchestratesPosture(fenced ? profile : 'build') || readOnlyCoordination && ['consult', 'plan'].includes(profile)) && codexSubagentsSafe(codexVersion);
     if (fenced) {
-      a.push(...CODEX_FENCES[profile]({ cwd, vaultDir, researchIsolation, knowledgeDir, projectReads, subagents: gated, codexVersion }));
+      a.push(...CODEX_FENCES[profile]({ cwd, vaultDir, researchIsolation, knowledgeDir, projectReads, subagents: gated, codexVersion, crossCliChild }));
     } else {
       // The daemon's build posture, mapped: SAFE keeps writes inside the
       // workspace, the default lets the agent run its own tests and git
@@ -334,7 +335,9 @@ export const CODEX_RUNTIME = {
       if (writableDirs.length) a.push('-c', `sandbox_workspace_write.writable_roots=${JSON.stringify(writableDirs)}`);
       a.push('-c', `sandbox_mode="${SAFE ? 'workspace-write' : 'danger-full-access'}"`);
       if (cardTurn) a.push('-c', 'approval_policy="never"', ...(agentTools?.codexApprovals ?? []));
-      a.push(...(cardTurn && profile === 'build' && codexSubagentsSafe(codexVersion) ? CARD_SUBAGENTS : noSubagents(codexVersion)));
+      // A subagent on another CLI's card has none of its own (crossCliPosture.mjs).
+      a.push(...(crossCliChild ? [...noSubagents(codexVersion), ...(SAFE ? CROSS_CLI_TMP_FENCE : [])]
+        : cardTurn && profile === 'build' && codexSubagentsSafe(codexVersion) ? CARD_SUBAGENTS : noSubagents(codexVersion)));
     }
 
     /**
@@ -521,9 +524,12 @@ const CODEX_FENCES = {
   // An orchestrated research card's children (2026-10-19) inherit this same
   // permission profile, approval policy and cwd (0.160.0 child_config.rs);
   // the gate refuses their writes.
-  research: ({ researchIsolation, subagents = false, codexVersion }) => {
+  research: ({ researchIsolation, subagents = false, codexVersion, crossCliChild = false }) => {
     if (!researchIsolation) throw new Error('Codex research requires its isolated input copy.');
-    return [...researchFence(researchIsolation), ...fencedTail({ web: true, imageGeneration: true, subagents, codexVersion })];
+    const fence = researchFence(researchIsolation);
+    // A child returns findings to its lead: even the artifact/scratch roots read only.
+    return [...(crossCliChild ? fence.map(a => a.startsWith('permissions.flowviantresearch.filesystem=') ? a.replaceAll('="write"', '="read"') : a) : fence),
+      ...fencedTail({ web: true, imageGeneration: !crossCliChild, subagents: !crossCliChild && subagents, codexVersion })];
   },
 };
 /** The fenced profile names — for the test that holds both tables to one set. */