flowviant 0.125.27 → 0.125.29

package/bin/lib/runTurn.mjs

@@ -203,6 +203,7 @@ function runPlainTurn(opts) {
     // one profile (turnProfile.mjs).
     const stdinText = rt.stdin?.({ prompt, system, profile: turnProfile.adapterProfile }) ?? null;
     const args = rt.args({
+      managedBrowser: opts.managedBrowser === true,
       cardTurn: opts.cardTurn === true,
       verifiedWorktree: opts.verifiedWorktree === true,
       orchestration: opts.orchestration === true,

package/bin/lib/runtimeAuth.mjs

@@ -1,4 +1,4 @@
-/** Claude Code's own auth verdict for the local desktop contract.
+/** Coding tools' own auth verdicts for the local desktop contract.
  *
  * The credential file is only a context clue (claudeAuth.mjs): on some boxes
  * Claude stores a working login in a keychain. Only `claude auth status --json`
@@ -15,6 +15,28 @@ const UNKNOWN = Object.freeze({ signedIn: null, billing: null, subscriptionType:
 const TTL_MS = 90_000;
 const SUBSCRIPTIONS = new Set(['pro', 'max', 'team', 'enterprise']);
 
+function cachedAuth(cachePath, bin, now, refresh) {
+  if (refresh) return null;
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+    if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
+        cached.result?.checkedAt === new Date(cached.at).toISOString() &&
+        [true, false, null].includes(cached.result?.signedIn) &&
+        [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
+  } catch { /* No usable cache: ask the CLI, including after an upgrade. */ }
+  return null;
+}
+
+function retainAuth(cachePath, bin, now, result) {
+  const measured = { ...result, checkedAt: new Date(now).toISOString(),
+    expiresAt: result.expiresAt ?? null, expiryKind: result.expiryKind ?? null };
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
+    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result: measured }), { mode: 0o600 });
+  } catch { /* Caching is optional; never break status. */ }
+  return measured;
+}
+
 export function parseClaudeAuthStatus(raw) {
   let value;
   try { value = JSON.parse(raw); } catch { return UNKNOWN; }
@@ -31,14 +53,8 @@ export function parseClaudeAuthStatus(raw) {
 
 export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(), '.flowviant', 'claude-auth-status.json'),
   refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync, contextFor = claudeAuthContext } = {}) {
-  if (!refresh) {
-    try {
-      const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
-      if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
-          [true, false, null].includes(cached.result?.signedIn) &&
-          [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
-    } catch { /* no cache, or unreadable cache: ask the CLI */ }
-  }
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
   let result = UNKNOWN;
   try {
     const child = spawn(bin, ['auth', 'status', '--json'], {
@@ -46,16 +62,40 @@ export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(
       stdio: ['ignore', 'pipe', 'ignore'],
     });
     if (!child.error && (child.status === 0 || child.status === 1)) result = parseClaudeAuthStatus(child.stdout);
-    if (result.signedIn === true && result.billing === 'subscription' && result.subscriptionType === null) {
+    if (result.signedIn === true && result.billing === 'subscription') {
       const context = contextFor();
-      if (context.source === 'file' && SUBSCRIPTIONS.has(context.subscriptionType)) {
-        result = { ...result, subscriptionType: context.subscriptionType };
+      if (context.source === 'file') {
+        if (result.subscriptionType === null && SUBSCRIPTIONS.has(context.subscriptionType)) {
+          result = { ...result, subscriptionType: context.subscriptionType };
+        }
+        // Access-token expiry is renewable. Only the store's explicit refresh
+        // expiry can describe the end of this login; absent stays unknown.
+        const expiry = Date.parse(context.refreshExpiresAt ?? '');
+        if (Number.isFinite(expiry)) result = { ...result, expiresAt: new Date(expiry).toISOString(), expiryKind: 'refresh' };
       }
     }
   } catch { /* A failed probe means unknown, not signed out. */ }
+  return retainAuth(cachePath, bin, now, result);
+}
+
+/** `codex login status` writes its verdict to stderr. Keep only the verdict,
+ * never its output: API-key mode can include credential material. */
+export function readCodexAuthStatus({ bin = 'codex', cachePath = join(homedir(), '.flowviant', 'codex-auth-status.json'),
+  refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync } = {}) {
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
+  let result = UNKNOWN;
   try {
-    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
-    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result }), { mode: 0o600 });
-  } catch { /* Caching is optional; never break status. */ }
-  return result;
+    const child = spawn(bin, ['login', 'status'], {
+      encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const words = `${child.stdout ?? ''}\n${child.stderr ?? ''}`.trim();
+    if (!child.error && child.status === 0 && /^logged in\b/im.test(words)) {
+      result = { signedIn: true, billing: /api.?key/i.test(words) ? 'api' : /chatgpt/i.test(words) ? 'subscription' : null, subscriptionType: null };
+    } else if (!child.error && child.status === 1 && /^not logged in\b/im.test(words)) {
+      result = { ...UNKNOWN, signedIn: false };
+    }
+  } catch { /* Unknown, never a fabricated sign-out. */ }
+  return retainAuth(cachePath, bin, now, result);
 }

package/bin/lib/runtimeClaude.mjs

@@ -123,7 +123,7 @@ export const CLAUDE_RUNTIME = {
    * strongest form of it available anywhere: `--append-system-prompt` sits
    * above the conversation rather than inside it.
    */
-  args({ 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 }) {
     // 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
@@ -135,7 +135,7 @@ export const CLAUDE_RUNTIME = {
     if (profile === 'wiki' && !Array.isArray(postureList)) {
       throw new Error(`a wiki turn's vault must be a path a Claude Code permission rule can name — ${JSON.stringify(vaultDir)} is not`);
     }
-    const a = [];
+    const a = managedBrowser ? ['--no-chrome'] : [];
     // THREE ANSWERS TO ONE QUESTION — "what conversation is this?" — and they
     // are mutually exclusive, never combined.
     //

package/bin/lib/runtimeCodex.mjs

@@ -66,7 +66,8 @@ function codexMcp(token, mcpUrl) {
  * browser, `computer_use` and `apps` switched ON; a read-only consult, a
  * plan, a capture chat, a wiki or an image turn asked for none of them, and
  * a browser or the desktop is a way around a filesystem fence. A build turn
- * keeps the person's own config.
+ * keeps the person's own config, except that a mounted managed browser
+ * replaces native browser/computer tools on that code turn.
  */
 export const NO_REACH_OUT = Object.freeze([
   '-c', 'features.browser_use=false',
@@ -280,7 +281,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({ 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 }) {
     // 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
@@ -348,6 +349,9 @@ export const CODEX_RUNTIME = {
      */
     if (a.includes('--ignore-user-config')) a.push(...(personal?.args ?? []));
 
+    if (managedBrowser && profile === 'build') {
+      for (const feature of ['browser_use', 'browser_use_external', 'in_app_browser', 'computer_use']) a.push('-c', `features.${feature}=false`);
+    }
     a.push(...mcp, ...resultSchemaArgs);
     if (gated) a.push(...codexOrchestratorArgs(codexVersion));
     a.push(streamInput ? '-' : codexPrompt({ system, prompt, profile }));

package/bin/lib/vault.mjs

@@ -29,6 +29,7 @@ import { execFileSync } from 'node:child_process';
 import { join, relative, sep } from 'node:path';
 import { gitRaw } from './git.mjs';
 import { planVaultSync } from './vaultDiff.mjs';
+import { realDirState } from './ownedDirs.mjs';
 
 const SYNC_STATE = '.flowviant-sync.json';
 
@@ -96,6 +97,7 @@ export function vaultConfigForeignKey(dir) {
  *  of its own, which `git init` copies in (measured, git 2.55) — and which the
  *  check above would then refuse on every sync. A vault needs none of it. */
 export function ensureVault(dir) {
+  if (realDirState(dir) === 'other') throw new Error('wiki vault must be a real directory');
   mkdirSync(dir, { recursive: true });
   if (!existsSync(join(dir, '.git'))) {
     try {

package/bin/lib/vaultDiff.mjs

@@ -18,6 +18,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { protectedWikiPage } from './wikiOwnership.mjs';
 
 // Mirror the server contract (shared schema) — a page that violates it is
 // skipped with a warning (and carried forward if previously synced), never
@@ -44,6 +45,18 @@ export const isSafePath = (p) =>
 
 const SKIPPED = Object.freeze({ pages: 0, uploaded: 0, deleted: 0, skipped: true });
 
+/** Draft publication uses exactly the uplink's page/count limits. Keep the
+ * constants here so pre-publication validation cannot drift from sync. */
+export function assertWikiDraftFits(changes, beforeCount, resultingCount) {
+  for (const [path, content] of changes) {
+    if (!isSafePath(path) || (content !== null && Buffer.byteLength(content) > MAX_FILE_BYTES)) {
+      throw new Error(`wiki draft page exceeds sync contract: ${path}`);
+    }
+  }
+  if (resultingCount === 0 && beforeCount > 0) throw new Error('wiki draft would empty the vault');
+  if (resultingCount > MAX_FILES && resultingCount > beforeCount) throw new Error('wiki draft exceeds page ceiling');
+}
+
 /**
  * Plan one sync.
  *
@@ -97,6 +110,10 @@ export function planVaultSync({ found, walkErrors = 0, prev = {}, read, scrub =
       carry(p, 'unreadable');
       continue;
     }
+    if (protectedWikiPage(p, text)) {
+      carry(p, 'human/reference source, outside generated output');
+      continue;
+    }
     // Uplink scrub: the cartographer quotes real repo files, and a repo file
     // can contain a synced secret — redact known values before upload. The
     // hash is computed on the SCRUBBED text so the diff state stays coherent.
@@ -122,6 +139,11 @@ export function planVaultSync({ found, walkErrors = 0, prev = {}, read, scrub =
       if (!(p in current)) current[p] = prev[p];
     }
   }
+  // A generated-output sync has no authority to delete sources, including
+  // reserved legacy pages that are no longer present in this local snapshot.
+  for (const p of Object.keys(prev)) {
+    if (!(p in current) && protectedWikiPage(p)) current[p] = prev[p];
+  }
 
   // A readable vault that suddenly presents ZERO pages while the server holds
   // many is almost always a broken/moved dir, not an intentional wipe — refuse

package/bin/lib/wikiDraft.mjs

@@ -0,0 +1,105 @@
+/** A cartographer edits a disposable draft, never the persistent wiki or the
+ * Knowledge store. Publish only a complete turn; failures leave last-good bytes.
+ * Portable page metadata is an assertion by the CLI, not a sync-time attestation. */
+import { lstatSync, readdirSync, readFileSync, writeFileSync, mkdtempSync, rmSync, renameSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join, dirname, basename } from 'node:path';
+import { ensureRealSubdir } from './ownedDirs.mjs';
+import { isSafePath, assertWikiDraftFits } from './vaultDiff.mjs';
+
+import { wikiScalars as scalars, protectedWikiPage } from './wikiOwnership.mjs';
+
+/** Never follow links into an imported vault. A partial read cannot be a draft
+ * basis: fail before the CLI starts rather than infer missing pages as deleted. */
+function pages(dir, prefix = '', out = new Map(), rejectLinks = false) {
+  if (!lstatSync(dir).isDirectory()) throw new Error('wiki directory must be a real directory');
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const path = prefix + entry.name;
+    if (entry.isSymbolicLink()) {
+      if (rejectLinks) throw new Error(`wiki draft contains a symlink: ${path}`);
+      continue;
+    }
+    if (entry.isDirectory()) pages(join(dir, entry.name), `${path}/`, out, rejectLinks);
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.set(path, readFileSync(join(dir, entry.name), 'utf8'));
+  }
+  return out;
+}
+
+function put(dir, path, text) {
+  if (!isSafePath(path)) throw new Error(`unsafe wiki page: ${path}`);
+  const parent = dirname(path);
+  if (parent !== '.' && !ensureRealSubdir(dir, parent)) throw new Error(`wiki parent is not a real directory: ${parent}`);
+  try {
+    if (!lstatSync(join(dir, path)).isFile()) throw new Error(`wiki destination is not a file: ${path}`);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const target = join(dir, path);
+  const temporary = join(dirname(target), `.${basename(target)}.${randomUUID()}`);
+  try {
+    writeFileSync(temporary, text, { flag: 'wx' });
+    renameSync(temporary, target);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+export function beginWikiDraft(vaultDir) {
+  if (lstatSync(vaultDir).isSymbolicLink()) throw new Error('wiki vault must not be a symlink');
+  const before = pages(vaultDir);
+  const dir = mkdtempSync(join(dirname(vaultDir), '.wiki-draft-'));
+  try {
+    for (const [path, text] of before) put(dir, path, text);
+  } catch (e) {
+    rmSync(dir, { recursive: true, force: true });
+    throw e;
+  }
+  return {
+    dir,
+    discard: () => rmSync(dir, { recursive: true, force: true }),
+    publish({ sha, repoFullName }) {
+      const candidate = pages(dir, '', new Map(), true);
+      const changes = new Map();
+      for (const [path, text] of candidate) {
+        const old = before.get(path);
+        if (old === text || protectedWikiPage(path, old ?? text)) continue;
+        const meta = scalars(text);
+        // Changed prose carrying a previous commit must not masquerade as
+        // verified. Preserve other frontmatter bytes and unknown custom fields.
+        const verified = meta('wiki-verified-at');
+        let content = text;
+        if (verified && (verified.toLowerCase() !== sha?.toLowerCase() || !/^[a-f0-9]{40}$/i.test(verified) ||
+          meta('wiki-origin') !== 'generated' || meta('wiki-repo') !== (repoFullName ?? ''))) {
+          content = text.replace(/^(---\r?\n[\s\S]*?\r?\n)---/, (fm) => fm.replace(/^wiki-verified-at:.*\r?\n/gm, ''));
+        }
+        changes.set(path, content);
+      }
+      for (const [path, text] of before) {
+        if (!candidate.has(path) && !protectedWikiPage(path, text)) changes.set(path, null);
+      }
+      const resulting = new Set(before.keys());
+      for (const [p, text] of changes) text === null ? resulting.delete(p) : resulting.add(p);
+      assertWikiDraftFits(changes, before.size, resulting.size);
+      // Human edits made during the turn win. Validate the complete read set
+      // before any write, including deletions and untouched source pages.
+      const current = pages(vaultDir);
+      if (current.size !== before.size || [...before].some(([p, text]) => current.get(p) !== text)) throw new Error('wiki changed during generation; draft not published');
+      const applied = [];
+      try {
+        for (const [p, text] of changes) {
+          if (text === null) rmSync(join(vaultDir, p));
+          else put(vaultDir, p, text);
+          applied.push(p);
+        }
+      } catch (e) {
+        for (const p of applied.reverse()) {
+          if (before.has(p)) put(vaultDir, p, before.get(p));
+          else rmSync(join(vaultDir, p), { force: true });
+        }
+        throw e;
+      }
+      return changes.size;
+    },
+  };
+}

package/bin/lib/wikiOwnership.mjs

@@ -0,0 +1,19 @@
+/** Generated wiki ownership; never grants writes to imported context. */
+export const wikiScalars = (text) => {
+  const fm = text.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+  return (key) => {
+    const lines = (fm?.[1] ?? '').split('\n').filter((line) => line.startsWith(`${key}:`));
+    return lines.length === 1 ? lines[0].slice(key.length + 1).trim().replace(/^["']|["']$/g, '') : '';
+  };
+};
+
+/** Reserved namespaces are never generated output, even for legacy pages.
+ * Legacy decisions are human-owned unless explicitly marked generated. */
+export function protectedWikiPage(path, text = '') {
+  const p = path.toLowerCase();
+  const origin = wikiScalars(text)('wiki-origin');
+  return p.split('/').at(-1) === 'instructions.md' ||
+    /^(imports|references|sources)\//.test(p) ||
+    (p.startsWith('decisions/') && origin !== 'generated') ||
+    (origin !== '' && origin !== 'generated');
+}

package/bin/lib/wikiRunner.mjs

@@ -30,6 +30,7 @@ import { sawSentinel } from './claude.mjs';
 import { runTurn as defaultRunTurn } from './runTurn.mjs';
 import { SYSTEM_WIKI, WIKI_KICKOFF, SYSTEM_REGROUND, REGROUND_KICKOFF } from './prompts.mjs';
 import { ensureVault, syncVault } from './vault.mjs';
+import { beginWikiDraft } from './wikiDraft.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
 import { runtimeLabel } from './runtimes.mjs';
 import { pickRuntimeFor as defaultPickRuntimeFor } from './runtimeDetection.mjs';
@@ -238,7 +239,8 @@ export function createWikiRunner({
       // always taken (audit 2026-10-10, F749).
       if (!SHA1_ABBREV_RE.test(String(sha).toLowerCase())) continue;
       try {
-        const out = gitRaw(['show', '--name-only', '--pretty=format:', String(sha)], repoRoot);
+        // Report both sides of a rename so old files: citations are affected.
+        const out = gitRaw(['show', '--no-renames', '--name-only', '--pretty=format:', String(sha)], repoRoot);
         for (const line of out.split('\n')) {
           const f = line.trim();
           if (f) files.add(f);
@@ -374,6 +376,7 @@ export function createWikiRunner({
          * readout. Null (and absent from the frame) when no CLI ran.
          */
         let usage = null;
+        let draft = null;
         const onUsage = (rt) => (u) => {
           usage = addUsage(usage, { ...u, runtime: rt });
         };
@@ -394,20 +397,23 @@ export function createWikiRunner({
           resetWorktree(wikiWt, getBaseRef());
           // No HEAD → '' — still writes the map, just ungrounded.
           const sha = gitOrNull(['rev-parse', 'HEAD'], wikiWt) ?? '';
-          // Sync the vault after the turn regardless of the sentinel: a died
-          // sweep's partial pages still persist (merge, no prune) — only a
-          // COMPLETED sweep finalizes, so an interrupted one can't erase pages.
+          const repoFullName = originSlug(repoRoot) || undefined;
+          const persistentVaultDir = vaultDir;
+          draft = beginWikiDraft(persistentVaultDir);
+          vaultDir = draft.dir;
+          // Only a complete draft can replace last-good pages or prune them.
+          // The CLI's write fence names the draft, never Knowledge or sources.
           const runSync = async (finalize) => {
             try {
               const r = await syncVault({
-                dir: vaultDir,
+                dir: persistentVaultDir,
                 url: WIKI_VAULT_URL,
                 token: FLEET_TOKEN,
                 userAgent: USER_AGENT,
                 finalize,
                 groundedAtSha: sha || undefined,
                 // Powers the GitHub blob links behind every cited file path.
-                repoFullName: originSlug(repoRoot) || undefined,
+                repoFullName,
                 warn,
                 // Redact synced secrets a page may have quoted from the repo.
                 scrub: envScrub,
@@ -435,7 +441,7 @@ export function createWikiRunner({
             sweepAttempts++;
             note(`${c.cyan('wiki')} ${c.dim(`— regenerating: your ${wikiLabel} is reading the repo…`)}`);
             const out = await runTurn({
-              prompt: WIKI_KICKOFF(sha, vaultDir),
+              prompt: WIKI_KICKOFF(sha, vaultDir, repoFullName),
               resume: false,
               system: SYSTEM_WIKI(vaultDir),
               cwd: wikiWt,
@@ -454,12 +460,13 @@ export function createWikiRunner({
             });
             const complete = sawSentinel(out, 'WIKI_DONE');
             if (complete) {
+              draft.publish({ sha, repoFullName });
               sweepCompleted = true;
               ok(`${c.cyan('wiki')} ${c.dim('— vault regenerated from your code.')}`);
             } else {
-              warn('wiki sweep ended without WIKI_DONE — partial pages synced');
+              warn('wiki sweep ended without WIKI_DONE — last good pages retained');
             }
-            await runSync(complete);
+            if (complete) await runSync(true);
           } else {
             const files = changedFilesForShas(task.shas);
             if (files === null) {
@@ -484,6 +491,7 @@ export function createWikiRunner({
                   title: task.title,
                   files,
                   vaultDir,
+                  repoFullName,
                   predictedPages: task.dirtiesPages ?? [],
                 }),
                 resume: false,
@@ -499,10 +507,11 @@ export function createWikiRunner({
                   wikiChild = ch;
                 },
               });
-              if (sawSentinel(out, 'REGROUND_DONE'))
+              if (sawSentinel(out, 'REGROUND_DONE')) {
+                draft.publish({ sha, repoFullName });
                 ok(`${c.cyan('wiki')} ${c.dim(`— vault updated for "${task.title}".`)}`);
-              else warn(`wiki re-ground for "${task.title}" ended without REGROUND_DONE.`);
-              await runSync(false);
+                await runSync(false);
+              } else warn(`wiki re-ground for "${task.title}" ended without REGROUND_DONE — last good pages retained.`);
             }
             // Consume the durable job: attempted = done (success or not — the
             // sync is idempotent and a failed turn heals on the next full
@@ -521,6 +530,7 @@ export function createWikiRunner({
         } catch (e) {
           warn(`wiki ${task.type} failed: ${e.message}`);
         } finally {
+          draft?.discard();
           wikiChild = null;
           if (heartbeat) clearInterval(heartbeat);
           /**

package/bin/lib/workAgentTools.mjs

@@ -27,13 +27,15 @@ import { postureToolsNote } from './postureTools.mjs';
 import { machineMcpServers } from './claudeMachineMcp.mjs';
 import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
 import { VIDEO_SERVER } from './videoRender.mjs';
+import { BROWSER_SERVER } from './managedBrowser.mjs';
 
 /** The servers the daemon itself mounts on a card turn, by the names the
  *  agent calls them: a multi-repository card's add_repository, an
  *  orchestrated card's routing, a build's UI review and a video card's
- *  render_video (2026-10-26). Never a project server's, whatever the base
+ *  render_video (2026-10-26), and a code turn's managed browser (2026-10-30).
+ *  Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER, browser: BROWSER_SERVER });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -46,7 +48,7 @@ export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositorie
  * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
  * needs one, and the keys the runner takes the mount as.
  */
-export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, browserConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
   // A turn reads the base ref afresh. Changes the agent has made to its
   // own worktree cannot silently change the next turn's tools.
   const source = sources.find((r) => r.wt === wt);
@@ -59,6 +61,7 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
     ...(repositoryTool ? { [CARD_TURN_SERVERS.repositories]: repositoryTool.config } : {}),
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
     ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
+    ...(posture === 'build' && browserConfig ? { [CARD_TURN_SERVERS.browser]: browserConfig } : {}),
     // A video card's render tool rides its fenced posture (videoRender.mjs).
     ...(videoConfig ? { [CARD_TURN_SERVERS.video]: videoConfig } : {}),
   } });

package/bin/lib/workAgentTurnExecution.mjs

@@ -70,6 +70,8 @@ import { measuredRuntimeVersion } from './runtimeDetection.mjs';
 import { createIntermediateArtifacts, IntermediateArtifactCapacityError } from './intermediateArtifacts.mjs';
 import { createUiReview } from './uiReview.mjs';
 import { createVideoRender } from './videoRender.mjs';
+import { createManagedBrowser } from './managedBrowser.mjs';
+import { completeBrowserReview, browserHandoffPrompt } from './browserHandoff.mjs';
 import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
 
 export function createAgentTurnExecution({
@@ -102,6 +104,7 @@ export function createAgentTurnExecution({
   exportModel,
   makeUiReview = createUiReview,
   makeVideoRender = createVideoRender,
+  makeManagedBrowser = createManagedBrowser,
 }) {
   const reportDelivery = createDeliveryReporter();
   /** How long the final flush may hold the settle. Bounded because the settle
@@ -410,6 +413,8 @@ export function createAgentTurnExecution({
     /** The CLI, unless a person already asked to stop this turn (Interrupt
      *  now): then nothing starts — no fresh retry, no continuation. */
     let uiReview = null;
+    let managedBrowser = null;
+    let browserNote = '';
     let uiReviewNote = '';
     let uiReviewEvidence = '';
     // A video card's render tool (videoRender.mjs), and the words a turn
@@ -424,6 +429,8 @@ export function createAgentTurnExecution({
       args.verifiedWorktree = true;
       args = withUiReview(args, uiReviewNote, uiReview?.env);
       args = withUiReview(args, videoNote);
+      args = withUiReview(args, browserNote, managedBrowser?.env);
+      args.managedBrowser = Boolean(managedBrowser);
       return runTurnImpl(args);
     };
     /**
@@ -473,6 +480,15 @@ export function createAgentTurnExecution({
     let orchestrator = null;
     let intermediateDelivery = null;
     try {
+      if (posture === 'build' && job.kind !== 'merge_resolve' && ['claude', 'codex'].includes(rt)) {
+        try {
+          managedBrowser = await makeManagedBrowser({ wt, turnId, signal: setupController.signal, onChild: ch => {
+            workChildren.set(ch, agentId); groupKillChildren?.add(ch);
+            return () => { workChildren.delete(ch); groupKillChildren?.delete(ch); };
+          } });
+          browserNote = managedBrowser.instructions;
+        } catch (error) { browserNote = `The managed browser could not start: ${envScrub(error.message)}. Report interactive browser checks unavailable.`; }
+      }
       if (posture === 'build' && job.kind !== 'merge_resolve') {
         try {
           uiReview = await makeUiReview({ wt, signal: setupController.signal, onChild: ch => {
@@ -499,10 +515,11 @@ export function createAgentTurnExecution({
           notify: message => liveInput ? run.live?.inject(message) === true : false,
           taken: id => run.live?.onTaken(id) });
       }
-      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, uiReviewConfig: uiReview?.config, videoConfig: videoRender?.config ?? null, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
+      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, uiReviewConfig: uiReview?.config, videoConfig: videoRender?.config ?? null, browserConfig: managedBrowser?.config, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
       projectTools = tools.projectTools;
       localCleanup?.begin(turnId);
       const { toolsNote } = tools;
+      let browserThread = agentResume.resumeThreadId;
       const agentTurnArgs = {
         ...((liveInput || orchestrator) ? { liveMessages: (run.live = makeLiveMessages({
           scope: 'agent', turnId, cwd: wt, sessionMetaPath, interrupted: () => run.interrupted,
@@ -550,12 +567,14 @@ export function createAgentTurnExecution({
         resume: agentResume.resume,
         resumeThreadId: agentResume.resumeThreadId,
         onInit: (init) => {
+          if (rt === 'claude' && typeof init.sessionId === 'string') browserThread = init.sessionId;
           orchestrator?.root(init.sessionId);
           // A server that did not connect, as the CLI said (unknown: nothing).
           trace.mcpStatus(init.mcpServers);
           agentResume.sawSession(init.sessionId);
         },
         onThreadId: (id) => {
+          browserThread = id;
           orchestrator?.root(id);
           agentResume.sawThread(id);
         },
@@ -726,6 +745,7 @@ export function createAgentTurnExecution({
           runtime: rt,
           beforeFresh: () => {
             agentResume.forgetThread();
+            browserThread = undefined;
             lastAnswer = null;
             model = null;
           },
@@ -736,19 +756,34 @@ export function createAgentTurnExecution({
           void postAgentActivity(agentId, 'resuming after an internal wait');
         } }
       );
-      out = await finishRepositoryDelivery({
-        job, run: repositoryRun, out, answer: () => lastAnswer,
-        resume: async (prompt) => {
+      out = await completeBrowserReview(out, {
+        browser: managedBrowser, signal: setupController.signal,
+        resume: async (handoff) => {
+          const thread = agentResume.threadNow() ?? browserThread;
+          if (!thread) throw new Error('The browser handoff could not resume: the CLI reported no conversation id. Interactive verification is incomplete.');
           lastAnswer = null;
           const counted = usage;
-          return runCli({
-            ...agentTurnArgs, prompt, liveContinuation: true,
-            onUsage: (next) => agentTurnArgs.onUsage(addUsage(counted, next)),
-            writableDirs: repositoryRun.sourcesNow().filter((r) => r.wt !== wt).map((r) => r.wt),
-            resume: true,
-            resumeThreadId: agentResume.threadNow() ?? agentTurnArgs.resumeThreadId,
+          trace.prose('text', handoff.reason === 'returned' ? 'Browser control returned. Resuming verification.' : 'The browser handoff ended. Resuming to report incomplete interactive checks.');
+          return runAgentWithInternalWaits(args => runCli(args), {
+            ...agentTurnArgs, prompt: browserHandoffPrompt(handoff), resume: true, resumeThreadId: thread, liveContinuation: true,
+            ...(repositoryRun ? { writableDirs: repositoryRun.sourcesNow().filter(r => r.wt !== wt).map(r => r.wt) } : {}),
+            onUsage: next => agentTurnArgs.onUsage(addUsage(counted, next)),
           });
         },
+        finish: current => finishRepositoryDelivery({
+          job, run: repositoryRun, out: current, answer: () => lastAnswer,
+          resume: async (prompt) => {
+            lastAnswer = null;
+            const counted = usage;
+            return runCli({
+              ...agentTurnArgs, prompt, liveContinuation: true,
+              onUsage: (next) => agentTurnArgs.onUsage(addUsage(counted, next)),
+              writableDirs: repositoryRun.sourcesNow().filter((r) => r.wt !== wt).map((r) => r.wt),
+              resume: true,
+              resumeThreadId: agentResume.threadNow() ?? browserThread,
+            });
+          },
+        }),
       });
     } finally {
       // The loopback capability stays registered until every retained CLI
@@ -759,6 +794,7 @@ export function createAgentTurnExecution({
       // owned by its review tool, then bind evidence to the final source
       // before the existing artifact upload and delivery settlement.
       try { await videoRender?.close(); } catch { /* a closed listener */ }
+      try { await managedBrowser?.close(); } catch { /* turn teardown continues */ }
       try { await uiReview?.close(); }
       finally {
         try { uiReviewEvidence = uiReview?.finalize() ?? uiReviewEvidence; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.27",
+  "version": "0.125.29",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {