@librechat/agents 3.3.8 → 3.3.9

package/src/run.ts

@@ -1,4 +1,5 @@
 // src/run.ts
+import { nanoid } from 'nanoid';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
@@ -39,6 +40,12 @@ import {
   ACTIVITY_LABEL_PROMPT,
   buildActivityLabelPrompt,
 } from '@/prompts/activityLabel';
+import {
+  Callback,
+  GraphEvents,
+  TitleMethod,
+  DEFAULT_RECURSION_LIMIT,
+} from '@/common';
 import {
   appendCallbacks,
   findCallback,
@@ -49,16 +56,10 @@ import {
   createTitleRunnable,
 } from '@/utils/title';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
-import { resolveMaxSeals } from '@/llm/preempt';
 import { initializeLangfuseTracing } from './instrumentation';
-import {
-  Callback,
-  GraphEvents,
-  TitleMethod,
-  DEFAULT_RECURSION_LIMIT,
-} from '@/common';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
+import { resolveMaxSeals } from '@/llm/preempt';
 import { StandardGraph } from '@/graphs/Graph';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
@@ -828,6 +829,18 @@ export class Run<_T extends t.BaseGraphState> {
     const traceName = config.runName ?? getLangfuseTraceName(traceMetadata);
     const streamLangfuseConfig = this.getStreamLangfuseConfig(graph);
     initializeLangfuseTracing(streamLangfuseConfig);
+    const streamRuntimeScope = resolveLangfuseRuntimeScope({
+      runLangfuse: streamLangfuseConfig,
+      langfuseOverlay: this.getStreamToolOutputTracingLangfuseConfig(graph),
+      traceIdSeed:
+        streamLangfuseConfig?.deterministicTraceId === true
+          ? this.id
+          : undefined,
+      // The graph's per-execution stamp, NOT the public run id: public ids
+      // may repeat across concurrent executions (retries, tenant-local
+      // message ids), and equal stamps defeat foreign-scope rejection.
+      runId: graph.langfuseScopeRunId,
+    });
     const langfuseHandler = createLangfuseHandler({
       langfuse: streamLangfuseConfig,
       userId,
@@ -838,6 +851,12 @@ export class Run<_T extends t.BaseGraphState> {
         streamLangfuseConfig?.deterministicTraceId === true
           ? this.id
           : undefined,
+      runId: graph.langfuseScopeRunId,
+      // The aggregate multi-agent policy from the runtime scope — the
+      // handler must restore THIS (not the primary agent's config-derived
+      // policy) when rejecting a foreign scope.
+      toolOutputTracing: streamRuntimeScope.toolOutputTracing,
+      traceName,
     });
     if (langfuseHandler != null) {
       config.runName = traceName;
@@ -1057,27 +1076,18 @@ export class Run<_T extends t.BaseGraphState> {
       // When opted in, seed the root trace id from this run's id so feedback /
       // other external signals can be attached to the trace later without a
       // lookup (see SeededTraceIdGenerator in ./instrumentation).
-      await withLangfuseRuntimeScope(
-        resolveLangfuseRuntimeScope({
-          runLangfuse: streamLangfuseConfig,
-          langfuseOverlay: this.getStreamToolOutputTracingLangfuseConfig(graph),
-          traceIdSeed:
-            streamLangfuseConfig?.deterministicTraceId === true
-              ? this.id
-              : undefined,
-        }),
-        () =>
-          withLangfuseAttributes(
-            {
-              langfuse: streamLangfuseConfig,
-              userId,
-              sessionId,
-              traceName,
-              traceMetadata,
-              tags: ['librechat', 'agent'],
-            },
-            consumeStream
-          )
+      await withLangfuseRuntimeScope(streamRuntimeScope, () =>
+        withLangfuseAttributes(
+          {
+            langfuse: streamLangfuseConfig,
+            userId,
+            sessionId,
+            traceName,
+            traceMetadata,
+            tags: ['librechat', 'agent'],
+          },
+          consumeStream
+        )
       );
     } catch (err) {
       streamThrew = true;
@@ -1438,18 +1448,42 @@ export class Run<_T extends t.BaseGraphState> {
     titlePromptTemplate,
   }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {
     let titleLangfuseHandler: CallbackEntry | undefined;
-    let titleLangfuseConfig: t.LangfuseConfig | undefined;
     let titleUserId: string | undefined;
     let titleSessionId: string | undefined;
     const titleContext =
       this.Graph == null
         ? undefined
         : this.Graph.agentContexts.get(this.Graph.defaultAgentId);
+    const titleLangfuseConfig = resolveLangfuseConfig(
+      this.langfuse,
+      titleContext?.langfuse
+    );
     const traceMetadata = createLangfuseTraceMetadata({
       messageId: 'title-' + this.id,
       agentName: titleContext?.name,
     });
     const titleRunName = getLangfuseTraceName(traceMetadata, 'LibreChat Title');
+    /** Scope identity carries an opaque per-execution component: public run
+     *  ids are unrestricted, so a purely derived id (`title-<runId>`) could
+     *  collide with an ordinary concurrent run literally named that way and
+     *  defeat foreign-scope rejection. */
+    const titleScopeRunId = `title:${this.id}:${nanoid()}`;
+    /** Seed policy mirrors `generateActivityLabel`:
+     *  `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so an
+     *  absent seed INHERITS an active parent run's and collapses the title
+     *  into that run's trace. Seeded when determinism is opted into OR a
+     *  parent seed is live; otherwise unseeded, matching the other paths. */
+    const inheritedTraceSeed = getTraceIdSeed();
+    const titleRuntimeScope = resolveLangfuseRuntimeScope({
+      runLangfuse: this.langfuse,
+      langfuseOverlay: titleContext?.langfuse,
+      traceIdSeed:
+        titleLangfuseConfig?.deterministicTraceId === true ||
+        inheritedTraceSeed != null
+          ? 'title-' + this.id
+          : undefined,
+      runId: titleScopeRunId,
+    });
 
     if (chainOptions != null) {
       titleUserId =
@@ -1460,10 +1494,6 @@ export class Run<_T extends t.BaseGraphState> {
         typeof chainOptions.configurable?.thread_id === 'string'
           ? chainOptions.configurable.thread_id
           : undefined;
-      titleLangfuseConfig = resolveLangfuseConfig(
-        this.langfuse,
-        titleContext?.langfuse
-      );
       initializeLangfuseTracing(titleLangfuseConfig);
       titleLangfuseHandler = createLangfuseHandler({
         langfuse: titleLangfuseConfig,
@@ -1475,6 +1505,9 @@ export class Run<_T extends t.BaseGraphState> {
           titleLangfuseConfig?.deterministicTraceId === true
             ? 'title-' + this.id
             : undefined,
+        runId: titleScopeRunId,
+        toolOutputTracing: titleRuntimeScope.toolOutputTracing,
+        traceName: chainOptions.runName ?? titleRunName,
       });
 
       if (titleLangfuseHandler != null) {
@@ -1567,12 +1600,8 @@ export class Run<_T extends t.BaseGraphState> {
 
     try {
       try {
-        return await withLangfuseRuntimeScope(
-          resolveLangfuseRuntimeScope({
-            runLangfuse: this.langfuse,
-            langfuseOverlay: titleContext?.langfuse,
-          }),
-          () => invokeTitleChain(invokeConfig)
+        return await withLangfuseRuntimeScope(titleRuntimeScope, () =>
+          invokeTitleChain(invokeConfig)
         );
       } catch (_e) {
         // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments
@@ -1585,12 +1614,8 @@ export class Run<_T extends t.BaseGraphState> {
         const safeConfig = Object.assign({}, rest, {
           callbacks: langfuseHandler ? [langfuseHandler] : [],
         });
-        return await withLangfuseRuntimeScope(
-          resolveLangfuseRuntimeScope({
-            runLangfuse: this.langfuse,
-            langfuseOverlay: titleContext?.langfuse,
-          }),
-          () => invokeTitleChain(safeConfig as Partial<RunnableConfig>)
+        return await withLangfuseRuntimeScope(titleRuntimeScope, () =>
+          invokeTitleChain(safeConfig as Partial<RunnableConfig>)
         );
       }
     } finally {
@@ -1692,10 +1717,13 @@ export class Run<_T extends t.BaseGraphState> {
       inheritedTraceSeed != null
         ? (traceSeed ?? `activity-label-${this.id}-${labelSeq}`)
         : undefined;
+    /** Opaque per-execution component: see `titleScopeRunId`. */
+    const labelScopeRunId = `activity-label:${this.id}:${labelSeq}:${nanoid()}`;
     const labelRuntimeScope = resolveLangfuseRuntimeScope({
       runLangfuse: this.langfuse,
       langfuseOverlay: labelContext?.langfuse,
       traceIdSeed: labelTraceSeed,
+      runId: labelScopeRunId,
     });
     /** Handler only when a session id resolved from
      *  `chainOptions.configurable.thread_id`: without it the label call has
@@ -1716,6 +1744,9 @@ export class Run<_T extends t.BaseGraphState> {
           labelLangfuseConfig?.deterministicTraceId === true
             ? labelTraceSeed
             : undefined,
+        runId: labelScopeRunId,
+        toolOutputTracing: labelRuntimeScope.toolOutputTracing,
+        traceName: labelChainOptions.runName ?? labelRunName,
       });
     }
     if (labelLangfuseHandler != null) {

package/src/scripts/activity-labels/captured.json

@@ -0,0 +1,56 @@
+[
+  {
+    "id": "sandbox-python-version",
+    "traceId": "eeab6f47000fe2a6aac76cde6bbc67fd",
+    "prompt": "Reasoning excerpts:\n- I'll work through each check methodically, running them one at a time and documenting what I find.\n\nTool calls:\n- run_tools_with_bash({\"code\":\"python3 --version\"}) → stdout:\nPython 3.14.4\n\nLabel:",
+    "productionLabel": "Confirmed Python 3.14.4 is installed"
+  },
+  {
+    "id": "mnt-data-write-test",
+    "traceId": "8ee41468850d42e5477af07759519e84",
+    "prompt": "Intent (assistant's last message): **Python version: 3.14.4**\n\nNow let's check if files in /mnt/data survive between calls.\n\nTool calls:\n- bash_tool({\"command\":\"echo \\\"hello from probe 1, written at $(date)\\\" > /mnt/data/persist_test.txt; cat /mnt/data/persist_test.txt\"}) → stdout:\nhello from probe 1, written at Wed Jul 29 11:30:09 AM UTC 2026\n\nLabel:",
+    "productionLabel": "Wrote test file to /mnt/data, confirmed persistence"
+  },
+  {
+    "id": "mnt-data-persistence",
+    "traceId": "64b318bd7251b66baccd75009d947682",
+    "prompt": "Intent (assistant's last message): **Python version: 3.14.4**\n\nNow let's check if files in /mnt/data survive between calls.\n\nReasoning excerpts:\n- I should make a second request to verify the behavior persists across multiple calls.\n\nTool calls:\n- bash_tool({\"command\":\"ls -la /mnt/data/persist_test.txt && cat /mnt/data/persist_test.txt\"}) → stdout:\n-rw------- 1 65534 65534 63 Jul 29 11:30 /mnt/data/persist_test.txt\nhello from probe 1, written at Wed Jul 29 11:30:09 AM UTC 2026\n\nLabel:",
+    "productionLabel": "Confirmed /mnt/data persists between tool calls"
+  },
+  {
+    "id": "mnt-data-tmpfs",
+    "traceId": "bff7f9766cc2916230403a04c47c92af",
+    "prompt": "Intent (assistant's last message): **Files in /mnt/data DO survive between calls** — the file I wrote in the previous, separate sandbox invocation is still there with its original content intact.\n\nNow let's check RAM and disk.\n\nTool calls:\n- bash_tool({\"command\":\"echo \\\"=== MEMORY ===\\\"; free -h; echo; echo \\\"=== DISK ===\\\"; df -h /mnt/data / /tmp 2>/dev/null\"}) → stdout:\n=== MEMORY ===\n\n=== DISK ===\nFilesystem      Size  Used Avail Use% Mounted on\ntmpfs           1.0G   32K  1.0G   1% /mnt/data\nnone             16M     0   16M   0% /\nnone             20M     0   20M   0% /tmp\n\nstderr:\nfree: Unable to create meminfo structure\nNote: /tmp files are same-call scratch only and were not persisted; use /mnt/data for files needed later.\n\nLabel:",
+    "productionLabel": "Confirmed /mnt/data is tmpfs with 1GB capacity"
+  },
+  {
+    "id": "cpu-meminfo-disk",
+    "traceId": "6faf26136e125c29fe0bae7ddd87c59e",
+    "prompt": "Intent (assistant's last message): `free` failed, let me try /proc/meminfo directly — and note disk is quite constrained (tmpfs-based, tiny root/tmp).\n\nTool calls:\n- bash_tool({\"command\":\"echo \\\"=== /proc/meminfo ===\\\"; cat /proc/meminfo 2>/dev/null | head -5\\necho\\necho \\\"=== nproc ===\\\"; nproc\\necho\\necho \\\"=== /proc/cpuinfo count ===\\\"; grep -c ^processor /proc/cpuinfo 2>/dev/null\\necho\\necho \\\"=== disk full df ===\\\"; df -h 2>/dev/null\"}) → stdout:\n=== /proc/meminfo ===\n\n=== nproc ===\n1\n\n=== /proc/cpuinfo count ===\n0\n\n=== disk full df ===\nFilesystem      Size  Used Avail Use% Mounted on\nnone             16M     0   16M   0% /\n/dev/vdc         16G  4.4G   11G  30% /usr\nnone             16M  4.0K   16M   1% /etc/hosts\ntmpfs            64M     0   64M   0% /dev/null\nnone             20M     0   20M   0% /tmp\ntmpfs           1.0G   32K  1.0G   1% /mnt/data\n\nLabel:",
+    "productionLabel": "Confirmed single CPU, /proc/meminfo empty, disk constrained with 16M root and 20M tmp"
+  },
+  {
+    "id": "rlimit-cgroup",
+    "traceId": "2797232991aa7e841081a6b6175bd62b",
+    "prompt": "Intent (assistant's last message): `/proc/meminfo` is empty/restricted, but I can check cgroup limits for a real memory figure.\n\nTool calls:\n- bash_tool({\"command\":\"echo \\\"=== cgroup memory limit ===\\\"\\nfor f in /sys/fs/cgroup/memory.max /sys/fs/cgroup/memory/memory.limit_in_bytes; do\\n  [ -f \\\"$f\\\" ] && echo \\\"$f: $(cat $f)\\\"\\ndone\\necho\\necho \\\"=== cgroup cpu ===\\\"\\nfor f in /sys/fs/cgroup/cpu.max /sys/fs/cgroup/cpu/cpu.cfs_quota_us; do\\n  [ -f \\\"$f\\\" ] && echo \\\"$f: $(cat $f)\\\"\\ndone\\necho\\npython3 -c \\\"import resource; print('soft/hard RLIMIT_AS:', resource.getrlimit(resource.RLIMIT_AS))\\\" 2>/dev/null\"}) → stdout:\n=== cgroup memory limit ===\n\n=== cgroup cpu ===\n\nsoft/hard RLIMIT_AS: (17179869184, 17179869184)\n\nLabel:",
+    "productionLabel": "Found RLIMIT_AS ceiling at 16GB, cgroup limits unavailable"
+  },
+  {
+    "id": "network-tools",
+    "traceId": "e813a6ee932da05d573ced56424265b8",
+    "prompt": "Intent (assistant's last message): No cgroup files readable, but RLIMIT_AS shows a **16 GiB address-space limit** — likely the effective memory ceiling. Now let's check network access.\n\nTool calls:\n- bash_tool({\"command\":\"echo \\\"=== ping ===\\\"; timeout 3 ping -c1 8.8.8.8 2>&1\\necho\\necho \\\"=== curl ===\\\"; timeout 5 curl -sS -o /dev/null -w \\\"HTTP_CODE:%{http_code}\\\\n\\\" https://www.google.com 2>&1\\necho\\necho \\\"=== curl example.com ===\\\"; timeout 5 curl -sS -o /dev/null -w \\\"HTTP_CODE:%{http_code}\\\\n\\\" http://example.com 2>&1\\necho\\necho \\\"=== DNS resolution ===\\\"; timeout 3 getent hosts google.com 2>&1\"}) → stdout:\n=== ping ===\ntimeout: failed to run command ‘ping’: No such file or directory\n\n=== curl ===\ntimeout: failed to run command ‘curl’: No such file or directory\n\n=== curl example.com ===\ntimeout: failed to run command ‘curl’: No such file or directory\n\n=== DNS resolution ===\n\nLabel:",
+    "productionLabel": "Network tools unavailable, DNS resolution failed"
+  },
+  {
+    "id": "dns-tcp",
+    "traceId": "d96b49502c4a0ecb4c9325c2e74b43bf",
+    "prompt": "Intent (assistant's last message): No curl/ping binaries — let me test connectivity directly via Python sockets/urllib instead.\n\nTool calls:\n- bash_tool({\"command\":\"python3 - <<'EOF'\\nimport socket, urllib.request, time\\n\\n# DNS test\\ntry:\\n    ip = socket.gethostbyname(\\\"example.com\\\")\\n    print(\\\"DNS resolution OK:\\\", ip)\\nexcept Exception as e:\\n    print(\\\"DNS resolution FAILED:\\\", repr(e))\\n\\n# raw TCP connect test\\ntry:\\n    s = socket.create_connection((\\\"8.8.8.8\\\", 53), timeout=4)\\n    print(\\\"TCP connect to 8.8.8.8:53 OK\\\")\\n    s.close()\\nexcept Exception as e:\\n    print(\\\"TCP connect FAILED:\\\", repr(e))\\n\\n# HTTP fetch test\\ntry:\\n    t0 = time.time()\\n    r = urllib.request.urlopen(\\\"http://example.com\\\", timeout=5)\\n    print(\\…) → stdout:\nDNS resolution FAILED: gaierror(-2, 'Name or service not known')\nTCP connect FAILED: PermissionError(1, 'Operation not permitted')\nHTTP fetch FAILED: URLError(gaierror(-3, 'Temporary failure in name resolution'))\n\nLabel:",
+    "productionLabel": "DNS and TCP connectivity both blocked or unavailable"
+  },
+  {
+    "id": "python-packages",
+    "traceId": "a6fcd0fd40b490285ced22c236023e2c",
+    "prompt": "Intent (assistant's last message): **No network access** — DNS resolution fails and raw TCP connections are blocked with a permission error. This sandbox is fully network-isolated.\n\nNow let's check for numpy/pandas/scipy/torch.\n\nTool calls:\n- bash_tool({\"command\":\"python3 - <<'EOF'\\nmods = [\\\"numpy\\\", \\\"pandas\\\", \\\"scipy\\\", \\\"torch\\\"]\\nfor m in mods:\\n    try:\\n        mod = __import__(m)\\n        ver = getattr(mod, \\\"__version__\\\", \\\"unknown\\\")\\n        print(f\\\"{m}: INSTALLED, version {ver}\\\")\\n    except ImportError as e:\\n        print(f\\\"{m}: NOT INSTALLED ({e})\\\")\\nEOF\"}) → stdout:\nnumpy: INSTALLED, version 2.4.6\npandas: INSTALLED, version 2.3.3\nscipy: INSTALLED, version 1.18.0\ntorch: NOT INSTALLED (No module named 'torch')\n\nLabel:",
+    "productionLabel": "Confirmed numpy, pandas, scipy installed; torch unavailable"
+  }
+]

package/src/scripts/activity-labels/checks.cjs

@@ -0,0 +1,205 @@
+/**
+ * Mechanical label checks. These catch format violations and the two
+ * measurable prose failures (register collapse via first-word tallies,
+ * cross-batch redundancy via content-word overlap); commit-log READABILITY
+ * still needs the human pass over results/latest.md.
+ *
+ * Ported from LibreChat #14527 with two divergences, both backport
+ * candidates for LibreChat's scripts/activity-labels/checks.js: tool-echo
+ * matching normalizes namespaced MCP names (see the candidate-set comment
+ * below), and COUNT_ECHO also catches spelled-out counts.
+ */
+const STOPWORDS = new Set([
+  'the',
+  'a',
+  'an',
+  'to',
+  'of',
+  'and',
+  'or',
+  'with',
+  'for',
+  'in',
+  'on',
+  'at',
+  'is',
+  'are',
+  'was',
+  'were',
+  'be',
+  'been',
+  'it',
+  'its',
+  'as',
+  'by',
+  'from',
+  'that',
+  'this',
+  'both',
+  'all',
+  'no',
+  'not',
+  'via',
+]);
+
+function words(label) {
+  return label.trim().split(/\s+/).filter(Boolean);
+}
+
+const SUFFIXES = [
+  'ations',
+  'ation',
+  'ence',
+  'ance',
+  'ings',
+  'ing',
+  'ed',
+  'es',
+  's',
+];
+
+/** Crude suffix stemmer so persists/persistence/persisted collide — enough
+ *  for overlap detection; linguistic correctness is not the goal. */
+function stem(word) {
+  if (word.length < 5) {
+    return word;
+  }
+  for (const suffix of SUFFIXES) {
+    if (word.endsWith(suffix) && word.length - suffix.length >= 4) {
+      return word.slice(0, word.length - suffix.length);
+    }
+  }
+  return word;
+}
+
+function contentWords(label) {
+  return words(label.toLowerCase().replace(/[^a-z0-9/._-]+/g, ' '))
+    .filter((word) => !STOPWORDS.has(word))
+    .map(stem);
+}
+
+/** Payload tokens carry the informative delta between template-shaped
+ *  labels: numbers, versions, paths, filenames. */
+function isPayload(word) {
+  return /\d/.test(word) || word.includes('/') || word.includes('.');
+}
+
+function jaccard(a, b) {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  if (setA.size === 0 || setB.size === 0) {
+    return 0;
+  }
+  let intersection = 0;
+  for (const word of setA) {
+    if (setB.has(word)) {
+      intersection += 1;
+    }
+  }
+  return intersection / (setA.size + setB.size - intersection);
+}
+
+const GENERIC_OPENER = /^(ran|used|executed|called|invoked|performed)\b/i;
+/** Digits or the spelled-out counts a label-length line can fit — the
+ *  instruction forbids counting calls either way. */
+const COUNT_ECHO =
+  /\b(\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\s+(tools?|commands?|calls?)\b/i;
+const DUP_THRESHOLD = 0.5;
+
+/**
+ * @param label generated label text
+ * @param entries the batch's tool entries (for tool-name echo detection)
+ * @param previousLabels labels generated EARLIER in the same case chain,
+ *   regardless of whether the variant saw them — redundancy is measured
+ *   uniformly so continuity variants can be compared against blind ones.
+ */
+function checkLabel(label, { entries = [], previousLabels = [] } = {}) {
+  const flags = [];
+  const wordList = words(label);
+  if (wordList.length < 4 || wordList.length > 9) {
+    flags.push(`len:${wordList.length}`);
+  }
+  if (/[.!?,;:]$/.test(label.trim())) {
+    flags.push('punct');
+  }
+  if (/^["'`]|["'`]$/.test(label.trim())) {
+    flags.push('quote');
+  }
+  if (/[*`]|^#|\[.*\]\(/.test(label)) {
+    flags.push('md');
+  }
+  if (GENERIC_OPENER.test(label.trim())) {
+    flags.push('opener');
+  }
+  const lower = label.toLowerCase();
+  for (const entry of entries) {
+    const name = String(entry.toolName ?? '').toLowerCase();
+    if (name.length <= 3) {
+      continue;
+    }
+    /** Namespaced MCP names (`mcp__github__search_repositories`) would
+     *  otherwise normalize their double underscores to double spaces and
+     *  never match a natural echo; collapse separator runs and also try
+     *  the post-namespace tail ("search repositories"). Only multi-char
+     *  candidates derived from the full name — never single middle
+     *  segments like "github", which are legitimate label subjects. */
+    const segments = name.split('__');
+    const tail = segments[segments.length - 1];
+    const candidates = new Set([
+      name,
+      name.replace(/_+/g, ' '),
+      tail,
+      tail.replace(/_/g, ' '),
+    ]);
+    let echoed = false;
+    for (const candidate of candidates) {
+      if (candidate.length > 3 && lower.includes(candidate)) {
+        echoed = true;
+        break;
+      }
+    }
+    if (echoed) {
+      flags.push(`tool-echo:${entry.toolName}`);
+      break;
+    }
+  }
+  if (COUNT_ECHO.test(label)) {
+    flags.push('count-echo');
+  }
+  /** Overlap splits into two flags: `restate` (high overlap, no payload
+   *  delta — the line adds nothing over a previous header; the production
+   *  2/3 and 7/8 failure) and `template` (high overlap but the differing
+   *  tokens are numbers/paths — same sentence frame, new information, e.g.
+   *  fib(1)→fib(2). Often fine, arguably better than synonym churn). */
+  const own = contentWords(label);
+  let maxOverlap = 0;
+  let worst = null;
+  for (const previous of previousLabels) {
+    const other = contentWords(previous);
+    const overlap = jaccard(own, other);
+    if (overlap > maxOverlap) {
+      maxOverlap = overlap;
+      worst = other;
+    }
+  }
+  if (maxOverlap > DUP_THRESHOLD && worst != null) {
+    const otherSet = new Set(worst);
+    const ownSet = new Set(own);
+    const differing = [
+      ...own.filter((word) => !otherSet.has(word)),
+      ...worst.filter((word) => !ownSet.has(word)),
+    ];
+    const informativeDelta = differing.some(isPayload);
+    flags.push(
+      `${informativeDelta ? 'template' : 'restate'}:${maxOverlap.toFixed(2)}`
+    );
+  }
+  return {
+    flags,
+    wordCount: wordList.length,
+    firstWord: wordList[0] ?? '',
+    maxOverlap,
+  };
+}
+
+module.exports = { checkLabel, contentWords, jaccard, words, stem };