gitnexus 1.6.4-rc.99 → 1.6.4

package/dist/cli/publish.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `gitnexus publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+export interface PublishOptions {
+    /** Override the auto-derived `owner/repo` id. */
+    id?: string;
+    /** Treat the cwd as the repo root (skip git-root walk). */
+    skipGit?: boolean;
+}
+export declare const publishCommand: (inputPath?: string, options?: PublishOptions) => Promise<void>;

package/dist/cli/publish.js

@@ -0,0 +1,174 @@
+/**
+ * `gitnexus publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+import path from 'path';
+import { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, } from '../_shared/index.js';
+import { getGitRoot, getRemoteOriginUrl, getCurrentCommit } from '../storage/git.js';
+import { hasIndex } from '../storage/repo-manager.js';
+import { cliInfo, cliError } from './cli-message.js';
+const REGISTER_HINT = 'Register your repo once with: npx @understand-quickly/cli add\n' +
+    'Or use the wizard: https://looptech-ai.github.io/understand-quickly/add.html';
+/**
+ * Hard cap on the dispatch fetch to keep CI publish steps from stalling
+ * for the OS TCP timeout (~2 min) when api.github.com is unreachable.
+ * Matches the pattern used in `src/core/embeddings/http-client.ts`.
+ */
+const DISPATCH_TIMEOUT_MS = 15_000;
+export const publishCommand = async (inputPath, options = {}) => {
+    // ── 0. Token gate FIRST — guarantees true no-op without the token. ──
+    // The README, CLI --help, and PR body all promise "exit 0 without
+    // UNDERSTAND_QUICKLY_TOKEN". Doing the index/repo-root checks before
+    // the token gate would make those promises false for users who haven't
+    // run `gitnexus analyze` yet but want to verify the command is wired.
+    const token = process.env[UNDERSTAND_QUICKLY_TOKEN_ENV];
+    if (!token) {
+        cliInfo(`[understand-quickly] ${UNDERSTAND_QUICKLY_TOKEN_ENV} is not set — skipping dispatch.\n` +
+            `Set it to a fine-grained PAT with "Repository dispatches: write" on ` +
+            `looptech-ai/understand-quickly to enable instant resync.\n` +
+            `(Without the token, the registry's nightly sync still picks up your entry.)`, { skipped: 'no-token' });
+        return;
+    }
+    // ── 1. Resolve the repo root (same precedence as `analyze`) ──────────
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (options.skipGit) {
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            cliError('[understand-quickly] not inside a git repository.\n' +
+                'Run from a repo, or pass --skip-git to publish from the current directory.');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    // ── 2. Confirm a GitNexus index exists ───────────────────────────────
+    // Publishing without an index is almost always a mistake — the
+    // registry's nightly sync would fetch a stale or missing graph file
+    // and mark the entry `missing`. Refuse loudly with a fix-it hint.
+    if (!(await hasIndex(repoPath))) {
+        cliError(`[understand-quickly] no GitNexus index found at ${repoPath}/.gitnexus.\n` +
+            'Run `gitnexus analyze` first, then re-run `gitnexus publish`.');
+        process.exitCode = 1;
+        return;
+    }
+    // ── 3. Derive the registry id ─────────────────────────────────────────
+    const id = options.id ?? parseOwnerRepoFromRemote(getRemoteOriginUrl(repoPath) ?? undefined) ?? null;
+    if (!id || !isValidOwnerRepo(id)) {
+        cliError(`[understand-quickly] could not derive a registry id from this repo.\n` +
+            `Pass --id <owner/repo> explicitly (e.g. --id looptech-ai/${path.basename(repoPath)}).\n` +
+            REGISTER_HINT);
+        process.exitCode = 1;
+        return;
+    }
+    // ── 4. Fire the dispatch ─────────────────────────────────────────────
+    const payload = buildUqDispatchPayload(id);
+    let response;
+    try {
+        response = await fetch(UNDERSTAND_QUICKLY_DISPATCH_URL, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${token}`,
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+                'User-Agent': 'gitnexus-cli',
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(DISPATCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        // `AbortSignal.timeout()` throws a `DOMException` with `name ===
+        // 'TimeoutError'` on Node 18.14+ (and on browsers/Bun). It is NOT
+        // a plain `AbortError`. Match the pattern used in
+        // gitnexus/src/core/embeddings/http-client.ts so the user sees the
+        // targeted "timed out" message instead of a generic "operation
+        // was aborted".
+        const isTimeout = err instanceof DOMException && err.name === 'TimeoutError';
+        if (isTimeout) {
+            cliError(`[understand-quickly] dispatch timed out after ${DISPATCH_TIMEOUT_MS}ms. ` +
+                `Check network access to api.github.com and retry.`, { id });
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            cliError(`[understand-quickly] dispatch network error: ${msg}`, { id });
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // GitHub returns 204 on success. Distinct branches for 401/403/404/422
+    // so users debug without checking the docs.
+    if (response.status === 204) {
+        await response.body?.cancel().catch(() => { });
+        // `getCurrentCommit` is only meaningful in the success path — moving
+        // it inside this branch removes a wasted child-process spawn on every
+        // error response (LOW 7).
+        const commit = getCurrentCommit(repoPath);
+        cliInfo(`[understand-quickly] dispatched sync-entry for ${id}` +
+            (commit ? ` @ ${commit.slice(0, 7)}` : '') +
+            '.\n' +
+            `Note: a 204 only confirms GitHub accepted the dispatch. Whether the ` +
+            `registry workflow finds an entry for "${id}" is logged at ` +
+            `https://github.com/looptech-ai/understand-quickly/actions/workflows/sync.yml`, { id, commit, status: response.status });
+        return;
+    }
+    if (response.status === 401) {
+        cliError(`[understand-quickly] dispatch returned 401 — the ${UNDERSTAND_QUICKLY_TOKEN_ENV} value is invalid or expired.\n` +
+            `Regenerate a fine-grained PAT at https://github.com/settings/personal-access-tokens ` +
+            `with Repository access scoped to looptech-ai/understand-quickly and the ` +
+            `"Repository dispatches: write" permission, then retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 403) {
+        cliError(`[understand-quickly] dispatch returned 403 — the token authenticated but ` +
+            `lacks the "Repository dispatches: write" permission on ` +
+            `looptech-ai/understand-quickly. Edit the PAT scopes and retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 404) {
+        cliError(`[understand-quickly] dispatch returned 404 — the token cannot reach ` +
+            `looptech-ai/understand-quickly. Verify the PAT has Repository access to ` +
+            `that exact repo (not just your own org).`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 422) {
+        // Malformed event_type / client_payload — a code bug in this CLI,
+        // not a user mistake. Surface so we get bug reports.
+        const body422 = await response.text().catch(() => '');
+        cliError(`[understand-quickly] dispatch returned 422 (this is a CLI bug; please report).\n` +
+            `Body: ${body422 || '(empty)'}`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    // 5xx and anything else → bubble the body so the user has something to act on.
+    const body = await response.text().catch(() => '');
+    cliError(`[understand-quickly] dispatch failed with HTTP ${response.status}: ${body || '(empty body)'}`, { id, status: response.status });
+    process.exitCode = 1;
+};

package/dist/config/ignore-service.js

@@ -21,6 +21,8 @@ const DEFAULT_IGNORE_LIST = new Set([
     'bower_components',
     'jspm_packages',
     'vendor', // PHP/Go
+    'third_party', // C/C++ (Google-style vendored dependencies)
+    '3rdparty', // C/C++ (alternate spelling, also Qt convention)
     // 'packages' removed - commonly used for monorepo source code (lerna, pnpm, yarn workspaces)
     'venv',
     '.venv',

package/dist/core/embeddings/hf-env.d.ts

@@ -1,3 +1,4 @@
+import { CircuitBreaker } from '../../_shared/index.js';
 /** Per-attempt timeout for the full model download (5 minutes). */
 export declare const HF_DOWNLOAD_TIMEOUT_MS: number;
 /** Maximum total download attempts (1 initial + N-1 retries). */
@@ -72,41 +73,15 @@ export declare function applyHfEnvOverrides(env: HfEnvSubset): void;
 export declare function isNetworkFetchError(message: string): boolean;
 /** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
 export declare const CIRCUIT_OPEN_TAG = "hf-circuit-open";
-/** Circuit-breaker states. */
-type CircuitState = 'closed' | 'open' | 'half-open';
 /**
- * Circuit breaker for HuggingFace model downloads.
- *
- * After `failureThreshold` consecutive network failures the circuit opens and
- * all subsequent calls to `withHfDownloadRetry` fail immediately without
- * issuing any network requests. After `resetTimeoutMs` the circuit enters the
- * half-open state and the next call is attempted — if it succeeds the circuit
- * closes again; if it fails the circuit re-opens.
- *
- * Exported for unit-testing; production code should use the module-level
- * `hfDownloadCircuit` singleton.
+ * Module-level singleton shared by both embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Per-process
+ * only — not persisted across restarts. Backed by the shared
+ * `CircuitBreaker` from `gitnexus-shared` (same state machine, same
+ * semantics, plus the single-permit half-open gate that prevents
+ * recovery-time stampedes).
  */
-export declare class HfDownloadCircuitBreaker {
-    readonly failureThreshold: number;
-    readonly resetTimeoutMs: number;
-    private _state;
-    private _failures;
-    /** Timestamp of the last recorded failure (ms since epoch). */
-    lastFailureAt: number;
-    constructor(failureThreshold?: number, resetTimeoutMs?: number);
-    /** Effective state, factoring in the reset-timeout transition. */
-    get state(): CircuitState;
-    /** Returns true when the circuit is open and calls should be rejected. */
-    isOpen(): boolean;
-    /** Record a successful call — resets the failure counter and closes the circuit. */
-    recordSuccess(): void;
-    /** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
-    recordFailure(): void;
-    /** @internal Reset to initial state (used in tests). */
-    reset(): void;
-}
-/** Module-level singleton shared by both embedder entry points. */
-export declare const hfDownloadCircuit: HfDownloadCircuitBreaker;
+export declare const hfDownloadCircuit: CircuitBreaker;
 /** @internal Returns true for errors that should abort without retry (circuit-open). */
 export declare function isHfCircuitOpenError(message: string): boolean;
 /**
@@ -119,8 +94,6 @@ export declare function isHfDownloadFailure(message: string): boolean;
  *  `ETIMEDOUT` so that `isNetworkFetchError` classifies it correctly.
  */
 export declare function withDownloadTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T>;
-/** @internal Async sleep (exposed for testing). */
-export declare function sleep(ms: number): Promise<void>;
 export interface HfRetryOptions {
     /** Maximum total attempts including the initial one (default: `HF_MAX_ATTEMPTS`). */
     maxAttempts?: number;
@@ -132,7 +105,7 @@ export interface HfRetryOptions {
      * Circuit-breaker instance to use. Defaults to the module-level
      * `hfDownloadCircuit` singleton. Pass a fresh instance in tests.
      */
-    circuit?: HfDownloadCircuitBreaker;
+    circuit?: CircuitBreaker;
     /**
      * Optional callback invoked before each retry (not the initial attempt).
      * @param attempt - 1-based retry number
@@ -160,4 +133,3 @@ export interface HfRetryOptions {
  *   the calling code still fire.
  */
 export declare function withHfDownloadRetry<T>(fn: () => Promise<T>, options?: HfRetryOptions): Promise<T>;
-export {};

package/dist/core/embeddings/hf-env.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import { join } from 'node:path';
+import { CircuitBreaker, withRetry } from '../../_shared/index.js';
 // ---------------------------------------------------------------------------
 // Download resilience defaults
 // ---------------------------------------------------------------------------
@@ -85,61 +86,18 @@ export function isNetworkFetchError(message) {
 /** @internal Used by `withHfDownloadRetry` to mark a circuit-open rejection. */
 export const CIRCUIT_OPEN_TAG = 'hf-circuit-open';
 /**
- * Circuit breaker for HuggingFace model downloads.
- *
- * After `failureThreshold` consecutive network failures the circuit opens and
- * all subsequent calls to `withHfDownloadRetry` fail immediately without
- * issuing any network requests. After `resetTimeoutMs` the circuit enters the
- * half-open state and the next call is attempted — if it succeeds the circuit
- * closes again; if it fails the circuit re-opens.
- *
- * Exported for unit-testing; production code should use the module-level
- * `hfDownloadCircuit` singleton.
+ * Module-level singleton shared by both embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Per-process
+ * only — not persisted across restarts. Backed by the shared
+ * `CircuitBreaker` from `gitnexus-shared` (same state machine, same
+ * semantics, plus the single-permit half-open gate that prevents
+ * recovery-time stampedes).
  */
-export class HfDownloadCircuitBreaker {
-    failureThreshold;
-    resetTimeoutMs;
-    _state = 'closed';
-    _failures = 0;
-    /** Timestamp of the last recorded failure (ms since epoch). */
-    lastFailureAt = 0;
-    constructor(failureThreshold = CB_FAILURE_THRESHOLD, resetTimeoutMs = CB_RESET_TIMEOUT_MS) {
-        this.failureThreshold = failureThreshold;
-        this.resetTimeoutMs = resetTimeoutMs;
-    }
-    /** Effective state, factoring in the reset-timeout transition. */
-    get state() {
-        if (this._state === 'open' && Date.now() - this.lastFailureAt > this.resetTimeoutMs) {
-            this._state = 'half-open';
-        }
-        return this._state;
-    }
-    /** Returns true when the circuit is open and calls should be rejected. */
-    isOpen() {
-        return this.state === 'open';
-    }
-    /** Record a successful call — resets the failure counter and closes the circuit. */
-    recordSuccess() {
-        this._failures = 0;
-        this._state = 'closed';
-    }
-    /** Record a failed call — increments the counter and opens the circuit when the threshold is reached. */
-    recordFailure() {
-        this._failures++;
-        this.lastFailureAt = Date.now();
-        if (this._failures >= this.failureThreshold) {
-            this._state = 'open';
-        }
-    }
-    /** @internal Reset to initial state (used in tests). */
-    reset() {
-        this._failures = 0;
-        this._state = 'closed';
-        this.lastFailureAt = 0;
-    }
-}
-/** Module-level singleton shared by both embedder entry points. */
-export const hfDownloadCircuit = new HfDownloadCircuitBreaker();
+export const hfDownloadCircuit = new CircuitBreaker({
+    failureThreshold: CB_FAILURE_THRESHOLD,
+    cooldownMs: CB_RESET_TIMEOUT_MS,
+    key: 'hf-download',
+});
 // ---------------------------------------------------------------------------
 // Retry + timeout wrapper
 // ---------------------------------------------------------------------------
@@ -171,10 +129,6 @@ export function withDownloadTimeout(fn, timeoutMs) {
         });
     });
 }
-/** @internal Async sleep (exposed for testing). */
-export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 /**
  * Retry wrapper for HuggingFace model downloads with per-attempt timeout and
  * circuit-breaker protection.
@@ -214,37 +168,65 @@ export async function withHfDownloadRetry(fn, options = {}) {
         ? Math.min(Math.floor(envMaxAttempts), HF_MAX_ATTEMPTS_CAP)
         : HF_MAX_ATTEMPTS;
     const { maxAttempts = resolvedMaxAttempts, baseDelayMs = HF_BASE_DELAY_MS, timeoutMs = resolvedTimeout, circuit = hfDownloadCircuit, onRetry, } = options;
-    if (circuit.isOpen()) {
-        const secsUntilReset = Math.ceil((circuit.resetTimeoutMs - (Date.now() - circuit.lastFailureAt)) / 1000);
+    if (circuit.getState() === 'open') {
+        // Compute remaining cooldown without consuming a probe permit.
+        const openedAt = circuit.getOpenedAt();
+        const secsUntilReset = openedAt !== null ? Math.ceil((circuit.getCooldownMs() - (Date.now() - openedAt)) / 1000) : 0;
         throw new Error(`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit is open after repeated network failures` +
             (secsUntilReset > 0 ? ` — will reset in ~${secsUntilReset}s` : ''));
     }
-    let lastError = new Error('unknown error');
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        try {
+    // Retry budget delegated to `withRetry` from gitnexus-shared. The
+    // HF-specific bits — per-attempt timeout, network-vs-non-network
+    // classification, circuit-breaker recording, onRetry callback — wire
+    // through the `isRetryable` callback. `circuitTripped` is the
+    // sentinel that lets us replace the final thrown error with a
+    // CIRCUIT_OPEN_TAG message when the breaker tripped mid-loop.
+    let circuitTripped = false;
+    try {
+        return await withRetry(async () => {
             const result = await withDownloadTimeout(fn, timeoutMs);
             circuit.recordSuccess();
             return result;
+        }, {
+            maxAttempts,
+            baseDelayMs,
+            // Disable the cap to match the bespoke pure-exponential
+            // progression. With the default `HF_MAX_ATTEMPTS_CAP = 10` and
+            // `baseDelayMs = 2000`, the largest possible delay is
+            // `2000 * 2^9 = ~17 minutes` — bounded enough not to need a cap.
+            capDelayMs: Number.MAX_SAFE_INTEGER,
+            isRetryable: (err, attempt) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                if (!isNetworkFetchError(error.message)) {
+                    // Non-network error (e.g. CUDA unavailable) — propagate
+                    // without retry. Use recordNeutral so the breaker's existing
+                    // failure-count progress isn't reset by a non-network failure
+                    // that says nothing about the CDN's health.
+                    circuit.recordNeutral();
+                    return { retry: false };
+                }
+                circuit.recordFailure();
+                if (circuit.getState() === 'open') {
+                    // Circuit just tripped — fail fast, no more retries.
+                    circuitTripped = true;
+                    return { retry: false };
+                }
+                // Mirror the bespoke onRetry contract: fire only when there's
+                // actually a next attempt.
+                if (attempt + 1 < maxAttempts) {
+                    onRetry?.(attempt + 1, maxAttempts, error);
+                }
+                return { retry: true };
+            },
+        });
+    }
+    catch (err) {
+        if (circuitTripped) {
+            throw new Error(`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${CB_FAILURE_THRESHOLD} consecutive failures`);
         }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-            if (!isNetworkFetchError(lastError.message)) {
-                // Non-network error (e.g. CUDA unavailable) — propagate without retry
-                throw lastError;
-            }
-            circuit.recordFailure();
-            if (circuit.isOpen()) {
-                // Circuit just tripped — fail fast, no more retries
-                throw new Error(`${CIRCUIT_OPEN_TAG}: HuggingFace download circuit opened after ${circuit.failureThreshold} consecutive failures`);
-            }
-            if (attempt < maxAttempts - 1) {
-                const delay = baseDelayMs * Math.pow(2, attempt);
-                onRetry?.(attempt + 1, maxAttempts, lastError);
-                await sleep(delay);
-            }
-        }
+        // All retries exhausted — rethrow the last network error so
+        // isNetworkFetchError patterns in the calling code still match and
+        // surface HF_ENDPOINT guidance.
+        throw err;
     }
-    // All retries exhausted — throw the last network error so isNetworkFetchError
-    // patterns in the calling code still match and surface HF_ENDPOINT guidance.
-    throw lastError;
 }

package/dist/core/embeddings/http-client.d.ts

@@ -3,6 +3,12 @@
  *
  * Shared fetch+retry logic for OpenAI-compatible /v1/embeddings endpoints.
  * Imported by both the core embedder (batch) and MCP embedder (query).
+ *
+ * Network resilience is delegated to `resilientFetch` from
+ * `gitnexus-shared` — bounded retries with exponential-backoff jitter,
+ * `Retry-After` honored on 429, and an in-process circuit breaker that
+ * fails fast on a flapping endpoint. Per-attempt timeout is enforced
+ * via `AbortSignal.timeout` on the underlying fetch.
  */
 /**
  * Check whether HTTP embedding mode is active (env vars are set).

package/dist/core/embeddings/http-client.js

@@ -3,12 +3,20 @@
  *
  * Shared fetch+retry logic for OpenAI-compatible /v1/embeddings endpoints.
  * Imported by both the core embedder (batch) and MCP embedder (query).
+ *
+ * Network resilience is delegated to `resilientFetch` from
+ * `gitnexus-shared` — bounded retries with exponential-backoff jitter,
+ * `Retry-After` honored on 429, and an in-process circuit breaker that
+ * fails fast on a flapping endpoint. Per-attempt timeout is enforced
+ * via `AbortSignal.timeout` on the underlying fetch.
  */
+import { CircuitOpenError, ResilientFetchExhaustedError, resilientFetch } from '../../_shared/index.js';
 const HTTP_TIMEOUT_MS = 30_000;
 const HTTP_MAX_RETRIES = 2;
 const HTTP_RETRY_BACKOFF_MS = 1_000;
 const HTTP_BATCH_SIZE = 64;
 const DEFAULT_DIMS = 384;
+const HTTP_BREAKER_KEY = 'embeddings-http';
 /**
  * Build config from the current process.env snapshot.
  * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
@@ -67,10 +75,10 @@ const safeUrl = (url) => {
  * @param batchIndex - Logical batch number (for error context)
  * @param attempt - Current retry attempt (internal)
  */
-const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, attempt = 0) => {
+const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0) => {
     let resp;
     try {
-        resp = await fetch(url, {
+        resp = await resilientFetch(url, {
             method: 'POST',
             signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
             headers: {
@@ -78,32 +86,28 @@ const httpEmbedBatch = async (url, batch, model, apiKey, batchIndex = 0, attempt
                 Authorization: `Bearer ${apiKey}`,
             },
             body: JSON.stringify({ input: batch, model }),
+        }, {
+            breakerKey: HTTP_BREAKER_KEY,
+            retry: { maxAttempts: HTTP_MAX_RETRIES + 1, baseDelayMs: HTTP_RETRY_BACKOFF_MS },
         });
     }
     catch (err) {
-        // Timeouts should not be retried — the server is unresponsive.
-        // AbortSignal.timeout() throws DOMException with name 'TimeoutError'.
-        const isTimeout = err instanceof DOMException && err.name === 'TimeoutError';
-        if (isTimeout) {
+        if (err instanceof CircuitOpenError) {
+            throw new Error(`Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`);
+        }
+        if (err instanceof DOMException && err.name === 'TimeoutError') {
             throw new Error(`Embedding request timed out after ${HTTP_TIMEOUT_MS}ms (${safeUrl(url)}, batch ${batchIndex})`);
         }
-        // DNS, connection errors — retry with backoff
-        if (attempt < HTTP_MAX_RETRIES) {
-            const delay = HTTP_RETRY_BACKOFF_MS * (attempt + 1);
-            await new Promise((r) => setTimeout(r, delay));
-            return httpEmbedBatch(url, batch, model, apiKey, batchIndex, attempt + 1);
+        if (err instanceof ResilientFetchExhaustedError) {
+            throw new Error(`Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`);
         }
         const reason = err instanceof Error ? err.message : String(err);
         throw new Error(`Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`);
     }
     if (!resp.ok) {
-        const status = resp.status;
-        if ((status === 429 || status >= 500) && attempt < HTTP_MAX_RETRIES) {
-            const delay = HTTP_RETRY_BACKOFF_MS * (attempt + 1);
-            await new Promise((r) => setTimeout(r, delay));
-            return httpEmbedBatch(url, batch, model, apiKey, batchIndex, attempt + 1);
-        }
-        throw new Error(`Embedding endpoint returned ${status} (${safeUrl(url)}, batch ${batchIndex})`);
+        // resilientFetch already retried 5xx/429; any non-OK response here is
+        // a terminal client error (4xx other than 429).
+        throw new Error(`Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`);
     }
     const data = (await resp.json());
     return data.data;

package/dist/core/group/bridge-db.js

@@ -589,12 +589,13 @@ export async function openBridgeDbReadOnly(groupDir) {
             await new Promise((r) => setTimeout(r, delay));
         }
     }
-    // Pino's NDJSON serialization is structurally injection-resistant
-    // (CodeQL js/log-injection): groupDir and err.message are JSON-escaped
-    // by the serializer, so no manual CRLF / U+2028 / ANSI sanitization is
-    // needed. Demoted to debug — only fires when the bridge truly gave up
-    // after retries, and operators only need it at debug verbosity.
-    bridgeLogger.debug({ groupDir, err: lastErr, attempts: LBUG_OPEN_RETRY_ATTEMPTS }, 'openBridgeDbReadOnly gave up');
+    // Strip CRLF from user-controlled strings before logging to close
+    // CodeQL js/log-injection. Pino's NDJSON serialization already
+    // JSON-escapes all values, but we sanitize here as a defence-in-depth
+    // measure so CodeQL can see the taint flow is broken.
+    const safeGroupDir = String(groupDir).replace(/[\r\n]/g, ' ');
+    const safeErrMsg = lastErr instanceof Error ? String(lastErr.message).replace(/[\r\n]/g, ' ') : undefined;
+    bridgeLogger.debug({ groupDir: safeGroupDir, errMsg: safeErrMsg, attempts: LBUG_OPEN_RETRY_ATTEMPTS }, 'openBridgeDbReadOnly gave up');
     return null;
 }
 /* ------------------------------------------------------------------ */

package/dist/core/group/config-parser.js

@@ -1,8 +1,25 @@
 import { createRequire } from 'node:module';
 const _require = createRequire(import.meta.url);
 const yaml = _require('js-yaml');
-const VALID_CONTRACT_TYPES = ['http', 'grpc', 'thrift', 'topic', 'lib', 'custom'];
+const VALID_CONTRACT_TYPES = [
+    'http',
+    'grpc',
+    'thrift',
+    'topic',
+    'lib',
+    'custom',
+    'include',
+];
 const VALID_ROLES = ['provider', 'consumer'];
+// Defaults matter for backward compatibility: any group.yaml that omits a
+// `detect.<type>` key inherits its value from this constant. Adding a new
+// extractor that defaults to `true` silently changes the behavior of every
+// existing group on the next sync. New extractors must default to `false`
+// (opt-in) so operators consciously enable them via group.yaml.
+//
+// `includes`: opt-in. The C/C++ IncludeExtractor (PR #1156) ships disabled by
+// default; enable with `detect.includes: true` for groups containing C/C++
+// repos that need cross-repo header tracking.
 const DEFAULT_DETECT = {
     http: true,
     grpc: true,
@@ -10,6 +27,7 @@ const DEFAULT_DETECT = {
     topics: true,
     shared_libs: true,
     embedding_fallback: true,
+    includes: false,
     workspace_deps: false,
 };
 const DEFAULT_MATCHING = {