pi-lens 3.8.69 → 3.8.71

package/dist/clients/format-events-publish.js

@@ -0,0 +1,299 @@
+/**
+ * Publishes `pilens:format:queued`, `pilens:format:start`, and
+ * `pilens:autofix:start` on pi's shared `pi.events` bus (#673, #684).
+ *
+ * Sibling to `clients/bus-publish.ts` (#482 `pilens:files:touched`) and
+ * `clients/diagnostics-publish.ts` (#502 `pilens:diagnostics`) rather than a
+ * new export crammed into either file: same emit plumbing shape and the same
+ * `PI_LENS_BUS_PUBLISH` kill switch (`isBusPublishEnabled`, imported from
+ * bus-publish.ts), but this producer owns its own emit-function singleton
+ * (wired separately from index.ts, same as diagnostics-publish.ts does) since
+ * it has nothing else in common with either sibling's module state.
+ *
+ * ## Motivation (#673)
+ *
+ * `pilens:files:touched` only fires AFTER deferred formatting has completed —
+ * it tells a same-process listener what pi-lens just mutated, in the past
+ * tense. #673 reported a concrete failure mode this leaves uncovered: another
+ * in-process extension (a review/snapshot controller) derives an immutable
+ * candidate tree from the live worktree mid-turn, unaware that pi-lens has a
+ * file queued for deferred formatting that will still land — silently
+ * invalidating the snapshot it just took. There was no bus signal for either
+ * of the two moments that matter to that use case:
+ *
+ *   1. A file NEWLY entering the deferred-format pending queue
+ *      (`pilens:format:queued` — one event per file, only on first queue
+ *      entry; a file re-touched by a second edit before `agent_end` does NOT
+ *      re-emit, to avoid event spam for repeated edits to the same file).
+ *   2. The deferred-format phase actually starting at `agent_end`
+ *      (`pilens:format:start` — one event per batch, only when there is at
+ *      least one queued file to format).
+ *
+ * This is deliberately visibility-only: it lets a listener know pi-lens MIGHT
+ * or IS ABOUT TO mutate specific files via deferred formatting, so it can
+ * choose to wait, re-derive, or flag its own snapshot as provisional. It is
+ * NOT a synchronous flush/barrier API (a caller cannot block deferred
+ * formatting via these events) — that remains a separate, explicitly
+ * out-of-scope future feature. Completion is already covered by the existing
+ * `pilens:files:touched` (`reason: "format"`) event; these two do not
+ * duplicate it.
+ *
+ * ## `pilens:autofix:start` (#684)
+ *
+ * Follow-up to #673/#674, applying the identical fix to a sibling race: the
+ * `agent_end` actionable-warnings autofix batch (`clients/runtime-agent-end.ts`,
+ * gated by `getFlag("lens-actionable-warning-autofix")`) also reads a cached
+ * report and applies fixes as a batch well after the edit that produced the
+ * warnings — same "runs later, unpredictably" shape as deferred formatting.
+ * It only emitted `pilens:files:touched` (`reason: "autofix"`) AFTER the fact.
+ * `pilens:autofix:start` fires once per batch, only when the cached
+ * actionable-warnings report is fresh (`checkActionableWarningsReportFresh`)
+ * AND has at least one autofix-eligible warning to act on — mirroring
+ * `pilens:format:start`'s "only when there's genuine work" gate. Note: this is
+ * distinct from `pipeline.ts`'s per-edit `runAutofix` (biome/ruff/eslint fixes
+ * applied synchronously inside the `tool_result` hook, awaited before the
+ * tool result returns) — that path isn't deferred and doesn't have this race,
+ * so it doesn't get a `start` event.
+ *
+ * Versioning policy: frozen-additive per event, same discipline as #482/#502.
+ * New optional fields may be added under the same `v: 1` for any of the three
+ * events; a breaking change to an existing field's meaning must bump that
+ * event's `v` independently (each event versions separately since they're
+ * unrelated payloads).
+ *
+ * Fire-and-forget: publishing must never affect the write path's or
+ * `agent_end`'s success or latency. Any failure (bus unavailable, emit
+ * throws) is swallowed; an optional `dbg` callback is invoked at most once
+ * per event type on first failure so a wired caller can log it without
+ * spamming.
+ */
+import { logBusEvent } from "./bus-events-logger.js";
+import { isBusPublishEnabled } from "./bus-publish.js";
+import { normalizeFilePath } from "./path-utils.js";
+export const BUS_FORMAT_QUEUED_EVENT = "pilens:format:queued";
+export const BUS_FORMAT_QUEUED_VERSION = 1;
+export const BUS_FORMAT_START_EVENT = "pilens:format:start";
+export const BUS_FORMAT_START_VERSION = 1;
+export const BUS_AUTOFIX_START_EVENT = "pilens:autofix:start";
+export const BUS_AUTOFIX_START_VERSION = 1;
+let busEmit;
+let hasLoggedQueuedFailure = false;
+let hasLoggedQueuedUnwired = false;
+let hasLoggedQueuedDisabled = false;
+let hasLoggedStartFailure = false;
+let hasLoggedStartUnwired = false;
+let hasLoggedStartDisabled = false;
+let hasLoggedAutofixStartFailure = false;
+let hasLoggedAutofixStartUnwired = false;
+let hasLoggedAutofixStartDisabled = false;
+/**
+ * Wire the emit function from pi's `pi.events` bus. Called once at extension
+ * factory time from index.ts, alongside `wireBusEmitter` (#482) and
+ * `wireDiagnosticsBusEmitter` (#502) — all three producers share the
+ * identical `pi.events.emit` binding, wired separately per producer.
+ */
+export function wireFormatEventsBusEmitter(emitFn) {
+    busEmit = emitFn;
+}
+/** Test-only: reset module state between test files. */
+export function _resetFormatEventsPublishForTests() {
+    busEmit = undefined;
+    hasLoggedQueuedFailure = false;
+    hasLoggedQueuedUnwired = false;
+    hasLoggedQueuedDisabled = false;
+    hasLoggedStartFailure = false;
+    hasLoggedStartUnwired = false;
+    hasLoggedStartDisabled = false;
+    hasLoggedAutofixStartFailure = false;
+    hasLoggedAutofixStartUnwired = false;
+    hasLoggedAutofixStartDisabled = false;
+}
+/**
+ * Publish one `pilens:format:queued` event for a file newly entering the
+ * deferred-format pending queue. Callers MUST only invoke this on the
+ * NEW-entry branch of `RuntimeCoordinator.deferFormat` (not on a re-touch of
+ * an already-queued file) — see `clients/runtime-tool-result.ts`'s call site.
+ * Fire-and-forget: never throws, never awaited by the write path.
+ */
+export function publishFormatQueued(args) {
+    if (!isBusPublishEnabled()) {
+        if (!hasLoggedQueuedDisabled) {
+            hasLoggedQueuedDisabled = true;
+            logBusEvent({
+                event: BUS_FORMAT_QUEUED_EVENT,
+                outcome: "skipped_disabled",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    if (!busEmit) {
+        if (!hasLoggedQueuedUnwired) {
+            hasLoggedQueuedUnwired = true;
+            logBusEvent({
+                event: BUS_FORMAT_QUEUED_EVENT,
+                outcome: "skipped_unwired",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    try {
+        const payload = {
+            v: BUS_FORMAT_QUEUED_VERSION,
+            source: "pi-lens",
+            filePath: normalizeFilePath(args.filePath),
+            cwd: normalizeFilePath(args.cwd),
+            tool: args.tool,
+        };
+        busEmit(BUS_FORMAT_QUEUED_EVENT, payload);
+        logBusEvent({
+            event: BUS_FORMAT_QUEUED_EVENT,
+            outcome: "emitted",
+            cwd: payload.cwd,
+            fileCount: 1,
+        });
+    }
+    catch (err) {
+        logBusEvent({
+            event: BUS_FORMAT_QUEUED_EVENT,
+            outcome: "emit_failed",
+            cwd: normalizeFilePath(args.cwd),
+            error: String(err),
+        });
+        if (!hasLoggedQueuedFailure) {
+            hasLoggedQueuedFailure = true;
+            args.dbg?.(`format-events-publish: pilens:format:queued emit failed (further failures suppressed): ${err}`);
+        }
+    }
+}
+/**
+ * Publish one `pilens:format:start` event when the `agent_end` deferred-
+ * format phase begins. Callers MUST only invoke this when `paths.length > 0`
+ * — see `clients/runtime-agent-end.ts`'s call site, placed at the same point
+ * as the existing `agent_end_deferred_format_start` latency-log phase so both
+ * signals represent the identical moment. Fire-and-forget: never throws,
+ * never awaited by `agent_end`.
+ */
+export function publishFormatStart(args) {
+    if (args.paths.length === 0)
+        return;
+    if (!isBusPublishEnabled()) {
+        if (!hasLoggedStartDisabled) {
+            hasLoggedStartDisabled = true;
+            logBusEvent({
+                event: BUS_FORMAT_START_EVENT,
+                outcome: "skipped_disabled",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    if (!busEmit) {
+        if (!hasLoggedStartUnwired) {
+            hasLoggedStartUnwired = true;
+            logBusEvent({
+                event: BUS_FORMAT_START_EVENT,
+                outcome: "skipped_unwired",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    try {
+        const paths = args.paths.map((p) => normalizeFilePath(p));
+        const payload = {
+            v: BUS_FORMAT_START_VERSION,
+            source: "pi-lens",
+            cwd: normalizeFilePath(args.cwd),
+            paths,
+            fileCount: paths.length,
+        };
+        busEmit(BUS_FORMAT_START_EVENT, payload);
+        logBusEvent({
+            event: BUS_FORMAT_START_EVENT,
+            outcome: "emitted",
+            cwd: payload.cwd,
+            fileCount: payload.fileCount,
+        });
+    }
+    catch (err) {
+        logBusEvent({
+            event: BUS_FORMAT_START_EVENT,
+            outcome: "emit_failed",
+            cwd: normalizeFilePath(args.cwd),
+            error: String(err),
+        });
+        if (!hasLoggedStartFailure) {
+            hasLoggedStartFailure = true;
+            args.dbg?.(`format-events-publish: pilens:format:start emit failed (further failures suppressed): ${err}`);
+        }
+    }
+}
+/**
+ * Publish one `pilens:autofix:start` event when the `agent_end`
+ * actionable-warnings autofix batch begins (#684). Callers MUST only invoke
+ * this when `paths.length > 0` — i.e. after the cached report has been
+ * confirmed fresh (`checkActionableWarningsReportFresh`) AND has at least one
+ * autofix-eligible warning to act on, the same "genuine work" gate
+ * `publishFormatStart` applies for deferred formatting — see
+ * `clients/runtime-agent-end.ts`'s call site, placed immediately before
+ * `applyConservativeActionableWarningFixes` is invoked. Fire-and-forget:
+ * never throws, never awaited by `agent_end`.
+ */
+export function publishAutofixStart(args) {
+    if (args.paths.length === 0)
+        return;
+    if (!isBusPublishEnabled()) {
+        if (!hasLoggedAutofixStartDisabled) {
+            hasLoggedAutofixStartDisabled = true;
+            logBusEvent({
+                event: BUS_AUTOFIX_START_EVENT,
+                outcome: "skipped_disabled",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    if (!busEmit) {
+        if (!hasLoggedAutofixStartUnwired) {
+            hasLoggedAutofixStartUnwired = true;
+            logBusEvent({
+                event: BUS_AUTOFIX_START_EVENT,
+                outcome: "skipped_unwired",
+                cwd: normalizeFilePath(args.cwd),
+            });
+        }
+        return;
+    }
+    try {
+        const paths = args.paths.map((p) => normalizeFilePath(p));
+        const payload = {
+            v: BUS_AUTOFIX_START_VERSION,
+            source: "pi-lens",
+            cwd: normalizeFilePath(args.cwd),
+            paths,
+            fileCount: paths.length,
+            eligibleCount: args.eligibleCount,
+        };
+        busEmit(BUS_AUTOFIX_START_EVENT, payload);
+        logBusEvent({
+            event: BUS_AUTOFIX_START_EVENT,
+            outcome: "emitted",
+            cwd: payload.cwd,
+            fileCount: payload.fileCount,
+        });
+    }
+    catch (err) {
+        logBusEvent({
+            event: BUS_AUTOFIX_START_EVENT,
+            outcome: "emit_failed",
+            cwd: normalizeFilePath(args.cwd),
+            error: String(err),
+        });
+        if (!hasLoggedAutofixStartFailure) {
+            hasLoggedAutofixStartFailure = true;
+            args.dbg?.(`format-events-publish: pilens:autofix:start emit failed (further failures suppressed): ${err}`);
+        }
+    }
+}

package/dist/clients/git-tracked-ignore.js

@@ -0,0 +1,208 @@
+/**
+ * Shared "untracked AND ignored" file-id computation (#679's `/lens-map`,
+ * reused by #694's review-graph ignore-gated node creation) — and, since
+ * #703, the sibling "tracked files" set that lets `getProjectIgnoreMatcher`
+ * (`file-utils.ts`) honor the OTHER half of the same git semantic.
+ *
+ * THE critical git semantic this exists to respect: a TRACKED file is never
+ * ignored, even when a `.gitignore` pattern matches it (pi-lens's own
+ * committed `clients/deps/*.js` vendored sources match the repo's `*.js`
+ * ignore pattern and MUST stay graph/map nodes) — which is why this asks git
+ * itself (`ls-files --others --ignored --exclude-standard` for the untracked
+ * side, `ls-files` alone for the tracked side) instead of running a pattern
+ * matcher over `.gitignore` (a matcher-only approach would wrongly drop
+ * tracked vendored files, e.g. #703's `clients/test-runner-client.ts`
+ * matching `.gitignore`'s `test-*.ts`).
+ *
+ * Degradation: when git is absent/fails/times out (not a git repo, bare
+ * checkout, etc.) both `collectUntrackedIgnoredIds` and `collectTrackedFiles`
+ * return `undefined` and every caller SKIPS/degrades — the graph/map shows
+ * what's known rather than guessing via a matcher that can't see tracked
+ * status, and `getProjectIgnoreMatcher` falls back to pattern-only behavior.
+ *
+ * Keying asymmetry (deliberate, not an oversight): `collectUntrackedIgnoredIds`
+ * keys its ids with `normalizeMapKey` (realpath-backed) because those ids are
+ * compared against review-graph/map NODE ids — externally-produced state that
+ * genuinely needs canonical on-disk casing/symlink resolution to match up.
+ * `collectTrackedFiles`'s ids, by contrast, are only ever compared against a
+ * `ProjectIgnoreMatcher`'s own `path.resolve`'d paths, produced by THIS
+ * process in the SAME walk — an ephemeral, self-consistent comparison per
+ * `normalizeEphemeralMapKey`'s contract (`path-utils.ts`), so it uses the
+ * cheap syntactic-only fold instead. Do not "fix" this asymmetry by unifying
+ * the two — they solve different problems (#703 review).
+ */
+import * as path from "node:path";
+import { isExcludedDirName } from "./file-utils.js";
+import { normalizeEphemeralMapKey, normalizeMapKey } from "./path-utils.js";
+import { safeSpawnAsync } from "./safe-spawn.js";
+/**
+ * Parses `git ls-files --others --ignored --exclude-standard` output
+ * (repo-relative paths, one per line) into normalized map-key file ids.
+ * Exported as a pure function so the parse/normalize step is unit-testable
+ * without mocking the spawn.
+ */
+export function parseUntrackedIgnoredOutput(stdout, cwd) {
+    const ids = new Set();
+    for (const line of stdout.split(/\r?\n/)) {
+        const rel = line.trim();
+        if (!rel)
+            continue;
+        // Paths inside shared-excluded dirs (node_modules, dist, .git, …) can
+        // never be review-graph/map nodes — the graph walk itself routes
+        // exclusion through `isExcludedDirName` — so skip them BEFORE paying for
+        // `normalizeMapKey` (realpath-backed, per-call filesystem cost): on
+        // pi-lens itself this prunes a 66k-line ignored list (node_modules) down
+        // to ~1.6k paths that actually need normalizing.
+        const dirSegments = rel.split("/").slice(0, -1);
+        if (dirSegments.some((segment) => isExcludedDirName(segment)))
+            continue;
+        ids.add(normalizeMapKey(path.join(cwd, rel)));
+    }
+    return ids;
+}
+async function fetchUntrackedIgnoredIds(cwd) {
+    try {
+        const result = await safeSpawnAsync("git", ["ls-files", "--others", "--ignored", "--exclude-standard"], { cwd, timeout: 10_000, resourceLabel: "git-tracked-ignore" });
+        if (result.error || result.status !== 0)
+            return undefined;
+        return parseUntrackedIgnoredOutput(result.stdout, cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+// #694: the review-graph build calls this on EVERY incremental/cascade
+// rebuild (a hot, per-edit path), not just `/lens-map`'s one-shot generation —
+// spawning `git ls-files` per edit would be a real per-keystroke cost. Memoize
+// per cwd with a short time bound: cheap enough that a `.gitignore` edit or a
+// newly-untracked file takes effect within a few seconds, but a burst of
+// per-edit rebuilds within that window shares one spawn.
+const CACHE_TTL_MS = 30_000;
+const _cache = new Map();
+/**
+ * The untracked-AND-ignored id set for `cwd`, memoized per-process with a
+ * {@link CACHE_TTL_MS} time bound so a hot rebuild loop (review-graph
+ * incremental/cascade builds) never spawns `git` per file/per edit — see the
+ * module doc for the tracked-file semantic and the degrade-to-undefined
+ * contract.
+ */
+export function collectUntrackedIgnoredIds(cwd) {
+    const key = normalizeMapKey(cwd);
+    const now = Date.now();
+    const cached = _cache.get(key);
+    if (cached && now - cached.fetchedAtMs < CACHE_TTL_MS)
+        return cached.promise;
+    const promise = fetchUntrackedIgnoredIds(cwd);
+    _cache.set(key, { promise, fetchedAtMs: now });
+    return promise;
+}
+/** Test hook: drop the memoized cache so a test's fake git state is re-read. */
+export function _resetUntrackedIgnoredCacheForTests() {
+    _cache.clear();
+}
+/**
+ * Parses `git ls-files` output (repo-relative paths, one per line, tracked
+ * files only — no `--others`) into normalized ids, keyed for comparison
+ * against a `ProjectIgnoreMatcher`'s own (non-realpath'd) `path.resolve`'d
+ * paths — NOT against {@link parseUntrackedIgnoredOutput}'s ids, which are
+ * realpath-keyed for a different consumer (review-graph/map node ids). The
+ * two sets are NOT directly comparable/mergeable despite the shared
+ * dir-exclusion-prune shape — see this file's module doc for the asymmetry.
+ *
+ * `cwd` is realpath'd exactly ONCE here (not per file) to reconcile the one
+ * divergence that matters in practice: on Windows, the matcher's
+ * `resolvedRoot` comes from `path.resolve` while this fetch's `cwd` may carry
+ * different on-disk casing (e.g. `c:\users` vs `C:\Users`) — a single
+ * realpath on the shared root, followed by a cheap syntactic fold
+ * (`normalizeEphemeralMapKey`) on every per-file join, reconciles that without
+ * paying `realpathSync` per tracked file (#703 perf follow-up — a ~2k-file
+ * repo was doing ~2k realpath calls in one synchronous burst per fetch).
+ * Accepted edge case: a symlinked or 8.3-short-name project root can still
+ * make the cheap per-file fold miss even after this one realpath — degrades
+ * to today's pattern-only behavior for that root, consistent with the
+ * fail-open contract elsewhere in this module.
+ */
+export function parseTrackedFilesOutput(stdout, cwd) {
+    const ids = new Set();
+    const base = normalizeMapKey(cwd);
+    for (const line of stdout.split(/\r?\n/)) {
+        const rel = line.trim();
+        if (!rel)
+            continue;
+        const dirSegments = rel.split("/").slice(0, -1);
+        if (dirSegments.some((segment) => isExcludedDirName(segment)))
+            continue;
+        ids.add(normalizeEphemeralMapKey(path.join(base, rel)));
+    }
+    return ids;
+}
+async function fetchTrackedFiles(cwd) {
+    try {
+        const result = await safeSpawnAsync("git", ["ls-files"], {
+            cwd,
+            timeout: 10_000,
+            resourceLabel: "git-tracked-ignore",
+        });
+        if (result.error || result.status !== 0)
+            return undefined;
+        return parseTrackedFilesOutput(result.stdout, cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+const _trackedCache = new Map();
+// Sync snapshot of the most recently RESOLVED tracked-files fetch per root,
+// keyed the same way as `_trackedCache`. `getProjectIgnoreMatcher`'s
+// `isIgnored` is sync-and-hot (#703 constraint) and can't await a promise, so
+// this is the seam it reads from: `ensureTrackedIndex` (file-utils.ts) awaits
+// `collectTrackedFiles` ONCE per walk, which populates this snapshot as a
+// side effect; `isIgnored` then reads the snapshot synchronously for every
+// file in that same walk. A caller that never primes sees an absent snapshot
+// entry and degrades to pattern-only behavior (fail-open, by design).
+const _trackedSnapshot = new Map();
+/**
+ * The tracked-files id set for `cwd` (i.e. `git ls-files`, no `--others`),
+ * memoized per-process with the same {@link CACHE_TTL_MS} time bound as
+ * {@link collectUntrackedIgnoredIds} — see that function's doc for the hot
+ * per-edit-rebuild-loop rationale. Also updates the synchronous snapshot
+ * `getTrackedFilesSnapshot` reads, so sync hot-path callers can consult a
+ * cheap in-memory Set instead of awaiting this promise per file.
+ */
+export function collectTrackedFiles(cwd) {
+    // #703 perf follow-up: `normalizeEphemeralMapKey`, not `normalizeMapKey` —
+    // this map's only readers/writers are `ensureTrackedIndex`/`isIgnored`
+    // (file-utils.ts), both of which derive `cwd` from the SAME matcher's
+    // `resolvedRoot` (`path.resolve`, not realpath) within one process, so the
+    // cheap syntactic fold is sufficient and avoids a realpath per call — see
+    // this file's module doc for why this diverges from `collectUntrackedIgnoredIds`.
+    const key = normalizeEphemeralMapKey(cwd);
+    const now = Date.now();
+    const cached = _trackedCache.get(key);
+    if (cached && now - cached.fetchedAtMs < CACHE_TTL_MS)
+        return cached.promise;
+    const promise = fetchTrackedFiles(cwd).then((result) => {
+        _trackedSnapshot.set(key, result);
+        return result;
+    });
+    _trackedCache.set(key, { promise, fetchedAtMs: now });
+    return promise;
+}
+/**
+ * Synchronous read of the most recent {@link collectTrackedFiles} result for
+ * `cwd`. Returns `undefined` when nothing has primed this root yet (never
+ * called `collectTrackedFiles`), when git degraded (no repo/spawn failure),
+ * OR when a fetch is still in flight — all three collapse to the same
+ * fail-open "tracked status unknown, use pattern-only behavior" contract.
+ * Called on every `isIgnored` check that reaches the tracked-rescue branch
+ * (file-utils.ts's `isTrackedAndRescued`), so this key MUST stay the cheap
+ * `normalizeEphemeralMapKey` fold, not a realpath.
+ */
+export function getTrackedFilesSnapshot(cwd) {
+    return _trackedSnapshot.get(normalizeEphemeralMapKey(cwd));
+}
+/** Test hook: drop the memoized tracked-files cache/snapshot. */
+export function _resetTrackedFilesCacheForTests() {
+    _trackedCache.clear();
+    _trackedSnapshot.clear();
+}

package/dist/clients/gitleaks-client.js

@@ -17,6 +17,13 @@
  *   - `gitleaks` reference in `package.json` deps, OR
  *   - a git pre-commit hook (.husky/, .git/hooks/) referencing gitleaks
  *
+ * `lens_diagnostics mode=full`'s fresh-fetch path (`clients/project-diagnostics/
+ * fresh-fetch.ts`) uses a looser "smart-default" gate instead — any tracked
+ * git repo, via `hasGitRepo` — since that's an explicitly-requested
+ * comprehensive review where gitleaks's low cost and advisory-only findings
+ * make the stricter default needlessly conservative. session_start and
+ * per-edit dispatch keep the strict gate above unchanged.
+ *
  * If the gate trips, the runner auto-installs gitleaks from GitHub releases
  * (installer entry registered in clients/installer/index.ts) and runs
  * `gitleaks detect --no-git --report-format json` against the analysis root.
@@ -95,6 +102,26 @@ export function hasGitleaksSignal(cwd) {
     }
     return false;
 }
+/**
+ * "Smart-default" tier from #130's own considered-but-unshipped options:
+ * fire whenever the project is a tracked git repo, not only when an explicit
+ * gitleaks signal is present. gitleaks's own scan target is "a git repo's
+ * history/tree" — nearly every project qualifies, so this is meaningfully
+ * looser than {@link hasGitleaksSignal}. Used ONLY by `mode=full`'s
+ * fresh-fetch path (an explicitly-requested comprehensive review, where
+ * gitleaks's low cost — ~10MB binary, no external DB pull — and advisory-only
+ * findings make the stricter opt-in gate needlessly conservative); session_start
+ * and per-edit dispatch keep the strict {@link hasGitleaksSignal} gate
+ * unchanged, so day-to-day noise/cost stays exactly as conservative as before.
+ */
+export function hasGitRepo(cwd) {
+    try {
+        return fs.existsSync(path.join(cwd, ".git"));
+    }
+    catch {
+        return false;
+    }
+}
 // --- Client ---
 export class GitleaksClient extends SecurityScanClient {
     constructor(verbose = false) {
@@ -107,6 +134,10 @@ export class GitleaksClient extends SecurityScanClient {
     static hasGitleaksSignal(cwd) {
         return hasGitleaksSignal(cwd);
     }
+    /** Smart-default tier (#130) — see {@link hasGitRepo}'s doc comment. */
+    static hasGitRepo(cwd) {
+        return hasGitRepo(cwd);
+    }
     /**
      * Auto-install via the GitHub-release path (registered in
      * `clients/installer/index.ts`) when gitleaks isn't already on PATH.
@@ -118,18 +149,22 @@ export class GitleaksClient extends SecurityScanClient {
     /**
      * Scan a directory tree for secrets.
      *
-     * Skips early when the directory shows no gitleaks opt-in signal. When
-     * gitleaks is unavailable, returns an empty result with an explanatory
-     * summary rather than failing the session_start task.
+     * Skips early when the directory shows no gitleaks opt-in signal — unless
+     * `requireSignal: false` (the `mode=full` fresh-fetch path uses this to
+     * apply the looser #130 "smart-default" gate, {@link hasGitRepo}, instead;
+     * session_start and per-edit dispatch never pass this, so their behavior
+     * is unchanged). When gitleaks is unavailable, returns an empty result
+     * with an explanatory summary rather than failing the session_start task.
      *
      * Re-entrancy safe: concurrent calls against the same root share a
      * single gitleaks process (mirrors `KnipClient` / `JscpdClient` /
      * `GovulncheckClient`).
      */
-    async scan(cwd) {
+    async scan(cwd, options) {
         const targetDir = path.resolve(cwd);
         const scannedAt = new Date().toISOString();
-        if (!GitleaksClient.hasGitleaksSignal(targetDir)) {
+        const requireSignal = options?.requireSignal ?? true;
+        if (requireSignal && !GitleaksClient.hasGitleaksSignal(targetDir)) {
             return {
                 ...EMPTY_RESULT,
                 success: true,