flint-agent 1.14.0

package/src/input-handler.js

@@ -0,0 +1,13 @@
+// Lock utility for serializing command execution (e.g. /paste, /auto, /new)
+// Message processing goes through bus drain loop (src/bus/drain-loop.js)
+import { app } from "./app-state.js";
+
+export function withLock(fn) {
+  const prev = app.lockChain;
+  let unlock;
+  app.lockChain = new Promise((r) => (unlock = r));
+  return prev.then(() => {
+    if (app.queueAborted) return;
+    return fn();
+  }).finally(unlock);
+}

package/src/input-text.js

@@ -0,0 +1,123 @@
+// What the operator sees must be what is sent.
+//
+// A pasted multi-line message looked cut and overwritten in the input box,
+// though the agent received it whole. Nothing was wrong with what was sent,
+// which is why it never showed up in a message log — the logs looked perfect.
+//
+// The cause is a character the terminal and the text disagree about. A paste
+// on Windows (and from some terminals) arrives with the line breaks as CRLF,
+// or as a bare CR. A terminal draws a CR as "back to column 0", so the next
+// line is written *over* the one before it:
+//
+//   paste: "line one\r\nline two\r\nline three"     30 chars, 2 CRs
+//   drawn: "\nline three"                            1 line, the rest gone
+//
+// So the operator sees one line and sends three. They fix it by retyping the
+// parts that appear to have vanished, which is the worst outcome: the
+// correction is guesswork, and what finally reaches the agent is the
+// retyped version, not what they pasted.
+//
+// The fix is here rather than in the component, because the disagreement is
+// about the text, not about the drawing: normalize the line endings once, at
+// the boundary, and everything downstream — the drawing, the cursor, the
+// submitted message — then works on the same string. Deliberately narrow: no
+// trimming, no rewrapping, no reflowing. A pasted diff, a stack trace or a
+// JSON blob must arrive exactly as it was pasted, or the agent is reasoning
+// about a document nobody sent.
+
+/**
+ * Does this text contain a CR that is not part of a CRLF pair?
+ *
+ * \r\n is an ordinary line ending and is left alone. A bare \r is not — it is
+ * a control character the terminal acts on, which is the whole bug.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasBareCR(text) {
+  if (!text) return false;
+  return /\r(?!\n)/.test(String(text));
+}
+
+/**
+ * The line endings a terminal cannot draw, turned into ones it can.
+ *
+ * CRLF first, then any remaining bare CR. Doing them in that order is what
+ * makes the result idempotent: after one pass there is no \r left at all, so
+ * a second pass is a no-op. That matters because the input normalizes on
+ * every keystroke.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeInputText(text) {
+  if (text === null || text === undefined) return "";
+  const s = String(text);
+  if (!s) return "";
+  if (!s.includes("\r")) return s;
+  return s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/**
+ * The text as the operator will see it in the input box.
+ *
+ * What the terminal would draw, given text a terminal can draw. Exported
+ * because "what does the operator see" is the question this whole module
+ * exists to answer, and it should be answerable in a test without rendering
+ * a terminal.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function displayTextFor(text) {
+  return expandTabs(normalizeInputText(text));
+}
+
+/**
+ * How many lines the operator can actually see, as opposed to how many the
+ * paste contained.
+ *
+ * Before the fix these two numbers differed, and the difference was the bug.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+export function visibleLineCount(text) {
+  const shown = displayTextFor(text);
+  return shown ? shown.split("\n").length : 0;
+}
+
+// The tab stop the input renders at. A tab in the input is a jump to the next
+// stop, so the operator sees a gap while the agent receives a 0x09; expanding
+// it shows the character and the gap as the same thing.
+const TAB_WIDTH = 4;
+
+/**
+ * Tabs as spaces, so what is drawn is what was typed.
+ *
+ * @param {string} text
+ * @param {number} [tabWidth]
+ * @returns {string}
+ */
+export function expandTabs(text, tabWidth = TAB_WIDTH) {
+  if (!text) return "";
+  const s = String(text);
+  if (!s.includes("\t")) return s;
+  let out = "";
+  for (const line of s.split("\n")) {
+    let col = 0;
+    for (const ch of line) {
+      if (ch === "\t") {
+        const pad = tabWidth - (col % tabWidth);
+        out += " ".repeat(pad);
+        col += pad;
+      } else {
+        out += ch;
+        col += 1;
+      }
+    }
+    out += "\n";
+  }
+  // split/join added a trailing newline that the input did not have.
+  return out.replace(/\n$/, "");
+}

package/src/launcher.js

@@ -0,0 +1,129 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+const userArgs = process.argv.slice(2);
+
+// --version answers and exits here too, not only in bin/flint.js: a host
+// that starts Flint with `npm start -- --version` or `node src/launcher.js
+// --version` got a console instead of a version (node integration test,
+// 2026-10-02).
+if (userArgs.includes("--version") || userArgs.includes("-v")) {
+  const { readFileSync } = await import("node:fs");
+  console.log(`flint ${JSON.parse(readFileSync(path.join(projectRoot, "package.json"), "utf8")).version}`);
+  process.exit(0);
+}
+
+const hasSessionArg = userArgs.some(a => a === "--last" || a === "--session" || a === "--list" || a === "--new");
+
+const RESTART_CODE = 42;
+
+// The session a restarting child asked to continue (src/restart.js). A
+// restart names its own session, so the operator's --new/--last/--session
+// from the first start are left out of the args then.
+let resumeSessionId = null;
+function withoutSessionArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--new" || args[i] === "--last") continue;
+    if (args[i] === "--session") { i++; continue; }
+    out.push(args[i]);
+  }
+  return out;
+}
+
+// The stdio mode (src/stdio) is driven by a program, not a person: no splash,
+// no spinner, and the agent runs in the folder it was started from, which is
+// the agent's own folder (its CLAUDE.md, .mcp.json and files).
+const stdioMode = userArgs.includes("--stdio") || userArgs.some((a, i) =>
+  (a === "--input-format" || a === "--output-format") && userArgs[i + 1] === "stream-json");
+
+// Clear screen + show the FLiNT mark (src/ui/splash.js) with a loading spinner
+// on its second row. Raw escapes, no chalk: the launcher loads nothing it can
+// avoid. Titanium is 256-colour 250, the spark yellow 220, grey 244.
+const _mark0 = " \x1b[38;5;250m▀▀▀ █   \x1b[38;5;220m▀\x1b[38;5;250m █▄ █ ▀█▀\x1b[0m";
+const _mark1 = " \x1b[38;5;250m█▀▀ █▄▄ █ █ ▀█  █\x1b[0m";
+const _frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+if (!stdioMode) process.stderr.write(`\x1b[2J\x1b[H\n${_mark0}\n${_mark1}   \x1b[38;5;244m${_frames[0]} loading...\x1b[0m`);
+let _fi = 0;
+let _released = false;
+const _spinner = setInterval(() => {
+  _fi = (_fi + 1) % _frames.length;
+  if (_released) return;
+  process.stderr.write(`\r${_mark1}   \x1b[38;5;244m${_frames[_fi]} loading...\x1b[0m`);
+}, 120);
+
+/**
+ * Hand the terminal over to the child.
+ *
+ * The spinner repaints with a bare `\r`, which the terminal reads as "back to
+ * column 0 of whatever line is current now". Once the child starts drawing,
+ * that is no longer the spinner's line: every tick reprints the FLINT AGENT
+ * banner on top of the child's own banner, and the startup banner with the
+ * first commands underneath it appears several times over.
+ *
+ * This used to be a fixed 500 ms after spawn, on the assumption that the child
+ * would be rendering by then. How long that takes depends on module load and on
+ * the machine, so a slow start got the spinner writing into a live UI, which is
+ * the reported glitch.
+ *
+ * The child is spawned with `stdio: "inherit"`, so it has no pipe handles to
+ * listen to: child.stdout and child.stderr are both null. An earlier attempt
+ * attached "release on first output" to those and did nothing at all, which
+ * would have left the spinner running forever while appearing to work. The
+ * streams stay inherited on purpose — piping them would cost Ink the TTY, and
+ * raw-mode key handling with it.
+ *
+ * So the child says when it has drawn, over an IPC channel that costs nothing
+ * and is invisible to the terminal. The interval is kept as a ceiling rather
+ * than removed: a child that dies without saying anything must not hold the
+ * event loop open, and `_released` makes the remaining ticks no-ops.
+ */
+function releaseTerminal() {
+  _released = true;
+  clearInterval(_spinner);
+}
+
+function start(extraArgs = []) {
+  const defaultArgs = (!hasSessionArg && extraArgs.length === 0 && !stdioMode) ? ["--new"] : [];
+  const baseArgs = extraArgs.length ? withoutSessionArgs(userArgs) : userArgs;
+  const args = [path.join(projectRoot, "src", "index.js"), ...baseArgs, ...defaultArgs, ...extraArgs];
+  const child = spawn(process.execPath, args, {
+    // The three standard streams stay inherited: piping them would cost Ink the
+    // TTY, and with it raw-mode key handling. The fourth slot is an IPC
+    // channel, which does not touch the terminal, and is how the child says
+    // "I have drawn" so the spinner stops repainting over it.
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
+    cwd: stdioMode ? process.cwd() : projectRoot,
+  });
+  if (stdioMode) releaseTerminal();
+
+  child.on("message", (msg) => {
+    if (msg && msg.type === "flint:ready") releaseTerminal();
+    if (msg && msg.type === "flint:restart" && typeof msg.sessionId === "string") resumeSessionId = msg.sessionId;
+  });
+
+  // `exit` always arrives, and it must stop the interval even if the child
+  // never said anything — otherwise it holds the event loop open.
+  child.on("exit", (code) => {
+    releaseTerminal();
+    if (code === RESTART_CODE && !stdioMode) {
+      // The same session when the child said which; a new one otherwise.
+      const id = resumeSessionId;
+      resumeSessionId = null;
+      start(id ? ["--session", id] : ["--new"]);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+  child.on("error", releaseTerminal);
+
+  // Forward Ctrl+C to child gracefully
+  process.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+}
+
+start();

package/src/logging/api-log.js

@@ -0,0 +1,95 @@
+import { appendFileSync } from "node:fs";
+import { config } from "../config.js";
+import path from "node:path";
+
+export function logApiCall(sessionId, callNum, messages, tools, reply, usage) {
+  if (!sessionId) return;
+  const file = path.join(config.sessionsDir, `${sessionId}.api.log`);
+  const ts = new Date().toISOString().slice(11, 19);
+
+  try {
+    if (messages) {
+      const sep = "=".repeat(60);
+      let totalChars = 0;
+      const lines = [];
+
+      for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        const contentLen = (m.content || "").length;
+        totalChars += contentLen;
+
+        let desc = `  [${i}] ${m.role}: ${contentLen} chars`;
+        if (m.role === "assistant" && m.tool_calls?.length) {
+          const toolNames = m.tool_calls.map((tc) => tc.function?.name || "?").join(", ");
+          desc += ` + tools=[${toolNames}]`;
+        }
+        if (m.role === "tool") {
+          const name = m._toolName || "?";
+          desc += ` (${name})`;
+          if (m._compressed) desc += ` [${m._compressed}]`;
+        }
+        lines.push(desc);
+      }
+
+      const toolCount = tools?.length || 0;
+      const header = [
+        `${sep}`,
+        `[${ts}] API Call #${callNum}`,
+        `${sep}`,
+        `Messages: ${messages.length} (${totalChars} chars total content)`,
+        `Tools: ${toolCount} definitions`,
+      ].join("\n");
+
+      appendFileSync(file, `${header}\n${lines.join("\n")}\n`);
+
+      // Full message dump: write complete content for prompt analysis
+      const rawFile = path.join(config.sessionsDir, `${sessionId}.messages.jsonl`);
+      try {
+        const entry = {
+          ts, callNum,
+          messages: messages.map(m => ({
+            role: m.role,
+            content: m.content || "",
+            tool_calls: m.tool_calls,
+            tool_call_id: m.tool_call_id,
+          })),
+          toolCount,
+        };
+        appendFileSync(rawFile, JSON.stringify(entry) + "\n");
+      } catch {}
+    }
+
+    if (reply) {
+      const contentLen = (reply.content || "").length;
+      const toolCalls = reply.tool_calls || [];
+      let toolDesc = "none";
+      if (toolCalls.length) {
+        toolDesc = toolCalls
+          .map((tc) => {
+            const name = tc.function?.name || "?";
+            let argsShort = "";
+            try {
+              const parsed = JSON.parse(tc.function?.arguments || "{}");
+              argsShort = Object.entries(parsed)
+                .map(([k, v]) => {
+                  const s = typeof v === "string" && v.length > 60 ? v.slice(0, 60) + "..." : String(v);
+                  return `${k}="${s}"`;
+                })
+                .join(", ");
+            } catch {}
+            return `${name}(${argsShort})`;
+          })
+          .join("; ");
+      }
+
+      const usageStr = usage
+        ? `prompt=${usage.prompt_tokens || 0} completion=${usage.completion_tokens || 0} total=${(usage.prompt_tokens || 0) + (usage.completion_tokens || 0)}`
+        : "n/a";
+
+      appendFileSync(
+        file,
+        `Response: ${contentLen} chars, tool_calls: ${toolDesc}\nUsage: ${usageStr}\n\n`,
+      );
+    }
+  } catch {}
+}

package/src/logging/chat-log-follower.js

@@ -0,0 +1,113 @@
+// The chat log must never stop writing, however long the session runs.
+//
+// Item 9: "chat.log silently stops after 1000 screen lines".
+//
+// The cause was a position tracked by array *length*. `addLine` caps the
+// on-screen `lines` array (src/store/ui-slice.js) at maxDisplayLines — 1000 by
+// default — by dropping the oldest entries. So the array stops growing once it
+// is full, and the subscriber decided what was new with:
+//
+//     if (lines.length > lastLineCount) {
+//       for (let i = lastLineCount; i < lines.length; i++) logChatLine(...);
+//       lastLineCount = lines.length;
+//     }
+//
+// At 1000 entries that condition is false forever. The log stops mid-session
+// and stays stopped: no error, no message, and the file on disk simply ends
+// where the screen filled up. Everything after that is lost — including the
+// lines you would most want, the turn where it went wrong.
+//
+// The store already stamps every line with a monotonic `id` (`nextLineId`).
+// That is the position which does not stop moving, and it is what this uses.
+//
+// The limit that cannot be engineered away: the log cannot be rebuilt from the
+// array, because the array no longer holds the lines. A follower can only
+// record what it saw as it went past. So this reports a gap when it starts
+// late rather than pretending to be complete — a follower that silently skips
+// what it missed is how this hid for so long.
+
+/**
+ * Follow the on-screen lines and write each new one to the chat log exactly
+ * once, for as long as the session runs.
+ *
+ * @param {object} deps
+ * @param {() => object} deps.getState
+ * @param {(fn: Function) => Function} deps.subscribe
+ * @param {(sessionId: string, text: string) => void} deps.log
+ * @returns {{start: Function, stop: Function, written: number}}
+ */
+export function createChatLogFollower({ getState, subscribe, log }) {
+  // The id of the last line written. Not the array length: the length stops
+  // moving at the cap, which is the entire bug.
+  let lastId = 0;
+  // clearScreen() resets nextLineId to 1, so ids restart. A single watermark
+  // would then read every later id as "already seen" and the log would die one
+  // screen in — the same silent failure, relocated. The generation counter is
+  // what makes the watermark per-page.
+  let generation = -1;
+  let unsubscribe = null;
+  let written = 0;
+
+  function currentGeneration(state) {
+    return state.clearCounter ?? 0;
+  }
+
+  function drain(state) {
+    const gen = currentGeneration(state);
+    if (gen !== generation) {
+      // A new page. Nothing is pending, and the id sequence restarts.
+      generation = gen;
+      lastId = 0;
+    }
+
+    // Log only what is newer than the watermark. Ids are not contiguous once
+    // the array has slid, so this is a comparison per line rather than a range.
+    for (const line of state.lines) {
+      if (line && typeof line.id === "number" && line.id > lastId) {
+        // A replayed line is already in this log (ui/replay.js).
+        if (!line.replay) {
+          log(state.sessionId ?? "", line.text);
+          written++;
+        }
+        lastId = line.id;
+      }
+    }
+  }
+
+  return {
+    /**
+     * Attach, and report anything that was already on screen.
+     *
+     * @returns {{skipped: number}} lines that existed before this ran
+     */
+    start() {
+      const state = getState();
+      generation = currentGeneration(state);
+      lastId = 0;
+
+      // Anything already on screen predates this follower. It cannot be
+      // logged honestly — it is not "skipped" by choice, it was never seen —
+      // so the count is returned rather than swallowed.
+      let skipped = 0;
+      for (const line of state.lines) {
+        if (line && typeof line.id === "number" && line.id > lastId) {
+          log(state.sessionId ?? "", line.text);
+          lastId = line.id;
+          written++;
+          skipped++;
+        }
+      }
+
+      unsubscribe = subscribe(() => drain(getState()));
+      return { skipped };
+    },
+
+    stop() {
+      if (unsubscribe) unsubscribe();
+      unsubscribe = null;
+    },
+
+    /** How many lines this follower has written. For tests and diagnostics. */
+    get written() { return written; },
+  };
+}

package/src/logging/chat-log.js

@@ -0,0 +1,15 @@
+import { appendFileSync } from "node:fs";
+import path from "node:path";
+import { config } from "../config.js";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+function stripAnsi(s) { return s.replace(ANSI_RE, ""); }
+
+export function logChatLine(sessionId, text) {
+  if (!sessionId) return;
+  const file = path.join(config.sessionsDir, `${sessionId}.chat.log`);
+  const ts = new Date().toISOString().slice(11, 19);
+  try {
+    appendFileSync(file, `[${ts}] ${stripAnsi(text)}\n`);
+  } catch {}
+}

package/src/logging/log-collector.js

@@ -0,0 +1,182 @@
+/**
+ * Log collector — background cleanup of old session files and stale registry entries.
+ *
+ * Runs once at startup (after a short delay) then periodically (default: every hour).
+ * Configurable via env:
+ *   AGENT_LOG_RETENTION_DAYS  — delete logs older than N days (default: 7)
+ *   AGENT_SESSION_RETENTION_DAYS — delete session JSONs older than N days (default: 30)
+ *   AGENT_CLEANUP_INTERVAL_MIN — interval in minutes (default: 60)
+ */
+
+import { readdirSync, statSync, unlinkSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { config } from "../config.js";
+import { createLogger } from "./logger.js";
+import { cleanup as busCleanupFn } from "../bus/index.js";
+
+const log = createLogger("collector");
+
+const LOG_RETENTION_DAYS = parseInt(process.env.AGENT_LOG_RETENTION_DAYS || "7", 10);
+const SESSION_RETENTION_DAYS = parseInt(process.env.AGENT_SESSION_RETENTION_DAYS || "30", 10);
+const CLEANUP_INTERVAL_MIN = parseInt(process.env.AGENT_CLEANUP_INTERVAL_MIN || "60", 10);
+
+// File extensions considered "log files" (shorter retention)
+const LOG_EXTENSIONS = new Set([".log"]);
+// Session data files (longer retention)
+const SESSION_EXTENSIONS = new Set([".json", ".hmac"]);
+
+function isExpired(filePath, retentionDays) {
+  try {
+    const stat = statSync(filePath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    return ageMs > retentionDays * 86400000;
+  } catch {
+    return false;
+  }
+}
+
+function getExtGroup(filename) {
+  // e.g. "2026-03-13T03-56-39.api.log" → ".log"
+  // e.g. "2026-03-13T03-56-39.json" → ".json"
+  const ext = path.extname(filename); // last extension
+  if (LOG_EXTENSIONS.has(ext)) return "log";
+  if (SESSION_EXTENSIONS.has(ext)) return "session";
+  return null;
+}
+
+function cleanDirectory(dir) {
+  if (!existsSync(dir)) return { logsRemoved: 0, sessionsRemoved: 0 };
+
+  let logsRemoved = 0;
+  let sessionsRemoved = 0;
+
+  try {
+    const files = readdirSync(dir);
+    for (const file of files) {
+      // Skip special files
+      if (file.startsWith(".")) continue;
+
+      const group = getExtGroup(file);
+      if (!group) continue;
+
+      const filePath = path.join(dir, file);
+      const retention = group === "log" ? LOG_RETENTION_DAYS : SESSION_RETENTION_DAYS;
+
+      if (isExpired(filePath, retention)) {
+        try {
+          unlinkSync(filePath);
+          if (group === "log") logsRemoved++;
+          else sessionsRemoved++;
+        } catch {}
+      }
+    }
+  } catch (err) {
+    log.warn("Failed to read directory for cleanup", { dir, error: err.message });
+  }
+
+  return { logsRemoved, sessionsRemoved };
+}
+
+async function cleanRegistry() {
+  const { homedir } = await import("node:os");
+  const { join } = await import("node:path");
+  const registryFile = join(homedir(), ".flint", "agents.json");
+
+  if (!existsSync(registryFile)) return 0;
+
+  try {
+    const data = JSON.parse(readFileSync(registryFile, "utf-8"));
+    if (!Array.isArray(data)) return 0;
+
+    const before = data.length;
+    const alive = data.filter((entry) => {
+      try {
+        // Check if process is still running
+        process.kill(entry.pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+    if (alive.length < before) {
+      writeFileSync(registryFile, JSON.stringify(alive, null, 2));
+    }
+
+    return before - alive.length;
+  } catch {
+    return 0;
+  }
+}
+
+function runCollector() {
+  log.debug("Log collector running");
+
+  // Clean main sessions directory
+  const main = cleanDirectory(config.sessionsDir);
+
+  // Clean children sessions directory
+  const childrenDir = path.join(config.projectRoot, "sessions", "children");
+  const children = cleanDirectory(childrenDir);
+
+  // Clean stale registry entries
+  const registryCleaned = cleanRegistry();
+
+  // Clean old bus messages
+  let busCleanup = { done: 0, failed: 0 };
+  try {
+    busCleanup = busCleanupFn();
+  } catch {}
+
+  const totalLogs = main.logsRemoved + children.logsRemoved;
+  const totalSessions = main.sessionsRemoved + children.sessionsRemoved;
+  const totalBus = busCleanup.done + busCleanup.failed;
+
+  if (totalLogs > 0 || totalSessions > 0 || registryCleaned > 0 || totalBus > 0) {
+    log.info("Cleanup complete", {
+      logsRemoved: totalLogs,
+      sessionsRemoved: totalSessions,
+      registryCleaned,
+      busMessagesRemoved: totalBus,
+    });
+  } else {
+    log.debug("Cleanup complete — nothing to remove");
+  }
+}
+
+let _interval = null;
+
+/**
+ * Start the background log collector.
+ * Runs immediately (after 5s delay), then every CLEANUP_INTERVAL_MIN minutes.
+ */
+export function startLogCollector() {
+  // Initial run after 5 seconds (let the app finish starting up)
+  const initialTimer = setTimeout(runCollector, 5000);
+  initialTimer.unref();
+
+  // Periodic run
+  _interval = setInterval(runCollector, CLEANUP_INTERVAL_MIN * 60000);
+  _interval.unref(); // Don't keep process alive just for cleanup
+
+  log.info("Log collector started", {
+    logRetentionDays: LOG_RETENTION_DAYS,
+    sessionRetentionDays: SESSION_RETENTION_DAYS,
+    intervalMin: CLEANUP_INTERVAL_MIN,
+  });
+}
+
+/**
+ * Stop the background log collector.
+ */
+export function stopLogCollector() {
+  if (_interval) {
+    clearInterval(_interval);
+    _interval = null;
+  }
+}
+
+/**
+ * Run collector once (for manual/command use).
+ */
+export { runCollector };