pi-lens 4.1.2 → 4.1.4

package/dist/clients/pipeline.js

@@ -25,7 +25,6 @@ import { classifyProbeFailure, createAvailabilityChecker, createAvailabilityLatc
 import { findDetektConfig } from "./dispatch/runners/detekt.js";
 import { detectFileKind, getFileKindLabel } from "./file-kinds.js";
 import { detectFileChangedAfterCommand, getProjectIgnoreMatcher, isExcludedDirName, } from "./file-utils.js";
-import { isInSpawnTimeoutCooldown } from "./spawn-timeout-cooldown.js";
 import { logLatency } from "./latency-logger.js";
 import { emitLensAnalysisComplete } from "./lens-events.js";
 import { publishFilesTouched } from "./bus-publish.js";
@@ -35,7 +34,8 @@ import { clearGraphCache } from "./review-graph/builder.js";
 import { BoundedLruCache } from "./bounded-cache.js";
 import { RUNTIME_CONFIG } from "./runtime-config.js";
 import { getAmbientAbortSignal, safeSpawnAsync } from "./safe-spawn.js";
-import { combineAbortSignals } from "./deadline-utils.js";
+import { bounded } from "./deadline-utils.js";
+import { enabledAuxiliaryLspServerIds } from "./dispatch/auxiliary-lsp.js";
 import { recordDegradationOnce } from "./degradation-ledger.js";
 import { dropFindingsForMissingPaths } from "./advisory-provenance.js";
 import { getAutofixPolicyForFile, getPreferredAutofixTools, getRubocopCommand, hasBiomeConfig, hasDetektConfig, hasEslintConfig, hasGolangciConfig, hasKtfmtConfig, hasKtlintConfig, hasOxlintConfig, hasRubocopConfig, hasSqlfluffConfig, hasStylelintConfig, markdownlintConfigArgs, } from "./tool-policy.js";
@@ -338,17 +338,10 @@ async function tryDetektFix(filePath, cwd) {
     const absPath = path.resolve(cwd, filePath);
     return detectFileChangedAfterCommand(filePath, cmd, ["--auto-correct", "--input", absPath, "--config", configPath], cwd, [1, 2]);
 }
-// Exported for #1995 cooldown wiring tests: the guard on this lane is
-// one of three mutation-proof surfaces.
 export async function tryMarkdownlintFix(filePath, cwd) {
     const cmd = await resolveToolCommandWithInstallFallback(cwd, "markdownlint");
     if (!cmd)
         return 0;
-    // #1995: skip the spawn entirely when the command is cooling down after a
-    // timeout — detectFileChangedAfterCommand also self-guards, but a wedged
-    // command should not even reach a second budget in the hot loop.
-    if (isInSpawnTimeoutCooldown(cmd))
-        return 0;
     // Shared config-args seam (#1247): the lint runner consumes the same
     // builder, so the bare --fix here can never fall back to markdownlint's
     // default all-rules-on config again (the whole-file CHANGELOG/AGENTS
@@ -695,7 +688,6 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
             const abort = getAmbientAbortSignal();
             if (abort?.aborted)
                 return;
-            const bail = combineAbortSignals(abort, AbortSignal.timeout(budgetMs));
             const startedAt = Date.now();
             const touch = lspService
                 .touchFile(filePath, fileContent, {
@@ -709,13 +701,45 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
                 dbg(`LSP resync after autofix error: ${err}`);
                 return "done";
             });
-            const bailed = new Promise((resolve) => {
-                if (!bail || bail.aborted)
-                    return resolve("bailed");
-                bail.addEventListener("abort", () => resolve("bailed"), { once: true });
+            // #2540: Kick off auxiliary server acquisition concurrently and unawaited
+            // with the ambient turn signal so auxiliary warmup overlaps with the primary
+            // server during resync. Leaves the single-occupancy deferred slot (#2509)
+            // free for actionable-warnings while Escape mid-turn abandons the wait.
+            //
+            // #2582 F3 — the #1766 F3 invariant re-opened for a different method.
+            // #2540 placed this kick-off BEFORE the primary touch, inside
+            // resyncLspFile's swallow-all catch, so anything that threw out of
+            // auxiliary acquisition abandoned the PRIMARY sync before it started:
+            // no touchFile, and no lsp_sync_abandoned record for the stall.
+            // Auxiliary warmup is a best-effort OVERLAP, never a precondition:
+            // the primary touch is already in flight above, and the async IIFE
+            // turns a synchronous throw out of the call into a rejection so
+            // `.catch` covers both failure directions. Order and containment are
+            // the invariant; do not hoist this back above the touch.
+            const auxServerIds = enabledAuxiliaryLspServerIds(getFlag);
+            if (auxServerIds.length > 0) {
+                void (async () => lspService.getAuxiliaryClientsForFile(filePath, new Set(auxServerIds), undefined, LSP_SPAWN_BUDGET_MS, abort, "tool_result_edit"))().catch(() => { });
+            }
+            // #2523 slice 2: this was `combineAbortSignals(abort,
+            // AbortSignal.timeout(budgetMs))` fed into a hand-rolled
+            // `Promise.race` — a private fifth copy of "deadline AND signal".
+            // `bounded()` is the same thing with the abandonment recorded, and
+            // without the composite signal that #2530 review F4 measured
+            // accumulating on the SOURCE.
+            //
+            // `touch` never rejects (it catches above) and never resolves
+            // `undefined`, so `undefined` here means exactly "a bound fired".
+            const outcome = await bounded(touch, {
+                ms: budgetMs,
+                // The ambient turn signal: set for the whole tool_result path and
+                // absent only in a bare unit harness, where the wall budget is
+                // still live (`bounded()` reads a missing signal as one that
+                // never aborts).
+                signal: abort,
+                hook: "tool_result_edit",
+                label: "resyncLspFile",
             });
-            const outcome = await Promise.race([touch, bailed]);
-            if (outcome === "bailed") {
+            if (outcome === undefined) {
                 // Abandon the still-pending write; the edit continues. Log it so this
                 // stall — previously an invisible hang — is queryable in latency.log.
                 //
@@ -725,12 +749,18 @@ export async function resyncLspFile(filePath, fileContent, needsContentRefresh,
                 // old wording blamed as "slow/wedged" did not exist yet. Distinguish
                 // the two via a fresh, synchronous inFlight lookup so the record keeps
                 // the discriminating identity (which server, which lifecycle state).
-                // Guarded: a test double or future service shape lacking the method
-                // must degrade to the old "timeout"/slow-wedged wording, not throw
-                // into the catch below and suppress this record entirely (#1766 F3).
-                const spawnInFlight = !abort?.aborted &&
-                    typeof lspService.isSpawnInFlight === "function" &&
-                    lspService.isSpawnInFlight(filePath);
+                // #2592: the `typeof lspService.isSpawnInFlight === "function"`
+                // hedge that used to wrap this call is GONE. It existed for one
+                // reason — 19 hand-rolled `getLSPService` doubles that lacked the
+                // method, whose TypeError would have landed in the catch below and
+                // suppressed this record entirely (#1766 F3) — and that population
+                // is now zero: every double is seeded from
+                // `makeLspServiceDouble`, `tests/support/lsp-double-baseline.json`
+                // is `{}`, and `tests/config/lsp-service-double-sweep.test.ts` reds
+                // on a fresh hand-rolled one. The real `LSPService` has always had
+                // the method (clients/lsp/index.ts), so the fallback was a test
+                // shape leaking into production — AGENTS.md shape 7.
+                const spawnInFlight = !abort?.aborted && lspService.isSpawnInFlight(filePath);
                 const reason = abort?.aborted
                     ? "aborted"
                     : spawnInFlight
@@ -791,12 +821,29 @@ export async function runFormatPhase(filePath, getFormatService, dbg) {
     let formatChanged = false;
     let formattersUsed = [];
     const formatFailures = [];
+    const formatUnavailable = [];
     let fileContent;
     const formatService = getFormatService();
     try {
         formatService.recordRead(filePath);
         const result = await formatService.formatFile(filePath);
-        formattersUsed = result.formatters.map((f) => f.name);
+        // An unavailable tool is NOT a formatter that ran (#2413): keep it out of
+        // `formattersUsed` (which drives change bookkeeping / turn summaries) and
+        // out of `formatFailures` (which requeues). Record it once, distinctly.
+        for (const f of result.formatters) {
+            if (f.outcome !== "unavailable")
+                continue;
+            const reason = f.error ?? "formatter executable not found";
+            formatUnavailable.push({ formatter: f.name, reason });
+            recordDegradationOnce({
+                kind: "formatter-unavailable",
+                subject: `${f.name}:${path.basename(filePath)}`,
+                reason,
+            });
+        }
+        formattersUsed = result.formatters
+            .filter((f) => f.outcome !== "unavailable")
+            .map((f) => f.name);
         if (result.anyChanged) {
             formatChanged = true;
             dbg("autoformat: " +
@@ -836,7 +883,13 @@ export async function runFormatPhase(filePath, getFormatService, dbg) {
     catch {
         fileContent = undefined;
     }
-    return { formatChanged, formattersUsed, formatFailures, fileContent };
+    return {
+        formatChanged,
+        formattersUsed,
+        formatFailures,
+        formatUnavailable,
+        fileContent,
+    };
 }
 /**
  * Build the 🔴 STOP blocker output with an inline code snippet for each

package/dist/clients/probe-home-state.js

@@ -0,0 +1,228 @@
+/**
+ * The #2506 probe-home redirect, whole: the decision, the per-process memo it
+ * is cached in, and the degradation event that decision produced.
+ *
+ * WHAT IT DECIDES. An ad-hoc probe against the BUILT `clients/*.js` — a bare
+ * `node -e`, a throwaway `.mjs`, a harness script — has no `PI_LENS_HOME` pin,
+ * so every logger and ledger it touches used to write into the maintainer's
+ * REAL `~/.pi-lens`. Confirmed live on 2026-09-02: two review probes left 42
+ * rows of `/p/.pi-lens.json` fixture garbage in real telemetry. When
+ * `PI_LENS_HOME` is unset and the process looks like a probe — `PILENS_PROBE=1`,
+ * a `cwd` inside a specific agent worktree, or a `cwd` under `os.tmpdir()` —
+ * `resolveProbeHomeDir()` answers with a per-probe directory instead.
+ *
+ * WHY IT ALL LIVES HERE and not beside its `getGlobalPiLensDir()` sibling in
+ * `file-utils.ts`, where round 2 of #2516 left it. `file-utils.ts` sits on an
+ * import cycle (it still does, via `safe-spawn.js` -> `resource-sampler.js` ->
+ * `instance-reaper.js` -> `file-utils.js`; the shorter route through
+ * `degradation-ledger.js` -> `extension-log.js` was this move's doing —
+ * `extension-log.ts` imported `file-utils.ts` for THIS function and nothing
+ * else, so the edge went with it, and the known-violations baseline dropped
+ * from 33 pinned cycles to 12 with none added). Fifteen log-family modules
+ * call `getGlobalPiLensLogDir()` at their OWN module
+ * top level. Under vitest's vite-SSR transform each import becomes a
+ * `__vite_ssr_import_N__` variable assigned in source order, so one of those
+ * top-level calls re-enters `file-utils.ts` while its body is only PARTWAY
+ * through those assignments — and a resolver sitting there then dereferences a
+ * binding that has not been assigned yet, throwing `ReferenceError: Cannot
+ * access '__vite_ssr_import_N__' before initialization`. Measured live: the
+ * re-entry arrives through `file-utils.ts`'s FIFTH import,
+ * `spawn-timeout-cooldown.js`, so every binding declared from the sixth import
+ * onward is unsafe on that path — which is most of the file.
+ *
+ * Round 2 of #2516 papered over that with an `isTestMode()` early return placed
+ * ahead of the first unsafe dereference. That was load-order luck, not a
+ * design: moving `file-utils.ts`'s own `isTestMode` import from fifth to last
+ * makes the GUARD LINE ITSELF throw the same error. It also DEFEATED the
+ * redirect for every process that has `VITEST` set but no `PI_LENS_HOME` pin —
+ * vitest's own globalSetup/child processes — sending their logs to the real
+ * home: the exact hermeticity hole the redirect exists to close.
+ *
+ * THIS module is off that cycle. It imports only node builtins and
+ * `path-utils.js`, itself a leaf (node builtins plus the vendored, zero-import
+ * `deps/minimatch.js`). A module off every cycle is fully evaluated before any
+ * importer's body runs — in plain ESM and under the vite-SSR transform alike —
+ * so none of its own bindings can ever be observed uninitialized, wherever an
+ * importer chooses to place the import. That is what makes the guard
+ * unnecessary rather than merely well-placed, and it is why module-scope
+ * `const`s (including the `Symbol.for` below) are ordinary here where they were
+ * a hazard in `file-utils.ts`.
+ *
+ * `tests/config/global-dir-probe-redirect.test.ts` pins the behaviour through
+ * real spawned `node` children, including the VITEST-set-but-unpinned case.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isUnderDir, normalizeFilePath } from "./path-utils.js";
+/**
+ * The memo lives in a process-wide `globalThis` slot rather than a plain
+ * module-scope `let` so that a bundled `dist/index.js` and the loose
+ * `clients/*.js` loaded into the same process — the shape #335 ships — share
+ * ONE decision instead of memoizing two. A `Symbol.for` key is interned by
+ * string, so both copies of this module resolve to the same slot.
+ */
+const RESOLUTION_SLOT = Symbol.for("pi-lens.probe-home-state.resolution");
+/** The memoized resolution for this process, or `undefined` before first use. */
+export function getProbeHomeResolution() {
+    return globalThis[RESOLUTION_SLOT];
+}
+/**
+ * The degradation row for a redirect that actually happened, or `undefined`
+ * when this process was not redirected (or has not resolved yet).
+ * `degradation-ledger.ts`'s `getDegradationSummary()` is the only caller — it
+ * folds this at READ time rather than having the resolver push a row, because a
+ * direct import between `file-utils.ts` and `degradation-ledger.ts` in EITHER
+ * direction (a dynamic `import()` included) adds unpinned `no-client-cycles`
+ * violations to the cycle named in this module's doc comment.
+ */
+export function getProbeHomeRedirectEvent() {
+    return getProbeHomeResolution()?.event;
+}
+/**
+ * Where pi-lens writes its LOGS, ledger rows and debug dumps: `~/.pi-lens/` by
+ * default, exactly like `getGlobalPiLensDir()` in `file-utils.ts` — but
+ * redirected to a per-probe directory when this process looks like an ad-hoc
+ * probe rather than a real pi session (#2506).
+ *
+ * Every log-family writer routes here: `latency.log`, `extension.log`,
+ * `sessionstart.log`, `cascade.log`, `read-guard.log`, `tree-sitter.log`,
+ * `word-index.log`, `bus-events.log`, `dispositions.log`, `dead-code.log`,
+ * `ast-grep-tools.log`, `actionable-warnings.log`, `review-graph.log`, the
+ * `logs/*.jsonl` diagnostic dir, the debug handle/heap dumps,
+ * `log-cleanup.ts`'s sweep over all of the above, and `smells-rollup.ts`'s
+ * read-side tail of `latency.log`/`bus-events.log` (a reader, but it must
+ * follow the same root or it tails a file nobody is writing).
+ *
+ * WHY IT LIVES IN THIS MODULE and not next to its `getGlobalPiLensDir()`
+ * sibling in `file-utils.ts` — see this file's header. Fifteen of the writers
+ * listed above call this function at their OWN module top level, and
+ * `file-utils.ts` is on an import cycle, so resolving from there could observe
+ * `file-utils.ts` mid-initialization. Resolving from a module off every cycle
+ * cannot.
+ *
+ * `PI_LENS_HOME` wins over any redirect, which is how
+ * `tests/support/vitest-setup.ts` keeps test workers hermetic. Note the
+ * redirect still applies under vitest for processes that setup does not cover
+ * (globalSetup, and children spawned without the pin): #2516 round 2's
+ * `isTestMode()` guard sent exactly those to the developer's real home.
+ *
+ * Deliberately does NOT write a line to the terminal when it fires. #1333 gives
+ * pi sole ownership of the TTY, and
+ * `tests/clients/extension-terminal-silence.test.ts` enforces that nothing
+ * under `clients/` calls `process.std*.write` or `console.*` (round 2 of
+ * #2506 shipped a `process.stderr.write` here and was red in CI for exactly
+ * that). Nor can it log through `extension-log.ts`'s
+ * `createSubsystemLogger`: that module imports THIS one, so an import back
+ * the other way would close a new, unpinned `no-client-cycles` cycle — and
+ * `extension.log` is itself redirected by this very function, so the line
+ * would land in the probe home nobody reads. The durable signal is the
+ * `global-dir-probe-redirect` degradation row instead, folded into
+ * `getDegradationSummary()` at read time via
+ * `getProbeHomeRedirectEvent()` above.
+ */
+export function getGlobalPiLensLogDir() {
+    const override = process.env.PI_LENS_HOME?.trim();
+    if (override)
+        return path.resolve(override);
+    return resolveProbeHomeDir() ?? path.join(os.homedir(), ".pi-lens");
+}
+/**
+ * Resolve the probe-home redirect at most ONCE per process, caching both the
+ * "yes, here" and the "no redirect" answers (#2506 round 3, F5). Round 2 read
+ * `process.cwd()` live on every call, which gave a single process up to three
+ * different global dirs as it chdir'd, and re-ran the whole decision on the hot
+ * logging path.
+ *
+ * `undefined` means "no redirect applies"; `getGlobalPiLensLogDir()` above
+ * falls back to the real home. This function never consults `PI_LENS_HOME` —
+ * that pin is handled by its caller, ahead of this decision, so a pinned
+ * process never memoizes a probe answer it would then keep after the pin
+ * changed.
+ */
+function resolveProbeHomeDir() {
+    const slot = globalThis;
+    const cached = slot[RESOLUTION_SLOT];
+    if (cached)
+        return cached.probeHome;
+    const cwd = process.cwd();
+    const probeHome = computeProbeHomeDir(cwd);
+    slot[RESOLUTION_SLOT] = {
+        probeHome,
+        event: probeHome ? { probeHome, cwd } : undefined,
+    };
+    return probeHome;
+}
+/**
+ * Clears the memoized decision AND the event it produced, so the next
+ * `getGlobalPiLensLogDir()` call re-resolves from scratch. Exercised by
+ * `tests/config/global-dir-probe-redirect.test.ts`, which drives the resolver
+ * repeatedly under different in-process conditions; without it the first call
+ * in a worker would pin the answer for every later case in the same file.
+ */
+export function _resetProbeHomeRedirectStateForTests() {
+    globalThis[RESOLUTION_SLOT] = undefined;
+}
+/** The redirect decision itself. */
+function computeProbeHomeDir(cwd) {
+    // The explicit force wins first: it is how a probe run from an ordinary
+    // project checkout opts in, and it must work even under a harness that has
+    // set a test-mode marker but no PI_LENS_HOME.
+    if (process.env.PILENS_PROBE === "1") {
+        return path.join(cwd, ".pi-lens-probe-home");
+    }
+    const worktreeRoot = findAgentWorktreeRoot(cwd);
+    if (worktreeRoot)
+        return path.join(worktreeRoot, ".pi-lens-probe-home");
+    if (isUnderRealDir(cwd, os.tmpdir())) {
+        return path.join(cwd, ".pi-lens-probe-home");
+    }
+    return undefined;
+}
+/**
+ * The directory of the SPECIFIC agent worktree containing `cwd`, or
+ * `undefined` when `cwd` is not inside one.
+ *
+ * Requires at least one path segment AFTER `worktrees/`, and anchors the
+ * probe home at that segment rather than at the live `cwd` (#2506 round 3,
+ * F5). Round 2's trailing `(\/|$)` alternative also matched a `cwd` of
+ * `.claude/worktrees` ITSELF, which would have put the probe home in the
+ * SHARED worktrees parent — every concurrent agent on the box writing into
+ * one directory, the cross-agent collision this redirect is supposed to
+ * prevent. Anchoring at the worktree also means a probe run from a
+ * subdirectory (`<worktree>/clients`) and one run from the worktree root
+ * agree on a single probe home instead of scattering one per cwd.
+ */
+function findAgentWorktreeRoot(cwd) {
+    const normalized = normalizeFilePath(path.resolve(cwd));
+    const match = /(?:^|\/)\.claude\/worktrees\/[^/]+(?:\/|$)/.exec(normalized);
+    if (!match)
+        return undefined;
+    return normalized.slice(0, match.index + match[0].length).replace(/\/$/, "");
+}
+/**
+ * `isUnderDir`, but with both sides resolved through `realpath` first
+ * (#2506 round 3, F7).
+ *
+ * On macOS `os.tmpdir()` reports `/var/folders/...` while a `cwd` created
+ * under it resolves to `/private/var/folders/...` (`/var` is a symlink to
+ * `/private/var`), so the two NEVER prefix-match unresolved and the tmpdir
+ * branch would be dead on every Mac. Windows has the same shape with 8.3
+ * short names and substituted drives. Both sides go through the same
+ * function, so `realpathSync.native`'s canonical Windows casing applies
+ * consistently; the result is used only for this containment test, never to
+ * build the returned path, so no casing change can leak into a log path.
+ * Best-effort by design: a path that does not exist yet (or an EPERM) falls
+ * back to its literal form rather than throwing on the logging hot path.
+ */
+function isUnderRealDir(child, parent) {
+    return isUnderDir(toRealPath(child), toRealPath(parent));
+}
+function toRealPath(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return target;
+    }
+}

package/dist/clients/process-bridge.js

@@ -0,0 +1,66 @@
+/**
+ * Shared process-bridge registration helper (#2437).
+ *
+ * `clients/read-bridge.ts` (#1265) and `clients/mutation-bridge.ts` (#2423)
+ * each mount a versioned, frozen method-table object at a well-known
+ * `globalThis[Symbol.for("pi-lens:...")]` key so a same-process producer can
+ * reach pi-lens's bookkeeping without importing its internals. Both bridges
+ * carried an identical mount body — a first-wins existence check,
+ * `Object.freeze`, and a non-writable/non-configurable `Object.defineProperty`
+ * — differing only in their key and method table (named by the #2432 review,
+ * refs #2423). This module owns that body once.
+ *
+ * NOT `clients/process-singletons.ts` (#2146): that module keeps a single
+ * MUTABLE, adopt-if-version-compatible value per "family" inside ONE shared
+ * container (a different, single key mounts the container itself, and a
+ * version mismatch there means "discard and rebuild"). A bridge's contract is
+ * the opposite: the documented producer protocol reads
+ * `globalThis[Symbol.for("pi-lens:mutation-bridge")]` directly as a frozen,
+ * first-wins, unreplaceable property, and a version mismatch is the
+ * PRODUCER's problem — an unsupported bridge it should not call — never a
+ * signal for pi-lens to silently reset its own mount. Reusing the singleton
+ * container would change that documented external contract, so this stays a
+ * separate, deliberately smaller leaf built for the bridge shape only.
+ *
+ * STATIC IMPORTS: none, deliberately. Both `read-bridge.ts` and
+ * `mutation-bridge.ts` import this module; it must stay a dependency leaf so
+ * neither gains an edge onto anything else in `clients/` (`no-client-cycles`).
+ */
+/**
+ * Mount `build()`'s result at `globalThis[key]`, once per process.
+ *
+ * First-wins: if `key` already exists on `globalThis` — from an earlier call
+ * in this process, whether this bridge's own prior registration or a
+ * redundant re-activation — `build()` is never invoked and the existing
+ * mount is left untouched. The mounted value is frozen and installed
+ * non-writable/non-configurable so no later code can silently replace or
+ * extend it; the `in` check above is what keeps a redundant call from
+ * throwing on that now-frozen property.
+ */
+export function registerProcessBridge(key, build) {
+    if (key in globalThis)
+        return;
+    const bridge = Object.freeze(build());
+    Object.defineProperty(globalThis, key, {
+        value: bridge,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+}
+/**
+ * The bridge mounted at `key`, or `undefined` when nothing is mounted, the
+ * mounted value is not an object, or its `version` does not equal `version`.
+ * A version mismatch means "not a bridge this caller recognizes" — never
+ * adopted and never reset; the reset-on-mismatch behavior belongs to
+ * `process-singletons.ts`'s different contract, not this one.
+ */
+export function getProcessBridge(key, version) {
+    const bridge = globalThis[key];
+    if (!bridge || typeof bridge !== "object")
+        return undefined;
+    const candidate = bridge;
+    if (candidate.version !== version)
+        return undefined;
+    return candidate;
+}