opencode-swarm 7.148.0 → 7.148.1

package/dist/cli/{pending-delegations-k4x00mqc.js → pending-delegations-78zaaxz4.js}

@@ -54,13 +54,13 @@ import {
   sweepStaleDelegations,
   updateCoderSettlement,
   writeDelegationFallback
-} from "./index-d3bdr78h.js";
+} from "./index-ch6sjm8q.js";
 import"./index-4cgee5vh.js";
 import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{pr-subscriptions-x2mqc3f1.js → pr-subscriptions-9mg6mwc0.js}

@@ -9,13 +9,13 @@ import {
   sweepStale,
   unsubscribe,
   updateSnapshot
-} from "./index-pgvx3rkq.js";
+} from "./index-2n9rwvcc.js";
 import"./index-4cgee5vh.js";
 import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{runner-gfzkp9nv.js → runner-rarzeth8.js}

@@ -3,14 +3,14 @@ import {
   _internals,
   createModelEvaluationExecutor,
   runEvaluation
-} from "./index-p62we2ar.js";
-import"./index-y586zet4.js";
+} from "./index-kpgj4ha6.js";
+import"./index-fv5cc1rd.js";
 import"./index-y8552snf.js";
 import"./index-r3mvsbtq.js";
-import"./index-7hctrdk8.js";
-import"./index-2y14mjfn.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-shazb5b6.js";
+import"./index-3yh2e5ca.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{scan-cursor-a6dhyf55.js → scan-cursor-zn2qf06a.js}

@@ -4,17 +4,17 @@ import {
   alreadyCuratedThisGeneration,
   claimNextScanBatch,
   getScanStatus
-} from "./index-016708th.js";
-import"./index-07zgs6y0.js";
+} from "./index-81n4ky69.js";
+import"./index-x46mmaep.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
 import"./index-ae75rja9.js";
-import"./index-qcm97jfh.js";
-import"./index-7hctrdk8.js";
+import"./index-qzstn430.js";
+import"./index-shazb5b6.js";
 import"./index-bk5tah7q.js";
-import"./index-2y14mjfn.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-3yh2e5ca.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{schema-p0vn1zgh.js → schema-ynwy7abm.js}

@@ -99,7 +99,7 @@ import {
   resolveGeneratedAgentRole,
   resolveGuardrailsConfig,
   stripKnownSwarmPrefix
-} from "./index-702zx3rk.js";
+} from "./index-qwzpsh3w.js";
 import"./index-cpg98bh1.js";
 import"./index-zjygnfay.js";
 import"./index-bk5tah7q.js";

package/dist/cli/{scope-persistence-zs97zkt7.js → scope-persistence-sh30937s.js}

@@ -23,11 +23,11 @@ import {
   tombstoneScopeBinding,
   writeScopeBindingToDisk,
   writeScopeToDisk
-} from "./index-52gnz782.js";
-import"./index-h879g4r4.js";
+} from "./index-c23yxr1s.js";
+import"./index-f115c8y6.js";
 import"./index-556ja8an.js";
-import"./index-ffevkn7k.js";
-import"./index-702zx3rk.js";
+import"./index-k5ze5v89.js";
+import"./index-qwzpsh3w.js";
 import"./index-cpg98bh1.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
@@ -36,9 +36,9 @@ import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
 import"./index-bk5tah7q.js";
-import"./index-2y14mjfn.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-3yh2e5ca.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{skill-generator-5qg15q1j.js → skill-generator-r3knfwrp.js}

@@ -33,18 +33,18 @@ import {
   sanitizeSlug,
   selectCandidateEntries,
   writeEvalStub
-} from "./index-dmbaaz6d.js";
-import"./index-n96wwf56.js";
-import"./index-zwpttdgn.js";
+} from "./index-hxqjf4me.js";
+import"./index-dwg0z10h.js";
+import"./index-jtnk7k6w.js";
 import"./index-rtry5xyf.js";
 import"./index-q7sjgr1y.js";
-import"./index-07zgs6y0.js";
-import"./index-gwrv6c56.js";
-import"./index-rcjq8dm4.js";
+import"./index-x46mmaep.js";
+import"./index-w49v4xd6.js";
+import"./index-shm69en5.js";
 import"./index-gprxjmm7.js";
 import"./index-n832052r.js";
-import"./index-ffevkn7k.js";
-import"./index-702zx3rk.js";
+import"./index-k5ze5v89.js";
+import"./index-qwzpsh3w.js";
 import"./index-cpg98bh1.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
@@ -53,12 +53,12 @@ import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
 import"./index-ae75rja9.js";
-import"./index-qcm97jfh.js";
-import"./index-7hctrdk8.js";
+import"./index-qzstn430.js";
+import"./index-shazb5b6.js";
 import"./index-bk5tah7q.js";
-import"./index-2y14mjfn.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-3yh2e5ca.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{telemetry-xzy0qeap.js → telemetry-1pnsftp0.js}

@@ -13,7 +13,7 @@ import {
   startHeartbeatTracking,
   stopHeartbeatTracking,
   telemetry
-} from "./index-q81s0m8k.js";
+} from "./index-ghbkknjz.js";
 import"./index-bpmtbmy9.js";
 import"./index-a76rekgs.js";
 export {

package/dist/cli/{worktree-collision-ownership-q2gswg16.js → worktree-collision-ownership-29md3k1n.js}

@@ -5,7 +5,7 @@ import {
 import {
   scanDelegationFallbacksForRecovery,
   scanDelegationsForRecovery
-} from "./index-d3bdr78h.js";
+} from "./index-ch6sjm8q.js";
 import {
   WORKTREE_PROVISIONING_OWNER_LEASE_MS,
   removeWorktreeProvisioningOwner,
@@ -22,8 +22,8 @@ import {
   bunSpawn
 } from "./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/cli/{worktree-isolation-ndb5fwys.js → worktree-isolation-yj7ssh24.js}

@@ -21,47 +21,47 @@ import {
   sanitizeWorktreeTaskId,
   standardWorktreeByCallID,
   standardWorktreeSerializationSessions
-} from "./index-crpb0qke.js";
-import"./index-p62we2ar.js";
-import"./index-jpa03jcc.js";
-import"./index-9pmmexsd.js";
-import"./index-ykjjqg79.js";
-import"./index-y586zet4.js";
+} from "./index-kztxn1ww.js";
+import"./index-kpgj4ha6.js";
+import"./index-2bsnwcmp.js";
+import"./index-5wypz451.js";
+import"./index-t6ys1386.js";
+import"./index-fv5cc1rd.js";
 import"./index-134d35c1.js";
 import"./index-nj6rmyeh.js";
 import"./index-y8552snf.js";
-import"./index-k6h5yc1j.js";
-import"./index-016708th.js";
+import"./index-q0gfmyzx.js";
+import"./index-81n4ky69.js";
 import"./index-70ha9e09.js";
 import"./index-c8s9a3zh.js";
 import"./index-9ss2m4rs.js";
 import"./index-g8wwj0sz.js";
-import"./index-pgvx3rkq.js";
-import"./index-dmbaaz6d.js";
-import"./index-n96wwf56.js";
-import"./index-zwpttdgn.js";
+import"./index-2n9rwvcc.js";
+import"./index-hxqjf4me.js";
+import"./index-dwg0z10h.js";
+import"./index-jtnk7k6w.js";
 import"./index-rtry5xyf.js";
 import"./index-zsrtt42s.js";
-import"./index-d3bdr78h.js";
+import"./index-ch6sjm8q.js";
 import"./index-fxvgaeq4.js";
-import"./index-n0fpefqx.js";
-import"./index-7ac5z627.js";
-import"./index-52gnz782.js";
-import"./index-h879g4r4.js";
+import"./index-py2rsw1a.js";
+import"./index-mfhpk4c6.js";
+import"./index-c23yxr1s.js";
+import"./index-f115c8y6.js";
 import"./index-556ja8an.js";
 import"./index-b43rt5ph.js";
 import"./index-q7sjgr1y.js";
 import"./index-3g0xk6tk.js";
 import"./index-85gkedsf.js";
-import"./index-07zgs6y0.js";
-import"./index-gwrv6c56.js";
+import"./index-x46mmaep.js";
+import"./index-w49v4xd6.js";
 import {
   resolveWorktreeIsolationConfig
-} from "./index-rcjq8dm4.js";
+} from "./index-shm69en5.js";
 import"./index-gprxjmm7.js";
 import"./index-n832052r.js";
-import"./index-ffevkn7k.js";
-import"./index-702zx3rk.js";
+import"./index-k5ze5v89.js";
+import"./index-qwzpsh3w.js";
 import"./index-cpg98bh1.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
@@ -70,12 +70,12 @@ import"./index-z6xqpmqg.js";
 import"./index-r3mvsbtq.js";
 import"./index-zjygnfay.js";
 import"./index-ae75rja9.js";
-import"./index-qcm97jfh.js";
-import"./index-7hctrdk8.js";
+import"./index-qzstn430.js";
+import"./index-shazb5b6.js";
 import"./index-bk5tah7q.js";
-import"./index-2y14mjfn.js";
-import"./index-6q35swn2.js";
-import"./index-q81s0m8k.js";
+import"./index-3yh2e5ca.js";
+import"./index-rsn4jm90.js";
+import"./index-ghbkknjz.js";
 import"./index-7g4c7s5r.js";
 import"./index-bpmtbmy9.js";
 import"./index-ed5ykebp.js";

package/dist/consensus/contracts.d.ts

@@ -292,7 +292,11 @@ export interface ConsensusCorpusHash {
  * the difference between an incomplete report and a misleading one.
  */
 export interface ConsensusTruncationV1 {
-    /** `maxEvidenceItems` cut the corpus before tallying. */
+    /**
+     * `maxEvidenceItems` cut the corpus before tallying, OR skill-usage
+     * compaction evicted history the corpus would otherwise have covered
+     * (issue #2038).
+     */
     corpus: boolean;
     /** Observations actually tallied, after filtering and after the corpus cut. */
     observations: number;

package/dist/consensus/corpus.d.ts

@@ -29,7 +29,7 @@
  *   `task_complexity` remap, which happens in `wrapFlatRetrospective` before the
  *   write branch — so the corpus reads normalized values while the file on disk
  *   keeps its legacy ones.
- *   Three upstream readers do populate PROCESS-LOCAL caches, which is worth
+ *   Four upstream readers do populate PROCESS-LOCAL caches, which is worth
  *   stating rather than hiding behind the word "read-only": `readTrajectory`
  *   fills the PRM in-memory trajectory cache (`src/prm/trajectory-store.ts`),
  *   while `readKnowledge` and `loadEvidence` fill the two SEPARATE maps in
@@ -44,6 +44,13 @@
  *   `floor(maxLines / 2)` = 500 ENTRIES. That 500 is unrelated to
  *   `MAX_TRACKED_TRAJECTORY_SESSIONS` = 500, which bounds how many SESSIONS the
  *   cache holds at once; the two constants merely happen to share a value.
+ *   The fourth is `readPendingManifest` (issue #2038), which the skill-usage
+ *   source calls for its coverage verdict: it memoizes the parsed sidecar
+ *   manifest keyed by the resolved path and validated against that file's mtime
+ *   and size, so a stale entry can never be served, and it holds one entry per
+ *   project directory the process has touched. It takes no lock, never
+ *   migrates, and never quarantines a corrupt sidecar — quarantine is reserved
+ *   for lock-taking paths, so mining still cannot mutate what it counts.
  *   None of these caches is on disk: nothing about them writes a file, and none
  *   survives the process. (The readers themselves obviously do read files — the
  *   claim above is that nothing here WRITES, not that nothing here touches the
@@ -73,7 +80,7 @@ import { readGateGroundTruth } from '../evaluation/gate-ground-truth.js';
 import { type GateAuditReadSummary } from '../evaluation/store.js';
 import { type LoadEvidenceResult } from '../evidence/manager.js';
 import type { RetrievalOutcome } from '../hooks/knowledge-types.js';
-import { readSkillUsageEntries } from '../hooks/skill-usage-log.js';
+import { readSkillUsageEntries, type readSkillUsageEntriesWithCoverage } from '../hooks/skill-usage-log.js';
 import type { TrajectoryEntry } from '../prm/types.js';
 import type { ConsensusCorpusHash, ConsensusSourceKind } from './contracts.js';
 /**
@@ -99,7 +106,11 @@ export interface CorpusObservation {
 export interface ConsensusCorpus {
     observations: CorpusObservation[];
     hashes: ConsensusCorpusHash[];
-    /** True when `maxEvidenceItems` truncated the stream. */
+    /**
+     * True when the returned stream is not the complete corpus — either
+     * `maxEvidenceItems` cut it, or a source could only return a bounded window
+     * (skill-usage under the issue #2038 compaction budget).
+     */
     truncated: boolean;
     /** Sources that threw while being read. Never fatal — the corpus degrades. */
     unreadableSources: ConsensusSourceKind[];
@@ -119,6 +130,18 @@ export interface CorpusReaders {
     listTrajectorySessions: (directory: string) => Promise<string[]>;
     readTrajectory: (sessionId: string, directory: string) => Promise<TrajectoryEntry[]>;
     readSkillUsageEntries: typeof readSkillUsageEntries;
+    /**
+     * Additive coverage seam (issue #2038 §7). Optional, and deliberately NOT
+     * part of `defaultReaders()`.
+     *
+     * The entries themselves keep coming from `readSkillUsageEntries` — which is
+     * already the bounded read funnel, so the observations are byte-identical —
+     * because `loadConsensusCorpus` merges as `{...defaultReaders(), ...options.readers}`.
+     * A default entry-bearing coverage reader would therefore silently outrank a
+     * caller that overrode only `readSkillUsageEntries`, turning an injected
+     * fixture into an empty corpus. Injecting this member overrides BOTH.
+     */
+    readSkillUsageEntriesWithCoverage?: typeof readSkillUsageEntriesWithCoverage;
     readKnowledgeEntries: (directory: string) => Promise<KnowledgeLike[]>;
     loadEvidence: (directory: string, taskId: string) => Promise<LoadEvidenceResult>;
     readRejectedLessons: (directory: string) => Promise<RejectedLessonLike[]>;

package/dist/consensus/miner.d.ts

@@ -133,7 +133,11 @@ export interface MineConsensusDeps {
 }
 export interface MineConsensusResult {
     report: ConsensusReportV1;
-    /** True when `maxEvidenceItems` truncated the corpus. */
+    /**
+     * True when `maxEvidenceItems` truncated the corpus, OR skill-usage
+     * compaction evicted history the corpus would otherwise have covered
+     * (issue #2038).
+     */
     truncated: boolean;
     /** Corpus sources that could not be read. */
     unreadableSources: string[];

package/dist/hooks/curator.d.ts

@@ -30,7 +30,7 @@ import { getSkillVersion, reviseSkill } from '../services/skill-reviser.js';
 import type { ComplianceObservation, CuratorConfig, CuratorInitResult, CuratorPhaseResult, CuratorSummary, KnowledgeRecommendation, PhaseDigestEntry } from './curator-types.js';
 import { getArchivedKnowledgeIds, readKnowledge, transactFile } from './knowledge-store.js';
 import type { KnowledgeConfig } from './knowledge-types.js';
-import { readSkillUsageEntries } from './skill-usage-log.js';
+import { readSkillUsageEntries, readSkillUsageEntriesWithCoverage } from './skill-usage-log.js';
 /**
  * Optional LLM delegate callback type.
  * Takes a system prompt and user input, returns the LLM output text.
@@ -51,7 +51,16 @@ export declare const _internals: {
     checkPhaseCompliance: typeof checkPhaseCompliance;
     normalizeAgentName: typeof normalizeAgentName;
     autoRetireSkills: typeof autoRetireSkills;
+    /**
+     * Retained deliberately (issue #2038 §7). The three curator decision sites
+     * now read through `readSkillUsageEntriesWithCoverage` because a coverage
+     * verdict and the entries it describes must come from ONE read, but this
+     * member keeps the `typeof readSkillUsageEntries` seam contract intact for
+     * existing callers and stubs rather than changing an exported symbol's type.
+     */
     readSkillUsageEntries: typeof readSkillUsageEntries;
+    readSkillUsageEntriesWithCoverage: typeof readSkillUsageEntriesWithCoverage;
+    recordCuratorSkips: typeof recordCuratorSkips;
     listSkills: typeof listSkills;
     parseDraftFrontmatter: typeof parseDraftFrontmatter;
     retireOrMarkStale: typeof retireOrMarkStale;
@@ -71,6 +80,37 @@ export interface RecommendationParseDiagnostic {
     reason: string;
 }
 export declare function normalizeRecommendationEntryIdToken(token: string): string | undefined;
+/**
+ * Fold one curator pass's skipped decisions into the durable `curator_skipped`
+ * counter in `.swarm/skill-usage-pending.json`.
+ *
+ * Called ONCE per site with the pass total — never inside the per-skill loop,
+ * because it takes the skill-usage lock and a lock per skill would be O(skills)
+ * synchronous I/O on the curator path.
+ *
+ * Two deliberate non-behaviors:
+ *  - **No health emit.** `emitSkillUsageHealth`'s trigger union has no curator
+ *    value. `curator_skipped` is a lifetime counter, so the next compaction or
+ *    consumption emit carries it; inventing a trigger here would widen a
+ *    contract this change does not own.
+ *  - **Lock failure drops the write.** Acquisition is non-blocking by design
+ *    (approved plan §9): maintenance is skipped, never forced. An observability
+ *    counter must never be the thing that blocks a curator pass.
+ *
+ * The `.swarm` guard is not defensiveness: the counter lives inside the store,
+ * and when the store directory does not exist there is no usage log either, so
+ * there is nothing to count into and nothing should be created on the way.
+ *
+ * **Why this lock-taking path does not run the legacy migration.** Approved plan
+ * §6/BLK-13 says `needsMigration` is evaluated on first touch by any path that
+ * takes the lock. This one deliberately does not: `ensureMigrated` is private to
+ * `skill-usage-log.ts`, and it is benign to omit here because the document this
+ * writes keeps whatever `migrated` value it loaded — `false` for an un-migrated
+ * store — so the next `pruneSkillUsageLog` / `applySkillUsageFeedback` still
+ * migrates on its own first touch. This path can advance a counter; it can never
+ * mark a store migrated, and therefore can never strand one.
+ */
+declare function recordCuratorSkips(directory: string, skipped: number): void;
 /**
  * Auto-retire generated skills whose violation rate exceeds 30% or
  * whose source knowledge entries are all archived.

package/dist/hooks/knowledge-store.d.ts

@@ -170,7 +170,9 @@ export declare function inferTags(lesson: string): string[];
  * @param directory - Project root directory (used to resolve `.swarm/knowledge.jsonl`).
  * @param deltas    - Array of {id, delta} tuples. Delta may be positive (boost) or negative (decay).
  */
-export declare function bumpKnowledgeConfidenceBatch(directory: string, deltas: Array<{
+export declare function bumpKnowledgeConfidenceBatch(directory: string, deltas: KnowledgeConfidenceDelta[], options?: ConfidenceFloorOptions): Promise<number>;
+/** A single confidence adjustment request. */
+export interface KnowledgeConfidenceDelta {
     id: string;
     delta: number;
     receipt_events?: Array<{
@@ -178,7 +180,29 @@ export declare function bumpKnowledgeConfidenceBatch(directory: string, deltas:
         timestamp: string;
         outcome: 'applied' | 'violated' | 'ignored';
     }>;
-}>, options?: ConfidenceFloorOptions): Promise<number>;
+}
+/**
+ * Discriminated result of a batch confidence bump (issue #2038, BLK-4).
+ *
+ * `bumpKnowledgeConfidenceBatch` returns `0` both for "no matching knowledge
+ * IDs" (permanent — the ids are archived, deleted, or mistyped) and for
+ * "threw / lock failed" (transient — contention or I/O). A single counter
+ * cannot decide dequeue-vs-retain for the skill-usage pending queue: dequeuing
+ * on the transient case silently drops feedback, retaining on the permanent
+ * case creates an unbounded exempt set. `failed` separates them.
+ */
+export interface BumpKnowledgeConfidenceResult {
+    /** Number of knowledge entries actually touched. */
+    applied: number;
+    /** True when the batch threw or its lock could not be acquired. */
+    failed: boolean;
+}
+/**
+ * Additive variant of {@link bumpKnowledgeConfidenceBatch} that distinguishes
+ * "applied nothing" from "failed to run". Existing consumers are unchanged;
+ * `bumpKnowledgeConfidenceBatch` is a thin wrapper over this function.
+ */
+export declare function bumpKnowledgeConfidenceBatchResult(directory: string, deltas: KnowledgeConfidenceDelta[], options?: ConfidenceFloorOptions): Promise<BumpKnowledgeConfidenceResult>;
 /** Options for the G2 confidence-floor action in bumpKnowledgeConfidenceBatch. */
 export interface ConfidenceFloorOptions {
     /** Action when a just-bumped entry sits at the confidence floor with a

package/dist/hooks/skill-scoring.d.ts

@@ -3,11 +3,13 @@
  * usage data from `.swarm/skill-usage.jsonl`.
  *
  * All public functions are pure over their inputs. File I/O goes through
- * `readSkillUsageEntries` (imported from `skill-usage-log.ts`).
+ * `readSkillUsageEntriesWithCoverage` (imported from `skill-usage-log.ts`), the
+ * bounded read funnel of issue #2038: it reports whether the window it returned
+ * is the full history, which `formatSkillIndexWithContext` discloses.
  * An `_internals` DI seam mirrors the pattern in `skill-usage-log.ts`
  * and `skill-propagation-gate.ts` for testability.
  */
-import { type SkillUsageEntry } from './skill-usage-log.js';
+import { type SkillUsageEntry, type SkillUsageReadCoverage } from './skill-usage-log.js';
 /** Per-skill ranking entry returned by `rankSkillsForContext`. */
 export interface SkillRankEntry {
     /** Repo-relative path to the skill file. */
@@ -32,6 +34,13 @@ export interface SkillStats {
         agent: string;
         count: number;
     }>;
+    /**
+     * What the window these stats were computed from could and could not see
+     * (issue #2038 §7). Absent only on a `SkillStats` built by hand; every
+     * value produced by {@link getSkillStats} carries it, so a consumer can tell
+     * "0% compliance" from "compaction evicted the compliant half".
+     */
+    coverage?: SkillUsageReadCoverage;
 }
 export type SkillRunner = 'opencode' | 'claude' | 'codex';
 /** Parsed state of an explicit (or absent) top-level audience declaration. */
@@ -158,7 +167,8 @@ export declare function rankSkillsForContext(skills: string[], taskContext: stri
  *
  * @param skillPath - Repo-relative path to the skill file.
  * @param directory - Project root directory.
- * @returns `SkillStats` with aggregate metrics. Returns zeros/empty when log is missing.
+ * @returns `SkillStats` with aggregate metrics, carrying the coverage of the
+ *          window they were computed from. Returns zeros/empty when log is missing.
  */
 export declare function getSkillStats(skillPath: string, directory: string): SkillStats;
 /**