chati-dev 4.5.27 → 4.5.29

package/src/tasks/handoff.js

@@ -7,8 +7,9 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { dirname } from 'path';
+import * as yaml from 'js-yaml';
+import { agentHandoffPath, findAgentHandoffPath } from '../utils/handoff-paths.js';
 
 /**
  * Build a handoff document from task execution results.
@@ -60,8 +61,8 @@ export function formatHandoff(handoff) {
     `from_task: ${handoff.from.task_id}`,
     `from_phase: ${handoff.from.phase}`,
     `to: ${handoff.to || 'orchestrator'}`,
-    `timestamp: ${handoff.timestamp}`,
-    `status: ${handoff.status}`,
+    ...(handoff.timestamp ? [`timestamp: ${handoff.timestamp}`] : []),
+    ...(handoff.status_declared === false ? [] : [`status: ${handoff.status}`]),
     `score: ${handoff.score ?? 'N/A'}`,
     '---',
     '',
@@ -112,6 +113,10 @@ export function formatHandoff(handoff) {
     lines.push('');
   }
 
+  if (handoff.deep_context) {
+    lines.push('## Deep Context', handoff.deep_context, '');
+  }
+
   return lines.join('\n');
 }
 
@@ -124,13 +129,12 @@ export function formatHandoff(handoff) {
  */
 export function saveHandoff(projectDir, handoff) {
   try {
-    const handoffsDir = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs');
+    const filePath = agentHandoffPath(projectDir, handoff.from.agent);
+    const handoffsDir = dirname(filePath);
     if (!existsSync(handoffsDir)) {
       mkdirSync(handoffsDir, { recursive: true });
     }
 
-    const filename = `${handoff.from.agent}-handoff.md`;
-    const filePath = join(handoffsDir, filename);
     const content = formatHandoff(handoff);
 
     writeFileSync(filePath, content, 'utf-8');
@@ -148,15 +152,14 @@ export function saveHandoff(projectDir, handoff) {
  * @returns {{ loaded: boolean, handoff: object|null, error: string|null }}
  */
 export function loadHandoff(projectDir, agentName) {
-  const filePath = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs', `${agentName}-handoff.md`);
-
-  if (!existsSync(filePath)) {
-    return { loaded: false, handoff: null, error: `No handoff found from agent '${agentName}'.` };
-  }
-
   try {
+    const filePath = findAgentHandoffPath(projectDir, agentName);
+    if (!filePath) {
+      return { loaded: false, handoff: null, error: `No handoff found from agent '${agentName}'.` };
+    }
     const raw = readFileSync(filePath, 'utf-8');
     const parsed = parseHandoffContent(raw);
+    if (!raw.trim() || !parsed.summary) throw new Error('Handoff summary is missing');
     return { loaded: true, handoff: parsed, error: null };
   } catch (err) {
     return { loaded: false, handoff: null, error: `Failed to parse handoff: ${err.message}` };
@@ -170,22 +173,17 @@ export function loadHandoff(projectDir, agentName) {
  * @returns {object} Parsed handoff data
  */
 export function parseHandoffContent(content) {
+  content = content.replace(/\r\n/g, '\n');
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
 
-  const meta = {};
+  let meta = {};
   let body = content;
 
   if (frontmatterMatch) {
-    const yamlPart = frontmatterMatch[1];
+    meta = yaml.load(frontmatterMatch[1], { schema: yaml.JSON_SCHEMA }) ?? {};
+    if (typeof meta !== 'object' || Array.isArray(meta)) throw new Error('Handoff metadata must be a mapping');
     body = frontmatterMatch[2];
-
-    for (const line of yamlPart.split('\n')) {
-      const match = line.match(/^(\w[\w_-]*):\s*(.+)$/);
-      if (match) {
-        meta[match[1]] = match[2].trim();
-      }
-    }
-  }
+  } else if (content.startsWith('---\n')) throw new Error('Handoff frontmatter is not closed');
 
   // Extract sections from body
   const sections = {};
@@ -193,9 +191,13 @@ export function parseHandoffContent(content) {
   const sectionLines = {};
 
   for (const line of body.split('\n')) {
-    const headerMatch = line.match(/^## (.+)/);
+    const headerMatch = line.match(/^## (.+)/) || line.match(/^### (Layer [12].+)/i);
     if (headerMatch) {
-      currentSection = headerMatch[1].toLowerCase().replace(/\s+/g, '_');
+      const title = headerMatch[1].trim();
+      currentSection = /^layer\s+1\s*(?::\s*(?:executive\s+)?summary|\(summary\))$/i.test(title)
+        ? 'summary' : /^layer\s+2\s*(?::\s*deep context|\(deep context\))$/i.test(title)
+          ? 'deep_context' : title.toLowerCase().replace(/\s+/g, '_');
+      if (Object.hasOwn(sectionLines, currentSection)) throw new Error('Conflicting handoff sections');
       sectionLines[currentSection] = [];
     } else if (currentSection) {
       sectionLines[currentSection].push(line);
@@ -210,17 +212,39 @@ export function parseHandoffContent(content) {
       .map(l => l.replace(/^- (\[.\] )?/, '').trim());
   }
 
+  // Presence, not truthiness, controls aliases. Invalid or conflicting fields
+  // cannot be hidden by another spelling or a stale legacy handoff.
+  const field = (names, valid, fallback = null, extra = []) => {
+    const values = [...names.filter(name => Object.hasOwn(meta, name)).map(name => meta[name]), ...extra];
+    if (values.some(value => !valid(value))) throw new Error(`Invalid handoff ${names[0]}`);
+    if (values.some(value => JSON.stringify(value) !== JSON.stringify(values[0]))) throw new Error(`Conflicting handoff ${names[0]}`);
+    return values.length ? values[0] : fallback;
+  };
+  const text = value => typeof value === 'string' && value.trim().length > 0;
+  const list = value => Array.isArray(value) && value.every(text);
+  const listField = (name, alias) => field(alias ? [name, alias] : [name], list, [],
+    Object.hasOwn(sections, name) ? [sections[name]] : []);
+  const rawScore = field(['score', 'quality_score'], value => value === 'N/A'
+    || (typeof value === 'number' && Number.isFinite(value))
+    || (typeof value === 'string' && /^\d+(?:\.\d+)?$/.test(value)));
+
   return {
-    from_agent: meta.from_agent || null,
-    from_task: meta.from_task || null,
-    to: meta.to || null,
-    timestamp: meta.timestamp || null,
-    status: meta.status || 'unknown',
-    score: meta.score !== 'N/A' ? parseInt(meta.score, 10) || null : null,
+    from_agent: field(['from_agent', 'agent'], text),
+    from_task: field(['from_task'], text),
+    from_phase: field(['from_phase'], text),
+    to: field(['to', 'next_agent'], text),
+    timestamp: field(['timestamp'], text),
+    status: field(['status'], text, 'unknown'),
+    // Preserve the legacy status default without confusing an omitted optional
+    // declaration with an explicit non-complete status. Derive from actual
+    // metadata presence, never from a caller-supplied status_declared field.
+    status_declared: Object.hasOwn(meta, 'status'),
+    score: rawScore === null || rawScore === 'N/A' ? null : Number(rawScore),
     summary: (sectionLines.summary || []).join(' ').trim(),
-    outputs: sections.outputs || [],
+    deep_context: (sectionLines.deep_context || []).join('\n').trim(),
+    outputs: listField('outputs', 'artifacts'),
     decisions: sections.decisions || [],
-    blockers: sections.blockers || [],
+    blockers: listField('blockers'),
     criteria_met: sections.criteria_met || [],
     criteria_unmet: sections.criteria_unmet || [],
   };

package/src/terminal/adapters/claude-adapter.js

@@ -21,6 +21,9 @@ export function buildCommand(config, provider) {
   const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
   const args = provider.baseArgs.filter((argument) => !(readOnly && argument === '--dangerously-skip-permissions'));
   if (readOnly) args.push('--permission-mode', 'plan', '--no-session-persistence');
+  if (config.councilToolIsolation === true) {
+    args.push('--restricted', '--strict-mcp-config', '--disable-slash-commands', '--tools', '', '--permission-prompts', 'none');
+  }
   let effectiveModel = null;
 
   if (config.model) {

package/src/terminal/adapters/codex-adapter.js

@@ -16,6 +16,19 @@ export function buildCommand(config, provider) {
   const args = [...provider.baseArgs];
   const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
   if (readOnly) args.push('-s', 'read-only', '--ephemeral');
+  else if (Array.isArray(config.writeScope) && config.writeScope.length > 0) {
+    // `codex exec` otherwise defaults to read-only, including agents that must
+    // write their reports/handoffs. This inner mode does not expand the outer
+    // OS-enforced write scopes and does not change approval or rule settings.
+    args.push('-s', 'workspace-write');
+  }
+  if (config.councilToolIsolation === true) {
+    // Keep the approval policy through exec's supported config override, not
+    // the global flag rejected after exec by the pinned CLI. The authority still
+    // removes command binaries and hides the source project. Council material
+    // is an immutable artifact bundle, deliberately not a Git checkout.
+    args.push('--ignore-user-config', '--ignore-rules', '-c', 'approval_policy="on-request"', '--skip-git-repo-check');
+  }
   let effectiveModel = null;
 
   if (config.model) {

package/src/terminal/adapters/grok-adapter.js

@@ -9,6 +9,7 @@ export function buildCommand(config, provider) {
   const args = [...provider.baseArgs];
   const readOnly = Array.isArray(config.writeScope) && config.writeScope.length === 0;
   if (readOnly) args.push('--permission-mode', 'plan', '--no-subagents', '--disable-web-search');
+  if (config.councilToolIsolation === true) args.push('--tools', '', '--output-format', 'json');
   let effectiveModel = null;
   if (config.model) {
     effectiveModel = provider.modelMap[config.model] || config.model;

package/src/terminal/agent-attempt-budget.js

@@ -0,0 +1,35 @@
+// The reserved claim owns the total execution budget, including preparation,
+// retry backoff, process cleanup and result persistence. A timeout is only one
+// attempt's budget and never extends that claim.
+const CLEANUP_RESERVE_MS = 60_000;
+export const AGENT_RETRY_DELAY_MS = 500;
+
+export function getAgentTimeout(agent) {
+  return agent === 'qa-planning' ? 1_200_000 : 600_000;
+}
+
+export function parseAgentTimeout(value, agent) {
+  const timeout = value === undefined ? getAgentTimeout(agent) : Number(value);
+  if ((value !== undefined && !/^\d+$/.test(String(value)))
+    || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647) {
+    throw Object.assign(new Error('Agent timeout must be a positive integer in milliseconds within the timer range.'), { code: 'INVALID_AGENT_TIMEOUT' });
+  }
+  return timeout;
+}
+
+export function createAgentAttemptBudget(timeout, expiresAt, { now = Date.now } = {}) {
+  const deadline = expiresAt === null ? Infinity : Date.parse(expiresAt);
+  if (Number.isNaN(deadline)) {
+    throw Object.assign(new Error('Execution claim has no valid expiration.'), { code: 'AGENT_EXECUTION_CLAIM_INVALID' });
+  }
+  function canStart(delayMs = 0) {
+    return deadline - now() >= timeout + CLEANUP_RESERVE_MS + delayMs;
+  }
+  function assertCanStart() {
+    if (!canStart()) {
+      throw Object.assign(new Error('The remaining execution claim lease cannot cover a full attempt and cleanup. No new provider process was launched.'),
+        { code: 'AGENT_EXECUTION_BUDGET_EXHAUSTED' });
+    }
+  }
+  return Object.freeze({ canStart, assertCanStart });
+}

package/src/terminal/browser-endpoint-proxy.js

@@ -0,0 +1,174 @@
+// Trusted transport, not an evidence issuer. Its caller supplies the private
+// native owner's proof function. It never accepts proof from HTTP/app output.
+import { createServer, request } from 'node:http';
+import { connect } from 'node:net';
+
+function error(code) { return Object.assign(new Error(code), { code }); }
+const HOP_HEADERS = new Set(['connection', 'proxy-connection', 'keep-alive', 'transfer-encoding',
+  'te', 'trailer', 'upgrade', 'proxy-authorization', 'proxy-authenticate']);
+function headersFor(headers) {
+  const omitted = new Set([...HOP_HEADERS, ...String(headers.connection || '').toLowerCase().split(',').map(value => value.trim())]);
+  return Object.fromEntries(Object.entries(headers).filter(([name]) => !omitted.has(name.toLowerCase())));
+}
+
+/** One retained TCP connection per upstream request/upgrade, proved before a
+ * single application byte is sent or forwarded. No upstream pool or reconnect.
+ * HTTP and WS use exactly the same proof path; CONNECT/other origins are denied.
+ * This alone does not enforce the browser/application OS network boundaries.
+ */
+export async function createVerifiedBrowserProxy({ hostname, applicationPort, timeoutMs, verifyPeer }) {
+  if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname || '')
+    || !Number.isInteger(applicationPort) || applicationPort < 1024 || applicationPort > 65535
+    || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1800000 || typeof verifyPeer !== 'function') {
+    throw error('BROWSER_PROXY_CONFIGURATION_INVALID');
+  }
+  const host = `${hostname}:${applicationPort}`;
+  const sockets = new Set();
+  const facts = { connections_proved: 0, owner_rejections: 0, policy_violations: 0, timed_out: false, closed: false };
+  let closePromise;
+  const server = createServer({ maxHeaderSize: 16384, requestTimeout: timeoutMs, headersTimeout: Math.min(timeoutMs, 5000) });
+  server.maxConnections = 64;
+  function own(socket) {
+    sockets.add(socket);
+    socket.on('error', () => {});
+    socket.once('close', () => sockets.delete(socket));
+    return socket;
+  }
+  server.on('connection', socket => own(socket));
+  function rejectPolicy(target) {
+    facts.policy_violations++;
+    target.destroy();
+  }
+  function targetUrl(req, upgrade) {
+    try {
+      const url = new URL(req.url);
+      if (url.hostname !== hostname || url.port !== String(applicationPort) || url.username || url.password
+        || url.hash || req.headers.host !== host || !(upgrade ? ['http:', 'ws:'] : ['http:']).includes(url.protocol)) return null;
+      return url;
+    } catch { return null; }
+  }
+  function openVerified() {
+    return new Promise((resolve, reject) => {
+      if (facts.closed) { reject(error('BROWSER_PROXY_CLOSED')); return; }
+      const socket = own(connect({ host: '127.0.0.1', port: applicationPort, family: 4 }));
+      socket.pause();
+      let settled = false; let retryTimer; let proofStarted = false;
+      const deadline = setTimeout(() => {
+        if (proofStarted) facts.owner_rejections++;
+        finish(error('BROWSER_ENDPOINT_PROOF_TIMEOUT'));
+      }, Math.min(timeoutMs, 2000));
+      function finish(failure) {
+        if (settled) return;
+        settled = true; clearTimeout(deadline); clearTimeout(retryTimer);
+        socket.off('error', onError); socket.off('close', onClose);
+        if (failure) { socket.destroy(); reject(failure); } else resolve(socket);
+      }
+      function onError(failure) { finish(failure); }
+      function onClose() { finish(error('BROWSER_ENDPOINT_CLOSED')); }
+      socket.once('error', onError); socket.once('close', onClose);
+      socket.once('connect', () => {
+        // These are read from this retained kernel-backed Socket, not a request.
+        const tuple = Object.freeze({ local_address: socket.localAddress, local_port: socket.localPort,
+          remote_address: socket.remoteAddress, remote_port: socket.remotePort });
+        async function prove() {
+          if (settled) return;
+          proofStarted = true;
+          try {
+            const proved = await verifyPeer(tuple);
+            if (settled) return;
+            if (facts.closed || socket.destroyed || !socket.readable || !socket.writable
+              || socket.localAddress !== tuple.local_address || socket.localPort !== tuple.local_port
+              || socket.remoteAddress !== tuple.remote_address || socket.remotePort !== tuple.remote_port) {
+              finish(error('BROWSER_ENDPOINT_CLOSED')); return;
+            }
+            // TCP connect can precede the application's accept(). Query this
+            // same retained connection again, within the original deadline.
+            // Only an explicit negative verdict is retryable, never a channel
+            // failure; the private proof channel supplies a fresh query ID.
+            if (proved === false) { retryTimer = setTimeout(() => { void prove(); }, 25); return; }
+            if (proved !== true) { facts.owner_rejections++; finish(error('BROWSER_ENDPOINT_OWNER_UNPROVEN')); return; }
+            facts.connections_proved++;
+            finish();
+          } catch (failure) {
+            if (!settled) facts.owner_rejections++;
+            finish(failure);
+          }
+        }
+        void prove();
+      });
+    });
+  }
+  async function forward(req, response, clientHead) {
+    const upgrade = clientHead !== undefined;
+    const client = upgrade ? response : req.socket;
+    const url = targetUrl(req, upgrade);
+    if (!url || req.method === 'CONNECT' || (upgrade && (req.method !== 'GET' || req.headers.upgrade?.toLowerCase() !== 'websocket'))) {
+      rejectPolicy(client); return;
+    }
+    req.pause();
+    let socket; let upstream;
+    try {
+      socket = await openVerified();
+      if (facts.closed || client.destroyed || req.aborted) throw error('BROWSER_PROXY_CLOSED');
+      const headers = { ...headersFor(req.headers), host };
+      if (upgrade) { headers.connection = 'Upgrade'; headers.upgrade = 'websocket'; }
+      else headers.connection = 'close';
+      // createConnection disables Node's agent. Never use agent:false here:
+      // that creates a new agent which could open an unproved second socket.
+      upstream = request({ hostname: '127.0.0.1', port: applicationPort, method: req.method,
+        path: `${url.pathname}${url.search}`, headers, createConnection: () => socket });
+      upstream.once('socket', assigned => {
+        if (assigned !== socket) { assigned.destroy(); upstream.destroy(); return; }
+        assigned.resume(); // Parser is attached now; pre-proof data stayed paused.
+      });
+      upstream.on('error', () => { socket.destroy(); response.destroy(); });
+      client.once('close', () => { upstream.destroy(); socket.destroy(); });
+      upstream.on('response', reply => {
+        if (upgrade) { reply.destroy(); socket.destroy(); client.destroy(); return; }
+        response.writeHead(reply.statusCode, headersFor(reply.headers));
+        reply.on('error', () => response.destroy());
+        response.once('close', () => { reply.destroy(); socket.destroy(); });
+        reply.pipe(response);
+      });
+      upstream.on('upgrade', (reply, upgradedSocket, head) => {
+        if (!upgrade || upgradedSocket !== socket || reply.statusCode !== 101
+          || reply.headers.upgrade?.toLowerCase() !== 'websocket') {
+          upgradedSocket.destroy(); response.destroy(); return;
+        }
+        const headers = { ...headersFor(reply.headers), connection: 'Upgrade', upgrade: 'websocket' };
+        client.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(headers).flatMap(([key, value]) =>
+          (Array.isArray(value) ? value : [value]).map(item => `${key}: ${item}\r\n`)).join('')}\r\n`);
+        if (head.length) client.write(head);
+        if (clientHead.length) socket.write(clientHead);
+        socket.once('close', () => client.destroy());
+        client.pipe(socket); socket.pipe(client);
+      });
+      if (upgrade) upstream.end(); else req.pipe(upstream);
+    } catch {
+      socket?.destroy(); upstream?.destroy();
+      if (upgrade) client.destroy(); else { response.writeHead(502, { connection: 'close' }); response.end(); }
+    }
+  }
+  server.on('request', (req, res) => { void forward(req, res); });
+  server.on('upgrade', (req, socket, head) => { void forward(req, socket, head); });
+  server.on('connect', (_req, socket) => rejectPolicy(socket));
+  server.on('clientError', (_error, socket) => rejectPolicy(socket));
+  async function close() {
+    if (closePromise) return closePromise;
+    facts.closed = true; clearTimeout(timer);
+    const stopped = [...sockets].map(socket => new Promise(resolve => { socket.once('close', resolve); socket.destroy(); }));
+    stopped.push(new Promise(resolve => { server.close(() => resolve()); }));
+    closePromise = Promise.all(stopped).then(() => {});
+    return closePromise;
+  }
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => { server.off('error', reject); resolve(); });
+  });
+  server.on('error', () => { void close(); });
+  const port = server.address().port;
+  const timer = setTimeout(() => { facts.timed_out = true; void close(); }, timeoutMs);
+  return Object.freeze({ serverUrl: `http://127.0.0.1:${port}`, port, close,
+    facts: () => Object.freeze({ ...facts, active_connections: sockets.size }),
+  });
+}

package/src/terminal/browser-observer-driver.js

@@ -0,0 +1,94 @@
+// Shared trusted Playwright scenario. OS containment, application lifetime and
+// process evidence belong to the caller, never to page content or this driver.
+import { setTimeout as delay } from 'node:timers/promises';
+
+export async function observeBrowserScenario({ chromium, config, launchOptions, isApplicationAlive }) {
+  const origin = `http://${config.hostname}:${config.application.port}`;
+  const observed = { passed: false, error_code: null, steps: [], artifacts: [],
+    policy_violations: 0, page_errors: 0, console_errors: 0, browser_version: null };
+  let browser; let stage = 'BROWSER_LAUNCH_FAILED';
+  function rejected(code) { throw Object.assign(new Error(code), { observationCode: code }); }
+  function allowedUrl(value, websocket = false) {
+    try {
+      const url = new URL(value);
+      return url.hostname === config.hostname && url.port === String(config.application.port)
+        && url.protocol === (websocket ? 'ws:' : 'http:') && !url.username && !url.password;
+    } catch { return false; }
+  }
+  try {
+    browser = await chromium.launch({ ...launchOptions, headless: true, chromiumSandbox: true });
+    observed.browser_version = browser.version();
+    const context = await browser.newContext({ serviceWorkers: 'block', acceptDownloads: false,
+      viewport: { width: 1280, height: 720 } });
+    context.setDefaultTimeout(Math.min(5000, config.timeout_ms));
+    await context.route('**/*', route => {
+      if (!allowedUrl(route.request().url())) { observed.policy_violations++; return route.abort('blockedbyclient'); }
+      return route.continue();
+    });
+    await context.routeWebSocket('**/*', socket => {
+      if (!allowedUrl(socket.url(), true)) { observed.policy_violations++; socket.close(); return; }
+      socket.connectToServer();
+    });
+    context.on('page', page => {
+      page.on('pageerror', () => { observed.page_errors++; });
+      page.on('console', message => { if (message.type() === 'error') observed.console_errors++; });
+      page.on('download', () => { observed.policy_violations++; });
+      page.on('framenavigated', frame => {
+        if (frame.url() !== 'about:blank' && !allowedUrl(frame.url())) observed.policy_violations++;
+      });
+    });
+    const page = await context.newPage();
+    stage = 'BROWSER_STEP_FAILED';
+    for (const [index, step] of config.steps.entries()) {
+      if (!isApplicationAlive()) rejected('BROWSER_APPLICATION_EXITED');
+      const record = { index, action: step.action, passed: false }; observed.steps.push(record);
+      if (step.action === 'navigate') {
+        const response = await page.goto(`${origin}${step.path}`, { waitUntil: 'load' });
+        if (!response || !response.ok()) rejected('BROWSER_NAVIGATION_FAILED');
+      } else {
+        const locator = page.locator(step.selector);
+        if (step.action === 'click') await locator.click();
+        else if (step.action === 'fill') await locator.fill(step.text);
+        else if (step.action === 'assert_visible') await locator.waitFor({ state: 'visible' });
+        else if (step.action === 'assert_text') {
+          await locator.waitFor({ state: 'attached' });
+          const assertionDeadline = performance.now() + Math.min(5000, config.timeout_ms);
+          while (await locator.textContent() !== step.text) {
+            if (performance.now() >= assertionDeadline) rejected('BROWSER_ASSERTION_FAILED');
+            await delay(25);
+          }
+        }
+      }
+      if (observed.policy_violations) rejected('BROWSER_DOMAIN_POLICY_VIOLATION');
+      record.passed = true;
+    }
+    stage = 'BROWSER_ARTIFACT_FAILED';
+    const protocol = await context.newCDPSession(page);
+    const snapshot = await protocol.send('DOMSnapshot.captureSnapshot', { computedStyles: [] });
+    const safeTags = new Set('HTML HEAD BODY TITLE META LINK STYLE SCRIPT DIV SPAN P H1 H2 H3 H4 H5 H6 A BUTTON INPUT FORM LABEL SELECT OPTION TEXTAREA UL OL LI TABLE THEAD TBODY TR TH TD MAIN NAV HEADER FOOTER SECTION ARTICLE ASIDE IMG SVG PATH CANVAS VIDEO AUDIO IFRAME BR HR STRONG EM B I PRE CODE'.split(' '));
+    const nodes = [];
+    for (const [documentIndex, document] of snapshot.documents.entries()) {
+      for (let index = 0; index < document.nodes.nodeType.length; index++) {
+        if (nodes.length >= 5000) rejected('BROWSER_DOM_SIZE_LIMIT');
+        const type = document.nodes.nodeType[index];
+        const name = snapshot.strings[document.nodes.nodeName[index]];
+        nodes.push({ document: documentIndex, index, parent: document.nodes.parentIndex[index],
+          type, tag: safeTags.has(name) ? name : type === 3 ? '#text' : type === 9 ? '#document' : 'OTHER',
+          ...(type === 3 ? { text: '[REDACTED]' } : {}) });
+      }
+    }
+    // Persist structure only, never raw DOM, attributes, values, bodies or logs.
+    observed.artifacts.push({ kind: 'dom', redaction_status: 'redacted',
+      content: { schema_version: 1, projection: 'dom-structure-all-values-redacted', nodes } });
+    if (observed.policy_violations) rejected('BROWSER_DOMAIN_POLICY_VIOLATION');
+    if (observed.page_errors || observed.console_errors) rejected('BROWSER_PAGE_ERRORS');
+    if (!isApplicationAlive()) rejected('BROWSER_APPLICATION_EXITED');
+    observed.passed = true;
+  } catch (error) { observed.error_code = error.observationCode || stage; }
+  finally {
+    if (browser) {
+      try { await browser.close(); } catch { observed.passed = false; observed.error_code = 'BROWSER_CLOSE_FAILED'; }
+    }
+  }
+  return observed;
+}

package/src/terminal/browser-observer-supervisor.js

@@ -0,0 +1,73 @@
+/* global configuration */
+// Executed from trusted installed source inside the outer network/PID sandbox.
+// Application code gets a second mount/PID namespace, without observer tools,
+// browser profiles, parent process descriptors, keys or operator files.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { get } from 'node:http';
+import { setTimeout as delay } from 'node:timers/promises';
+import { chromium } from '/run/chati-observer-tools/playwright-core/index.mjs';
+import { observeBrowserScenario } from '/run/chati-observer-tools/observer-driver.mjs';
+
+const config = configuration;
+const observed = { passed: false, error_code: null, steps: [], artifacts: [],
+  policy_violations: 0, page_errors: 0, console_errors: 0, browser_version: null, application_stopped: false };
+let application; let applicationClosed; let applicationExited = false;
+let stage = 'BROWSER_APPLICATION_START_FAILED';
+function rejected(code) { throw Object.assign(new Error(code), { observationCode: code }); }
+function ready() {
+  return new Promise((resolve) => {
+    const request = get({ hostname: '127.0.0.1', port: config.application.port, path: config.ready_path,
+      headers: { Host: `${config.hostname}:${config.application.port}` }, timeout: 250 }, (response) => {
+      const ok = response.statusCode >= 200 && response.statusCode < 400;
+      response.destroy(); resolve(ok);
+    });
+    request.on('timeout', () => request.destroy()); request.on('error', () => resolve(false));
+  });
+}
+try {
+  application = spawn('/usr/bin/bwrap', [
+    '--die-with-parent', '--unshare-pid', '--unshare-ipc', '--unshare-uts',
+    // Network remains shared with the *isolated* observer, never the host.
+    ...['/usr', '/bin', '/sbin', '/lib', '/lib64'].filter((path) => existsSync(path)).flatMap((path) => ['--ro-bind', path, path]),
+    '--dir', '/etc', ...(existsSync('/etc/ld.so.cache') ? ['--ro-bind', '/etc/ld.so.cache', '/etc/ld.so.cache'] : []),
+    '--dev', '/dev', '--proc', '/proc', '--tmpfs', '/tmp', '--tmpfs', '/run',
+    '--bind', config.working_dir, config.working_dir,
+    '--ro-bind', '/run/chati-observer-tools/application', '/run/chati-application',
+    '--chdir', config.working_dir, '--', '/run/chati-application', ...config.application.args,
+  ], { detached: true, env: { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', TZ: 'UTC',
+    TMPDIR: '/tmp', PORT: String(config.application.port), HOST: '127.0.0.1' }, stdio: ['pipe', 'pipe', 'pipe'] });
+  let appBytes = 0;
+  for (const stream of ['stdout', 'stderr']) application[stream].on('data', (bytes) => {
+    // Never mix builder-controlled stdout with the observation protocol.
+    appBytes += bytes.length;
+    if (appBytes > 2 * 1024 * 1024) {
+      try { process.kill(-application.pid, 'SIGKILL'); } catch { /* group already exited */ }
+    }
+  });
+  applicationClosed = new Promise((resolve) => {
+    application.once('error', () => { applicationExited = true; resolve(); });
+    application.once('close', () => { applicationExited = true; resolve(); });
+  });
+  application.stdin.on('error', () => {});
+  application.stdin.end(config.application.stdin);
+  const deadline = performance.now() + Math.min(30000, config.timeout_ms);
+  while (!await ready()) {
+    if (applicationExited) rejected('BROWSER_APPLICATION_EXITED');
+    if (performance.now() >= deadline) rejected('BROWSER_APPLICATION_NOT_READY');
+    await delay(25);
+  }
+  stage = 'BROWSER_LAUNCH_FAILED';
+  Object.assign(observed, await observeBrowserScenario({ chromium, config, isApplicationAlive: () => !applicationExited,
+    launchOptions: { executablePath: `/run/chati-observer-tools/chromium/${config.browser_file}`,
+      args: [`--host-resolver-rules=MAP ${config.hostname} 127.0.0.1, MAP * ~NOTFOUND`, '--no-proxy-server'] } }));
+} catch (error) {
+  observed.error_code = error.observationCode || stage;
+} finally {
+  if (application && !applicationExited) {
+    try { process.kill(-application.pid, 'SIGKILL'); } catch { /* process exited during cleanup */ }
+  }
+  if (applicationClosed) await applicationClosed;
+  observed.application_stopped = applicationExited;
+}
+process.stdout.write(JSON.stringify(observed));