@link-assistant/hive-mind 2.11.3 → 2.11.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.11.4
+
+### Patch Changes
+
+- 6b3df3c: Stop reporting an empty `--model formal-ai` run as a success. Formal AI sessions are now attributed to Link.Assistant at $0.00, token usage is parsed for all six tools, the two duplicate auto-restart loops are one N/M budget that fails visibly when it is exhausted, and a pull request whose net diff is empty (or holds only the solver's own placeholder) is neither described as changed nor announced as ready to merge. Docker images now pin Formal AI 0.317.0 so the upstream workspace-effect and self-healing fixes are distributed with Hive Mind.
+
 ## 2.11.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.11.3",
+  "version": "2.11.4",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent-commander.lib.mjs

@@ -11,7 +11,9 @@ import { resolveCodexReasoningEffort } from './codex.options.lib.mjs';
 import { mapClaudeSubAgentModelToEnvValue, mapModelForTool } from './models/index.mjs';
 import { buildCodexDisable1mContextConfigArgs, buildCodexSubSessionSizeConfigArgs, parseSubSessionSize } from './sub-session-size.lib.mjs';
 import { detectUsageLimit } from './usage-limit.lib.mjs';
+import { applyFormalAiPricingOverride } from './formal-ai-pricing.lib.mjs'; // Issue #2119
 import { getCacheReadTokenCount, getCumulativeContextInputTokens, getOutputTokenCount } from './context-fill.lib.mjs';
+import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 
 export const AGENT_COMMANDER_TOOLS = new Set(['claude', 'codex', 'opencode', 'agent', 'qwen', 'gemini']);
 
@@ -257,25 +259,34 @@ const enrichPricingInfoWithTokenUsage = ({ pricingInfo = null, usage = null, too
   };
 };
 
-export const summarizeAgentCommanderResult = ({ result, tool }) => {
+export const summarizeAgentCommanderResult = ({ result, tool, model = null }) => {
   const plainOutput = result?.output?.plain || '';
   if (result?.metadata && typeof result.metadata === 'object') {
     const metadata = result.metadata;
     const streamTokenUsage = metadata.streamTokenUsage || result.usage || null;
-    const pricingInfo = enrichPricingInfoWithTokenUsage({
+    const enrichedPricingInfo = enrichPricingInfoWithTokenUsage({
       pricingInfo: metadata.pricingInfo || null,
       usage: streamTokenUsage,
       tool,
       publicPricingEstimate: metadata.publicPricingEstimate ?? metadata.pricingInfo?.totalCostUSD ?? null,
     });
+    // Issue #2119: a Formal AI session belongs to Link.Assistant at $0.00, no
+    // matter which agentic CLI agent-commander drove it.
+    const { pricingInfo, publicPricingEstimate, anthropicTotalCostUSD } = applyFormalAiPricingOverride({
+      model,
+      pricingInfo: enrichedPricingInfo,
+      publicPricingEstimate: metadata.publicPricingEstimate ?? enrichedPricingInfo?.totalCostUSD ?? null,
+      anthropicTotalCostUSD: metadata.anthropicTotalCostUSD ?? null,
+      tokenUsage: streamTokenUsage,
+    });
     return {
       success: metadata.success === true,
       sessionId: metadata.sessionId || result.sessionId || null,
       limitReached: !!metadata.limitReached,
       limitResetTime: metadata.limitResetTime || null,
       limitTimezone: metadata.limitTimezone || null,
-      anthropicTotalCostUSD: metadata.anthropicTotalCostUSD ?? null,
-      publicPricingEstimate: metadata.publicPricingEstimate ?? pricingInfo?.totalCostUSD ?? null,
+      anthropicTotalCostUSD,
+      publicPricingEstimate,
       pricingInfo,
       resultSummary: metadata.resultSummary || null,
       resultModelUsage: metadata.resultModelUsage || null,
@@ -291,12 +302,19 @@ export const summarizeAgentCommanderResult = ({ result, tool }) => {
   const usage = result?.usage || null;
   const resultMessage = [...messages].reverse().find(message => message?.type === 'result') || null;
   const totalCost = typeof resultMessage?.total_cost_usd === 'number' ? resultMessage.total_cost_usd : null;
-  const publicPricingEstimate = tool === 'agent' && typeof usage?.totalCost === 'number' ? usage.totalCost : null;
-  const pricingInfo = enrichPricingInfoWithTokenUsage({
-    pricingInfo: publicPricingEstimate !== null ? { totalCostUSD: publicPricingEstimate, source: 'agent-commander' } : null,
+  const rawPublicPricingEstimate = tool === 'agent' && typeof usage?.totalCost === 'number' ? usage.totalCost : null;
+  const enrichedPricingInfo = enrichPricingInfoWithTokenUsage({
+    pricingInfo: rawPublicPricingEstimate !== null ? { totalCostUSD: rawPublicPricingEstimate, source: 'agent-commander' } : null,
     usage,
     tool,
-    publicPricingEstimate,
+    publicPricingEstimate: rawPublicPricingEstimate,
+  });
+  const { pricingInfo, publicPricingEstimate, anthropicTotalCostUSD } = applyFormalAiPricingOverride({
+    model,
+    pricingInfo: enrichedPricingInfo,
+    publicPricingEstimate: rawPublicPricingEstimate ?? enrichedPricingInfo?.totalCostUSD ?? null,
+    anthropicTotalCostUSD: tool === 'claude' ? totalCost : null,
+    tokenUsage: usage,
   });
 
   return {
@@ -305,8 +323,8 @@ export const summarizeAgentCommanderResult = ({ result, tool }) => {
     limitReached: usageLimit.isUsageLimit,
     limitResetTime: usageLimit.resetTime,
     limitTimezone: usageLimit.timezone,
-    anthropicTotalCostUSD: tool === 'claude' ? totalCost : null,
-    publicPricingEstimate: publicPricingEstimate ?? pricingInfo?.totalCostUSD ?? null,
+    anthropicTotalCostUSD,
+    publicPricingEstimate,
     pricingInfo,
     resultSummary: extractResultSummary(messages, plainOutput),
     resultModelUsage: null,
@@ -367,13 +385,16 @@ export const executeWithAgentCommander = async params => {
 
   const result = await controller.stop();
   await log(`[agent-commander] ${tool} exited with code ${result.exitCode}`);
-  return summarizeAgentCommanderResult({ result, tool });
+  return summarizeAgentCommanderResult({ result, tool, model: argv.model });
 };
 
 export const checkForUncommittedChanges = async (tempDir, owner, repo, branchName, $, log = defaultLog, autoCommit = false, autoRestartEnabled = true) => {
   await log('\n🔍 Checking for uncommitted changes...');
+  // Issue #2119: AI tools leave scratch state (.formal-ai/, .playwright-mcp/) in
+  // the workspace. Ignoring it here keeps it out of both this check and 'git add -A'.
+  await ensureAiToolScratchIgnored(tempDir, log);
   const gitStatusResult = await $({ cwd: tempDir })`git status --porcelain 2>&1`;
-  const statusOutput = gitStatusResult.stdout?.toString().trim() || '';
+  const statusOutput = filterAiToolScratchFromStatus(gitStatusResult.stdout?.toString().trim() || '');
 
   if (!statusOutput) {
     await log('✅ No uncommitted changes found');

package/src/agent-token-usage.lib.mjs

@@ -2,6 +2,7 @@
 
 import Decimal from 'decimal.js-light';
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
+import { parseJsonRecords } from './json-stream.lib.mjs';
 import { getCumulativeContextInputTokens, getRestoredContextInputTokens } from './context-fill.lib.mjs';
 
 export const createTokenFieldAvailability = () => ({
@@ -95,15 +96,10 @@ export const accumulateAgentStepFinishUsage = (usage, data) => {
 export const parseAgentTokenUsage = output => {
   const usage = createAgentTokenUsage();
 
-  for (const rawLine of output.split('\n')) {
-    const line = rawLine.trim();
-    if (!line || !line.startsWith('{')) continue;
-
-    try {
-      accumulateAgentStepFinishUsage(usage, sanitizeObjectStrings(JSON.parse(line)));
-    } catch {
-      continue;
-    }
+  // Issue #2119: records are framed by balanced JSON rather than by newlines,
+  // so pretty-printed (multi-line) and concatenated records are counted too.
+  for (const record of parseJsonRecords(output)) {
+    accumulateAgentStepFinishUsage(usage, sanitizeObjectStrings(record));
   }
 
   return usage;

package/src/agent.lib.mjs

@@ -21,12 +21,15 @@ import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import Decimal from 'decimal.js-light';
 import semver from 'semver';
-import { agentModels, defaultModels, freeToBaseModelMap } from './models/index.mjs';
+import { agentModels, defaultModels, freeToBaseModelMap, isFormalAiModel } from './models/index.mjs';
 import { logPreparedToolCommand, resolveFormalAiToolInvocation } from './formal-ai.lib.mjs';
+import { buildFormalAiPricingInfo } from './formal-ai-pricing.lib.mjs'; // Issue #2119
 import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
+import { createJsonStreamScanner, parseJsonRecords } from './json-stream.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { attachStreamingInput, finalizeBidirectionalHandler, setupBidirectionalHandler } from './bidirectional-interactive.lib.mjs';
+import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
 
 export { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage };
 
@@ -111,6 +114,10 @@ const getBaseModelForPricing = modelName => {
  *   - opencodeCost: Actual billed cost from OpenCode Zen (free for most models)
  */
 export const calculateAgentPricing = async (modelId, tokenUsage) => {
+  // Issue #2119: Formal AI requests never reach OpenCode Zen, so neither the
+  // provider label nor a models.dev price lookup applies to them.
+  if (isFormalAiModel(modelId)) return buildFormalAiPricingInfo(modelId, tokenUsage);
+
   // Extract the model name from provider/model format
   // e.g., 'opencode/grok-code' -> 'grok-code'
   const modelName = modelId.includes('/') ? modelId.split('/').pop() : modelId;
@@ -632,80 +639,92 @@ export const executeAgentCommand = async params => {
         }
       };
 
-      for await (const chunk of execCommand.stream()) {
-        if (chunk.type === 'stdout') {
-          const output = chunk.data.toString();
-          // Split output into individual lines for NDJSON parsing
-          // Agent outputs NDJSON (newline-delimited JSON) format where each line is a separate JSON object
-          // This allows us to parse each event independently and extract structured data like session IDs
-          const lines = output.split('\n');
-          for (const line of lines) {
-            if (!line.trim()) continue;
-            try {
-              const data = sanitizeObjectStrings(JSON.parse(line));
-              // Issue #1968: a bare `null`/primitive NDJSON line must not abort
-              // event processing (any data.X access would throw on null).
-              if (data === null || typeof data !== 'object') continue;
-              // Output formatted JSON
-              await log(JSON.stringify(data, null, 2));
-              // Capture session ID from the first message
-              const eventSessionId = data.sessionID || data.session_id || data.sessionId;
-              if (!sessionId && eventSessionId) {
-                sessionId = eventSessionId;
-                await log(`📌 Session ID: ${sessionId}`);
-              }
-              // Issue #1250: Accumulate token usage during streaming
-              accumulateTokenUsage(data);
-              await markBidirectionalStateFromAgentEvent(data);
-              // Issue #1201: Detect error events during streaming for reliable detection
-              if (data.type === 'error' || data.type === 'step_error') {
-                streamingErrorDetected = true;
-                streamingErrorMessage = data.message || data.error || line.substring(0, 100);
-                await log(`⚠️  Error event detected in stream: ${streamingErrorMessage}`, { level: 'warning' });
-              }
-              // Issue #1263: Track text content for result summary
-              // Agent outputs text via 'text', 'assistant', or 'message' type events
-              if (data.type === 'text' && data.text) {
-                lastTextContent = data.text;
-              } else if (data.type === 'assistant' && data.message?.content) {
-                // Extract text from assistant message content
-                const content = Array.isArray(data.message.content) ? data.message.content : [data.message.content];
-                for (const item of content) {
-                  if (item.type === 'text' && item.text) {
-                    lastTextContent = item.text;
-                  }
-                }
-              } else if (data.type === 'message' && data.content) {
-                // Direct message content
-                if (typeof data.content === 'string') {
-                  lastTextContent = data.content;
-                } else if (Array.isArray(data.content)) {
-                  for (const item of data.content) {
-                    if (item.type === 'text' && item.text) {
-                      lastTextContent = item.text;
-                    }
-                  }
-                }
-              } else if (data.type === 'result' && data.result) {
-                // Explicit result message (like Claude outputs)
-                lastTextContent = data.result;
-              }
-              // Issue #1276: Detect successful completion events
-              // When agent emits session.idle or log with "exiting loop" message, it completed successfully
-              // This means any previous error events were recovered from (e.g., timeout then retry)
-              if (isAgentSuccessfulCompletionEvent(data)) {
-                agentCompletedSuccessfully = true;
+      // Issue #2119: agentic CLIs do not all emit strict one-record-per-line
+      // NDJSON. `formal-ai with agent --verbose` emits pretty-printed,
+      // multi-line records, and records can also be concatenated without a
+      // separator (issue #1250) or split across process chunks. A line-based
+      // JSON.parse dropped every structured event in those cases, which is how
+      // a session that really used 21677/22834 tokens was published as
+      // "Token usage: 0 input, 0 output" with no session id and no result
+      // summary. The scanner frames records by balanced JSON instead of by
+      // newlines, and surfaces anything that is not JSON as plain text.
+      const stdoutScanner = createJsonStreamScanner();
+      const stderrScanner = createJsonStreamScanner();
+
+      const handleAgentJsonEvent = async (raw, value) => {
+        const data = sanitizeObjectStrings(value);
+        // Issue #1968: a bare `null`/primitive record must not abort event
+        // processing (any data.X access would throw on null).
+        if (data === null || typeof data !== 'object') return;
+        // Output formatted JSON
+        await log(JSON.stringify(data, null, 2));
+        // Capture session ID from the first message (agent may use stdout or stderr)
+        const eventSessionId = data.sessionID || data.session_id || data.sessionId;
+        if (!sessionId && eventSessionId) {
+          sessionId = eventSessionId;
+          await log(`📌 Session ID: ${sessionId}`);
+        }
+        // Issue #1250: Accumulate token usage during streaming
+        accumulateTokenUsage(data);
+        await markBidirectionalStateFromAgentEvent(data);
+        // Issue #1201: Detect error events during streaming for reliable detection
+        if (data.type === 'error' || data.type === 'step_error') {
+          streamingErrorDetected = true;
+          streamingErrorMessage = data.message || data.error || raw.substring(0, 100);
+          await log(`⚠️  Error event detected in stream: ${streamingErrorMessage}`, { level: 'warning' });
+        }
+        // Issue #1263: Track text content for result summary
+        // Agent outputs text via 'text', 'assistant', or 'message' type events
+        if (data.type === 'text' && data.text) {
+          lastTextContent = data.text;
+        } else if (data.type === 'assistant' && data.message?.content) {
+          // Extract text from assistant message content
+          const content = Array.isArray(data.message.content) ? data.message.content : [data.message.content];
+          for (const item of content) {
+            if (item.type === 'text' && item.text) {
+              lastTextContent = item.text;
+            }
+          }
+        } else if (data.type === 'message' && data.content) {
+          // Direct message content
+          if (typeof data.content === 'string') {
+            lastTextContent = data.content;
+          } else if (Array.isArray(data.content)) {
+            for (const item of data.content) {
+              if (item.type === 'text' && item.text) {
+                lastTextContent = item.text;
               }
-              // Issue #1296: Detect step_finish with reason "stop" as successful completion
-              // This is a clear marker of success - agent finished normally, not due to error or limit
-              // When this event appears, we should ignore any error events that appeared earlier in the stream
-              // (e.g., timeout errors that were recovered from via retry logic)
-              if (data.type === 'step_finish' && data.part?.reason === 'stop') agentCompletedSuccessfully = true;
-            } catch {
-              // Not JSON - log as plain text
-              await log(line);
             }
           }
+        } else if (data.type === 'result' && data.result) {
+          // Explicit result message (like Claude outputs)
+          lastTextContent = data.result;
+        }
+        // Issue #1276: Detect successful completion events
+        // When agent emits session.idle or log with "exiting loop" message, it completed successfully
+        // This means any previous error events were recovered from (e.g., timeout then retry)
+        if (isAgentSuccessfulCompletionEvent(data)) {
+          agentCompletedSuccessfully = true;
+        }
+        // Issue #1296: Detect step_finish with reason "stop" as successful completion
+        // This is a clear marker of success - agent finished normally, not due to error or limit
+        // When this event appears, we should ignore any error events that appeared earlier in the stream
+        // (e.g., timeout errors that were recovered from via retry logic)
+        if (data.type === 'step_finish' && data.part?.reason === 'stop') agentCompletedSuccessfully = true;
+      };
+
+      const handleAgentStreamEvents = async events => {
+        for (const event of events) {
+          if (event.type === 'json') await handleAgentJsonEvent(event.raw, event.value);
+          // Not JSON - log as plain text
+          else await log(event.value);
+        }
+      };
+
+      for await (const chunk of execCommand.stream()) {
+        if (chunk.type === 'stdout') {
+          const output = chunk.data.toString();
+          await handleAgentStreamEvents(stdoutScanner.write(output));
           lastMessage = output;
           fullOutput += output; // Collect for both pricing calculation and error detection
         }
@@ -714,69 +733,8 @@ export const executeAgentCommand = async params => {
           const errorOutput = chunk.data.toString();
           if (errorOutput) {
             // Agent sends all output (including verbose logs and structured events) to stderr
-            // Process each line as NDJSON, same as stdout handling
-            const stderrLines = errorOutput.split('\n');
-            for (const stderrLine of stderrLines) {
-              if (!stderrLine.trim()) continue;
-              try {
-                const stderrData = sanitizeObjectStrings(JSON.parse(stderrLine));
-                // Issue #1968: skip bare `null`/primitive lines (see stdout handler above).
-                if (stderrData === null || typeof stderrData !== 'object') continue;
-                // Output formatted JSON (same formatting as stdout)
-                await log(JSON.stringify(stderrData, null, 2));
-                // Capture session ID from stderr too (agent sends it via stderr)
-                const eventSessionId = stderrData.sessionID || stderrData.session_id || stderrData.sessionId;
-                if (!sessionId && eventSessionId) {
-                  sessionId = eventSessionId;
-                  await log(`📌 Session ID: ${sessionId}`);
-                }
-                // Issue #1250: Accumulate token usage during streaming (stderr)
-                accumulateTokenUsage(stderrData);
-                await markBidirectionalStateFromAgentEvent(stderrData);
-                // Issue #1201: Detect error events during streaming (stderr) for reliable detection
-                if (stderrData.type === 'error' || stderrData.type === 'step_error') {
-                  streamingErrorDetected = true;
-                  streamingErrorMessage = stderrData.message || stderrData.error || stderrLine.substring(0, 100);
-                  await log(`⚠️  Error event detected in stream: ${streamingErrorMessage}`, { level: 'warning' });
-                }
-                // Issue #1263: Track text content for result summary (stderr)
-                if (stderrData.type === 'text' && stderrData.text) {
-                  lastTextContent = stderrData.text;
-                } else if (stderrData.type === 'assistant' && stderrData.message?.content) {
-                  const content = Array.isArray(stderrData.message.content) ? stderrData.message.content : [stderrData.message.content];
-                  for (const item of content) {
-                    if (item.type === 'text' && item.text) {
-                      lastTextContent = item.text;
-                    }
-                  }
-                } else if (stderrData.type === 'message' && stderrData.content) {
-                  if (typeof stderrData.content === 'string') {
-                    lastTextContent = stderrData.content;
-                  } else if (Array.isArray(stderrData.content)) {
-                    for (const item of stderrData.content) {
-                      if (item.type === 'text' && item.text) {
-                        lastTextContent = item.text;
-                      }
-                    }
-                  }
-                } else if (stderrData.type === 'result' && stderrData.result) {
-                  lastTextContent = stderrData.result;
-                }
-                // Issue #1276: Detect successful completion events (stderr)
-                // When agent emits session.idle or log with "exiting loop" message, it completed successfully
-                if (isAgentSuccessfulCompletionEvent(stderrData)) {
-                  agentCompletedSuccessfully = true;
-                }
-                // Issue #1296: Detect step_finish with reason "stop" as successful completion (stderr)
-                // This is a clear marker of success - agent finished normally, not due to error or limit
-                if (stderrData.type === 'step_finish' && stderrData.part?.reason === 'stop') {
-                  agentCompletedSuccessfully = true;
-                }
-              } catch {
-                // Not JSON - log as plain text
-                await log(stderrLine);
-              }
-            }
+            // Process it exactly like stdout so telemetry is never stream-specific
+            await handleAgentStreamEvents(stderrScanner.write(errorOutput));
             // Also collect stderr for error detection
             fullOutput += errorOutput;
           }
@@ -785,6 +743,10 @@ export const executeAgentCommand = async params => {
         }
       }
 
+      // Release any record that was still being assembled when the stream ended.
+      await handleAgentStreamEvents(stdoutScanner.flush());
+      await handleAgentStreamEvents(stderrScanner.flush());
+
       // Simplified error detection for agent tool
       // Issue #886: Trust exit code - agent now properly returns code 1 on errors with JSON error response
       // Don't scan output for error patterns as this causes false positives during normal operation
@@ -795,24 +757,17 @@ export const executeAgentCommand = async params => {
       // 2. Explicit JSON error messages from agent (type: "error")
       // 3. Usage limit detection (handled separately)
       const detectAgentErrors = stdoutOutput => {
-        const lines = stdoutOutput.split('\n');
+        // Issue #2119: frame records by balanced JSON, not by newlines, so
+        // pretty-printed and concatenated records are still inspected.
+        for (const record of parseJsonRecords(stdoutOutput)) {
+          const msg = sanitizeObjectStrings(record);
 
-        for (const line of lines) {
-          if (!line.trim()) continue;
+          // Issue #1968: ignore bare `null`/primitive records (msg.type would throw on null).
+          if (msg === null || typeof msg !== 'object') continue;
 
-          try {
-            const msg = sanitizeObjectStrings(JSON.parse(line));
-
-            // Issue #1968: ignore bare `null`/primitive lines (msg.type would throw on null).
-            if (msg === null || typeof msg !== 'object') continue;
-
-            // Check for explicit error message types from agent
-            if (msg.type === 'error' || msg.type === 'step_error') {
-              return { detected: true, type: 'AgentError', match: msg.message || msg.error || line.substring(0, 100) };
-            }
-          } catch {
-            // Not JSON - ignore for error detection
-            continue;
+          // Check for explicit error message types from agent
+          if (msg.type === 'error' || msg.type === 'step_error') {
+            return { detected: true, type: 'AgentError', match: msg.message || msg.error || JSON.stringify(msg).substring(0, 100) };
           }
         }
 
@@ -1112,11 +1067,14 @@ export const executeAgentCommand = async params => {
 export const checkForUncommittedChanges = async (tempDir, owner, repo, branchName, $, log, autoCommit = false, autoRestartEnabled = true) => {
   // Similar to OpenCode version, check for uncommitted changes
   await log('\n🔍 Checking for uncommitted changes...');
+  // Issue #2119: AI tools leave scratch state (.formal-ai/, .playwright-mcp/) in
+  // the workspace. Ignoring it here keeps it out of both this check and 'git add -A'.
+  await ensureAiToolScratchIgnored(tempDir, log);
   try {
     const gitStatusResult = await $({ cwd: tempDir })`git status --porcelain 2>&1`;
 
     if (gitStatusResult.code === 0) {
-      const statusOutput = gitStatusResult.stdout.toString().trim();
+      const statusOutput = filterAiToolScratchFromStatus(gitStatusResult.stdout.toString().trim());
 
       if (statusOutput) {
         await log('📝 Found uncommitted changes');

package/src/ai-tool-scratch.lib.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * Issue #2119: keep AI tools' own scratch state out of the solver's workspace
+ * bookkeeping.
+ *
+ * AI tools drop working files into the directory they are run in. Formal AI
+ * writes `.formal-ai/` (a `general-change-plan.lino` plan file and friends);
+ * Playwright MCP writes `.playwright-mcp/` (issue #1124). Neither belongs to the
+ * user's change, but `git status --porcelain` reports them all the same, so the
+ * solver read them as "the AI left uncommitted changes" and restarted the tool -
+ * every iteration, forever, because restarting recreates the same scratch dir:
+ *
+ *     🔍 Checking for uncommitted changes...
+ *     ?? .formal-ai/
+ *     📝 Found uncommitted changes
+ *     🔄 AUTO-RESTART: Restarting Agent to handle uncommitted changes...
+ *
+ * (docs/case-studies/issue-2119/data/logs/agent-scala-solution-draft.log:5425)
+ *
+ * The same state also reached `git add -A` on the auto-commit paths, which would
+ * have published a tool's private scratch files in the user's pull request.
+ *
+ * Every tool integration has its own `checkForUncommittedChanges`
+ * (claude/codex/agent/opencode/gemini/qwen/agent-commander), so filtering inside
+ * any one of them would fix one caller and leave the rest. Instead the paths are
+ * written to `.git/info/exclude`, which makes git itself stop reporting them:
+ * every status check, every `git add -A` and every diff agrees, without touching
+ * the repository's own `.gitignore` (that would show up in the pull request).
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Scratch paths AI tools create inside the workspace they are run in.
+ *
+ * Keep this list to directories a tool owns entirely. Anything a user might
+ * legitimately want committed must not be here.
+ */
+export const AI_TOOL_SCRATCH_PATHS = [
+  { path: '.formal-ai/', tool: 'formal-ai' },
+  { path: '.playwright-mcp/', tool: 'playwright-mcp' },
+];
+
+const EXCLUDE_HEADER = '# hive-mind: AI tool scratch directories (issue #2119)';
+
+/**
+ * Does this `git status --porcelain` line describe only AI tool scratch state?
+ *
+ * @param {string} statusLine - e.g. `?? .formal-ai/`
+ * @returns {boolean}
+ */
+export const isAiToolScratchPath = statusLine => {
+  if (typeof statusLine !== 'string') return false;
+  // Porcelain v1: two status characters, a space, then the path.
+  const filePath = statusLine.slice(3).trim().replace(/^"|"$/g, '');
+  if (!filePath) return false;
+  return AI_TOOL_SCRATCH_PATHS.some(({ path: scratchPath }) => {
+    const withoutSlash = scratchPath.replace(/\/$/, '');
+    return filePath === withoutSlash || filePath.startsWith(`${withoutSlash}/`);
+  });
+};
+
+/**
+ * Drop AI tool scratch entries from `git status --porcelain` output.
+ *
+ * A fallback for workspaces set up before `ensureAiToolScratchIgnored` ran (an
+ * existing clone, a resumed run), so a stale scratch directory cannot restart
+ * the restart loop.
+ *
+ * @param {string} statusOutput - raw `git status --porcelain` output
+ * @returns {string} the same output without scratch-only lines
+ */
+export const filterAiToolScratchFromStatus = statusOutput => {
+  if (!statusOutput) return '';
+  return statusOutput
+    .split('\n')
+    .filter(line => line.trim() && !isAiToolScratchPath(line))
+    .join('\n');
+};
+
+/**
+ * Teach a cloned workspace to ignore AI tool scratch directories.
+ *
+ * Writes to `.git/info/exclude` rather than `.gitignore`: the exclude file is
+ * local to the clone, is never staged, and therefore never appears in the pull
+ * request. Idempotent - re-running leaves the file unchanged.
+ *
+ * @param {string} tempDir - the cloned workspace
+ * @param {(msg: string, opts?: object) => Promise<void>} [log]
+ * @returns {Promise<{applied: boolean, reason?: string, added?: string[]}>}
+ */
+export const ensureAiToolScratchIgnored = async (tempDir, log = null) => {
+  const excludePath = path.join(tempDir, '.git', 'info', 'exclude');
+  const report = async msg => {
+    if (log) await log(msg, { verbose: true });
+  };
+
+  let existing = '';
+  try {
+    existing = await fs.readFile(excludePath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      await report(`⚠️  Could not read ${excludePath}: ${error.message}`);
+      return { applied: false, reason: 'unreadable' };
+    }
+    // A worktree or a fresh clone may not have the file yet; creating it is fine.
+  }
+
+  const existingLines = new Set(
+    existing
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+  );
+  const missing = AI_TOOL_SCRATCH_PATHS.map(entry => entry.path).filter(scratchPath => !existingLines.has(scratchPath));
+
+  if (missing.length === 0) {
+    return { applied: true, reason: 'already_present', added: [] };
+  }
+
+  const separator = existing && !existing.endsWith('\n') ? '\n' : '';
+  const block = existingLines.has(EXCLUDE_HEADER) ? `${missing.join('\n')}\n` : `${EXCLUDE_HEADER}\n${missing.join('\n')}\n`;
+
+  try {
+    await fs.mkdir(path.dirname(excludePath), { recursive: true });
+    await fs.writeFile(excludePath, `${existing}${separator}${block}`, 'utf8');
+  } catch (error) {
+    await report(`⚠️  Could not update ${excludePath}: ${error.message}`);
+    return { applied: false, reason: 'unwritable' };
+  }
+
+  await report(`🧹 Ignoring AI tool scratch directories in this workspace: ${missing.join(', ')}`);
+  return { applied: true, added: missing };
+};
+
+export default {
+  AI_TOOL_SCRATCH_PATHS,
+  ensureAiToolScratchIgnored,
+  filterAiToolScratchFromStatus,
+  isAiToolScratchPath,
+};