pi-lens 3.8.67 → 3.8.69

package/dist/clients/agent-nudge.js

@@ -0,0 +1,262 @@
+import { logLatency } from "./latency-logger.js";
+import { normalizeMapKey } from "./path-utils.js";
+const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
+const MAX_NAMES_SHOWN = 5;
+// Module-level accumulator: one process/session, so a plain map keyed via
+// normalizeMapKey (house style — every map/set key in this module MUST go
+// through it; a hand-rolled replace() is the exact trap that cost two red CI
+// rounds on #458's reconcile tests, PR #491) is sufficient. Cleared ONLY
+// inside consumeAgentNudge() (i.e. only at actual injection into a `context`
+// call) — deliberately NOT tied to turn_start/agent_end/agent_settled, so
+// entries accumulated during run A's turn_end survive until run B's first
+// `context` call in the same session (the cross-run `git status` case).
+const _touched = new Map();
+// Count of bus-reported paths dropped by the relevance filter (file never
+// read/edited this session) since the last consume — drained alongside the
+// accumulator so the `agent_nudge` phase can report how much the filter
+// actually suppresses, which is the metric that validates (or indicts) the
+// "only nudge for files the session saw" rule.
+let _relevanceFilteredCount = 0;
+/** Test-only: clear accumulator state between test files/cases. */
+export function _resetAgentNudgeForTests() {
+    _touched.clear();
+    _relevanceFilteredCount = 0;
+    _enabledCache = undefined;
+}
+// --- Kill switch (lazy, memoized — house style per clients/quiet-window.ts) ---
+let _enabledCache;
+/** `PI_LENS_AGENT_NUDGE=0` disables accumulation and injection outright. */
+export function isAgentNudgeEnabled() {
+    if (_enabledCache === undefined) {
+        _enabledCache = process.env.PI_LENS_AGENT_NUDGE !== "0";
+    }
+    return _enabledCache;
+}
+function isValidPayload(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const p = data;
+    return (p.v === 1 &&
+        p.source === "pi-lens" &&
+        (p.reason === "autofix" || p.reason === "format") &&
+        Array.isArray(p.paths));
+}
+/**
+ * Record a `pilens:files:touched` event into the accumulator, filtered to
+ * files the session has actually read or edited (read-guard is the source of
+ * truth — `getReadHistory`/`getEditHistory` both key internally via
+ * `normalizeFilePath`, so either separator form on the incoming bus payload
+ * or the guard's stored records resolves to the same record regardless of
+ * which form was recorded first).
+ */
+function recordTouchedEvent(payload, getReadGuard) {
+    const readGuard = getReadGuard();
+    if (!readGuard)
+        return;
+    for (const rawPath of payload.paths) {
+        const isRelevant = readGuard.getReadHistory(rawPath).length > 0 ||
+            readGuard.getEditHistory(rawPath).length > 0;
+        if (!isRelevant) {
+            _relevanceFilteredCount++;
+            continue;
+        }
+        const mapKey = normalizeMapKey(rawPath);
+        const existing = _touched.get(mapKey);
+        if (existing) {
+            existing.reasons.add(payload.reason);
+            // "local" is sticky — see AccumulatedFileOrigin doc. A file already
+            // recorded via the cross-process feed, now also reported by this
+            // session's own bus, upgrades to "local".
+            existing.origin = "local";
+        }
+        else {
+            _touched.set(mapKey, {
+                displayPath: rawPath,
+                reasons: new Set([payload.reason]),
+                origin: "local",
+            });
+        }
+    }
+}
+/**
+ * Feed entries read from the cross-process `recent-touches.json` record
+ * (#492, clients/recent-touches.ts) into the SAME accumulator #485 uses for
+ * in-process bus events — one accumulator, one `consumeAgentNudge` call, one
+ * batched context message regardless of how many files came from which
+ * channel.
+ *
+ * Relevance filtering differs by call site (#492 point 6) and is therefore
+ * the CALLER's responsibility, not this function's:
+ *   - parent at turn_start: read-guard history FIRST (a parent usually has
+ *     one), falling back to recency-only for files it hasn't read (a parent
+ *     about to `git commit` needs attribution even for unread files);
+ *   - child at session_start: recency + file-existence only (no read
+ *     history exists yet this early).
+ * `readCrossProcessTouchesForTurnStart` / `...ForSessionStart` in
+ * recent-touches.ts already apply their own recency/existence/self-pid
+ * filtering before entries reach here — this function does not re-derive
+ * relevance, it only merges into the accumulator and marks provenance.
+ *
+ * Self-exclusion (an entry this process itself published never nudges
+ * itself) and path+ts dedup across repeated reads of the record are both
+ * handled upstream in recent-touches.ts (pid filter + last-consumed cursor),
+ * so entries reaching this function are already the "new, foreign" set.
+ */
+export function recordCrossProcessTouches(entries) {
+    if (!isAgentNudgeEnabled())
+        return;
+    for (const entry of entries) {
+        const mapKey = normalizeMapKey(entry.path);
+        const existing = _touched.get(mapKey);
+        if (existing) {
+            existing.reasons.add(entry.reason);
+            // "local" is sticky (see AccumulatedFileOrigin) — never downgrade an
+            // already-local entry back to cross-process.
+        }
+        else {
+            _touched.set(mapKey, {
+                displayPath: entry.path,
+                reasons: new Set([entry.reason]),
+                origin: "cross-process",
+            });
+        }
+    }
+}
+/**
+ * Subscribe to `pilens:files:touched` on pi's shared event bus. Called once
+ * at extension factory time from index.ts, mirroring `wireBusEmitter`'s
+ * placement (clients/bus-publish.ts). No-ops silently when `pi.events` or
+ * `.on` is unavailable (older pi host) — never throws.
+ */
+export function wireAgentNudgeSubscriber(args) {
+    const { events, getReadGuard, dbg } = args;
+    if (!events?.on)
+        return;
+    try {
+        events.on(BUS_FILES_TOUCHED_EVENT, (data) => {
+            if (!isAgentNudgeEnabled())
+                return;
+            if (!isValidPayload(data))
+                return;
+            try {
+                recordTouchedEvent(data, getReadGuard);
+            }
+            catch (err) {
+                dbg?.(`agent-nudge: failed to record touched event: ${err}`);
+            }
+        });
+    }
+    catch (err) {
+        dbg?.(`agent-nudge: subscribe failed (older pi host?): ${err}`);
+    }
+}
+/**
+ * Consume the accumulated touched-file set and produce (at most) one context
+ * message, e.g.:
+ *   "pi-lens: 2 file(s) were autoformatted after your last turn: a.ts, b.ts —
+ *    working-tree changes to these are expected; re-read before editing."
+ * The provenance framing ("pi-lens ... expected") matters: the primary pain
+ * case is an agent running `git status` (often at the START of a brand-new
+ * run/session, not just mid-run) and burning turns investigating diffs it
+ * did not knowingly make. Naming pi-lens as the source lets the agent act
+ * (re-read, proceed) instead of investigating.
+ *
+ * #492: attribution is three-way by the batch's origin mix (see
+ * AccumulatedFileOrigin) — still ONE message total (never split local vs.
+ * cross-process into two separate injections; the agent gets one coherent
+ * picture of everything unexplained in the working tree), but the wording
+ * must never assign a LOCAL file to another instance:
+ *   - all local         → "after your last turn" (the original #485 wording,
+ *                         unchanged — verified by the pre-existing #485
+ *                         tests);
+ *   - all cross-process → "by another pi-lens instance (e.g. a subagent's)";
+ *   - mixed             → "after your last turn (N of them by another
+ *                         pi-lens instance)" — the base framing stays local
+ *                         and the cross-process portion is counted out
+ *                         precisely, so no local file is ever misattributed
+ *                         to another instance.
+ *
+ * Clears the accumulator ONLY here, on actual injection — never on
+ * agent_end/agent_settled/turn_start. Files formatted at the last turn_end of
+ * a PREVIOUS run must still nudge at the first turn of the NEXT run in the
+ * same session: this function is invoked from the `context` extension event
+ * (index.ts), which fires before every provider/LLM call — including the
+ * very first call of a fresh `agent_start` — so the accumulator surviving
+ * across run boundaries is exactly what makes that cross-run delivery work.
+ * Empty accumulator ⇒ returns undefined ⇒ zero bytes injected.
+ */
+export function consumeAgentNudge(dbg) {
+    const entries = Array.from(_touched.values());
+    _touched.clear();
+    const filesFiltered = _relevanceFilteredCount;
+    _relevanceFilteredCount = 0;
+    if (!isAgentNudgeEnabled())
+        return undefined;
+    if (entries.length === 0)
+        return undefined;
+    try {
+        const filesTotal = entries.length;
+        const shown = entries.slice(0, MAX_NAMES_SHOWN);
+        const remaining = filesTotal - shown.length;
+        // Determine a single verb covering every reason seen across all
+        // accumulated files (not just the shown subset) — most turns will have
+        // a single uniform reason, so keep that common case terse; a mix of
+        // autofix + format across the batch falls back to a combined verb.
+        const allReasons = new Set();
+        for (const e of entries) {
+            for (const r of e.reasons)
+                allReasons.add(r);
+        }
+        const verbLabel = allReasons.size > 1
+            ? "autofixed/reformatted"
+            : allReasons.has("format")
+                ? "reformatted"
+                : "autofixed";
+        const names = shown.map((e) => e.displayPath);
+        const nameList = remaining > 0
+            ? `${names.join(", ")}, and ${remaining} more`
+            : names.join(", ");
+        const crossProcessCount = entries.filter((e) => e.origin === "cross-process").length;
+        const localCount = filesTotal - crossProcessCount;
+        // Three-way attribution (see the function doc): never assign a local
+        // file to another instance — a mixed batch keeps the local base framing
+        // and calls out the cross-process portion by exact count.
+        const attribution = localCount === 0
+            ? "by another pi-lens instance (e.g. a subagent's)"
+            : crossProcessCount === 0
+                ? "after your last turn"
+                : `after your last turn (${crossProcessCount} of them by another pi-lens instance)`;
+        const message = `pi-lens: ${filesTotal} file(s) were ${verbLabel} ${attribution}: ${nameList} — working-tree changes to these are expected; re-read before editing.`;
+        logLatency({
+            type: "phase",
+            filePath: "<pi-lens>",
+            phase: "agent_nudge",
+            durationMs: 0,
+            metadata: {
+                filesTotal,
+                filesShown: shown.length,
+                // Relevance-filter drops since the last consume (files the session
+                // never read/edited) — NOT the display overflow, which is
+                // filesTotal - filesShown.
+                filesFiltered,
+                reasonMix: Array.from(allReasons),
+                // #492: origin mix so cross-process pickup rate is observable
+                // alongside the existing relevance-filter metric.
+                originLocal: localCount,
+                originCrossProcess: crossProcessCount,
+            },
+        });
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: `[pi-lens automated context — not a user request] ${message}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        dbg?.(`agent-nudge: consume failed: ${err}`);
+        return undefined;
+    }
+}

package/dist/clients/biome-client.js

@@ -8,9 +8,9 @@
  * Docs: https://biomejs.dev/
  */
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
+import { getGlobalPiLensDir } from "./file-utils.js";
 import { findGlobalBinary } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 // --- Client ---
@@ -56,7 +56,7 @@ export class BiomeClient {
         // the tool is already installed but not in the project's node_modules.
         // On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
         const isWin = process.platform === "win32";
-        const piLensBin = path.join(os.homedir(), ".pi-lens", "tools", "node_modules", ".bin");
+        const piLensBin = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin");
         const candidates = isWin
             ? [
                 path.join(resolveCwd, "node_modules", ".bin", "biome.cmd"),

package/dist/clients/bus-publish.js

@@ -0,0 +1,110 @@
+/**
+ * Publishes `pilens:files:touched` on pi's shared `pi.events` bus (#482).
+ *
+ * This is pi-lens's FIRST `pi.events` broadcast surface: it exists so other
+ * extensions in the same session can observe files pi-lens writes
+ * autonomously (autofix/format runners) without reverse-engineering us —
+ * writes the agent makes itself via its own tool calls are NOT ours to
+ * broadcast; the host already knows about those (see the seam audit in
+ * AGENTS.md / issue #482).
+ *
+ * Versioning policy: the payload is frozen-additive. New optional fields may
+ * be added under the same `v: 1`; a breaking/incompatible change to an
+ * existing field's meaning must bump `v`.
+ *
+ * Fire-and-forget: publishing must never affect the write path's success or
+ * latency. Any failure (bus unavailable, emit throws) is swallowed; a `dbg`
+ * callback is invoked at most once on first failure so a wired caller can log
+ * it without spamming.
+ */
+import { normalizeFilePath } from "./path-utils.js";
+import { appendRecentTouches } from "./recent-touches.js";
+export const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
+export const BUS_FILES_TOUCHED_VERSION = 1;
+let busEmit;
+let hasLoggedFailure = false;
+/**
+ * Wire the emit function from pi's `pi.events` bus. Called once at extension
+ * factory time from index.ts (module-level singleton, same pattern as
+ * `initLensEvents`). Never called ⇒ `publishFilesTouched` no-ops, which is
+ * exactly the state unit tests and the MCP server path run in (no pi host,
+ * no `pi.events`).
+ */
+export function wireBusEmitter(emitFn) {
+    busEmit = emitFn;
+}
+/** Test-only: reset module state between test files. */
+export function _resetForTests() {
+    busEmit = undefined;
+    hasLoggedFailure = false;
+    _envCache = undefined;
+}
+let _envCache;
+/**
+ * Lazy env read (house style) so tests can flip `PI_LENS_BUS_PUBLISH` at
+ * runtime via `_resetForTests` + re-set the env var. Kill switch: set to `0`
+ * to disable publishing outright.
+ */
+export function isBusPublishEnabled() {
+    if (_envCache === undefined) {
+        _envCache = process.env.PI_LENS_BUS_PUBLISH !== "0";
+    }
+    return _envCache;
+}
+/**
+ * Publish one `pilens:files:touched` event for a logical write batch (one
+ * event per call site invocation, not per file). Fire-and-forget: never
+ * throws, never awaited by the caller's write path.
+ *
+ * #492: this is also the producer seam for the cross-process
+ * `recent-touches.json` record (clients/recent-touches.ts) — parent and
+ * child pi processes run this exact function, so appending here (rather
+ * than at each of the several `publishFilesTouched` call sites) guarantees
+ * every future call site gets cross-process propagation for free. The
+ * append is independent of `busEmit` being wired (a bare/MCP/test host with
+ * no `pi.events` still gets a cross-process record — the in-process bus and
+ * the on-disk record are two separate deliveries of the same payload, and
+ * the record is the ONLY one of the two that survives a process boundary).
+ * Fire-and-forget, same as the bus emit: never awaited, failures swallowed
+ * and dbg-logged (never break the publish path).
+ */
+export function publishFilesTouched(args) {
+    if (args.origin === "bus")
+        return;
+    if (args.paths.length === 0)
+        return;
+    if (!isBusPublishEnabled())
+        return;
+    void appendRecentTouches({
+        cwd: args.cwd,
+        reason: args.reason,
+        paths: args.paths,
+        sessionId: args.sessionId,
+    }).catch((err) => {
+        args.dbg?.(`bus-publish: recent-touches append failed: ${err}`);
+    });
+    if (!busEmit)
+        return;
+    try {
+        const payload = {
+            v: BUS_FILES_TOUCHED_VERSION,
+            source: "pi-lens",
+            reason: args.reason,
+            paths: args.paths.map((p) => normalizeFilePath(p)),
+            cwd: normalizeFilePath(args.cwd),
+        };
+        if (args.fixes && args.fixes.length > 0) {
+            payload.fixes = args.fixes.map((f) => ({
+                ...f,
+                path: normalizeFilePath(f.path),
+            }));
+        }
+        busEmit(BUS_FILES_TOUCHED_EVENT, payload);
+    }
+    catch (err) {
+        if (!hasLoggedFailure) {
+            hasLoggedFailure = true;
+            args.dbg?.(`bus-publish: pilens:files:touched emit failed (further failures suppressed): ${err}`);
+        }
+    }
+}

package/dist/clients/deps/ast-grep-napi.js

@@ -1,3 +1,22 @@
+/**
+ * Centralized LAZY accessor for `@ast-grep/napi` (a native addon — loaded on
+ * demand, never at module-eval). See ./typescript.ts for the rationale.
+ * Types are re-exported; the module itself is fetched via `loadAstGrepNapi()`.
+ *
+ * Resolved to an absolute `file://` URL via `createRequire` before importing: an
+ * absolute-path dynamic import works under pi's bundled host, a bare specifier
+ * does not. The path is converted to a `file://` URL (a raw Windows path is not
+ * a valid import specifier); bare import kept as a fallback.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const _require = createRequire(import.meta.url);
 export function loadAstGrepNapi() {
-    return import("@ast-grep/napi");
+    try {
+        const entry = _require.resolve("@ast-grep/napi");
+        return import(pathToFileURL(entry).href);
+    }
+    catch {
+        return import("@ast-grep/napi");
+    }
 }

package/dist/clients/deps/pi-tui.js

@@ -1,5 +1,8 @@
 /**
  * Centralized accessor for `@earendil-works/pi-tui`. See ./typescript.ts for the
  * rationale. (pi-tui is a pi-bundled core package, host-provided at runtime.)
+ *
+ * Re-export named bindings, not `export *`: with the package kept external, a
+ * wildcard re-export leaves the namespace undefined at runtime under the bundle.
  */
-export * from "@earendil-works/pi-tui";
+export { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";

package/dist/clients/deps/typebox.js

@@ -1,6 +1,9 @@
 /**
  * Centralized accessor for `typebox`. See ./typescript.ts for the rationale.
  * (typebox is a pi-bundled core package, so it resolves from the host at
- * runtime — but it's still routed through here for a uniform dep surface.)
+ * runtime -- but it's still routed through here for a uniform dep surface.)
+ *
+ * Re-export named bindings, not `export *`: with the package kept external, a
+ * wildcard re-export leaves the namespace undefined at runtime under the bundle.
  */
-export * from "typebox";
+export { Type } from "typebox";

package/dist/clients/deps/web-tree-sitter.js

@@ -1,3 +1,24 @@
+/**
+ * Centralized LAZY accessor for `web-tree-sitter` (wasm — loaded on demand). See
+ * ./typescript.ts for the rationale. Types are re-exported; the module itself is
+ * fetched via `loadWebTreeSitter()`.
+ *
+ * Resolved to an absolute `file://` URL via `createRequire` before importing: an
+ * absolute-path dynamic import works under pi's bundled host, a bare specifier
+ * does not. The package `exports` map exposes only the `.` entry (no custom
+ * subpath), so we resolve the bare package name and convert it to a `file://`
+ * URL (a raw Windows path is not a valid import specifier); bare import kept as
+ * a fallback.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const _require = createRequire(import.meta.url);
 export function loadWebTreeSitter() {
-    return import("web-tree-sitter");
+    try {
+        const entry = _require.resolve("web-tree-sitter");
+        return import(pathToFileURL(entry).href);
+    }
+    catch {
+        return import("web-tree-sitter");
+    }
 }

package/dist/clients/diagnostic-logger.js

@@ -3,12 +3,12 @@
  *
  * Log file: ~/.pi-lens/logs/{date}.jsonl
  */
-import * as os from "node:os";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
+import { getGlobalPiLensDir } from "./file-utils.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
 function getLogDir() {
-    return path.join(os.homedir(), ".pi-lens", "logs");
+    return path.join(getGlobalPiLensDir(), "logs");
 }
 function getLogFile() {
     const date = new Date().toISOString().split("T")[0];

package/dist/clients/diagnostics-publish.js

@@ -0,0 +1,180 @@
+/**
+ * Publishes `pilens:diagnostics` on pi's shared `pi.events` bus (#502).
+ *
+ * Sibling to `clients/bus-publish.ts` (the #482 `pilens:files:touched`
+ * producer) rather than a new export crammed into that file: the two events
+ * share the emit plumbing (`wireBusEmitter`) and the `PI_LENS_BUS_PUBLISH`
+ * kill switch, but this producer owns its OWN piece of module state (the
+ * previously-reported-paths set for clean-transition tracking, the seq
+ * counter) that has nothing to do with files-touched.
+ *
+ * ## CONSUMER CONTRACT — staleness / replace semantics (2026-07-11 design, #502)
+ *
+ * Diagnostics are STATE; bus events are point-in-time snapshots of a slice of
+ * that state. To guarantee a consumer can always reconstruct the latest
+ * known picture from the event stream alone, this producer follows LSP
+ * `publishDiagnostics` semantics:
+ *
+ * 1. **Full-replace per file, never a delta.** Every event carries the
+ *    COMPLETE current diagnostic set for each file it mentions. An event
+ *    mentioning path P replaces everything a consumer previously held for P
+ *    — never merge/append across events for the same path.
+ * 2. **Empty array = explicitly clean.** When a previously-reported file's
+ *    diagnostics clear, this producer emits `{path, diagnostics: []}` for it
+ *    exactly once, on the transition. Silence never means clean (the #240
+ *    doctrine, applied here on the producer side) — a consumer that stops
+ *    hearing about a path has learned NOTHING about its current state.
+ * 3. **Monotonic `seq` + `ts` per emission.** `seq` increments once per
+ *    `publishDiagnostics` call (module-level counter, process-lifetime
+ *    monotonic — never reset except in tests). Out-of-order receipt resolves
+ *    deterministically: higher `seq` always wins, lower is discarded.
+ * 4. **`pilens:files:touched` (#482) is an INVALIDATION HINT, not new data.**
+ *    Between an edit landing (a files:touched event) and the next
+ *    diagnostics batch for that path, a consumer's previously-held
+ *    diagnostics for that path are PROVISIONAL — the file has changed on
+ *    disk but pi-lens hasn't re-analyzed it yet. Consumers that want to
+ *    avoid rendering stale annotations across that window should treat a
+ *    files:touched path as "diagnostics pending" until the next
+ *    pilens:diagnostics event mentions it (at any seq).
+ *
+ * Late-joiners are a non-problem in-process: extensions activate at
+ * `session_start`, before any turn emits, so v1 is push-only (no
+ * request/replay). #478's future `pilens:rpc:diagnostics` pull API reuses
+ * this exact `PilensDiagnosticsPayload` shape verbatim — push and pull are
+ * two deliveries of the same schema over the same lens-engine seam; #478
+ * stays separately gated on #449 registry dogfooding.
+ *
+ * ## Emission seam
+ *
+ * `publishDiagnostics` is called once per write batch immediately after
+ * `recordDiagnostics` (clients/widget-state.ts) commits the FINAL per-file
+ * diagnostic set for that batch — i.e. after format, autofix, and dispatch
+ * have all run (see pipeline.ts's phase order). This guarantees the emitted
+ * event reflects post-batch latest state, not an intermediate runner result:
+ * widget-state's `allDiagnostics` store is exactly what `recordDiagnostics`
+ * just wrote, so reading it back at the same call site can't race a later
+ * write in the same batch.
+ *
+ * Versioning policy: frozen-additive, same discipline as #482. New optional
+ * fields may be added under `v: 1`; a breaking change to an existing field's
+ * meaning must bump `v`.
+ */
+import { normalizeFilePath } from "./path-utils.js";
+import { isBusPublishEnabled } from "./bus-publish.js";
+export const BUS_DIAGNOSTICS_EVENT = "pilens:diagnostics";
+export const BUS_DIAGNOSTICS_VERSION = 1;
+/** Max diagnostics carried per file per event — aligned with the widget's own per-file storage cap (`MAX_STORED_DIAGNOSTICS_PER_FILE`, clients/widget-state.ts). */
+export const MAX_DIAGNOSTICS_PER_FILE_EVENT = 12;
+let busEmit;
+let hasLoggedFailure = false;
+let seqCounter = 0;
+/** Paths this producer has reported with at least one non-empty diagnostics array, so we know when to fire the one-time clean-transition event. */
+const reportedDirtyPaths = new Set();
+/**
+ * Wire the emit function from pi's `pi.events` bus. Called once at extension
+ * factory time from index.ts, same call as `wireBusEmitter` (#482) — both
+ * producers share the identical `pi.events.emit` binding.
+ */
+export function wireDiagnosticsBusEmitter(emitFn) {
+    busEmit = emitFn;
+}
+/** Test-only: reset module state between test files. */
+export function _resetDiagnosticsPublishForTests() {
+    busEmit = undefined;
+    hasLoggedFailure = false;
+    seqCounter = 0;
+    reportedDirtyPaths.clear();
+}
+function capDiagnostics(diagnostics) {
+    if (diagnostics.length <= MAX_DIAGNOSTICS_PER_FILE_EVENT) {
+        return { capped: diagnostics, truncated: false };
+    }
+    // Prioritize errors first (same "blockers first" spirit as the widget cap).
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    const rest = diagnostics.filter((d) => d.severity !== "error");
+    if (errors.length >= MAX_DIAGNOSTICS_PER_FILE_EVENT) {
+        return {
+            capped: errors.slice(0, MAX_DIAGNOSTICS_PER_FILE_EVENT),
+            truncated: true,
+        };
+    }
+    return {
+        capped: [
+            ...errors,
+            ...rest.slice(0, MAX_DIAGNOSTICS_PER_FILE_EVENT - errors.length),
+        ],
+        truncated: true,
+    };
+}
+/**
+ * Publish one `pilens:diagnostics` event for a write batch's final
+ * per-file diagnostic state. Fire-and-forget: never throws, never awaited.
+ *
+ * Full-replace semantics (see module doc): each `files` entry here is
+ * treated as the COMPLETE current set for that path. Additionally, for
+ * every path in `reportedDirtyPaths` that is NOT present in this call's
+ * `files` list but has gone clean via a prior call in THIS same invocation,
+ * callers must pass an explicit `{path, diagnostics: []}` entry — this
+ * function does not infer clean transitions for paths it isn't told about.
+ * The one caller (the pipeline write-batch seam) always passes the
+ * single file it just analyzed, so the common clean-transition path is:
+ * dispatch returns zero diagnostics for a file this producer previously
+ * reported dirty -> caller passes `{path, diagnostics: []}` -> emitted once,
+ * `reportedDirtyPaths` drops the path so a SECOND clean run of the same file
+ * does not re-emit (still clean -> silence is fine once the transition
+ * itself has been announced).
+ */
+export function publishDiagnostics(args) {
+    if (args.origin === "bus")
+        return;
+    if (args.files.length === 0)
+        return;
+    if (!isBusPublishEnabled())
+        return;
+    if (!busEmit)
+        return;
+    try {
+        const fileEntries = args.files.map((f) => {
+            const normPath = normalizeFilePath(f.path);
+            const { capped, truncated } = capDiagnostics(f.diagnostics);
+            if (capped.length > 0) {
+                reportedDirtyPaths.add(normPath);
+            }
+            else {
+                reportedDirtyPaths.delete(normPath);
+            }
+            const entry = {
+                path: normPath,
+                diagnostics: capped,
+            };
+            if (truncated)
+                entry.truncated = true;
+            return entry;
+        });
+        seqCounter += 1;
+        const payload = {
+            v: BUS_DIAGNOSTICS_VERSION,
+            source: "pi-lens",
+            cwd: normalizeFilePath(args.cwd),
+            seq: seqCounter,
+            ts: Date.now(),
+            files: fileEntries,
+        };
+        busEmit(BUS_DIAGNOSTICS_EVENT, payload);
+    }
+    catch (err) {
+        if (!hasLoggedFailure) {
+            hasLoggedFailure = true;
+            args.dbg?.(`diagnostics-publish: pilens:diagnostics emit failed (further failures suppressed): ${err}`);
+        }
+    }
+}
+/**
+ * Whether `path` was last reported with a non-empty diagnostic set (i.e. a
+ * clean run for it now would be a transition worth emitting `[]` for).
+ * Exposed for the pipeline call site to decide whether to include a
+ * currently-clean file in the batch it passes to `publishDiagnostics`.
+ */
+export function wasPreviouslyReportedDirty(path) {
+    return reportedDirtyPaths.has(normalizeFilePath(path));
+}