@cleocode/caamp 2026.8.1 → 2026.8.3

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { CaampInjectionAction } from '@cleocode/contracts/caamp-markers';
 import { WorktreeHandle } from '@cleocode/cant';
 import { PlatformPaths, SystemInfo } from '@cleocode/paths';
 export { PlatformPaths, SystemInfo } from '@cleocode/paths';
@@ -1467,7 +1468,7 @@ interface InstructionUpdateSummary {
     /** Detailed action log per instruction file. */
     actions: Array<{
         file: string;
-        action: 'created' | 'added' | 'consolidated' | 'updated' | 'intact';
+        action: CaampInjectionAction;
         providers: string[];
         configFormats: ConfigFormat[];
     }>;
@@ -2999,6 +3000,112 @@ declare function writeConfig(filePath: string, format: ConfigFormat, key: string
  */
 declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
 
+/**
+ * Atomic file writes and cross-process file locking.
+ *
+ * CAAMP mutates files that are shared by *every* project on the machine — most
+ * critically `~/.agents/AGENTS.md`, which every `cleo init`, `cleo upgrade` and
+ * `cleo doctor` run rewrites regardless of which project it was invoked from.
+ * A plain `writeFile` on such a path is `open(O_TRUNC)` followed by one or more
+ * `write(2)` calls: two processes interleaving there can leave a caller reading
+ * a half-written file, and a reader racing a writer can observe a truncated
+ * one.
+ *
+ * Two primitives remove that class of failure:
+ *
+ * - `writeFileAtomic` — the canonical tmp-then-rename primitive from
+ *   `@cleocode/core/tools/fs.js`. `rename(2)` within a filesystem is atomic, so
+ *   a concurrent reader sees either the whole old file or the whole new one,
+ *   never a mixture. It is re-exported here for callers already importing this
+ *   module; the definition lives in core, per the tools-vs-skills boundary.
+ * - {@link withFileLock} — serialise a whole read-modify-write cycle across
+ *   processes via an `O_EXCL` guard file, so two writers cannot both read the
+ *   pre-state and then clobber each other's result. Generalised from the
+ *   bespoke copy that lived inline in `lock-utils.ts` (now a caller).
+ *
+ * @task T12051
+ */
+/**
+ * Options controlling {@link withFileLock}.
+ *
+ * @public
+ */
+interface FileLockOptions {
+    /**
+     * Number of acquisition attempts before throwing.
+     *
+     * @defaultValue 400
+     */
+    retries?: number;
+    /**
+     * Delay between attempts, in milliseconds.
+     *
+     * @defaultValue 25
+     */
+    delayMs?: number;
+    /**
+     * Age at which an existing guard file is treated as abandoned and removed.
+     *
+     * @defaultValue 30000
+     */
+    staleMs?: number;
+}
+/**
+ * Run `fn` while holding an exclusive cross-process lock on `targetPath`.
+ *
+ * The lock is a `<targetPath>.lock` guard file created with `O_EXCL`, which is
+ * atomic on POSIX and on Windows. A guard left behind by a crashed process is
+ * reclaimed once it exceeds `staleMs`.
+ *
+ * The guard is always released, including when `fn` throws.
+ *
+ * @param targetPath - Path being protected (the guard is a sibling of it)
+ * @param fn - Work to perform while holding the lock
+ * @param options - Retry, delay and staleness tuning
+ * @returns Whatever `fn` returns
+ * @throws Error if the lock cannot be acquired within `retries` attempts
+ *
+ * @example
+ * ```typescript
+ * const action = await withFileLock(agentsMd, async () => {
+ *   const before = await readFile(agentsMd, "utf-8");
+ *   await writeFileAtomic(agentsMd, transform(before));
+ *   return "updated";
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Throw if a read looks like it landed inside another process's
+ * truncate-then-write window.
+ *
+ * `writeFileAtomic` makes *our* writes indivisible, but callers outside this
+ * package still rewrite instruction files with a plain `writeFile`, which is
+ * `open(O_TRUNC)` followed by `write(2)`. A read landing between those two
+ * returns an empty string for a file that is not empty on disk. Reconciling
+ * from that observation would replace every byte of the user's content with a
+ * lone CAAMP block.
+ *
+ * Failing closed is the right trade: the caller retries or reports, and the
+ * file is left exactly as it was.
+ *
+ * @param filePath - Path that was read, for the error message
+ * @param content - What the read returned
+ * @param sizeOnDisk - `stat().size` for the same path
+ * @throws Error when `content` is empty but `sizeOnDisk` is greater than zero
+ *
+ * @example
+ * ```typescript
+ * const text = await readFile(p, "utf-8");
+ * if (text.length === 0) assertNotTornRead(p, text, (await stat(p)).size);
+ * ```
+ *
+ * @public
+ */
+declare function assertNotTornRead(filePath: string, content: string, sizeOnDisk: number): void;
+
 /**
  * Skill installer - canonical + symlink model
  *
@@ -4483,13 +4590,36 @@ declare function resolveNativeEvent(nativeName: string): Array<{
 declare function getHookMappingsVersion(): string;
 
 /**
- * Marker-based instruction file injection
+ * CAAMP marker engine — parsing, damage repair, and canonical block rendering.
  *
- * Injects content blocks between CAAMP markers in instruction files
- * (CLAUDE.md, AGENTS.md, GEMINI.md) and agent-definition files
- * (cleo-subagent.md, seed agent profiles) per provider's native folder.
+ * The grammar itself lives in `@cleocode/contracts/caamp-markers` (const data
+ * in the leaf package, because `@cleocode/core` and `@cleocode/caamp` depend on
+ * each other and cannot share a module directly). This file is the only place
+ * that turns that grammar into behaviour.
+ *
+ * ## Why damage repair exists
+ *
+ * A CAAMP block is delimited by two HTML comments. Losing a single character
+ * from an opening marker — `<!-- CAAMP:START -->` becoming `!-- CAAMP:START -->`
+ * — used to be unrecoverable *and* self-amplifying:
+ *
+ * 1. The strict pattern no longer matched the block.
+ * 2. `inject()` concluded the file had no CAAMP block at all and **prepended a
+ *    fresh one**, rather than replacing the damaged one.
+ * 3. The file now contained two blocks. The protocol text they reference was
+ *    loaded into every agent's context twice.
+ * 4. `cleo doctor` reported "markers unbalanced" and prescribed `cleo upgrade`
+ *    — which ran `inject()` again and could only make it worse.
+ *
+ * That ratchet was observed in the wild on `~/.agents/AGENTS.md`, which had
+ * accumulated three blocks from two separate single-byte losses.
+ *
+ * {@link normalizeMarkers} breaks the loop by healing near-miss markers back to
+ * canonical form *before* any decision is made about the file, so a damaged
+ * block is recognised and replaced instead of duplicated.
+ *
+ * @task T12051
  */
-
 /**
  * A single parsed CAAMP block extracted from a file.
  *
@@ -4505,6 +4635,209 @@ interface CaampBlock {
     /** Zero-based character offset immediately after the block in the file. */
     endIndex: number;
 }
+/**
+ * Result of healing damaged markers in a string.
+ *
+ * @public
+ */
+interface NormalizeResult {
+    /** Content with every recognised marker rewritten to canonical form. */
+    content: string;
+    /** How many marker lines were rewritten. `0` means the input was already canonical. */
+    repaired: number;
+}
+/**
+ * Build a fresh global pattern matching a complete canonical CAAMP block.
+ *
+ * A new `RegExp` is returned on every call deliberately. A shared module-level
+ * `RegExp` carrying the `g` flag holds a mutable `lastIndex`, so reusing one
+ * across `.test()` or `.exec()` calls silently skips matches — a defect that
+ * previously existed in `removeInjection`.
+ *
+ * @returns A new `RegExp` with the `g` flag; capture group 1 is the block body
+ *
+ * @example
+ * ```typescript
+ * for (const m of content.matchAll(blockPattern())) {
+ *   console.log(m[1]);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function blockPattern(): RegExp;
+/**
+ * Rewrite every damaged CAAMP marker line back to its canonical form.
+ *
+ * Only whole lines are considered, so prose that merely mentions a marker is
+ * left alone. Lines that are already canonical are matched but rewritten to an
+ * identical string, and therefore are not counted as repairs.
+ *
+ * @param content - Raw file contents
+ * @returns The healed content and the number of marker lines actually changed
+ *
+ * @example
+ * ```typescript
+ * const { content, repaired } = normalizeMarkers(await readFile(p, "utf-8"));
+ * if (repaired > 0) console.log(`healed ${repaired} damaged marker(s)`);
+ * ```
+ *
+ * @public
+ */
+declare function normalizeMarkers(content: string): NormalizeResult;
+/**
+ * Parse every canonical CAAMP block out of a file's contents.
+ *
+ * Blocks are returned in order of appearance. An opening marker with no
+ * matching closing marker is skipped rather than throwing, so a corrupted file
+ * can still be inspected.
+ *
+ * Call {@link normalizeMarkers} first if the input may contain damaged markers
+ * — this function is deliberately strict.
+ *
+ * @param fileContent - Raw text content of the file
+ * @returns Array of parsed CAAMP blocks
+ *
+ * @example
+ * ```typescript
+ * const blocks = parseBlocks(await readFile(agentsMd, "utf-8"));
+ * console.log(`${blocks.length} block(s)`);
+ * ```
+ *
+ * @public
+ */
+declare function parseBlocks(fileContent: string): CaampBlock[];
+/**
+ * Wrap content in canonical CAAMP markers.
+ *
+ * @param content - Body of the block
+ * @returns The full block, markers included
+ *
+ * @example
+ * ```typescript
+ * buildBlock("@AGENTS.md");
+ * // "<!-- CAAMP:START -->\n@AGENTS.md\n<!-- CAAMP:END -->"
+ * ```
+ *
+ * @public
+ */
+declare function buildBlock(content: string): string;
+/**
+ * Where {@link reconcile} places the block when the file has none yet.
+ *
+ * Only applies to a file that has no CAAMP block at all — an existing block is
+ * always replaced where it already is, never moved.
+ *
+ * @public
+ */
+type BlockInsertPosition = 'prepend' | 'append';
+/**
+ * Outcome of reconciling a file's contents against the desired CAAMP block.
+ *
+ * @public
+ */
+interface ReconcileResult {
+    /** The file contents that should be on disk. */
+    content: string;
+    /** Number of blocks found before reconciliation. */
+    blocksBefore: number;
+    /** Number of damaged marker lines healed. */
+    repaired: number;
+}
+/**
+ * Reconcile a file's contents so it contains exactly one canonical CAAMP block
+ * carrying `desiredContent`.
+ *
+ * The rules, in order:
+ *
+ * 1. Damaged markers are healed first, so a corrupted block is recognised as a
+ *    block rather than treated as absent.
+ * 2. If the file has no block, one is inserted — at the top by default, or at
+ *    the bottom when `insert` is `'append'` (which is what the Pi harness has
+ *    always done for its own `AGENTS.md`).
+ * 3. If the file has one or more blocks, the **first** is replaced in place and
+ *    any others are removed. Replacing in place matters: prepending instead
+ *    would walk the block up the file on every run, and would separate it from
+ *    any heading a user wrote above it.
+ * 4. All text outside CAAMP blocks is preserved. CAAMP owns the region between
+ *    its markers and nothing else in the file. The only change made outside
+ *    them is whitespace tidying — runs of three or more newlines collapse to
+ *    two, and the file ends with exactly one newline. No non-blank line is
+ *    ever removed, reordered or rewritten.
+ *
+ * This function is pure — it performs no I/O, which is what makes the
+ * behaviour straightforward to test exhaustively.
+ *
+ * @param existing - Current file contents
+ * @param desiredContent - Body the single surviving block should carry
+ * @param insert - Placement when the file has no block yet
+ * @returns The reconciled content plus what was found on the way
+ *
+ * @example
+ * ```typescript
+ * const { content, blocksBefore, repaired } = reconcile(onDisk, "@AGENTS.md");
+ * if (content !== onDisk) await writeFileAtomic(path, content);
+ * ```
+ *
+ * @public
+ */
+declare function reconcile(existing: string, desiredContent: string, insert?: BlockInsertPosition): ReconcileResult;
+/**
+ * Merge the bodies of several CAAMP blocks into one, preserving order and
+ * dropping exact duplicate lines.
+ *
+ * Used by repair, which — unlike injection — does not know what the block
+ * *should* contain. Keeping the union rather than picking a winner means no
+ * reference is silently dropped when two blocks legitimately differ (a project
+ * block carrying `@AGENTS.md` and a global one carrying
+ * `@~/.agents/AGENTS.md`, for instance).
+ *
+ * @param blocks - Blocks to merge, in file order
+ * @returns The merged body
+ *
+ * @example
+ * ```typescript
+ * mergeBlockBodies(parseBlocks(content));
+ * // "@AGENTS.md\n@~/.agents/AGENTS.md"
+ * ```
+ *
+ * @public
+ */
+declare function mergeBlockBodies(blocks: readonly CaampBlock[]): string;
+/**
+ * Restore a file to exactly one well-formed CAAMP block without needing to
+ * know what that block should contain.
+ *
+ * This is what `cleo caamp repair` and `cleo doctor` use. Injection knows the
+ * desired body and calls {@link reconcile}; repair does not, so it derives the
+ * surviving body from what is already there via {@link mergeBlockBodies}.
+ *
+ * Deriving rather than deduplicating matters: the previous repair removed only
+ * blocks with *identical* bodies, so a file with two blocks carrying different
+ * references was reported as "2 blocks (expected 1)" by the health check and
+ * then left untouched by the repair the health check prescribed — an
+ * unfixable warning loop.
+ *
+ * @param existing - Current file contents
+ * @returns The repaired content plus what was found on the way
+ *
+ * @example
+ * ```typescript
+ * const { content, blocksBefore, repaired } = repairContent(onDisk);
+ * ```
+ *
+ * @public
+ */
+declare function repairContent(existing: string): ReconcileResult;
+
+/**
+ * Marker-based instruction file injection
+ *
+ * Injects content blocks between CAAMP markers in instruction files
+ * (CLAUDE.md, AGENTS.md, GEMINI.md) and agent-definition files
+ * (cleo-subagent.md, seed agent profiles) per provider's native folder.
+ */
+
 /**
  * Parse all CAAMP blocks from a file's content string.
  *
@@ -4515,6 +4848,15 @@ interface CaampBlock {
  * @param fileContent - Raw text content of the file
  * @returns Array of parsed CAAMP blocks
  *
+ * @remarks
+ * Strict: a block whose marker has been damaged (for example a lost `<`) is
+ * not seen. Run {@link normalizeMarkers} first when the input may be corrupt.
+ *
+ * @example
+ * ```typescript
+ * const blocks = parseCaampBlocks(await readFile(agentsMd, "utf-8"));
+ * ```
+ *
  * @public
  */
 declare function parseCaampBlocks(fileContent: string): CaampBlock[];
@@ -4532,6 +4874,13 @@ interface DedupeResult {
     kept: number;
     /** `true` if the file was modified on disk; `false` if it was already clean. */
     modified: boolean;
+    /**
+     * Number of damaged marker lines healed back to canonical form.
+     *
+     * Non-zero means the file had corruption that the strict block pattern could
+     * not see — the condition that used to make duplicates accumulate invisibly.
+     */
+    repaired: number;
 }
 /**
  * Deduplicate CAAMP blocks in a file by content.
@@ -4585,6 +4934,75 @@ declare function dedupeFile(filePath: string): Promise<DedupeResult>;
  * @public
  */
 declare function dedupeFiles(filePaths: string[]): Promise<DedupeResult[]>;
+/**
+ * Every instruction file CAAMP may have written to, for a given project.
+ *
+ * Covers three tiers, because corruption in any one of them affects every
+ * agent session:
+ *
+ * 1. The **global hub** `~/.agents/AGENTS.md` — the highest-risk file in the
+ *    system. Every `cleo init`, `cleo upgrade` and `cleo doctor` run rewrites
+ *    it regardless of which project invoked them, and until T12051 no health
+ *    check looked at it at all.
+ * 2. The project's own `AGENTS.md`, `CLAUDE.md` and `GEMINI.md`.
+ * 3. Each detected provider's global instruction file.
+ *
+ * Paths are de-duplicated and returned whether or not they exist; callers skip
+ * missing ones.
+ *
+ * @param projectDir - Absolute path to the project directory
+ * @param providers - Detected providers whose global files should be included
+ * @returns De-duplicated absolute paths, global hub first
+ *
+ * @example
+ * ```typescript
+ * const paths = instructionFileCascade("/project", getInstalledProviders());
+ * const results = await dedupeFiles(paths);
+ * ```
+ *
+ * @public
+ */
+declare function instructionFileCascade(projectDir: string, providers: Provider[]): string[];
+/**
+ * Summary of a repair sweep across instruction files.
+ *
+ * @public
+ */
+interface RepairResult {
+    /** Per-file outcomes, in cascade order. Files that do not exist are omitted. */
+    files: DedupeResult[];
+    /** Total damaged marker lines healed across all files. */
+    repaired: number;
+    /** Total duplicate blocks removed across all files. */
+    removed: number;
+    /** How many files were actually rewritten. */
+    filesModified: number;
+}
+/**
+ * Heal damaged CAAMP markers and collapse duplicate blocks across a project's
+ * whole instruction-file cascade.
+ *
+ * This is the repair that `cleo doctor` prescribes. It is deliberately
+ * content-agnostic — it does not need to know what *should* be inside the
+ * block, so it can restore a file to a well-formed single-block state without
+ * a provider registry lookup or a template refresh.
+ *
+ * Safe to run repeatedly: a healthy cascade reports `repaired: 0`,
+ * `removed: 0`, `filesModified: 0` and performs no writes.
+ *
+ * @param projectDir - Absolute path to the project directory
+ * @param providers - Detected providers whose global files should be included
+ * @returns Aggregate repair summary
+ *
+ * @example
+ * ```typescript
+ * const result = await repairInstructionFiles("/project", getInstalledProviders());
+ * console.log(`healed ${result.repaired} marker(s), removed ${result.removed} duplicate(s)`);
+ * ```
+ *
+ * @public
+ */
+declare function repairInstructionFiles(projectDir: string, providers: Provider[]): Promise<RepairResult>;
 /**
  * Check the status of a CAAMP injection block in an instruction file.
  *
@@ -4618,7 +5036,8 @@ declare function checkInjection(filePath: string, expectedContent?: string): Pro
  * Behavior depends on the file state:
  * - File does not exist: creates the file with the injection block → `"created"`
  * - File exists without markers: prepends the injection block → `"added"`
- * - File exists with multiple markers (duplicates): consolidates into single block → `"consolidated"`
+ * - File exists with a damaged marker: heals it and replaces in place → `"repaired"`
+ * - File exists with multiple markers (duplicates): consolidates into a single block → `"consolidated"`
  * - File exists with markers, content differs: replaces the block → `"updated"`
  * - File exists with markers, content matches: no-op → `"intact"`
  *
@@ -4627,11 +5046,21 @@ declare function checkInjection(filePath: string, expectedContent?: string): Pro
  *
  * @param filePath - Absolute path to the instruction file
  * @param content - Content to inject between CAAMP markers
- * @returns Action taken: `"created"`, `"added"`, `"consolidated"`, `"updated"`, or `"intact"`
+ * @returns The {@link CaampInjectionAction} describing what was done
  *
  * @remarks
- * Handles duplicate marker consolidation automatically. When multiple CAAMP
- * blocks are detected (from manual edits or bugs), they are merged into one.
+ * Damaged markers are healed *before* the file is classified. This is what
+ * stops a single lost character from ratcheting into duplicate blocks: prior
+ * to T12051 a marker that lost its leading `<` was invisible to the block
+ * pattern, so this function concluded the file had no block and prepended a
+ * second one — permanently doubling the injected protocol text, and doubling
+ * again on the next mishap.
+ *
+ * The whole read-modify-write cycle runs under a cross-process lock and the
+ * write itself is atomic, because the busiest target — `~/.agents/AGENTS.md` —
+ * is rewritten by every project on the machine.
+ *
+ * All text outside the CAAMP markers is preserved verbatim.
  *
  * @example
  * ```typescript
@@ -4641,7 +5070,7 @@ declare function checkInjection(filePath: string, expectedContent?: string): Pro
  *
  * @public
  */
-declare function inject(filePath: string, content: string): Promise<'created' | 'added' | 'consolidated' | 'updated' | 'intact'>;
+declare function inject(filePath: string, content: string): Promise<CaampInjectionAction>;
 /**
  * Remove the CAAMP injection block from an instruction file.
  *
@@ -4654,6 +5083,9 @@ declare function inject(filePath: string, content: string): Promise<'created' |
  * Cleans up any leftover blank lines after removing the block. If the file
  * would be entirely empty after removal, the file itself is deleted.
  *
+ * Blocks whose markers are damaged are healed first, so uninstall removes them
+ * too rather than leaving orphaned fragments behind.
+ *
  * @example
  * ```typescript
  * const removed = await removeInjection("/project/CLAUDE.md");
@@ -4712,7 +5144,7 @@ declare function checkAllInjections(providers: Provider[], projectDir: string, s
  *
  * @public
  */
-declare function injectAll(providers: Provider[], projectDir: string, scope: 'project' | 'global', content: string): Promise<Map<string, 'created' | 'added' | 'consolidated' | 'updated' | 'intact'>>;
+declare function injectAll(providers: Provider[], projectDir: string, scope: 'project' | 'global', content: string): Promise<Map<string, CaampInjectionAction>>;
 /**
  * Options for ensuring a provider instruction file.
  *
@@ -4745,7 +5177,7 @@ interface EnsureProviderInstructionFileResult {
     /** Instruction file name from the provider registry. */
     instructFile: string;
     /** Action taken. */
-    action: 'created' | 'added' | 'consolidated' | 'updated' | 'intact';
+    action: CaampInjectionAction;
     /** Provider ID. */
     providerId: string;
 }
@@ -4859,7 +5291,7 @@ interface WriteAgentFileResult {
     /** Absolute path to the written agent-definition file. */
     filePath: string;
     /** Action taken. */
-    action: 'created' | 'added' | 'consolidated' | 'updated' | 'intact';
+    action: CaampInjectionAction;
 }
 /**
  * Options for writing agent-definition files to provider agent folders.
@@ -8449,4 +8881,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallSkillOptions, type InstructionUpdateSummary, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillRowData, type SkillRowSourceType, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inferSkillSourceType, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeAgentFileToAllProviders, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type BlockInsertPosition, CANONICAL_HOOK_EVENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type FileLockOptions, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallSkillOptions, type InstructionUpdateSummary, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizeResult, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type ReconcileResult, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type RepairResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillRowData, type SkillRowSourceType, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetPlatformPathsCache, assertNotTornRead, blockPattern, buildBlock, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inferSkillSourceType, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, instructionFileCascade, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, mergeBlockBodies, normalizeMarkers, normalizeRecommendationCriteria, parseBlocks, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, reconcile, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, repairContent, repairInstructionFiles, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, withFileLock, writeAgentFileToAllProviders, writeConfig };

package/dist/index.js

@@ -71,8 +71,11 @@ import {
   validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-QUAT7JH6.js";
+} from "./chunk-6KBUDJZI.js";
 import {
+  assertNotTornRead,
+  blockPattern,
+  buildBlock,
   buildInjectionContent,
   buildSkillsMap,
   checkAllInjections,
@@ -104,14 +107,22 @@ import {
   groupByInstructFile,
   inject,
   injectAll,
+  instructionFileCascade,
+  mergeBlockBodies,
+  normalizeMarkers,
+  parseBlocks,
   parseCaampBlocks,
   parseInjectionContent,
   providerSupports,
   providerSupportsById,
+  reconcile,
   removeInjection,
+  repairContent,
+  repairInstructionFiles,
   resolveAlias,
+  withFileLock,
   writeAgentFileToAllProviders
-} from "./chunk-EH5U4PRC.js";
+} from "./chunk-3IQUGSIV.js";
 import {
   CANONICAL_HOOK_EVENTS,
   HOOK_CATEGORIES,
@@ -274,7 +285,7 @@ function shouldOverrideSkill(skillName, incomingSource, existingEntry) {
   return true;
 }
 async function validateInstructionIntegrity(providers, projectDir, scope, expectedContent) {
-  const { checkAllInjections: checkAllInjections2 } = await import("./injector-3TOVIDBO.js");
+  const { checkAllInjections: checkAllInjections2 } = await import("./injector-6YGSK3B6.js");
   const results = await checkAllInjections2(providers, projectDir, scope, expectedContent);
   const issues = [];
   for (const result of results) {
@@ -310,6 +321,9 @@ export {
   PiRequiredError,
   RECOMMENDATION_ERROR_CODES,
   _resetPlatformPathsCache,
+  assertNotTornRead,
+  blockPattern,
+  buildBlock,
   buildHookMatrix,
   buildInjectionContent,
   buildLibraryFromFiles,
@@ -397,6 +411,7 @@ export {
   installBatchWithRollback,
   installMcpServer,
   installSkill,
+  instructionFileCascade,
   isCaampOwnedSkill,
   isExclusivityMode,
   isMarketplaceScoped,
@@ -406,7 +421,10 @@ export {
   listCanonicalSkills,
   listMcpServers,
   loadLibraryFromModule,
+  mergeBlockBodies,
+  normalizeMarkers,
   normalizeRecommendationCriteria,
+  parseBlocks,
   parseCaampBlocks,
   parseInjectionContent,
   parseSkillFile,
@@ -416,6 +434,7 @@ export {
   rankSkills,
   readConfig,
   recommendSkills,
+  reconcile,
   recordSkillInstall,
   registerSkillLibrary,
   registerSkillLibraryFromPath,
@@ -425,6 +444,8 @@ export {
   removeMcpServerFromAll,
   removeSkill,
   removeSkillFromLock,
+  repairContent,
+  repairInstructionFiles,
   resetDetectionCache,
   resetExclusivityModeOverride,
   resolveAlias,
@@ -453,6 +474,7 @@ export {
   validateInstructionIntegrity,
   validateRecommendationCriteria,
   validateSkill,
+  withFileLock,
   writeAgentFileToAllProviders,
   writeConfig
 };