flowviant 0.125.18 → 0.125.21

package/bin/lib/websiteAccess.mjs

@@ -0,0 +1,68 @@
+/** Bounded website metadata only. Neither assistant prose nor page bodies are
+ * evidence of a loaded page. Browser integrations supply explicit observations
+ * through result metadata, never by embedding claims in a tool input. */
+import { scrubCut } from './uplinkScrub.mjs';
+import { REFERENCE_DIAGNOSTICS } from './publicReferenceProtocol.mjs';
+
+export function websiteUrl(value, scrub = s => s) {
+  if (typeof value !== 'string' || value.length > 8_192) return undefined;
+  try {
+    // Scrub before URL serialization can escape a known secret in its path.
+    const url = new URL(scrub(value));
+    if (!['http:', 'https:'].includes(url.protocol)) return undefined;
+    url.username = ''; url.password = ''; url.search = ''; url.hash = '';
+    return scrub(url.href).slice(0, 500);
+  } catch { return undefined; }
+}
+
+export function websiteRequest(name, input, scrub) {
+  const method = name === 'WebSearch' ? 'search' : name === 'WebFetch' ? 'fetch' :
+    name === 'WebsiteAccess' ? (['search', 'fetch', 'browser', 'tool', 'capability'].includes(input.method) ? input.method : 'tool') :
+    /^(?:mcp__|[^.]+\.)/.test(name ?? '') && websiteUrl(input?.url) ? 'tool' : null;
+  if (!method) return null;
+  const requestedUrl = websiteUrl(input?.url, scrub);
+  return {
+    method, tool: scrubCut(name === 'WebsiteAccess' ? input.tool ?? 'website' : name, 120, scrub),
+    ...(requestedUrl ? { requestedUrl } : {}), access: 'unknown',
+  };
+}
+
+/** Only fixed, recognized runtime errors can leave the machine. Never retain
+ * arbitrary tool output, even when is_error is set by the native runtime. */
+export function observeWebsite(e, meta, scrub) {
+  const w = e.website;
+  const output = scrubCut(meta.output ?? '', 16_384, scrub);
+  const lines = output.split('\n', 80);
+  const diagnostic = lines.find(line => Object.values(REFERENCE_DIAGNOSTICS).includes(line) || /^(?:Error: )?(?:MCP tool call requires approval, but approval policy is never|Tool (?:WebFetch|WebSearch) is not available|Browser executable not found|Browser sandbox unavailable|Request timed out|fetch failed|Network request failed|Not accessible via this tool)\.?$/i.test(line) || line.startsWith('flowviant: this turn is read-only, so '));
+  const failed = meta.isError === true || (Number.isSafeInteger(meta.exitCode) && meta.exitCode !== 0);
+  w.access = failed ? 'failed' : 'unknown';
+  if (failed && diagnostic) {
+    e.errorMessage = diagnostic.slice(0, 500);
+    if (diagnostic.length > 500) e.errorTruncated = true;
+    if (/^flowviant:/.test(diagnostic)) {
+      w.access = 'permission_denied'; w.permissionSource = 'flowviant';
+    } else if (/requires approval/.test(diagnostic)) {
+      w.access = 'permission_denied'; w.permissionSource = 'runtime';
+    } else if (/not available|not found|sandbox unavailable/i.test(diagnostic)) w.access = 'unavailable';
+  }
+  // Explicit daemon-owned integration result, not a tool-input or prose field.
+  // This is the emission seam used by the isolated browser/capture consumers.
+  const observed = meta.website;
+  if (meta.result) w.observedAt = new Date().toISOString();
+  if (meta.result && observed && typeof observed === 'object') {
+    if (['unknown', 'loaded', 'search_results', 'failed', 'unavailable', 'permission_denied', 'challenge', 'partial'].includes(observed.access)) w.access = observed.access;
+    const finalUrl = websiteUrl(observed.finalUrl, scrub);
+    if (finalUrl) w.finalUrl = finalUrl;
+    if (Number.isInteger(observed.httpStatus) && observed.httpStatus >= 100 && observed.httpStatus <= 599) w.httpStatus = observed.httpStatus;
+    if (['flowviant', 'runtime', 'unknown'].includes(observed.permissionSource)) w.permissionSource = observed.permissionSource;
+    if (['advertised', 'unavailable', 'unknown'].includes(observed.availability)) w.availability = observed.availability;
+    if (typeof observed.observedAt === 'string') w.observedAt = scrubCut(observed.observedAt, 40, scrub);
+  }
+  // Search completion is evidence of a search, never of opening its hits.
+  if (w.method === 'search' && w.access === 'unknown' && !failed && meta.result && meta.toolSuccess === true) w.access = 'search_results';
+  if (w.method === 'search' && w.access === 'loaded') w.access = 'unknown';
+  if (!meta.result) w.access = 'unknown';
+  e.outcome = !meta.result ? 'unknown' : ['failed', 'unavailable', 'permission_denied'].includes(w.access) ? 'failed' :
+    failed ? 'failed' : meta.toolSuccess === true || ['loaded', 'search_results', 'challenge', 'partial'].includes(w.access) ? 'success' : 'unknown';
+  if (e.outcome === 'failed') e.errorCategory = w.access === 'permission_denied' ? 'denied' : w.access === 'unavailable' ? 'unavailable_tool' : 'tool_error';
+}

package/bin/lib/websiteTrace.mjs

@@ -0,0 +1,36 @@
+import { createToolLog } from './workToolLog.mjs';
+import { createHash } from 'node:crypto';
+
+/** Reuse the turn collector for agent research too. Trace entries are snapshots:
+ * later results must not mutate a request already queued or sent. */
+export function createWebsiteTrace(cwd, trace, attributed) {
+  const { pushToolEvent } = createToolLog(cwd);
+  const inventory = new Map();
+  const emit = (event, owner) => {
+    const send = id => trace.tool(event, id);
+    if (owner && attributed) attributed(owner, send); else send(owner);
+  };
+  return (name, input, meta = {}) => {
+    const e = pushToolEvent(name, input, meta);
+    if (!e?.website) return false;
+    const event = structuredClone(e);
+    if (event.id) {
+      // The trace scopes/caps ids. Hash the complete native identity first so
+      // long child prefixes cannot hide the call id at that boundary.
+      const id = createHash('sha256').update(JSON.stringify([meta.agentId ?? null, event.id])).digest('hex');
+      event.id = trace.agentId(`web:${id}`);
+    }
+    // Startup inventory belongs beside a reference attempt, not in every
+    // coding turn. An actual unavailable/denied capability result still emits
+    // immediately, even if no request can follow it.
+    if (event.website.method === 'capability' && !event.website.requestedUrl && event.website.access === 'unknown') {
+      inventory.set(event.website.tool, { event, owner: meta.agentId });
+      if (inventory.size > 12) inventory.delete(inventory.keys().next().value);
+      return true;
+    }
+    for (const pending of inventory.values()) emit(pending.event, pending.owner);
+    inventory.clear();
+    emit(event, meta.agentId);
+    return true;
+  };
+}

package/bin/lib/work.mjs

@@ -1,3 +1,4 @@
+import { reportLocalCleanup } from './localCleanupReport.mjs';
 /**
  * Work sessions — the Workbench tabs and the agent lanes, daemon side: THE
  * MANAGER that builds every lane and hands each one exactly what it uses.
@@ -27,6 +28,7 @@
  * whole — `workBusy` and the returned surface. A pure rule or constant
  * (REPO_PLACE, the resume-id guards, brainFor, the turn lock) is IMPORTED by
  * every lane that reads it, never carried through here.
+ *   workLocalCleanup.mjs   released managed session and agent cleanup
  *   workPlaces.mjs         where a session works, its worktree, its markers
  *   workSessionGroups.mjs  which process groups each tab started
  *   workChildren.mjs       the live CLI children, teardown, the admission
@@ -60,6 +62,10 @@
  *   repositoryPlaces + agentRepositories: multi-repo places; the live brief: workAgentBrief, workAgentBriefRunner)
  */
 
+import { dirname, join } from 'node:path';
+import { placeTurnLockedByLivePid } from './turnLock.mjs';
+import { createWorkLocalCleanup } from './workLocalCleanup.mjs';
+import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
 import { trackedRepositorySetup } from './repositorySetup.mjs';
 import { createRepositoryPlaces } from './repositoryPlaces.mjs';
 import { createAgentRepositories } from './agentRepositories.mjs';
@@ -91,7 +97,7 @@ import { createWorkSessionRuntime } from './workSessionRuntime.mjs';
 import { createAdoptCarry } from './workAdoptCarry.mjs';
 import { createWorkSessionTurns } from './workSessionTurns.mjs';
 import { createWorkRetire } from './workRetire.mjs';
-import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT, PROJECT_ID } from './config.mjs';
 import { gitNet as gitNetIn, excludeInWorktree } from './git.mjs';
 import { createProjectLandedObserver } from './projectLanded.mjs';
 import { createPlaceLock } from './placeLock.mjs';
@@ -110,6 +116,7 @@ export function createWorkManager({
   getBaseRef,
   getMcpUrl,
   getLeaseTtl, exportModel,
+  getCleanupPermission = () => false,
   /** "The repo picture changed — look again." See the caller in fleet.mjs. */
   onRepoChanged = () => {},
   /**
@@ -156,6 +163,7 @@ export function createWorkManager({
    */
   const artifacts = createArtifactReporter({
     fleetUrl: FLEET_URL,
+    projectIdentity: () => PROJECT_ID,
     token: FLEET_TOKEN,
     userAgent: USER_AGENT,
     scrub: envScrub,
@@ -211,7 +219,7 @@ export function createWorkManager({
 
   const { placeOf, notePlace, learnPlaces, placeDir, branchAt, placeWtFor, sessionMetaPath, worktreeBornAt } =
     createWorkPlaces({ repoRoot, baseDir, baseRef, onRepoChanged });
-  const { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses } =
+  const { sessionGroups, noteSessionGroup, pruneSessionGroups, sessionProcesses, cleanupProcessesIdle } =
     createWorkSessionGroups({ repoRoot });
   const { workChildren, groupKillChildren, shutdownWork, liveTurnCount, liveTurns, admit } =
     createWorkChildren({ extraLiveTurns });
@@ -226,6 +234,39 @@ export function createWorkManager({
     getArtifactsAccepted,
     log: (line) => warn(line),
   });
+  const { reconcileLocalCleanup, cleanupBusy } = createWorkLocalCleanup({
+    placeLocks, inPlace, permission: getCleanupPermission,
+    onResult: reportLocalCleanup, onIncomplete: reportLocalCleanup,
+    eligible: place => {
+      if (shipping.size || cleanupProcessesIdle(place) !== true) return false;
+      const wt = placeDir(place), lock = wt && sessionMetaPath(wt, 'flowviant-turn.lock');
+      return Boolean(lock) && !placeTurnLockedByLivePid(lock);
+    },
+    targetsFor: place => {
+      if (!PROJECT_ID) return [];
+      const agentId = place.slice(2), siblings = repositoryPlaces?.entries(place);
+      const roots = siblings?.length ? siblings.filter(r => r.writable).map(r => r.wt) : [placeDir(place)];
+      return roots.flatMap(wt => {
+        const statePath = wt && sessionMetaPath(wt, 'flowviant-local-cleanup', agentId);
+        if (!statePath) return [];
+        return [{ placeDir: wt, agentId, projectId: PROJECT_ID, statePath,
+          operations: ({ guard, recoveryMemo, preparedOnly }) => {
+            const output = artifacts.cacheFor({ placeDir: wt, agentId, cleanupGuard: guard, recoveryMemo, preparedOnly });
+            if (!output) return [];
+            const managed = createManagedLocalCleanup({ placeDir: wt, projectId: PROJECT_ID, agentId,
+              path: sessionMetaPath(wt, 'flowviant-managed-local', agentId),
+              codexHome: join(dirname(statePath), `flowviant-agent-codex-home-${agentId}`),
+              outputCache: output, getUses: () => guard() ? [] : ['lifecycle-unknown-or-active'],
+            });
+            return [...output.records().map(ref => ({ ref: { ...ref, kind: 'artifact' },
+              prepare: () => output.prepareEviction(ref), run: () => output.evict(ref) })),
+            ...managed.records().map(ref => ({ ref,
+              prepare: () => managed.prepare(ref), run: () => managed.reclaimOne(ref) }))];
+          } }];
+      });
+    },
+    log: line => warn(line),
+  });
   const { reportSessionWorktree, reportPlaceWorktrees, burstListeners, reportWorktrees } =
     createWorkPlaceReports({
       repositoryPlaces,
@@ -387,6 +428,7 @@ export function createWorkManager({
     publishAgentBranch, stopAgentPublishing,
     admit,
     workChildren,
+    groupKillChildren,
     agentPublished,
     agentRemoteAt,
     fetchAgentFiles,
@@ -455,7 +497,7 @@ export function createWorkManager({
     workChildren.size > 0 ||
     workAnswering.size > 0 ||
     pendingWorkReports.size > 0 ||
-    pendingShipReports.size > 0;
+    pendingShipReports.size > 0 || cleanupBusy();
 
   return {
     flushWorkReports,
@@ -473,6 +515,7 @@ export function createWorkManager({
     retireWorkSessions,
     reportWorktrees,
     reconcileIdleArtifacts,
+    reconcileLocalCleanup,
     shutdownWork,
     workBusy,
     runningAgentCount: () => agentTurns.size,

package/bin/lib/workAgentPlans.mjs

@@ -1,3 +1,4 @@
+import { fetchResultInputs } from './resultInputs.mjs';
 import { planWork, reportPlanOutcome } from './workActivity.mjs';
 /** Agent plan claims, read-only planning turns, and proposal reports. */
 import { PLAN_RECOVERY_SYSTEM, parsePlanDiagnosis, watchPlanAttempt } from './workPlanRecovery.mjs';
@@ -287,6 +288,7 @@ export function createWorkAgentPlans({
          */
         const liveAgents = (Array.isArray(job.liveAgents) ? job.liveAgents : []).map(a =>
           liveAgentContext(a, measureAgentFootprint({ placeId: a?.placeId, baseDir, baseRef })));
+        await fetchResultInputs(repoRoot, job.resultInputs);
         const knowledgeDir = knowledgeDirFor(repoRoot);
         discovery.toolLog.baseline = measureRepositoryBaseline({ cwd: repoRoot, baseRef, knowledgeDir });
         discovery.toolLog.captureBaseline = repositoryBaselineOf(job.captureBaseline);
@@ -351,6 +353,7 @@ export function createWorkAgentPlans({
           });
         };
         let context = AGENT_PLAN_KICKOFF({ tasks, liveAgents, agentCap: Number.isInteger(job.agentCap) && job.agentCap > 0 ? job.agentCap : 3 });
+        if (job.resultContext) context += '\n\n' + job.resultContext;
         if (job.recovery?.start) context += '\nSTART REPAIR: This is a supporting diagnosis for an already approved Start. Return exactly ONE group with the same ordered taskIds, attachment target (or absence) and CLI. Preserve the approval; do not start an unapproved sibling. Diagnose admission/pickup errors and repair planning evidence/context. Ask only a genuine person-only question in the diagnostic JSON. Approval and source revision (data): ' + JSON.stringify(job.recovery.start);
         const system = withProjectContext(SYSTEM_PLAN, { knowledgeDir }) + '\n\n' + discoveryGuide(rt, 'planning') + '\n\n' + REPOSITORY_BASELINE_PARAGRAPH(discovery.toolLog.baseline, discovery.toolLog.captureBaseline, discovery.toolLog.reconciliation);
         if (job.recovery) {

package/bin/lib/workAgentPrecheck.mjs

@@ -12,10 +12,12 @@ import { gitOrNull } from './git.mjs';
 import { parsePrecheck } from './agentPlan.mjs';
 import { readStash } from './agentCards.mjs';
 import { c, note } from './ui.mjs';
-import { runTurn } from './runTurn.mjs';
+import { runTurn as defaultRunTurn } from './runTurn.mjs';
 import { SYSTEM_PRECHECK, AGENT_PRECHECK_KICKOFF } from './prompts.mjs';
 import { scrub as envScrub } from './uplinkScrub.mjs';
-import { pickRuntimeFor } from './runtimeDetection.mjs';
+import { detectRuntimes as defaultDetectRuntimes } from './runtimeDetection.mjs';
+import { canRun, runtimeById } from './runtimes.mjs';
+import { brainFor } from './workBrain.mjs';
 import { runCappedTurn } from './workCappedTurn.mjs';
 import { taskIdsFromMessage } from './worktreeDiff.mjs';
 import { limitLine } from './cliLimit.mjs';
@@ -23,12 +25,12 @@ import { fleetEndpoint, isConsideredRefusal } from './fleetWire.mjs';
 import { postFleetJson } from './fleetPost.mjs';
 import { agentBrowserHome } from './noWindowEnv.mjs';
 
-export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workChildren }) {
+export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workChildren, runTurn = defaultRunTurn, detectRuntimes = defaultDetectRuntimes }) {
   const AGENT_PRECHECK_URL = fleetEndpoint('agent-precheck', FLEET_URL);
 
   // ── THE AI PRE-REVIEW ──────────────────────────────────────────────────────
   //
-  // A FRESH Claude reads the branch before the human does. The owner asked for
+  // A fresh conversation reads the branch before the human does. The owner asked for
   // it in these words: "before having the user manually check, can we have the
   // daemon … spawn an agent to review the work so basically we get an ai to look
   // at the review before a human looks at it for a double check."
@@ -135,15 +137,14 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
     return { text, taskIds: [...taskIds] };
   };
 
-  const runPrecheck = async (agentId, wt, agentName, repository) => {
-    /**
-     * WHICH CLI READS. `pickRuntimeFor('consult')` — the same picker the scratch
-     * planner uses, and for the same reason: this prompt was written against
-     * Claude, and a machine with no read-only-capable runtime simply does not
-     * produce a precheck. Nothing is posted and nothing is said on the row.
-     */
-    const rt = pickRuntimeFor('consult');
-    if (!rt) return;
+  const runPrecheck = async (agentId, wt, agentName, repository, source) => {
+    // A fresh read-only conversation, on this agent's CLI/model/effort.
+    // Missing provenance or a missing CLI skips this optional reading; it
+    // never licenses a machine-wide provider substitution.
+    if (!source) return;
+    const rt = source.runtime || 'claude';
+    if (!canRun(runtimeById(rt), 'consult') || !detectRuntimes().some(row => row.id === rt && row.installed)) return;
+    const brain = brainFor(source, rt);
     /**
      * THE PRESSURE GUARD, at the spawn, exactly as every other unattended lane
      * asks it. `churn` and never `interactive`: nobody is watching this, and a
@@ -232,6 +233,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
           profile: 'consult',
           cwd: wt,
           runtime: rt,
+          ...brain,
           // The agent's own browser profile, in the worktree this reader stands
           // in; no display either way (noWindowEnv.mjs, 2026-09-29).
           browserHome: agentBrowserHome(sessionMetaPath, wt, agentId),
@@ -242,8 +244,7 @@ export function createWorkAgentPrecheck({ baseRef, admit, sessionMetaPath, workC
           work: { kind: 'pre-review', id: agentId, name: agentName },
           // The CLI's own count for this reading. Set, never accumulated: one
           // turn is one `result` event, and the adding-up is the server's.
-          // Tagged with the CLI, so a Claude pre-review of a Codex agent is
-          // charged as Claude's and not folded into the agent's own figure.
+          // Tagged with the same CLI as the associated agent.
           onUsage: (u) => {
             usage = { ...u, runtime: rt };
           },

package/bin/lib/workAgentReview.mjs

@@ -29,7 +29,7 @@ export function createWorkAgentReview({ runCheck, runPrecheck }) {
    * INSIDE the place's writer lock on a path whose callers settle real work —
    * `runAgentMerge` in particular reports a claimed merge after this returns.
    */
-  const runReviewEntry = async (agentId, wt, agentName, repository) => {
+  const runReviewEntry = async (agentId, wt, agentName, repository, brain) => {
     let result = { status: 'unknown' };
     try {
       result = await runCheck(agentId, wt, repository) ?? result;
@@ -37,7 +37,7 @@ export function createWorkAgentReview({ runCheck, runPrecheck }) {
       /* the row keeps its previous check answer, which is null the first time */
     }
     try {
-      await runPrecheck(agentId, wt, agentName, repository);
+      await runPrecheck(agentId, wt, agentName, repository, brain);
     } catch {
       /* no pre-review is posted, and absence renders nothing */
     }

package/bin/lib/workAgentTools.mjs

@@ -31,7 +31,7 @@ import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
  *  agent calls them: a multi-repository card's add_repository, and an
  *  orchestrated card's routing. Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review' });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -44,7 +44,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, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = 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);
@@ -56,6 +56,7 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
   const projectTools = prepareAgentTools(snapshot, rt, env, wt, { codexHome, fenced: posture !== 'build', turnServers: {
     ...(repositoryTool ? { [CARD_TURN_SERVERS.repositories]: repositoryTool.config } : {}),
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
+    ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
   } });
   try {
     const mountsProjectMcp = TURN_PROFILES[posture]?.projectMcp === true && runnerToolCapabilities(rt).mcp;

package/bin/lib/workAgentTurnExecution.mjs

@@ -1,3 +1,6 @@
+import { reportLocalCleanup } from './localCleanupReport.mjs';
+import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
+import { createCaptureRetention } from './referenceCaptures.mjs';
 import { imageRevisionInstructions } from './artifactIteration.mjs';
 import { agentChildScope } from './agentQueueContext.mjs';
 import { measureTestFindings } from './testFindings.mjs';
@@ -33,6 +36,7 @@ import { addUsage } from './turnUsage.mjs';
 import { stashCard } from './agentCards.mjs';
 import { c } from './ui.mjs';
 import { runTurn } from './runTurn.mjs';
+import { liveGroups, processesSupported } from './processes.mjs';
 import { killGroup } from './processGroup.mjs';
 import { AGENT_TASK_SPEC } from './prompts.mjs';
 import { agentKickoff, agentFollowupKickoff, agentTurnSystem } from './workAgentTurnShape.mjs';
@@ -42,6 +46,7 @@ import { scrub as envScrub } from './uplinkScrub.mjs';
 import { canRun, runtimeById } from './runtimes.mjs';
 import { toolEventOf, CLAUDE_TOOL_PROSE_KINDS, scrubNativeText } from './runtimeEvents.mjs';
 import { makeTraceRelay } from './trace.mjs';
+import { createWebsiteTrace } from './websiteTrace.mjs';
 import { prepareCardTools } from './workAgentTools.mjs';
 import { runTurnResumingOnce } from './resumeLost.mjs';
 import { runAgentWithInternalWaits } from './agentInternalWait.mjs';
@@ -61,6 +66,8 @@ import { knownCodexModels } from './runtimeOfferings.mjs';
 import { codexSubagentsSafe } from './runtimeCodex.mjs';
 import { measuredRuntimeVersion } from './runtimeDetection.mjs';
 import { createIntermediateArtifacts } from './intermediateArtifacts.mjs';
+import { createUiReview } from './uiReview.mjs';
+import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
 
 export function createAgentTurnExecution({
   admit,
@@ -80,6 +87,7 @@ export function createAgentTurnExecution({
   runReviewEntry,
   runMergeCheck,
   workChildren,
+  groupKillChildren,
   agentChildren,
   postAgentTrace,
   postAgentActivity,
@@ -89,6 +97,7 @@ export function createAgentTurnExecution({
   makeLiveMessages = createLiveMessages,
   runTurnImpl = runTurn,
   exportModel,
+  makeUiReview = createUiReview,
 }) {
   const reportDelivery = createDeliveryReporter();
   /** How long the final flush may hold the settle. Bounded because the settle
@@ -247,7 +256,7 @@ export function createAgentTurnExecution({
       return;
     }
     /**
-     * …AND ITS SCRATCH BESIDE IT, EMPTY (0.115.0): a fenced shell's temp files
+     * …AND ITS SCRATCH BESIDE IT (0.115.0): a fenced shell's temp files
      * (a here-document, `mktemp`) go under `.flowviant/tmp`, which Codex's
      * design fence grants because `/tmp` is read-only in there
      * (`ensureFenceScratch`). Made for every file kind — one rule, no kind
@@ -356,6 +365,9 @@ export function createAgentTurnExecution({
      * CLAUDE_TOOL_PROSE_KINDS.
      */
     const doubledKinds = runtimeById(rt)?.parse ? null : CLAUDE_TOOL_PROSE_KINDS;
+    const websiteTrace = createWebsiteTrace(wt, trace, (id, emit) => {
+      if (orchestrator) orchestrator.attributed(id, emit); else emit(id);
+    });
 
     /**
      * WHICH BRAIN THIS CONTAINER WAS PINNED TO — the same `brainFor` the tab
@@ -389,7 +401,14 @@ export function createAgentTurnExecution({
     const spawnedChildren = new Set();
     /** The CLI, unless a person already asked to stop this turn (Interrupt
      *  now): then nothing starts — no fresh retry, no continuation. */
-    const runCli = (args) => (run.interrupted ? Promise.resolve('') : runTurnImpl(args));
+    let uiReview = null;
+    let uiReviewNote = '';
+    let uiReviewEvidence = '';
+    const runCli = (args) => {
+      if (run.interrupted) return Promise.resolve('');
+      args = withUiReview(args, uiReviewNote, uiReview?.env);
+      return runTurnImpl(args);
+    };
     /**
      * WHAT THIS TURN SPENT, AS THE CLI COUNTED IT (2026-09-19).
      *
@@ -427,10 +446,28 @@ export function createAgentTurnExecution({
       artifactsBefore.imageRevision = job.imageRevision;
       artifactInstructions += '\n\n' + imageRevisionInstructions(job.imageRevision, job.resultInputs);
     }
+    const cleanupPath = sessionMetaPath(wt, 'flowviant-managed-local', agentId);
+    const localCleanup = PROJECT_ID && cleanupPath ? createManagedLocalCleanup({
+      placeDir: wt, projectId: PROJECT_ID, agentId, path: cleanupPath,
+      codexHome: agentResume.codexHome,
+      outputCache: artifacts.cacheFor?.({ placeDir: wt, agentId }) ?? null,
+    }) : null;
     let projectTools = null;
     let orchestrator = null;
     let intermediateDelivery = null;
     try {
+      if (posture === 'build' && job.kind !== 'merge_resolve') {
+        try {
+          uiReview = await makeUiReview({ wt, signal: setupController.signal, onChild: ch => {
+            workChildren.set(ch, agentId); groupKillChildren?.add(ch);
+            return () => { workChildren.delete(ch); groupKillChildren?.delete(ch); };
+          } });
+          uiReviewNote = uiReview.instructions;
+        } catch (error) {
+          uiReviewNote = `Local UI self-review is unavailable: ${envScrub(error.message)}. Report browser, image and interaction checks as unrun with this reason when relevant; do not install tools or weaken isolation.`;
+          uiReviewEvidence = uiReviewNote;
+        }
+      }
       if (orchestrating) {
         orchestrator = await createOrchestrator({ turnId, runtime: rt, trace, admit,
           assignmentContext: () => agentChildScope(job),
@@ -441,8 +478,9 @@ 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, 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, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
       projectTools = tools.projectTools;
+      localCleanup?.begin(turnId);
       const { toolsNote } = tools;
       const agentTurnArgs = {
         ...((liveInput || orchestrator) ? { liveMessages: (run.live = makeLiveMessages({
@@ -458,6 +496,9 @@ export function createAgentTurnExecution({
         })) } : {}),
         // The kickoff and the system prompt, composed by the agent lane's
         // shape (workAgentTurnShape.mjs) from what this run measured.
+        signal: setupController.signal,
+        onReferenceCapture: createCaptureRetention({ report: (files, { placeDir }) => artifacts.report({ placeDir, before: new Map(), agentId, turnId, requireStored: true, referenceCapture: true,
+          includeNames: new Set(files.map(f => f.name)), requiredOutputs: files.map(({ name, sha256 }) => ({ name, sha256 })) }) }),
         researchHandoff: job.researchHandoff,
         resultInputs: job.resultInputs,
         intermediateFiles,
@@ -573,6 +614,7 @@ export function createAgentTurnExecution({
         // the builder itself (bounded window BEFORE its caps; see
         // toolEventOf). A tool it does not know pushes nothing.
         onToolEvent: (name, input, meta) => {
+          if (websiteTrace(name, input, meta)) return;
           if (meta?.agentId) {
             if (!meta.result) {
               const event = toolEventOf(name, input, wt, envScrub);
@@ -688,6 +730,14 @@ export function createAgentTurnExecution({
       // answer is scrubbed; then it can leave the machine's secret set.
       out = envScrub(out);
       if (lastAnswer) lastAnswer = envScrub(lastAnswer);
+      // The builder has finished its fix/recheck loop. Close only resources
+      // owned by its review tool, then bind evidence to the final source
+      // before the existing artifact upload and delivery settlement.
+      try { await uiReview?.close(); }
+      finally {
+        try { uiReviewEvidence = uiReview?.finalize() ?? uiReviewEvidence; }
+        catch (error) { uiReviewEvidence = `Local UI review final source/evidence measurement unavailable: ${envScrub(error.message)}. Earlier checks do not establish the final source.`; }
+      }
       await run.live?.stop();
       await orchestrator?.close(run.interrupted);
       await brief?.stop();
@@ -730,6 +780,7 @@ export function createAgentTurnExecution({
       // The ran marker and the thread this turn spoke under, written now
       // that the turn is over (workAgentResume.mjs).
       agentResume.persist();
+      localCleanup?.capture();
       /**
        * AN ACTION THAT CHANGES WHAT THE MACHINE WOULD MEASURE MUST CAUSE A
        * NEW MEASUREMENT — the rule every session settle keeps, and the one
@@ -793,7 +844,21 @@ export function createAgentTurnExecution({
       wt,
       modelExports: intermediateDelivery?.modelExports,
     });
+    appendUiReviewEvidence(body, uiReviewEvidence);
     if (body.outcome === 'delivered') intermediateDelivery?.commit();
+    // This place's writer lock is still held. Measure the exited children
+    // and their groups before releasing any file requirements. Dirty repository files are unrelated to managed scratch eligibility.
+    if (localCleanup) {
+      const cleanupResults = localCleanup.capture(); // binds newly uploaded exact image counterparts
+      const groups = new Set([...spawnedChildren].map(ch => ch.pid).filter(pid => Number.isInteger(pid) && pid > 1));
+      const drained = !run.interrupted && processesSupported() && groups.size > 0 &&
+        [...spawnedChildren].every(ch => ch.exitCode != null || ch.signalCode != null) && liveGroups(groups).size === 0;
+      cleanupResults.push(...localCleanup.completeTurn({ drained,
+        handoffComplete: body.outcome === 'delivered', uploadsComplete: artifacts.pendingCount?.() === 0 }));
+      cleanupResults.push(...await localCleanup.reclaim({ drained }));
+      for (const result of cleanupResults) reportLocalCleanup({ ...result,
+        projectId: PROJECT_ID, agentId, placeDir: wt, place, turnId });
+    }
     if (res) setRuntimeLimit(PROJECT_ID, rt, null);
     if (body.outcome === 'delivered' && job.task?.taskType === 'tests' && res?.testFindings) {
       body.testFindings = measureTestFindings(res.testFindings, repositoryRun?.sourcesNow() ?? [{ wt, baseRef: baseRef(), id: job.repos?.length === 1 ? job.repos[0] : null }], envScrub);
@@ -831,7 +896,7 @@ export function createAgentTurnExecution({
     // pre-review HERE, in the worktree we are already standing in and still
     // hold the lock on — see `runReviewEntry`. Only after the settle that may
     // say delivered: the three `nothing` settles never opened it.
-    if (final && reply?.review === true) await runReviewEntry(agentId, wt, job.agentName);
+    if (final && reply?.review === true) await runReviewEntry(agentId, wt, job.agentName, undefined, job);
     } finally { await repositoryRun?.tool?.close(); }
   };
 

package/bin/lib/workAgentTurns.mjs

@@ -53,6 +53,7 @@ export function createWorkAgentTurns({
   stopAgentPublishing = () => {},
   admit,
   workChildren,
+  groupKillChildren,
   agentPublished,
   agentRemoteAt,
   /** The turn's files, fetched into its worktree (workAttachments.mjs, 0.112.0). */
@@ -138,6 +139,7 @@ export function createWorkAgentTurns({
     runMergeCheck,
     exportModel,
     workChildren,
+    groupKillChildren,
     agentChildren,
     postAgentTrace,
     postAgentActivity,
@@ -322,7 +324,7 @@ export function createWorkAgentTurns({
           const wt = typeof held.body.worktree === 'string' ? held.body.worktree : null;
           if (reply?.review === true && isSafePathSegment(place) && wt && existsSync(wt)) {
             await inPlace(place, place.startsWith(AGENT_PLACE_PREFIX), () =>
-              runReviewEntry(String(job.agentId || ''), wt, job.agentName)
+              runReviewEntry(String(job.agentId || ''), wt, job.agentName, undefined, job)
             );
           }
         })()