opencode-swarm 7.159.2 → 7.160.0

package/dist/health/learning-health.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Learning/operations health — bounded-window alarm registry (issue #2044).
+ *
+ * Lives in `src/health/`, NOT `src/observability/`: this module performs
+ * bounded artifact I/O (`.swarm/learning-health.json`) and imports telemetry,
+ * both of which the observability directory's zero-I/O contract forbids
+ * (enforced by `tests/unit/observability/no-io.test.ts`).
+ *
+ * This module owns the eight alarm families the observability series assigned
+ * to PR 16:
+ *
+ *   1. `headroom_dead_streak`       — repeated zero/negative effective headroom
+ *   2. `model_limit_fallback`       — context-limit resolution fell back off the
+ *                                     host/live or user-override rungs
+ *   3. `retrieval_outcome_liveness` — retrieval → terminal receipt → application
+ *                                     outcome chain stalled
+ *   4. `role_participation`         — eligible workflow roles not participating
+ *   5. `promoted_fixture_share`     — promoted-tier evidence dominated by
+ *                                     non-field (fixture/synthetic-class) sources
+ *   6. `archive_activity_mismatch`  — close archive empty/invalid while recorded
+ *                                     activity predicted content
+ *   7. `recovery_ledger_pressure`   — background delegation recovery ledger near
+ *                                     its 4 MiB bound
+ *   8. `compaction_drop_coverage`   — store compaction dropping/corrupting
+ *                                     records across the six audited stores
+ *
+ * ## Contracts (issue #2044 items 5-10)
+ *
+ * - **Bounded windows with cooldown + hysteresis.** Every alarm raises only on
+ *   its per-family condition inside a bounded window, re-emits at most once per
+ *   cooldown interval (`sustained`), and recovers explicitly. Duplicate facts
+ *   (same kind + timestamp) and late/out-of-order facts never storm alerts: the
+ *   window is a monotonic append; a late fact counts but never rewinds
+ *   `windowStartMs`.
+ * - **Per-canonical-project/session state with explicit eviction.** Session
+ *   scopes are keyed `<projectRef>/<sessionRef>` when the producer knows its
+ *   project directory and `u/<sessionRef>` when it does not (the chat-transform
+ *   hooks receive no directory), so identical session ids under distinct
+ *   projects never collide. Scope maps are FIFO-evicted at
+ *   {@link MAX_HEALTH_SCOPES}; fact rings at {@link MAX_FACTS_PER_SCOPE}.
+ * - **No raw content.** Payloads and the persisted artifact carry counts,
+ *   closed-vocabulary enums, booleans, millisecond timestamps, model/provider
+ *   identity, and 16-hex salted session refs from
+ *   `pseudonymousSessionRef` — never raw session ids, paths, queries, prompts,
+ *   or responses (item 10).
+ * - **Persistence is transitions + compact per-scope counters ONLY** (item 9):
+ *   what incident reconstruction needs. This module intentionally contains NO
+ *   invocation-owned transient-retry or `nonTransientCircuit` state, so there is
+ *   nothing of that class to persist or rehydrate — restarts resume health
+ *   accumulation from the persisted counters, which is health state, not
+ *   invocation state.
+ * - **Typed health-source registration, no fake sink** (item 8):
+ *   {@link HEALTH_SOURCES} cites every real producer and reader file:line.
+ *   There is deliberately NO `sink` source and NO "sink loss" value — issue
+ *   #2047 / PR 19 must register its own real producer and reader.
+ *
+ * Every alarm is wired to production readers: the `/swarm status` Learning
+ * Health section and the `/swarm diagnose` learning-health check (both via
+ * {@link readLearningHealth}); `context_status` additionally exposes model-limit
+ * provenance directly.
+ */
+import type { ContextWindowSource } from '../config/context-window';
+/** The eight alarm families owned by this module. */
+export type LearningHealthAlarmId = 'headroom_dead_streak' | 'model_limit_fallback' | 'retrieval_outcome_liveness' | 'role_participation' | 'promoted_fixture_share' | 'archive_activity_mismatch' | 'recovery_ledger_pressure' | 'compaction_drop_coverage';
+export type LearningHealthTransition = 'raised' | 'sustained' | 'recovered';
+export type LearningHealthSeverity = 'warning' | 'critical';
+export type LearningHealthScopeClass = 'session' | 'identity' | 'project';
+/** Identifier of a producer subsystem feeding alarms (typed registration). */
+export type HealthSourceId = 'context_budget' | 'model_limits' | 'knowledge_receipts' | 'curator_compliance' | 'promotion_evidence' | 'close_archive' | 'delegation_ledger' | 'store_health_events';
+export interface HealthSourceRegistration {
+    /** file:line of the live producer call site. */
+    readonly producer: string;
+    /** file:line of every live reader of this source's data. */
+    readonly readers: readonly string[];
+    /** Alarms this source feeds. */
+    readonly alarms: readonly LearningHealthAlarmId[];
+}
+export declare const HEALTH_SOURCES: Readonly<Record<HealthSourceId, HealthSourceRegistration>>;
+/** Per-family thresholds. Documented constants, deliberately not user config. */
+export declare const LEARNING_HEALTH_ALARM_CONFIG: Readonly<{
+    headroom_dead_streak: Readonly<{
+        windowMs: 600000;
+        raiseFacts: 3;
+        cooldownMs: 1800000;
+        severity: LearningHealthSeverity;
+    }>;
+    model_limit_fallback: Readonly<{
+        windowMs: 1800000;
+        cooldownMs: 3600000;
+        severity: LearningHealthSeverity;
+    }>;
+    retrieval_outcome_liveness: Readonly<{
+        windowMs: 1800000;
+        cooldownMs: 900000;
+        severity: LearningHealthSeverity;
+        gap2StalenessMs: 600000;
+    }>;
+    role_participation: Readonly<{
+        windowMs: 86400000;
+        raiseFacts: 2;
+        cooldownMs: 43200000;
+        severity: LearningHealthSeverity;
+    }>;
+    promoted_fixture_share: Readonly<{
+        windowMs: 604800000;
+        raiseShare: 0.5;
+        clearShare: 0.3;
+        minEvidence: 4;
+        cooldownMs: 86400000;
+        severity: LearningHealthSeverity;
+    }>;
+    archive_activity_mismatch: Readonly<{
+        windowMs: 0;
+        cooldownMs: 86400000;
+        severity: LearningHealthSeverity;
+    }>;
+    recovery_ledger_pressure: Readonly<{
+        windowMs: 900000;
+        raisePct: 0.8;
+        clearPct: 0.7;
+        cooldownMs: 1800000;
+        severity: LearningHealthSeverity;
+    }>;
+    compaction_drop_coverage: Readonly<{
+        windowMs: 3600000;
+        corruptRaise: 1;
+        droppedRaise: 100;
+        cooldownMs: 3600000;
+        severity: LearningHealthSeverity;
+    }>;
+}>;
+/**
+ * Receipt sources that count as FIELD evidence for the fixture-share alarm:
+ * real workflow actors in a real run. `delegate` is field-but-non-independent —
+ * the independence dimension belongs to the promotion gate
+ * (src/hooks/knowledge-types.ts:410-418) and is deliberately NOT duplicated
+ * here.
+ */
+export declare const FIELD_RECEIPT_SOURCES: ReadonlySet<string>;
+/**
+ * Receipt sources that count as NON-FIELD (fixture/synthetic-class) evidence:
+ * authorized overrides, manual/migration imports, administrative gate
+ * releases, and `unknown` (fail-closed — a forged or missing label never counts
+ * as field).
+ */
+export declare const NON_FIELD_RECEIPT_SOURCES: ReadonlySet<string>;
+interface PersistedTransition {
+    alarm: LearningHealthAlarmId;
+    transition: LearningHealthTransition;
+    severity: LearningHealthSeverity;
+    atMs: number;
+    coverageFacts: number;
+}
+export declare const _internals: {
+    now: () => number;
+    emitTelemetry: (payload: Record<string, unknown>) => void;
+    writeArtifact: (directory: string, contents: string) => Promise<void>;
+    readArtifact: (directory: string) => Promise<string | null>;
+};
+/** Alarm payload detail — counts/enums/refs only, never raw content. */
+export interface AlarmEmitDetail {
+    sessionRef?: string;
+    model?: string;
+    provider?: string;
+    limitSource?: string;
+    denominatorFallback?: boolean;
+    pressurePct?: number;
+    band?: string;
+    sharePct?: number;
+    fieldCount?: number;
+    nonFieldCount?: number;
+    store?: string;
+    dropped?: number;
+    corrupt?: number;
+    retained?: number;
+    accepted?: number;
+    gapType?: 'membership_to_terminal' | 'terminal_to_application';
+    role?: string;
+    phase?: number;
+    reason?: string;
+}
+/** Serialize current health state to `.swarm/learning-health.json` (fire-and-forget). */
+export declare function persistLearningHealth(directory: string): Promise<void>;
+/**
+ * Observe one context-budget evaluation. `dead` = usagePercent ≥ 1.0
+ * (zero/negative effective headroom). The alarm raises after
+ * {@link LEARNING_HEALTH_ALARM_CONFIG.headroom_dead_streak.raiseFacts} distinct
+ * dead observations in the window and recovers on a healthy observation below
+ * the warn threshold. Attribution, not suppression: the payload always carries
+ * `limit_source` and `denominator_fallback` so an operator can tell real
+ * exhaustion from a stale static-table denominator — the "fallback hides
+ * dead-headroom loops" defect this alarm exists to surface.
+ */
+export declare function observeContextHeadroom(input: {
+    sessionID: string;
+    /** Project directory when the producer knows it (threaded from the plugin
+     * wiring at handler construction); the chat-transform input itself carries
+     * none. Scopes key by `<projectRef>/<sessionRef>` when present. */
+    directory?: string;
+    usagePercent: number;
+    limit: number;
+    limitSource: string;
+    warnThreshold: number;
+}): void;
+/**
+ * Observe one model-limit resolution. Fallback-active when the resolution came
+ * from the static tables or the flat default (not host/live, not a user
+ * override); recovery when the same identity later resolves from host/override.
+ */
+export declare function observeModelLimitResolution(input: {
+    modelID?: string;
+    providerID?: string;
+    /** Project directory when the producer knows it (threaded through
+     * resolveModelLimit); identity scopes key project-prefixed when present. */
+    directory?: string;
+    resolution: ContextWindowSource;
+    /** Which override key class matched (compound/model/default) — the alias
+     * provenance for user-authored limits (issue #2044 item 2). */
+    aliasKeyClass?: 'compound' | 'model' | 'default';
+    /** True when a user-authored override failed usability validation and was
+     * skipped (never coerced) — surfaced durably, not just as a warning. */
+    invalidOverride?: boolean;
+}): void;
+/**
+ * Observe one receipt-ledger transition. Called from the ledger's post-lock
+ * observation drain where the project directory and the observation record are
+ * both in hand. Gap-1: membership committed without a terminal within the
+ * window. Gap-2: a terminal with outcome 'applied' without an authoritative
+ * application closure — either an `architect_marker`-sourced application
+ * outcome or any gate release (the release valve is one-way, so a release MUST
+ * count as closure). Gap-2 opens only past the gate's staleness horizon.
+ */
+export declare function observeReceiptTransition(input: {
+    directory: string;
+    kind: string;
+    traceId: string;
+    receiptOutcome?: string;
+    receiptSource?: string;
+    /**
+     * OPTIONAL membership commit time for gap-2 staleness anchoring. Intentionally
+     * not populated by the current ledger drain (PRR-008): anchoring gap-2
+     * eligibility to the TERMINAL time (the fallback when absent) is the
+     * conservative bound — it can only delay eligibility, never fire the alarm
+     * before the application gate's own staleness escalation has had its
+     * window. Kept as an explicit input so a future ledger observation can
+     * tighten the anchor without an API change.
+     */
+    membershipCommittedAtMs?: number;
+    atMs?: number;
+}): void;
+/**
+ * Observe one curator phase-compliance pass. `gaps` carries the compliance
+ * observation types counted as participation gaps; `agentsUsed` is the set of
+ * roles that DID participate. The structural-zero guard keeps a single review
+ * window with no eligible opportunity from ever raising.
+ */
+export declare function observeCuratorCompliance(input: {
+    directory: string;
+    phase?: number;
+    gapTypes: readonly string[];
+    agentsUsed: readonly string[];
+}): void;
+/**
+ * Observe one promotion-evidence record. Classification is closed-vocabulary:
+ * field sources are real workflow actors; everything else (overrides, manual
+ * and migration imports, administrative releases, unknown) is non-field and
+ * `unknown` NEVER counts as field (fail-closed against forged labels).
+ */
+export declare function observePromotionEvidence(input: {
+    directory: string;
+    receiptSource: string | undefined;
+}): void;
+/**
+ * Observe one close-archive result. Raises when the archive is empty/invalid
+ * while recorded activity predicted content; recovers on the next valid,
+ * non-empty archive. Late-arriving activity never retro-raises — the payload
+ * records what was known at decision time.
+ */
+export declare function observeCloseArchive(input: {
+    directory: string;
+    archiveValid: boolean;
+    archiveEmpty: boolean;
+    activityPredictsContent: boolean;
+}): void;
+/**
+ * Observe one delegation-ledger health collection. Raises at pressure ≥ 0.8
+ * (near the 4 MiB recovery bound) or on the compact-overdue / fail-closed
+ * bands; clears below 0.7 (hysteresis). `uncertain` surfaces recovery
+ * observation failures as closed reason codes.
+ */
+export declare function observeDelegationLedgerPressure(input: {
+    directory: string;
+    pressurePct: number;
+    band: string;
+    uncertain?: boolean;
+}): void;
+/**
+ * Direct, directory-bearing store-health observation (final-critic finding 3):
+ * the six audited stores call this at their health-event emit sites, so family
+ * 8 is fed from its real producers from the FIRST event — not only after an
+ * operator opens a status surface.
+ */
+export declare function observeStoreHealth(input: {
+    directory: string;
+    kind: string;
+    payload: Record<string, unknown>;
+}): void;
+declare function observeStoreHealthEvent(event: string, data: Record<string, unknown>, directory?: string): void;
+/**
+ * Idempotent no-op registration point (PR #2446 review): family 8 is fed
+ * DIRECTLY by all six audited stores via {@link observeStoreHealth}, so no
+ * telemetry listener is attached. The historical listener double-fed every
+ * store event (direct + listener observed the same emission into two scope
+ * namespaces); it was removed. This function remains as the documented
+ * registration seam so future feeds have one call site to wire — it performs
+ * no work today and never touches the plugin init path.
+ */
+export declare function ensureLearningHealth(): void;
+/**
+ * Test teardown: clear all in-memory health state. Never used in production
+ * code paths.
+ */
+export declare function resetLearningHealthForTest(): void;
+export interface ActiveLearningHealthAlarm {
+    alarm: LearningHealthAlarmId;
+    severity: LearningHealthSeverity;
+    scopeClass: LearningHealthScopeClass;
+    scopeRef: string;
+    ageMs: number;
+    coverageFacts: number;
+    transitionCount: number;
+}
+export interface LearningHealthSnapshot {
+    activeAlarms: readonly ActiveLearningHealthAlarm[];
+    totalTransitions: number;
+    updatedAtMs: number;
+}
+/**
+ * Read learning health for a project: rehydrate any persisted artifact,
+ * lazily evaluate window-based alarms (liveness gaps age into raises without a
+ * timer), and persist the refreshed state. Fail-open: any error yields an
+ * empty snapshot.
+ */
+export declare function readLearningHealth(directory: string): Promise<LearningHealthSnapshot>;
+/** All transitions in the bounded ring (newest last). Test/diagnostic accessor. */
+export declare function getLearningHealthTransitions(): readonly PersistedTransition[];
+/**
+ * Tier-0 test exports (writing-tests skill): pure-or-near-pure internals that
+ * tests exercise directly. `observeStoreHealthEvent` is the shared core the
+ * public `observeStoreHealth` wraps; tests use it to drive family-8 logic
+ * without constructing a directory scope.
+ */
+export declare const _test_exports: {
+    observeStoreHealthEvent: typeof observeStoreHealthEvent;
+};
+export {};

package/dist/hooks/context-budget.d.ts

@@ -6,6 +6,7 @@
  * to provide proactive context management guidance to the architect agent.
  */
 import type { PluginConfig } from '../config';
+import { observeContextHeadroom } from '../health/learning-health';
 import { telemetry } from '../telemetry';
 interface MessageInfo {
     role: string;
@@ -34,13 +35,21 @@ interface MessageWithParts {
 }
 export declare const _internals: {
     telemetryContextPruned: typeof telemetry.contextPruned;
+    observeContextHeadroom: typeof observeContextHeadroom;
 };
 /**
  * Creates the experimental.chat.messages.transform hook for context budget tracking.
  * Injects warnings when context usage exceeds configured thresholds.
  * Only operates on messages for the architect agent.
  */
-export declare function createContextBudgetHandler(config: PluginConfig, resolveAgentModel?: (agentName: string) => string | undefined): (_input: Record<string, never>, _output: {
+export declare function createContextBudgetHandler(config: PluginConfig, resolveAgentModel?: (agentName: string) => string | undefined, 
+/**
+ * Project directory (threaded from the plugin wiring at handler
+ * construction — the chat-transform hook input itself carries none). Used
+ * ONLY to scope + persist the #2044 headroom health observation; every
+ * budget behavior is identical without it.
+ */
+directory?: string): (_input: Record<string, never>, _output: {
     messages?: MessageWithParts[];
 }) => Promise<void>;
 export {};

package/dist/hooks/curator.d.ts

@@ -24,6 +24,7 @@
  * This dual dispatch means agent lists are incomplete — they capture factory-dispatched
  * curators but omit hook-dispatched ones. This is by design for hook-internal operations.
  */
+import { observeCuratorCompliance } from '../health/learning-health';
 import { checkRecommendations, recordEmittedRecommendations } from '../services/recommendation-ledger.js';
 import { listSkills, parseDraftFrontmatter, retireOrMarkStale, retireSkill } from '../services/skill-generator.js';
 import { getSkillVersion, reviseSkill } from '../services/skill-reviser.js';
@@ -51,6 +52,7 @@ export declare const _internals: {
     checkPhaseCompliance: typeof checkPhaseCompliance;
     normalizeAgentName: typeof normalizeAgentName;
     autoRetireSkills: typeof autoRetireSkills;
+    observeCuratorCompliance: typeof observeCuratorCompliance;
     /**
      * Retained deliberately (issue #2038 §7). The three curator decision sites
      * now read through `readSkillUsageEntriesWithCoverage` because a coverage

package/dist/hooks/final-context-accounting.d.ts

@@ -43,6 +43,8 @@ interface FinalAccountingOptions {
     /** Same seam createContextBudgetHandler uses: resolves the
      * configured target model for an agent name. */
     resolveAgentModelFn?: (agentName: string) => string | undefined;
+    /** Project directory (#2044): scopes the model-limit health observation. */
+    directory?: string;
 }
 /**
  * One-shot-per-band warning suppression (#2107 §3), backed by the

package/dist/hooks/model-limits.d.ts

@@ -25,6 +25,8 @@
  * live derivation replaced. They exist so a first-turn `messages.transform`
  * consumer degrades to a plausible number instead of the flat 128 000 floor.
  */
+import { type ContextWindowSource } from '../config/context-window';
+import { observeModelLimitResolution } from '../health/learning-health';
 /**
  * Native model context limits (in tokens) when used on their native platform.
  *
@@ -85,21 +87,46 @@ export declare function extractModelInfo(messages: MessageWithParts[]): {
  * @returns the sessionID, or `undefined` when no message carries one.
  */
 export declare function extractSessionId(messages: MessageWithParts[] | undefined): string | undefined;
+/**
+ * Coarse provenance class for a resolved model limit (issue #2044 item 1).
+ * Maps the fine-grained {@link ContextWindowSource} rung onto the five classes
+ * the issue names: `host` (the live `model.limit.context`), `override` (any
+ * user-authored `model_limits` entry), `provider_cap` / `native` (the two
+ * known-stale static tables), and `fallback` (the flat 128k default).
+ */
+export type ModelLimitSource = 'host' | 'override' | 'provider_cap' | 'native' | 'fallback';
+/** Provenance-bearing result of {@link resolveModelLimit} (issue #2044). */
+export interface ModelLimitResolution {
+    /** The resolved context limit in tokens. */
+    limit: number;
+    /** Coarse provenance class — the issue's enum. */
+    source: ModelLimitSource;
+    /** Which fine-grained resolution rung produced the limit. */
+    resolution: ContextWindowSource;
+}
+export declare function classifyModelLimitSource(resolution: ContextWindowSource): ModelLimitSource;
 /**
  * Static-table lookup used as `fallbackLookup` for
- * {@link resolveContextWindow}. Preserves the historical precedence of
- * the two tables relative to each other (provider cap first, then a
- * longest-prefix native match), and is reachable only when no live
- * `model.limit.context` was available.
+ * {@link resolveContextWindow}. Preserves the historical precedence of the two
+ * tables relative to each other (provider cap first, then a longest-prefix
+ * native match), and says WHICH table matched so the resolution source can
+ * distinguish `static_provider_cap` from `static_native` (issue #2044).
+ * Reachable only when no live `model.limit.context` was available.
  */
-export declare function lookupStaticModelLimit(modelID?: string, providerID?: string): number | undefined;
+export declare function lookupStaticModelLimit(modelID?: string, providerID?: string): {
+    tokens: number;
+    table: 'provider_cap' | 'native';
+} | undefined;
 /**
- * Resolves the context limit for a given model/provider combination.
+ * Resolves the context limit for a given model/provider combination WITH
+ * provenance (issue #2044).
  *
  * Thin adapter over the single derivation in `src/config/context-window.ts` —
  * this function exists so the `experimental.chat.messages.transform` consumers
- * (`context-budget.ts`, `knowledge-injector.ts`, `tools/context-status.ts`)
- * keep their existing `(modelID, providerID, overrides)` call shape. All
+ * (`context-budget.ts`, `knowledge-injector.ts`, `tools/context-status.ts`,
+ * `final-context-accounting.ts`) keep their existing
+ * `(modelID, providerID, overrides)` call shape while receiving the typed
+ * `{ limit, source }` provenance the observability series requires. All
  * ordering logic lives in the shared resolver; see its module header.
  *
  * Resolution order (first usable value wins):
@@ -111,44 +138,48 @@ export declare function lookupStaticModelLimit(modelID?: string, providerID?: st
  *    match (both known-stale; see the module header)
  * 6. `DEFAULT_MODEL_CONTEXT_TOKENS` (128000)
  *
- * Two ordering changes vs. the pre-#1619 implementation, both deliberate:
- * - `configOverrides.default` moved from below the static tables to above
- *   them. An explicitly authored user value losing to a hardcoded table was a
- *   defect; it is now consistent with the compound and model-only keys, which
- *   already outranked the tables.
- * - The live `model.limit.context` was inserted above both tables, which is
- *   the entire point of this change.
- *
- * Any value that is not a finite number ≥ 1000 is skipped rather than used, so
- * a malformed override or a catalog entry with `limit.context: 0` can never
- * produce a `NaN` / `Infinity` percentage.
+ * Any value that is not a finite number ≥ 1000 (untrusted rungs) / ≥ 1 (user
+ * rungs) is SKIPPED, never coerced; skipped user overrides are surfaced via a
+ * bounded `invalid_override_skipped` observation instead of silently
+ * disappearing (issue #2044 item 2).
  *
  * @param modelID - The model identifier (e.g., "claude-sonnet-4-6", "gpt-5")
  * @param providerID - The provider identifier (e.g., "github-copilot", "anthropic")
  * @param configOverrides - User configuration overrides (`context_budget.model_limits`)
  * @param liveContextLimit - The live `model.limit.context` recorded for this
  *   session by the `system.transform` hook, when one has been seen
- * @returns The resolved context limit in tokens
+ * @returns The resolved limit with coarse source class and fine-grained rung
  *
  * @example
  * // Live value wins over the stale static tables
  * resolveModelLimit("claude-sonnet-4-6", "github-copilot", {}, 200000)
- * // Returns: 200000
+ * // Returns: { limit: 200000, source: 'host', resolution: 'live_model_limit' }
  *
  * @example
  * // Explicit user override beats the live value
  * resolveModelLimit("gpt-5", "github-copilot", { "github-copilot/gpt-5": 60000 }, 400000)
- * // Returns: 60000
+ * // Returns: { limit: 60000, source: 'override', resolution: 'user_provider_model' }
  *
  * @example
  * // No live value: falls back to the static table (prefix match)
  * resolveModelLimit("claude-sonnet-4-6-20260301", "anthropic", {})
- * // Returns: 200000
+ * // Returns: { limit: 200000, source: 'native', resolution: 'static_native' }
  *
  * @example
  * // Malformed live value is ignored, not divided by
  * resolveModelLimit(undefined, undefined, {}, 0)
- * // Returns: 128000
+ * // Returns: { limit: 128000, source: 'fallback', resolution: 'static_default' }
  */
-export declare function resolveModelLimit(modelID?: string, providerID?: string, configOverrides?: Record<string, number>, liveContextLimit?: unknown): number;
+export declare function resolveModelLimit(modelID?: string, providerID?: string, configOverrides?: Record<string, number>, liveContextLimit?: unknown, 
+/** Project directory (threaded from the consumers) — scopes the #2044
+ * fallback-health observation to the owning project. */
+directory?: string): ModelLimitResolution;
+/**
+ * Bounded observation seam (invariant-7 DI): routes the model-limit fallback
+ * fact into the learning-health registry. Tests replace this to avoid touching
+ * global health state; production uses the real observer.
+ */
+export declare const _internals: {
+    observeResolution: typeof observeModelLimitResolution;
+};
 export {};

package/dist/hooks/skill-usage-pending.d.ts

@@ -389,4 +389,4 @@ export declare function buildSkillUsageHealthPayload(doc: SkillUsagePendingDocum
 export declare function emitSkillUsageHealth(doc: SkillUsagePendingDocument, trigger: SkillUsageHealthPayload['trigger'], gauges: {
     bytes: number;
     limitBytes: number;
-}): void;
+}, directory?: string): void;