@herjarsa/omo-meta-governor 0.50.2 → 0.52.0

package/README.md

@@ -29,6 +29,8 @@
   - [Auto-upgrade (v0.26.0)](#auto-upgrade-v0260)
   - [Git hooks](#git-hooks)
   - [Process safeguards](#process-safeguards)
+  - [CLI-Anything hub (v0.28.0)](#cli-anything-hub-v0280)
+  - [On-demand upgrades (W4-C)](#on-demand-upgrades-w4-c)
 - [Persistence & observability](#persistence--observability)
 - [CI monitor (v0.25.0)](#ci-monitor-v0250)
 - [Configuration reference](#configuration-reference)
@@ -84,18 +86,18 @@ Minimal config to enable the governance pipeline:
 }
 ```
 
-### Oracle frequency (v0.38.4+, Option D)
+### Oracle frequency
 
 Controls when the plugin invokes Oracle for verification:
 
 ```jsonc
 {
   "oracle": {
-    // "per-stop" (default): Oracle invoked ONLY at the final-gate AND when
+    // "final-only" (default): Oracle invoked ONLY at the final-gate. Zero mid-work.
+    // "per-stop": Oracle invoked ONLY at the final-gate AND when
     // scoring reaches stop band (action === "stop"). warn/escalate log only.
-    // "final-only": Oracle invoked ONLY at the final-gate. Zero mid-work.
     // "off": Oracle never invoked automatically. Set oracleVerified manually.
-    "frequency": "per-stop"
+    "frequency": "final-only"
   }
 }
 ```
@@ -103,6 +105,18 @@ Controls when the plugin invokes Oracle for verification:
 The `<promise>DONE</promise>` / `<promise>PLAN-COMPLETE</promise>` final-gate
 ALWAYS invokes Oracle regardless of `oracle.frequency`.
 
+| `frequency` | Mid-work Oracle | Final-gate Oracle | Typical invocations / session |
+|---|---|---|---|
+| `final-only` (default) | Never — even `stop` decisions log without an Oracle prompt | Always | Exactly 1 (final-gate); zero mid-work interruptions |
+| `per-stop` | ONLY when scoring reaches the stop band (`action === "stop"`); `warn`/`escalate` log only (`escalation suppressed by oracle.frequency`) | Always | 1 (final-gate) + 1 per stop-level emergency |
+| `off` | Never invoked automatically | Never — set `oracleVerified` manually (e.g. via `omo_recall`) | 0 |
+
+Implementation: `selectEscalationTarget()` in `src/scoring-engine.ts`
+returns `null` for `off`/`final-only` (any action) and for `per-stop` unless
+action is `"stop"`; `src/plugin.ts` respects the `null` (logs `escalation
+suppressed by oracle.frequency`) while the DONE final-gate handler
+(`detectPlanCompleteSignal` path) invokes Oracle separately.
+
 ---
 
 ## What it does
@@ -404,6 +418,61 @@ Config: `graphSync.killOrphanedOnInit` (default `true`) — on graph-sync
 init the plugin sweeps orphaned `graphify`/`codegraph` processes left
 by previous crashed runs. Set to `false` to disable the sweep.
 
+### CLI-Anything hub (v0.28.0)
+
+Parallel to graph-sync, the plugin ensures the CLI-Anything ecosystem
+(`cli-hub` registry/installer + `npx skills` meta-skill) is installed and
+current. **Opt-out: enabled by default** — every default projection uses
+`!== false`, so omitting the block means ON:
+
+```jsonc
+{
+  "meta_governor": {
+    "cliAnything": {
+      "enabled": true,          // default true — opt-out
+      "autoInstall": true,      // default true
+      "autoUpgrade": true,      // default true
+      "upgradeCheckTtlMs": 86400000  // 24h registry-query TTL
+    }
+  }
+}
+```
+
+To disable (e.g. offline machines, hermetic tests):
+
+```jsonc
+{
+  "meta_governor": {
+    "cliAnything": { "enabled": false }
+  }
+}
+```
+
+Independent of `graphSync.enabled` (W1-A1 desanidado): disabling graphSync
+does NOT disable cliAnything and vice-versa. Both run fire-and-forget at
+factory invocation, never blocking session start. The test seam
+`__test_onCliAnythingInit` mirrors `__test_onGraphSyncInit` for placement
+assertions without spawning real subprocesses.
+
+### On-demand upgrades (W4-C)
+
+Two tools expose the backend upgrade path on demand (codegraph + graphify):
+
+| Tool | What it does | Use case |
+|------|--------------|----------|
+| `omo_upgrade_check` | Dry-run version table (installed / latest / upgrade-needed per backend). NEVER installs anything. | "Is an upgrade pending?" — safe to call any time |
+| `omo_upgrade_run` | Executes the upgrade path once. Respects the 24h TTL cache (`upgradeCheckTtlMs`, default `86400000`): skips with `skipped:true` when the cache is fresh. Best-effort, never throws. | "Upgrade the backends now" |
+
+Both are registered on all three surfaces: V1 `tool` hook (governance-enabled
+and governance-disabled paths), V2 (`registerOmoTools`), and MCP
+(`getAdapters()` + `MCP_TOOL_NAMES`).
+
+> **Nota `syncIntervalMs` (startup-only):** `syncIntervalMs` applies ONLY to
+> the `skillHub` registry sync (periodic background refresh of the skill
+> catalog). `omo_upgrade_check` / `omo_upgrade_run` are **on-demand /
+> startup-only** — they NEVER use `setInterval` and never poll in the
+> background.
+
 ## MCP server mode (v0.31.0)
 
 OpenCode Desktop and OpenChamber spawn `opencode serve` in HTTP/sidecar mode
@@ -575,6 +644,7 @@ All configuration lives under the `meta_governor` key in
 | `protocolEnforcement` | object | — | Sisyphus protocol enforcement. |
 | `skillPriming` | object | — | Proactive skill-selection nudge (v0.20.0). |
 | `graphSync` | object | — | Graph synchronization (auto-init codegraph/graphify). |
+| `cliAnything` | object | — | CLI-Anything hub auto-install + auto-upgrade (opt-out, enabled by default). |
 
 ### `decision`
 
@@ -615,9 +685,13 @@ All configuration lives under the `meta_governor` key in
 |-------|------|---------|-------------|
 | `saveDecisions` | boolean | `true` | Whether to save decision records. |
 | `saveLessons` | boolean | `true` | Whether to save lessons. |
-| `autoRemember.enabled` | boolean | `true` | v0.49.1: kill-switch for the Phase 4 auto-remember prompt (warn/escalate/stop → agentmemory_memory_save). Set `false` to disable it entirely. |
-| `autoRemember.cooldownMs` | number | `300000` | v0.49.1: min ms between two auto-remember fires in the same session. |
-| `autoRemember.dedupe` | boolean | `true` | v0.49.1: identical content is never re-queued in the same session. |
+| `autoRemember.enabled` | boolean | `false` | Opt-in kill-switch for the auto-remember prompt (escalate/stop only → `omo_remember`). Conscience fix 2026-09-27: default flipped `true` → `false`; `warn` no longer triggers. |
+| `autoRemember.cooldownMs` | number | `300000` | Min ms between two auto-remember fires in the same session. |
+| `autoRemember.dedupe` | boolean | `true` | Identical content (stable key: action + evidence sources + deviation categories, score floats excluded) is never re-queued in the same session. |
+| `conscience.enabled` | boolean | `false` | Master switch for conscience memory persistence (opt-in). |
+| `conscience.maxMemoriesPerSession` | integer | `5` | Max conscience memories persisted per session. |
+| `conscience.toolRoute` | enum | `omo_remember` | Tool route for conscience writes (`omo_remember` only). |
+| `conscience.requireNovelty` | boolean | `true` | When true, only novel structured content (`mistake`, `whatToDo`, `whereToGo`, `toolRoute`) is persisted; raw dumps forbidden. |
 
 ### `modelOverride`
 
@@ -674,6 +748,19 @@ All configuration lives under the `meta_governor` key in
 | `upgradeCachePath` | string | — | **v0.26.0** — path for the upgrade cache file. |
 | `checkGraphifyNeedsUpdate` | boolean | `true` | **v0.26.0** — run `graphify check-update` after upgrade. |
 
+### `cliAnything`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Opt-out master switch — set `cliAnything.enabled:false` to disable. Canonical `!== false` projection. |
+| `autoInstall` | boolean | `true` | Auto-install `cli-hub` + meta-skill when missing. |
+| `autoUpgrade` | boolean | `true` | Auto-upgrade on factory init (TTL-gated). |
+| `cachePath` | string | — | Upgrade-check cache file (effective default `newPluginPaths().cliAnythingUpgradeCheck`). |
+| `upgradeCheckTtlMs` | number | `86400000` | Min ms between registry queries (24h). Effective default applied at call-site (`plugin.ts`). |
+| `cliHubBin` | string | `"cli-hub"` | Path to `cli-hub` binary. |
+| `skillsBin` | string | `"npx skills"` | Path to `npx skills` invocation. |
+| `installScope` | enum | `"global"` | `"global"` \| `"project"`. |
+
 ---
 
 ## Architecture overview

package/dist/closed-loop-learning.d.ts

@@ -15,7 +15,26 @@
  * - Decisions go to agentmemory_memory_save (type: "fact").
  * - No file I/O, no MCP calls — just decision logic + DI write.
  */
-import type { AgentmemoryWriteBackend, ClosedLoopConfig, LearnFromOutcomeInput, LearnFromOutcomeOutput } from "./types";
+import type { AgentmemoryWriteBackend, ClosedLoopConfig, Decision, Deviation, LearnFromOutcomeInput, LearnFromOutcomeOutput } from "./types";
+/**
+ * v0.51.1 (P1 lesson-spam guard, Wave A T-5df16a0e): minimum lesson
+ * confidence. Lessons below this are noise: 5311 Action-continue rows at
+ * confidence 0.3 flooded recall. Only high-value lessons persist.
+ */
+export declare const MIN_LESSON_CONFIDENCE = 0.5;
+/**
+ * Lesson confidence for a decision: the strongest available signal -
+ * max(|score|, best evidence confidence) - clamped to [0.3, 0.8].
+ * Evidence confidence matters: a warn at -0.4 backed by 0.8-confidence
+ * evidence is high-value signal, while a neutral continue near 0 with no
+ * evidence collapses to the 0.3 floor (below MIN_LESSON_CONFIDENCE).
+ */
+export declare function lessonConfidenceForDecision(decision: Decision): number;
+/**
+ * Neutral continues carry no learnable signal and must never persist as
+ * lessons - they were the entire 5311-row Action-continue spam class.
+ */
+export declare function isNeutralContinueDecision(decision: Decision): boolean;
 /** Severity ordering for threshold comparison. */
 declare const SEVERITY_ORDER: Record<string, number>;
 /**
@@ -29,4 +48,53 @@ export declare function observeAndLearn(input: LearnFromOutcomeInput, backend: A
  * Helper: create a default ClosedLoopConfig.
  */
 export declare function defaultClosedLoopConfig(): ClosedLoopConfig;
+/**
+ * Conscience value-gate (D3). Single gate for all conscience memory writes.
+ *
+ * Requires ALL of:
+ * - action in {escalate, stop} (D1 — warn/continue never persist)
+ * - config.enabled
+ * - config.saveLessons !== false
+ * - severityMeetsThreshold(deviations, config.minSeverityToLearn)
+ * - novelty === true (caller-owned novelty check)
+ * - lessonCount < config.maxLessonsPerSession
+ */
+export interface ShouldPersistConscienceMemoryInput {
+    readonly action: Decision["action"];
+    readonly deviations: readonly Deviation[];
+    readonly config: ClosedLoopConfig;
+    readonly novelty: boolean;
+    readonly lessonCount: number;
+}
+export declare function shouldPersistConscienceMemory(input: ShouldPersistConscienceMemoryInput): boolean;
+/**
+ * Stable dedupe key (D5). Hash of stable fields only — action + sorted
+ * evidence sources + sorted deviation categories. Score floats are
+ * deliberately excluded: float jitter previously defeated dedupe.
+ */
+export interface ConscienceDedupeKeyInput {
+    readonly action: string;
+    readonly evidenceSources: readonly string[];
+    readonly deviationCategories: readonly string[];
+}
+export declare function conscienceDedupeKey(input: ConscienceDedupeKeyInput): string;
+/**
+ * Structured conscience memory content (D4/D6). Built via buildLessonContent
+ * + extractConcepts — never a raw dump. Delivery route is always the
+ * Zod-validated omo_remember tool.
+ */
+export interface BuildConscienceMemoryContentInput {
+    readonly action: "escalate" | "stop";
+    readonly mistake: string;
+    readonly whatToDo: string;
+    readonly whereToGo: string;
+    readonly toolRoute: "omo_remember";
+    readonly score: number;
+    readonly files: readonly string[];
+}
+export interface ConscienceMemoryContent {
+    readonly content: string;
+    readonly concepts: string[];
+}
+export declare function buildConscienceMemoryContent(input: BuildConscienceMemoryContentInput): ConscienceMemoryContent;
 export { SEVERITY_ORDER };

package/dist/config.d.ts

@@ -45,8 +45,10 @@ export interface MetaGovernorPluginConfig {
         /** v0.18.0: was silently dropped by loadOrchestratorConfig */
         defaultEscalationTarget?: "oracle" | "user";
         /**
-         * v0.38.4 Option D: Oracle invocation frequency. Derived from
-         * `oracle.frequency` (canonical) — exposed here only as a fallback.
+         * v0.38.4 Option D: Oracle invocation frequency.
+         * @deprecated READ-ONLY fallback — do not set. Canonical knob is
+         * `oracle.frequency`; this field is read only for back-compat with
+         * pre-v0.38.4 configs and is ignored when `oracle.frequency` is set.
          * Users should set `oracle.frequency` in opencode.jsonc, not this field.
          */
         oracleFrequency?: "per-stop" | "final-only" | "off";
@@ -64,28 +66,41 @@ export interface MetaGovernorPluginConfig {
             cooldownMs?: number;
             dedupe?: boolean;
         };
+        /**
+         * v0.50.0 (D10): conscience memory gate config. Canonical source for
+         * high-value memory persistence (escalate|stop only, value-gated).
+         * NOTE: typed structurally (not ConscienceConfig) so config.ts
+         * typechecks regardless of T1 landing order — shapes must match
+         * ClosedLoopConfig.conscience once T1 lands.
+         */
+        conscience?: {
+            enabled?: boolean;
+            maxMemoriesPerSession?: number;
+            toolRoute?: "omo_remember";
+            requireNovelty?: boolean;
+        };
     };
     /** Model override for MetaGovernor internal LLM usage. */
     modelOverride?: ModelOverrideConfig;
     /**
-     * v0.38.4: Oracle invocation frequency. Controls when the plugin invokes
+     * Oracle invocation frequency. Controls when the plugin invokes
      * Oracle for verification — reduces noisy mid-work escalations.
      *
-     * - `"per-stop"` (default, Option D): Oracle is invoked ONLY at the
-     *   final-gate (`<promise>DONE</promise>`) AND when score crosses the
-     *   stop threshold (`≤ -stopThreshold`). warn/escalate decisions log
-     *   but do NOT inject an Oracle prompt mid-work. Best balance: silent
-     *   on normal work, brake on emergencies, mandatory at done.
-     *
-     * - `"final-only"` (Option A): Oracle is invoked ONLY at the final-gate.
+     * - `"final-only"` (default): Oracle is invoked ONLY at the final-gate.
      *   Even stop-level decisions log without injecting an Oracle prompt.
-     *   Use when you want zero mid-work interruptions.
+     *   Zero mid-work interruptions.
+     *
+     * - `"per-stop"`: Oracle is invoked ONLY at the final-gate
+     *   (`<promise>DONE</promise>`) AND when score crosses the stop
+     *   threshold (`≤ -stopThreshold`). warn/escalate decisions log but do
+     *   NOT inject an Oracle prompt mid-work. Brake on emergencies,
+     *   mandatory at done.
      *
      * - `"off"`: Oracle is never invoked. The post-wave gate still requires
      *   `oracleVerified` — set it manually via `omo_recall` if you need it.
      */
     oracle?: {
-        /** @default "per-stop" */
+        /** @default "final-only" */
         frequency?: "per-stop" | "final-only" | "off";
     };
     /** Intervention config for visible decision injection. */
@@ -100,7 +115,8 @@ export interface MetaGovernorPluginConfig {
         minActionForMessage?: "warn" | "escalate" | "stop";
         /**
          * v0.10.0: rate-limit interventions to break instruction loops.
-         * @default 3
+         * v0.51.x (Wave A P3): severity-tiered quota — only escalate/stop consume.
+         * @default 5
          */
         maxInterventionsPerSession?: number;
         /**
@@ -205,6 +221,11 @@ export interface MetaGovernorPluginConfig {
         injectIntoSystem?: boolean;
         auditToolCalls?: boolean;
     };
+    /** Wave B workflow gates (explore-before-implement). All default false. */
+    workflowGates?: {
+        enabled?: boolean;
+        requirePlan?: boolean;
+    };
     /** Graph sync config for auto-initializing codegraph/graphify. */
     graphSync?: {
         /** @default true */
@@ -248,20 +269,28 @@ export interface MetaGovernorPluginConfig {
          * Default false (opt-in — multi-project users want explicit control). */
         addToGlobalGraph?: boolean;
     };
-    /** v0.28.0: CLI-Anything hub auto-install + auto-upgrade. Opt-in.
+    /** v0.28.0: CLI-Anything hub auto-install + auto-upgrade. Opt-out
+     *  (enabled by default; set `cliAnything.enabled: false` to disable).
      *  When enabled, the plugin ensures `cli-anything-hub` (pip) and
-     *  `cli-hub-meta-skill` (npx skills) are installed and current. */
+     *  `cli-hub-meta-skill` (npx skills) are installed and current.
+     *  Canonical projection is `!== false` (see loadOrchestratorConfig
+     *  cliAnything projection and orchestrator.ts CLI-Anything defaults). */
     cliAnything?: {
-        /** @default false */
+        /** @default true (opt-out via `cliAnything.enabled: false`;
+         * canonical `!== false` projection in orchestrator.ts) */
         enabled?: boolean;
         /** @default true */
         autoInstall?: boolean;
         /** @default true */
         autoUpgrade?: boolean;
+        /** @default newPluginPaths().cliAnythingUpgradeCheck
+         * (effective default applied at call-site, plugin.ts) */
         cachePath?: string;
-        /** @default 86400000 */
+        /** @default 86400000 (24h; effective default applied at call-site, plugin.ts:649) */
         upgradeCheckTtlMs?: number;
+        /** @default "cli-hub" */
         cliHubBin?: string;
+        /** @default "npx skills" */
         skillsBin?: string;
         /** @default "global" */
         installScope?: "global" | "project";

package/dist/custom-tools.d.ts

@@ -23,6 +23,19 @@ import type { SqliteBackend } from "./sqlite-backend";
 import type { GraphRetrieval } from "./graph-retrieval";
 import type { MetricsCollector } from "./metrics";
 import { type CodeGraphTools } from "./codegraph-tools";
+/**
+ * Canonical routing suffix for a tool description (Wave C part 2).
+ *
+ * Why this exists: the agent sees tool descriptions on every turn, while the
+ * graph-priming injection fires once per session. Embedding the canonical
+ * routing line in the description keeps "which tool for which question"
+ * visible without depending on that one-shot injection.
+ *
+ * Why lookup by ROUTING_MATRIX: the matrix is the single canonical source -
+ * reusing it here keeps descriptions in sync when the matrix changes, instead
+ * of duplicating tool-name literals at each call site.
+ */
+export declare function routingSuffixFor(toolName: string): string;
 /**
  * Module-level reference to the PendingDeliveryRegistry. The plugin
  * factory sets this once at startup. Bridge tools call it via
@@ -441,6 +454,29 @@ export declare function buildOmoHookStatusTool(deps: OmoHookStatusDeps): {
     args: {};
     execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
 };
+export interface OmoUpgradeDeps {
+    cwd: string;
+    /** Optional runner DI seam for tests. When undefined, uses real subprocesses. */
+    runner?: (cmd: string, opts?: {
+        timeoutMs?: number;
+    }) => string;
+    /** Min ms between registry queries. Default 24h. */
+    upgradeCheckTtlMs?: number;
+    /** Override the upgrade cache file path. Tests use this. */
+    upgradeCachePath?: string;
+}
+/** `omo_upgrade_check` — dry-run version check. NEVER installs anything. */
+export declare function buildOmoUpgradeCheckTool(deps: OmoUpgradeDeps): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
+};
+/** `omo_upgrade_run` — perform the backend upgrade path once. Best-effort, never throws. */
+export declare function buildOmoUpgradeRunTool(deps: OmoUpgradeDeps): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
+};
 export interface OmoCliAnythingDeps {
     cwd: string;
     /** Optional runner DI seam for tests. When undefined, uses real execSync. */

package/dist/delivery-registry.d.ts

@@ -34,6 +34,7 @@ export interface PendingDelivery {
 export type DeliveryStatus = "pending" | "delivered" | "expired";
 export declare class PendingDeliveryRegistry {
     private readonly entries;
+    private static readonly MAX_ENTRIES;
     /** When mcpArgs match is disabled (no mcpArgs available on observed call) */
     private deliveredCount;
     private expiredCount;

package/dist/enforcement-resources.d.ts

@@ -1,46 +1,23 @@
-/**
- * v0.37.0 (audit enforcement) — MCP enforcement resources for OpenChamber.
- *
- * Bug (audit v2 P0-2): In OpenChamber (HTTP mode), the plugin factory never
- * runs. Only MCP tools are exposed. All text-based instructions (Oracle rule 4,
- * agentmemory rule 8, skill-priming) live in `output.messages.push` /
- * `system.transform` which require plugin hooks. OpenChamber receives ZERO
- * enforcement.
- *
- * Fix: expose the rules as MCP resources that the agent can `resources/read`
- * at startup. Works in both plugin-CLI and OpenChamber modes.
- *
- * Contract:
- * - `meta-governor://rules/oracle` → Oracle gate rule text
- * - `meta-governor://rules/agentmemory` → omo_remember rule text
- * - `meta-governor://rules/skill-priming` → skill discovery rule text
- * - `meta-governor://rules/protocol` → Sisyphus protocol enforcement rules
- *
- * The returned text uses a `[SYSTEM-NUDGE]` prefix the LLM can detect.
- */
 export declare const ENFORCEMENT_RESOURCE_URIS: readonly ["meta-governor://rules/oracle", "meta-governor://rules/agentmemory", "meta-governor://rules/skill-priming", "meta-governor://rules/protocol"];
 export type EnforcementResourceUri = (typeof ENFORCEMENT_RESOURCE_URIS)[number];
 /**
- * Build the Oracle gate rule (v0.38.4 Option D — Oracle frequency).
+ * Build the Oracle gate rule (Oracle frequency).
  *
- * v0.38.4 REWRITE: Oracle is no longer auto-invoked mid-work for every
- * multi-file change. Instead, the `oracle.frequency` config controls when
- * Oracle fires:
- *   - `"per-stop"` (default): Oracle invoked at the final-gate
+ * Oracle is no longer auto-invoked mid-work for every multi-file change.
+ * Instead, the `oracle.frequency` config controls when Oracle fires:
+ *   - `"final-only"` (default): Oracle invoked ONLY at the final-gate.
+ *     Even stop-level decisions log without invoking Oracle mid-work.
+ *   - `"per-stop"`: Oracle invoked at the final-gate
  *     (<promise>DONE</promise>) AND when the scoring engine reaches the
  *     stop band (action === "stop"). warn/escalate log but do NOT
  *     invoke Oracle mid-work.
- *   - `"final-only"`: Oracle invoked ONLY at the final-gate. Even
- *     stop-level decisions log without invoking Oracle mid-work.
  *   - `"off"`: Oracle is NEVER invoked automatically. The agent must
  *     set `oracleVerified` manually (e.g. via omo_recall).
  *
  * The DONE final-gate is ALWAYS Oracle-verified regardless of frequency.
  *
  * Same MCP resource contract as before — `meta-governor://rules/oracle`
- * still returns this text. The previous "INVOKE triggers per multi-file
- * change" was the source of the noise — now mid-work Oracle is
- * gated by score band, not file count.
+ * still returns this text.
  */
 export declare function buildOracleRule(): string;
 /**

package/dist/graph-sync.d.ts

@@ -186,6 +186,13 @@ export declare const logToFile: typeof _logToFile;
  * triggering a network call.
  */
 export declare function isNewerVersion(installed: string | null | undefined, latest: string | null | undefined): boolean;
+/**
+ * P4 (v0.51.x): self-version STALE_CACHE polarity gate. Returns true ONLY
+ * when `latest` (npm registry) is strictly newer than `loaded` (running
+ * bundle) — equal versions (incl. "v"-prefix/whitespace variants) and
+ * loaded-newer-than-npm (local dev) stay silent. Pure: no I/O, no TTL.
+ */
+export declare function shouldWarnStaleCache(loaded: string | null | undefined, latest: string | null | undefined): boolean;
 /**
  * v0.12.0: persisted cache of latest-version lookups so we don't
  * hammer npm/pip registries on every plugin load.