@herbertgao/pi-extensions 2026.10.1 → 2026.10.2

package/node_modules/pi-lens/dist/clients/deferred-lsp-work.js

@@ -1,106 +0,0 @@
-/**
- * The one owner of "work that keeps talking to the LSP service after the hook
- * that started it has returned" (#2504 review round 2, F3).
- *
- * #2504 moved the cold-cache actionable-warnings fresh-pull loop off the
- * awaited `turn_end` hook. That loop then had effectively ONE bound: it
- * captured the COMPLETED turn's `ctx.signal` — which `index.ts` clears from
- * the ambient slot in its `finally`, so it can never fire — plus a 60 s wall
- * deadline checked only BETWEEN files. A wedged `getDiagnostics` was therefore
- * unbounded, the loop kept opening files (and could re-spawn servers) after
- * `turn_end` returned and after the LSP idle reset, a `session_shutdown`
- * landing mid-loop hit the #234 spawn-at-teardown shape, and the handle was a
- * module-level `let` with no reset that a second deferral simply overwrote.
- *
- * This module supplies the missing halves: ONE registered handle (held by
- * whichever deferral got there first, released when its work settles — see
- * `armDeferredLspWork`) and ONE abort signal that
- * `resetLSPService` fires — the single choke point through which
- * `session_shutdown`, `session_start` and the idle reset all retire the
- * service, so no caller has to remember to wire each lifecycle event
- * separately. Aborting only ever settles a promise; it never spawns, which is
- * what AGENTS.md's #234 teardown rule requires of anything reachable from
- * `session_shutdown`.
- *
- * Deliberately a zero-dependency leaf, for the same reason
- * `map-with-concurrency.ts` is one: `clients/lsp/index.ts` must not gain an
- * import edge to `actionable-warnings.ts` (and through it `lsp/edits.ts`,
- * `lsp-mutation.ts`, the durable store …) for a 20-line handle registry.
- */
-let deferredController;
-let deferredWork;
-/**
- * Abort the in-flight deferred LSP work, if any, and drop the slot.
- *
- * Safe at teardown: it settles a promise and spawns nothing. Idempotent — a
- * second call with no armed work is a no-op.
- */
-export function abortDeferredLspWork(reason) {
-    const controller = deferredController;
-    deferredController = undefined;
-    deferredWork = undefined;
-    controller?.abort(new Error(reason));
-}
-/**
- * Claim the deferred-work slot, or `undefined` when an incumbent still holds
- * it. THE INCUMBENT WINS (#2504 review round 3, F-A(d)).
- *
- * Round 2 had arming ABORT the previous deferral, reasoning that two loops
- * must not run concurrently against one LSP service. The first half of that is
- * right and still holds — there is exactly one slot. The second half was
- * backwards about which loop to keep. A deferral is armed by a turn that
- * primed NO LSP cache, which in a live editing session is every turn; so every
- * turn cancelled its predecessor, and an aborted loop publishes nothing by
- * design (its service is presumed gone). Back-to-back editing turns therefore
- * delivered NOTHING AT ALL — the exact delivery AC #2504 exists to preserve.
- *
- * Keeping the incumbent inverts that: the loop that is already talking to the
- * service runs to completion and publishes, and the newcomer is declined and
- * says so out loud. The cost is stated rather than silent — the declining
- * turn's cold files go unchecked on this channel until a later turn defers.
- *
- * Declining cannot latch. `registerDeferredLspWork` releases the slot the
- * moment the work settles, and the loop itself is bounded twice over
- * (`ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS` between files, a per-round-trip
- * timeout inside them), so an incumbent always yields the slot in bounded
- * time. Teardown is unaffected: `abortDeferredLspWork` still evicts the
- * incumbent unconditionally, which is how `resetLSPService` retires it.
- */
-export function armDeferredLspWork() {
-    if (isDeferredLspWorkArmed())
-        return undefined;
-    const controller = new AbortController();
-    deferredController = controller;
-    deferredWork = undefined;
-    return controller.signal;
-}
-/**
- * Register the armed work's promise so callers (and tests) have something to
- * await. Ignored when the slot has already been re-armed or aborted since — a
- * late registration must not resurrect a retired handle.
- *
- * Registration also arranges the RELEASE (#2504 review round 3, F-A(d)):
- * because the slot now turns a newcomer away rather than evicting the
- * incumbent, something has to hand it back, and the only correct moment is
- * when the work settles. Guarded on identity, so a slot re-armed or aborted in
- * the meantime is never cleared by a stale finalizer.
- */
-export function registerDeferredLspWork(signal, work) {
-    if (deferredController?.signal !== signal)
-        return;
-    deferredWork = work;
-    void work.finally(() => {
-        if (deferredController?.signal !== signal)
-            return;
-        deferredController = undefined;
-        deferredWork = undefined;
-    });
-}
-/** The in-flight deferred work, or an already-resolved promise when idle. */
-export function awaitDeferredLspWork() {
-    return deferredWork ?? Promise.resolve();
-}
-/** True while a deferral holds the slot and has not been aborted. */
-export function isDeferredLspWorkArmed() {
-    return deferredController?.signal.aborted === false;
-}

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -1,426 +0,0 @@
-/** Bounded, process-local telemetry for behavior degraded during one session. */
-import { logExtension } from "./extension-log.js";
-import { DEGRADATION_ENTRIES_PER_KIND, LEDGER_FIELD_MAX, truncateForLedger, } from "./ledger-bounds.js";
-import { logLatency } from "./latency-logger.js";
-import { getSinkRotations, getSinkOptionConflicts, getSinkWriteFailures, resetSinkRotations, resetSinkWriteFailures, } from "./ndjson-logger.js";
-// #2146: pulled at READ time, never pushed. `process-singletons.ts` is a
-// dependency leaf on purpose — it cannot import this module without closing a
-// no-client-cycles cycle through instance-registry/instance-reaper — so the
-// ledger reaches IN for its reset log, the same inversion `getSinkWriteFailures`
-// above uses.
-import { getProcessSingletonResets, PROCESS_SINGLETON_RESET_KIND, } from "./process-singletons.js";
-// #2506: same inversion, same reason — the log-dir resolver cannot import this
-// module (directly OR dynamically). THIS module is on a no-client-cycles cycle
-// via extension-log.ts; the resolver's whole correctness argument is that it
-// sits off every cycle, so an edge in that direction would put it back on one.
-// `getGlobalPiLensLogDir()`'s probe-home-redirect event is therefore written
-// into `probe-home-state.ts` and read back here instead. See that module's doc
-// comment for the full account.
-import { getProbeHomeRedirectEvent } from "./probe-home-state.js";
-// Re-exported so existing importers keep one name for the ledger's bound.
-export { LEDGER_FIELD_MAX, truncateForLedger };
-const ENTRIES_PER_KIND = DEGRADATION_ENTRIES_PER_KIND;
-const MAX_DISTINCT_KINDS = 32;
-const OVERFLOW_KIND = "other";
-const groups = new Map();
-const onceKeys = new Set();
-const tallies = new Map();
-// Monotonic session-boundary counter (#1536 review F5): callers that keep
-// their OWN once-per-session latch outside the ledger (a per-instance Set
-// the ledger itself doesn't own) can compare this lazily at use time and
-// clear their latch on a mismatch — the same clear-on-transition shape as
-// project-trust.ts's trustGeneration, but keyed to the ledger's own reset
-// (resetDegradationLedger, wired into handleSessionStart) rather than a
-// trust change.
-let ledgerGeneration = 0;
-/** Current session generation. Bump on every `resetDegradationLedger()`. */
-export function getDegradationLedgerGeneration() {
-    return ledgerGeneration;
-}
-/**
- * Test-only population probe for bounded-container regressions. Keep this
- * read-only and deliberately expose sizes, not the retained identities.
- */
-export function _getDegradationLedgerStateForTests() {
-    return {
-        onceKeys: onceKeys.size,
-        tallies: tallies.size,
-        retainedEntries: [...groups.values()].reduce((total, group) => total + group.entries.length, 0),
-    };
-}
-export function recordDegradation(record) {
-    try {
-        const kind = boundedKind(record.kind);
-        const subject = subjectForLedger(record.subject);
-        const reason = truncateForLedger(record.reason);
-        let group = groups.get(kind);
-        if (!group) {
-            group = { count: 0, entries: [] };
-            groups.set(kind, group);
-        }
-        const admitted = group.entries.length < ENTRIES_PER_KIND;
-        group.count += 1;
-        // Bounded at RECORD time (#1366 review): reasons carry arbitrary error
-        // text; a 10KB message must never become a 10KB health line or a 10KB
-        // retained string.
-        group.entries.push({ subject, reason });
-        if (group.entries.length > ENTRIES_PER_KIND)
-            group.entries.shift();
-        return admitted;
-    }
-    catch (error) {
-        debugLedgerFailure("record", error);
-        // Telemetry must never break the observed path.
-        return false;
-    }
-}
-/** Record at most once per kind/subject during the current session. */
-export function recordDegradationOnce(record) {
-    try {
-        const kind = boundedKind(record.kind);
-        const subject = subjectForLedger(record.subject);
-        const key = `${kind}\0${subject}`;
-        if (onceKeys.has(key))
-            return;
-        onceKeys.add(key);
-        if (recordDegradation({ kind, subject, reason: record.reason })) {
-            logDurableDegradation(kind, subject, 1, record.metadata, record.code);
-        }
-    }
-    catch (error) {
-        debugLedgerFailure("record-once", error);
-        // Telemetry must never break the observed path.
-    }
-}
-/**
- * Count a repeated degradation while retaining one latest-reason entry per
- * kind/subject. The group count remains the exact event total.
- *
- * Returns `true` when this call is the FIRST occurrence recorded for this
- * kind/subject pair (the ledger is the single source of truth for that
- * tally already — via `tallies` — so callers that need a once-per-subject
- * "rising edge" signal, e.g. to gate a verbose one-time log line before
- * falling back to the bounded count, read it off this return value instead
- * of hand-rolling their own parallel `Set`/latch). #1716 reuses this same
- * signal to gate `navRequest`'s detailed timeout/late-answer log writes.
- */
-export function incrementDegradationCount(record) {
-    try {
-        const kind = boundedKind(record.kind);
-        const subject = subjectForLedger(record.subject);
-        const reason = truncateForLedger(record.reason);
-        const key = `${kind}\0${subject}`;
-        const count = (tallies.get(key) ?? 0) + 1;
-        tallies.set(key, count);
-        let group = groups.get(kind);
-        if (!group) {
-            group = { count: 0, entries: [] };
-            groups.set(kind, group);
-        }
-        const existing = group.entries.findIndex((candidate) => candidate.subject === subject);
-        const admitted = existing >= 0 || group.entries.length < ENTRIES_PER_KIND;
-        group.count += 1;
-        // #1816: append the count AFTER truncation, never before. `reason` is
-        // already bounded above, so re-truncating the concatenation pushed the
-        // suffix past LEDGER_FIELD_MAX and silently ate it — a 200-char reason
-        // lost the one field that says how often the degradation fired.
-        const entry = { subject, reason: `${reason} (count: ${count})` };
-        if (existing >= 0)
-            group.entries.splice(existing, 1);
-        group.entries.push(entry);
-        if (group.entries.length > ENTRIES_PER_KIND)
-            group.entries.shift();
-        // Durable rows use the summary's admission and emit the first event and
-        // power-of-two milestones only, keeping the sink bounded.
-        if (admitted && isPowerOfTwo(count)) {
-            logDurableDegradation(kind, subject, count, record.metadata, record.code);
-        }
-        return count === 1;
-    }
-    catch (error) {
-        debugLedgerFailure("increment", error);
-        // Telemetry must never break the observed path.
-        return false;
-    }
-}
-/**
- * Persist the accepted ledger mutation through the existing rotated NDJSON
- * latency stream. `logLatency` owns the timestamp, PID, serialization, secret
- * redaction, and write queue. The subject and kind were already bounded by the
- * ledger before reaching this seam.
- */
-function logDurableDegradation(kind, subject, count, metadata, code) {
-    const boundedMetadata = boundLedgerMetadata(metadata);
-    logLatency({
-        type: "phase",
-        phase: "degradation_ledger",
-        filePath: subject,
-        durationMs: 0,
-        metadata: {
-            ...boundedMetadata,
-            kind,
-            subject,
-            count,
-            ledgerGeneration,
-            // Reserved row field, written AFTER the bounded caller metadata so the
-            // `MAX_METADATA_KEYS` cap cannot evict the stable code (#2418).
-            ...(code ? { code } : {}),
-        },
-    });
-}
-const MAX_METADATA_KEYS = 8;
-function boundLedgerMetadata(metadata) {
-    if (!metadata)
-        return {};
-    const entries = Object.entries(metadata);
-    const kept = entries.slice(0, MAX_METADATA_KEYS);
-    const bounded = Object.fromEntries(kept.map(([key, value]) => [key, truncateForLedger(value)]));
-    const dropped = entries.length - kept.length;
-    if (dropped > 0)
-        bounded.metadataDropped = dropped;
-    return bounded;
-}
-function isPowerOfTwo(value) {
-    return value > 0 && (value & (value - 1)) === 0;
-}
-/**
- * A subject is an IDENTITY: it is the row's discriminator, the `filePath` of
- * its durable latency row, and the text `renderDegradationLines` prints after
- * the count. A blank one names nothing — `⚠ kind: 1 — : reason` — so blank and
- * missing are the same case and both read `unknown` (#3389 verify round 2,
- * F3395-02: a socket error carrying `code: ""` wrote an empty subject).
- *
- * This is deliberately NOT `normalizeForLedger`'s job, though every ledger
- * field passes through it: that normalizer keeps falsy primitives on purpose
- * (`tests/clients/ledger-bounds.test.ts` "keeps primitives, including falsy
- * ones"), because a metadata VALUE of `""` or `0` is data, not absence. Only
- * the identity fields fold blank into missing, and `0`/`false` still name
- * something here too — the check reads the NORMALIZED text, never the caller's
- * truthiness.
- */
-function subjectForLedger(value) {
-    const subject = truncateForLedger(value);
-    return subject.trim() === "" ? "unknown" : subject;
-}
-function boundedKind(value) {
-    const kind = truncateForLedger(value);
-    if (groups.has(kind) || kind === OVERFLOW_KIND)
-        return kind;
-    // Keep one slot available for all kinds beyond the cardinality bound.
-    return groups.size < MAX_DISTINCT_KINDS - 1 ? kind : OVERFLOW_KIND;
-}
-export function getDegradationSummary() {
-    const summary = [...groups.entries()].map(([kind, group]) => ({
-        kind,
-        count: group.count,
-        droppedCount: group.count - group.entries.length,
-        latestReasons: group.entries.map((entry) => ({ ...entry })),
-    }));
-    // Folded in at read time, not written into `groups` (#1970) — see the
-    // `log-sink-write-failure` doc comment on `DegradationKind` for why this
-    // kind never goes through `recordDegradation`.
-    const sinkFailures = getSinkWriteFailures();
-    if (sinkFailures.length > 0) {
-        summary.push({
-            kind: "log-sink-write-failure",
-            count: sinkFailures.reduce((total, sink) => total + sink.droppedCount, 0),
-            droppedCount: 0,
-            latestReasons: sinkFailures.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger(`${sink.droppedCount} dropped write(s) after reopen-retry failed`),
-            })),
-        });
-    }
-    // #2505, same read-time fold: a mid-session rotation is visible without
-    // this module writing about it through the very sink family it is
-    // reporting on — see the `log-sink-rotated` doc comment on
-    // `DegradationKind`.
-    const sinkRotations = getSinkRotations();
-    const rotated = sinkRotations.filter((sink) => sink.rotationCount > 0);
-    if (rotated.length > 0) {
-        summary.push({
-            kind: "log-sink-rotated",
-            count: rotated.reduce((total, sink) => total + sink.rotationCount, 0),
-            droppedCount: 0,
-            latestReasons: rotated.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger(`${sink.rotationCount} rotation(s) at the configured byte bound`),
-            })),
-        });
-    }
-    // A rotation the writer ATTEMPTED and could not complete is a different
-    // fact from a rotation that happened, and the only signal that a sink is
-    // growing past its bound right now (#2505 review F2).
-    const rotateFailed = sinkRotations.filter((sink) => sink.failureCount > 0);
-    if (rotateFailed.length > 0) {
-        summary.push({
-            kind: "log-sink-rotate-failed",
-            count: rotateFailed.reduce((total, sink) => total + sink.failureCount, 0),
-            droppedCount: 0,
-            latestReasons: rotateFailed.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger(`${sink.failureCount} failed rotation attempt(s); this sink is growing past its byte bound`),
-            })),
-        });
-    }
-    const optionConflicts = getSinkOptionConflicts();
-    if (optionConflicts.length > 0) {
-        summary.push({
-            kind: "log-sink-option-conflict",
-            count: optionConflicts.length,
-            droppedCount: 0,
-            latestReasons: optionConflicts.map((sink) => ({
-                subject: truncateForLedger(sink.file),
-                reason: truncateForLedger("shared writer rotation options differed across module graphs; first writer retained ownership"),
-            })),
-        });
-    }
-    // #2146, same read-time fold: process-singleton resets live in the leaf
-    // module's own bounded log. One entry per family, so this group's count is
-    // the number of families this build could not adopt, never an event tally.
-    const singletonResets = getProcessSingletonResets();
-    if (singletonResets.length > 0) {
-        summary.push({
-            kind: PROCESS_SINGLETON_RESET_KIND,
-            count: singletonResets.length,
-            droppedCount: 0,
-            latestReasons: singletonResets.map((reset) => ({
-                subject: truncateForLedger(reset.family),
-                reason: truncateForLedger(reset.reason),
-            })),
-        });
-    }
-    // #2506, same read-time fold: `getGlobalPiLensLogDir()`'s probe-home redirect
-    // fires at most once per process (see `probe-home-state.ts`), so this is a
-    // presence check, not a tally.
-    const probeHomeRedirect = getProbeHomeRedirectEvent();
-    if (probeHomeRedirect) {
-        summary.push({
-            kind: "global-dir-probe-redirect",
-            count: 1,
-            droppedCount: 0,
-            latestReasons: [
-                {
-                    subject: truncateForLedger(probeHomeRedirect.probeHome),
-                    reason: truncateForLedger(`PI_LENS_HOME unset with cwd in an agent worktree/tmp probe context (${probeHomeRedirect.cwd}), or PILENS_PROBE=1 forced it; LOGS redirected away from the real home directory (tools, bin and instances.json are unaffected)`),
-                },
-            ],
-        });
-    }
-    return summary;
-}
-function isRenderableSummary(value) {
-    if (!Array.isArray(value))
-        return false;
-    return value.every((group) => {
-        if (group === null || typeof group !== "object")
-            return false;
-        const candidate = group;
-        return (typeof candidate.kind === "string" &&
-            typeof candidate.count === "number" &&
-            Array.isArray(candidate.latestReasons) &&
-            candidate.latestReasons.every((entry) => entry !== null &&
-                typeof entry === "object" &&
-                typeof entry.subject === "string" &&
-                typeof entry.reason === "string"));
-    });
-}
-/**
- * Kinds that record something the system did ON PURPOSE, correctly, and
- * that a reader only needs a tally of — never a call to action (#2505
- * review). A routine log rotation at the configured bound is the writer
- * working as designed; giving it the same warning marker a real
- * degradation gets trains the reader to ignore the marker. The FAILED
- * rotation is the line that has to stand out, so it is deliberately NOT
- * in this set.
- */
-const INFORMATIONAL_DEGRADATION_KINDS = new Set([
-    "log-sink-rotated",
-    // #2504 review round 8 (S1): both fire on the ordinary re-edit cadence
-    // (a carry-forward window closing, or a session boundary) and are
-    // self-healing -- the next turn's analysis or deferral re-observes the
-    // file -- so a `⚠` overstates them the same way a routine log rotation
-    // would.
-    "actionable-warnings-inband-superseded",
-    "actionable-warnings-deferred-superseded",
-    // #2523: a hook await abandoned because the session is tearing down. The
-    // teardown signal firing is the design working, so it is a tally; the
-    // BUDGET blow-out (`hook-await-exceeded`) is the line that has to stand
-    // out, and a caller's own Escape records nothing at all.
-    "hook-await-abandoned",
-    // #2524: can fire on a query that ultimately settles `ok` (see the kind's
-    // doc comment above) and is frequent/self-healing by design — a `⚠` would
-    // cry wolf on the sampler's ordinary best-effort data loss.
-    "resource-sampler-scanner-escalated",
-    // #2874: a successful legacy-directory migration is an upgrade tally, not
-    // a call to action. The hash-only subject avoids exposing the project path.
-    "data_dir_migrated",
-]);
-export function renderDegradationLines(summary = getDegradationSummary()) {
-    if (!isRenderableSummary(summary))
-        return [];
-    if (summary.length === 0)
-        return [];
-    return [
-        "Degradations:",
-        ...summary.map((group) => {
-            if (INFORMATIONAL_DEGRADATION_KINDS.has(group.kind)) {
-                return `  ${group.kind}: ${group.count}`;
-            }
-            const latest = group.latestReasons.at(-1);
-            return `  ⚠ ${group.kind}: ${group.count}${latest ? ` — ${latest.subject}: ${latest.reason}` : ""}`;
-        }),
-    ];
-}
-function debugLedgerFailure(operation, error) {
-    try {
-        logExtension({
-            subsystem: "degradation-ledger",
-            level: "debug",
-            message: `${operation} failed: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-    catch {
-        // Debug logging must not compromise the non-fatal telemetry contract.
-    }
-}
-/** Session-boundary/test reset. */
-export function resetDegradationLedger() {
-    groups.clear();
-    onceKeys.clear();
-    tallies.clear();
-    ledgerGeneration++;
-    // #1970, catalog shape 17: the sink write-failure tally is a
-    // process-lifetime latch too — it re-arms alongside the rest of the
-    // ledger rather than surviving past the session that observed it.
-    resetSinkWriteFailures();
-    // #2505, same catalog shape 17 re-arm: a rotation tally recurs (new writes
-    // keep crossing the bound), so clearing it costs nothing and a later
-    // session re-observes the fact fresh.
-    resetSinkRotations();
-    // #2146 review F3: the OTHER pulled source, `getProcessSingletonResets()`,
-    // deliberately does NOT re-arm here, and the difference from its neighbour
-    // above is the point. A sink write failure recurs — new writes fail, so
-    // clearing the tally costs nothing and a later session re-observes the
-    // problem. A process-singleton reset happens once, at module-evaluation
-    // time, and cannot recur: after it, the container holds only compatible
-    // cells. Clearing it would show the fact in the first session's
-    // `pilens_health` and hide it from every session after, which is exactly
-    // when someone reads that line. The row is bounded independently of the
-    // session (one entry per family, capped at 16), so leaving it costs a fixed
-    // handful of lines and keeps a process-scope fact visible for the process's
-    // life. Deliberate exception to catalog shape 17, not an oversight.
-    //
-    // `getProbeHomeRedirectEvent()` (#2506) is the same shape as the
-    // process-singleton case above and for the same reason: the redirect is
-    // resolved at most once per PROCESS (memoized in the `globalThis` slot
-    // `probe-home-state.ts` owns, not a session-scoped one), so it cannot
-    // recur within this process's life either — clearing it here would hide
-    // the fact from every session after the first in the same probe process.
-}
-// Re-exported so every existing importer keeps its specifier. The value now
-// lives in the `ledger-bounds.js` leaf (#2426), so a producer that only needs
-// the BOUND does not have to import the ledger — and cannot be broken by a test
-// that mocks it wholesale.
-export { DEGRADATION_ENTRIES_PER_KIND };
-export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;