@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/staleness/fingerprint.js

@@ -1,15 +1,9 @@
-/**
- * File and directory fingerprinting primitives shared by every resource
- * checker. Two-tier comparison: stat (mtime+size) first for the hot path,
- * sha256 only on miss.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 export function sha256(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
 }
-/** Fingerprint a single file. Returns null when the file is unreadable. */
 export function fingerprintFile(filePath) {
     try {
         const stat = fs.statSync(filePath);
@@ -20,17 +14,6 @@ export function fingerprintFile(filePath) {
         return null;
     }
 }
-/**
- * Names we never fingerprint: OS metadata, VCS bookkeeping, dep caches,
- * build outputs. Matches the SKILL_COPY_IGNORE set used by the sync writer
- * in `src/lib/installations/versions.ts`.
- *
- * Important: this is an allowlist of noise, NOT a blanket "skip every
- * dot-prefixed entry". Plugins keep their manifest at
- * `.claude-plugin/plugin.json` — a dot-prefix skip would make plugin
- * manifests invisible to the fingerprint and silently break staleness
- * detection for plugins.
- */
 const FINGERPRINT_SKIP = new Set([
     '.DS_Store',
     '.git',
@@ -39,11 +22,6 @@ const FINGERPRINT_SKIP = new Set([
     '__pycache__',
     'node_modules',
 ]);
-/**
- * Fingerprint all files in a directory recursively. Returned sorted by
- * absolute path so ordering is deterministic regardless of readdir order.
- * Noise entries (see `FINGERPRINT_SKIP`) are excluded.
- */
 export function fingerprintDir(dirPath) {
     const results = [];
     function walk(dir) {
@@ -71,7 +49,6 @@ export function fingerprintDir(dirPath) {
     results.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     return results;
 }
-/** Hot-path file staleness: stat-only when mtime+size match, sha256 on miss. */
 export function isFileStale(stored, currentPath) {
     if (stored.path !== currentPath)
         return true;
@@ -85,11 +62,6 @@ export function isFileStale(stored, currentPath) {
         return true;
     }
 }
-/**
- * Hot-path directory staleness. Compares sorted paths first (catches add /
- * remove / rename), then stat each file (skips reads when mtime+size match),
- * sha256 only on stat mismatch.
- */
 export function isDirStale(storedDirPath, storedFiles, currentDirPath) {
     if (storedDirPath !== currentDirPath)
         return true;
@@ -114,12 +86,6 @@ export function isDirStale(storedDirPath, storedFiles, currentDirPath) {
     }
     return false;
 }
-/**
- * Walk a directory and return sorted absolute paths of every regular file.
- * No content reads. Uses the same FINGERPRINT_SKIP allowlist as
- * `fingerprintDir` so both produce the same path set (required for the
- * dir-stale path comparison to work).
- */
 function walkDirPaths(dirPath) {
     const results = [];
     function walk(dir) {
@@ -144,7 +110,6 @@ function walkDirPaths(dirPath) {
     results.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     return results;
 }
-/** True if two sorted-or-unsorted name sets differ. */
 export function nameSetDiffers(a, b) {
     if (a.length !== b.length)
         return true;

package/dist/lib/staleness/index.d.ts

@@ -1,37 +1,9 @@
-/**
- * Staleness library entrypoint. Aggregates per-resource checkers into the
- * two operations the rest of the codebase needs:
- *
- *   - `buildManifest(agent, version, cwd)` — snapshot current state.
- *   - `isStale(manifest, agent, version, cwd)` — true when any tracked
- *     resource has drifted from its stored fingerprint, or when an artifact
- *     the last full sync wrote (`writtenTargets`) has been deleted from the
- *     version home (#2398).
- *
- * `loadManifest` / `saveManifest` round-trip the on-disk JSON. The format
- * version stays at 1; new optional fields (workflows, plugins) on old files
- * read as empty maps which forces a single re-sync.
- */
 import type { AgentId } from '../types.js';
 import { type SyncManifest, type FileEntry, type DirEntry, type PluginEntry, type RulesEntry } from './types.js';
 export type { SyncManifest } from './types.js';
 export { MANIFEST_VERSION } from './types.js';
 export declare function loadManifest(agent: AgentId, version: string): SyncManifest | null;
 export declare function saveManifest(agent: AgentId, version: string, manifest: SyncManifest): void;
-/**
- * Snapshot current resource fingerprints for `agent@version`.
- *
- * When `previous` is supplied (the still-loaded post-guard manifest), any
- * entry whose stored path/mtime/size still match via the checker's `isFresh`
- * is carried forward without re-hashing. Measured: full rebuild ~716 ms →
- * carry-forward near the 5.67 ms `isStale` cost on an unchanged tree
- * (RUSH-2320 #3).
- */
 export declare function buildManifest(agent: AgentId, version: string, cwd: string, previous?: SyncManifest | null): SyncManifest;
-/**
- * True when any tracked resource has drifted from the stored manifest.
- * Walks every resource type in turn and returns true at the first miss —
- * sync detection should be cheap when nothing changed.
- */
 export declare function isStale(manifest: SyncManifest, agent: AgentId, version: string, cwd: string): boolean;
 export type { FileEntry, DirEntry, PluginEntry, RulesEntry };

package/dist/lib/staleness/index.js

@@ -1,17 +1,3 @@
-/**
- * Staleness library entrypoint. Aggregates per-resource checkers into the
- * two operations the rest of the codebase needs:
- *
- *   - `buildManifest(agent, version, cwd)` — snapshot current state.
- *   - `isStale(manifest, agent, version, cwd)` — true when any tracked
- *     resource has drifted from its stored fingerprint, or when an artifact
- *     the last full sync wrote (`writtenTargets`) has been deleted from the
- *     version home (#2398).
- *
- * `loadManifest` / `saveManifest` round-trip the on-disk JSON. The format
- * version stays at 1; new optional fields (workflows, plugins) on old files
- * read as empty maps which forces a single re-sync.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getVersionsDir } from '../state.js';
@@ -27,10 +13,6 @@ import { buildRules, isRulesStale } from './checkers/rules.js';
 import { MANIFEST_VERSION, } from './types.js';
 import { nameSetDiffers } from './fingerprint.js';
 export { MANIFEST_VERSION } from './types.js';
-/**
- * Standard checkers — uniform contract. Rules and permissions have extra
- * context (agent/version, preset env) so they're wired explicitly below.
- */
 const STANDARD_CHECKERS = [
     { checker: commandsChecker, field: 'commands' },
     { checker: skillsChecker, field: 'skills' },
@@ -40,7 +22,6 @@ const STANDARD_CHECKERS = [
     { checker: workflowsChecker, field: 'workflows' },
     { checker: pluginsChecker, field: 'plugins' },
 ];
-// ─── Public API ──────────────────────────────────────────────────────────────
 function manifestPath(agent, version) {
     return path.join(getVersionsDir(), agent, version, 'home', '.sync-manifest.json');
 }
@@ -68,18 +49,9 @@ export function saveManifest(agent, version, manifest) {
         try {
             fs.unlinkSync(tmp);
         }
-        catch { /* ignore */ }
+        catch { }
     }
 }
-/**
- * Snapshot current resource fingerprints for `agent@version`.
- *
- * When `previous` is supplied (the still-loaded post-guard manifest), any
- * entry whose stored path/mtime/size still match via the checker's `isFresh`
- * is carried forward without re-hashing. Measured: full rebuild ~716 ms →
- * carry-forward near the 5.67 ms `isStale` cost on an unchanged tree
- * (RUSH-2320 #3).
- */
 export function buildManifest(agent, version, cwd, previous) {
     const manifest = {
         v: MANIFEST_VERSION,
@@ -93,11 +65,6 @@ export function buildManifest(agent, version, cwd, previous) {
         subagents: {},
         workflows: {},
         plugins: {},
-        // Empty baseline ("nothing recorded to verify"). The full-sync
-        // orchestrator (versions.ts) replaces this with the writer-reported
-        // artifact paths right before saving; a manifest built outside that path
-        // simply verifies nothing. Only an ABSENT field (a pre-upgrade manifest
-        // on disk) forces the one-time migration re-sync in isStale.
         writtenTargets: [],
     };
     for (const { checker, field } of STANDARD_CHECKERS) {
@@ -128,11 +95,6 @@ export function buildManifest(agent, version, cwd, previous) {
     }
     return manifest;
 }
-/**
- * True when any tracked resource has drifted from the stored manifest.
- * Walks every resource type in turn and returns true at the first miss —
- * sync detection should be cheap when nothing changed.
- */
 export function isStale(manifest, agent, version, cwd) {
     for (const { checker, field } of STANDARD_CHECKERS) {
         const storedMap = (manifest[field] ?? {});
@@ -151,12 +113,6 @@ export function isStale(manifest, agent, version, cwd) {
         return true;
     if (isRulesStale(manifest.rules, agent, version, cwd))
         return true;
-    // Home-side deletion check (#2398): every artifact the last full sync wrote
-    // must still exist, or the version home has rotted and needs a re-sync —
-    // regardless of source fingerprints. One existsSync per path, no content
-    // reads, so the fast-guard budget holds (RUSH-2320). A manifest that
-    // predates the field reads as stale once so the next full sync records the
-    // baseline (same precedent as the optional workflows/plugins maps).
     if (manifest.writtenTargets === undefined)
         return true;
     for (const target of manifest.writtenTargets) {

package/dist/lib/staleness/layers.d.ts

@@ -1,37 +1,14 @@
-/**
- * Layer resolution for resources. Encapsulates which DotAgents repos a given
- * resource type reads from and in what precedence. Centralized so every
- * checker, plus the sync writer, agrees on the same set.
- *
- * Resolution model:
- *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
- *     project > user > system > extras. Same-named entries shadow.
- *   - "first-wins, no project" (hooks): security exclusion — see
- *     `src/lib/installations/versions.ts:1832-1836` for the rationale. User > system > extras.
- *   - "merged" (permissions): every layer contributes; first-wins on name.
- *   - "composed" (rules): preset + subrules resolved per-name across layers.
- */
-/** Layer of provenance for a single resource entry. */
 export type LayerScope = 'project' | 'user' | 'system' | 'extra';
 export interface Layer {
     scope: LayerScope;
-    /** Absolute path of the repo root (e.g. `~/.agents`). */
     base: string;
-    /** Set only when scope === 'extra'. */
     alias?: string;
 }
 export declare function clearLayerCache(): void;
-/** All layers a "first-wins with project" resource consults, in precedence order. */
 export declare function firstWinsLayers(cwd: string): Layer[];
-/** Hooks-only: layers excluding project (security exclusion). */
 export declare function hookLayers(): Layer[];
-/**
- * Resolve a single resource by name. Returns the first matching layer's
- * absolute path plus the layer scope, or null when no layer has it.
- */
 export declare function resolveByName(layers: Layer[], relative: string, predicate: (full: string) => boolean): {
     path: string;
     layer: Layer;
 } | null;
-/** Convenience: list names found by reading a relative subdir across all given layers. */
 export declare function listAcrossLayers(layers: Layer[], relative: string, filter: (name: string, fullPath: string) => boolean): string[];

package/dist/lib/staleness/layers.js

@@ -1,40 +1,12 @@
-/**
- * Layer resolution for resources. Encapsulates which DotAgents repos a given
- * resource type reads from and in what precedence. Centralized so every
- * checker, plus the sync writer, agrees on the same set.
- *
- * Resolution model:
- *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
- *     project > user > system > extras. Same-named entries shadow.
- *   - "first-wins, no project" (hooks): security exclusion — see
- *     `src/lib/installations/versions.ts:1832-1836` for the rationale. User > system > extras.
- *   - "merged" (permissions): every layer contributes; first-wins on name.
- *   - "composed" (rules): preset + subrules resolved per-name across layers.
- */
 import * as path from 'path';
 import * as fs from 'fs';
 import { getProjectAgentsDir, getUserAgentsDir, getAgentsDir, getEnabledExtraRepos, } from '../state.js';
-// ─── Per-process memoization ─────────────────────────────────────────────────
-//
-// `firstWinsLayers(cwd)` and `hookLayers()` get called from every checker for
-// every resource — easily 50+ times per `isStale` call. Each call invokes
-// `getProjectAgentsDir(cwd)` (walks up the filesystem) and `getEnabledExtraRepos()`
-// (reads agents.yaml). Memoizing at process scope eliminates the redundancy.
-//
-// Safety: in a CLI invocation, neither cwd nor the user/system base dirs
-// change mid-process, so the cache is always correct. Tests that exercise
-// different HOMEs/cwds run in separate subprocesses (per `_harness.ts`), so
-// the module's process-scope cache resets between scenarios.
-//
-// `clearLayerCache()` is exposed for tests or long-running daemons that need
-// to force re-discovery.
 const firstWinsCache = new Map();
 let hookLayersCache = null;
 export function clearLayerCache() {
     firstWinsCache.clear();
     hookLayersCache = null;
 }
-/** All layers a "first-wins with project" resource consults, in precedence order. */
 export function firstWinsLayers(cwd) {
     const cached = firstWinsCache.get(cwd);
     if (cached)
@@ -51,7 +23,6 @@ export function firstWinsLayers(cwd) {
     firstWinsCache.set(cwd, layers);
     return layers;
 }
-/** Hooks-only: layers excluding project (security exclusion). */
 export function hookLayers() {
     if (hookLayersCache)
         return hookLayersCache;
@@ -64,10 +35,6 @@ export function hookLayers() {
     hookLayersCache = layers;
     return layers;
 }
-/**
- * Resolve a single resource by name. Returns the first matching layer's
- * absolute path plus the layer scope, or null when no layer has it.
- */
 export function resolveByName(layers, relative, predicate) {
     for (const layer of layers) {
         const full = path.join(layer.base, relative);
@@ -76,7 +43,6 @@ export function resolveByName(layers, relative, predicate) {
     }
     return null;
 }
-/** Convenience: list names found by reading a relative subdir across all given layers. */
 export function listAcrossLayers(layers, relative, filter) {
     const seen = new Set();
     for (const layer of layers) {

package/dist/lib/staleness/prune.d.ts

@@ -1,58 +1,5 @@
-/**
- * Manifest-bounded prune (RUSH-2438).
- *
- * `agents sync` was additive-only: it installed/updated resources present in
- * source but never removed a resource that had been DELETED from source, so a
- * removed command/skill/hook lingered in every installed version home forever
- * (and stayed live in the `/` menu). Bare `agents sync <agent>` full syncs did
- * sweep orphans, but the repo-scoped forms the reconcile path actually uses —
- * `agents sync <agent>@all system`, `agents sync <agent> system --force` — pass
- * a selection, which turned the orphan sweeps off. This closes that gap.
- *
- * The prune set is computed by name, bounded by the sync manifest:
- *
- *     prune = (names the last sync recorded as installed)
- *           − (names still present in source across ALL layers)
- *           ∩ (names currently materialized in the version home)
- *
- * Each clause is a safety guarantee:
- *   - The manifest bound means only agents-installed resources are ever
- *     candidates — a file the user hand-authored into the version home was
- *     never recorded, so it is never touched.
- *   - Diffing against ALL layers (not just the scoped one) means a resource
- *     still provided by any other layer — e.g. a same-named user command that
- *     shadows a removed system command — stays: it is still "in source".
- *   - Requiring the name to be materialized skips work for anything already
- *     gone and never errors on a missing path.
- *
- * When there is NO manifest we cannot know what a prior sync installed, so we
- * FAIL LOUD by pruning nothing and reporting it — never a "delete everything
- * not in source" guess. The manifest is written by the next full sync, so the
- * baseline heals itself.
- *
- * Deletion itself is delegated to each writer's `remove()` (the inverse of
- * `write()`), so per-harness layout knowledge — native file vs command-skill
- * dir vs goose recipe — lives in one place and can't drift.
- */
 import type { AgentId } from '../types.js';
 import type { SyncManifest } from './types.js';
-/**
- * Kinds prune reconciles. Restricted to the name-keyed file/dir resources whose
- * writer implements `remove()`. Deliberately excluded, each with a reason:
- *   - hooks — a version-home hook script is coupled to a settings.json /
- *     hooks.json REGISTRATION. Pruning the last hook to zero would delete the
- *     script but must also GC its registration in the same pass, and that lands
- *     in `src/lib/hooks/install.ts` — a Windows-portable-path surface the CI windows leg
- *     gates on. Split to RUSH-2456 so this PR stays Linux-only-green; hook FILES
- *     are still reconciled by the in-write orphan sweep (versions.ts, gated on
- *     `hooksToSync > 0`).
- *   - rules / permissions — synced as a wholesale rewrite (one composed file /
- *     the full allowlist), so a removed rule or group already drops out.
- *   - plugins — carry their own reconciliation via `cleanOrphanedPluginSkills`.
- *   - mcp — registered through each agent's CLI/config, a separate removal path.
- *   - subagents / workflows — no clean per-name inverse yet (multi-agent index
- *     finalize; native workflow trees); tracked for a follow-up.
- */
 export declare const PRUNABLE_KINDS: readonly ["commands", "skills"];
 export type PrunableKind = typeof PRUNABLE_KINDS[number];
 interface PruneInput {
@@ -60,30 +7,12 @@ interface PruneInput {
     version: string;
     versionHome: string;
     cwd: string;
-    /**
-     * The sync manifest loaded BEFORE this sync ran — the record of what the last
-     * sync installed. `null` means no prior full sync established a baseline.
-     */
     previousManifest: SyncManifest | null;
-    /**
-     * Current source resource names across ALL layers (project/user/system/extras),
-     * per prunable kind. A name present here is still "in source" and never pruned.
-     */
     sourceNames: Record<PrunableKind, ReadonlyArray<string>>;
 }
 interface PruneOutcome {
-    /** Names actually removed from the version home, per kind. */
     pruned: Record<PrunableKind, string[]>;
-    /**
-     * True when prune ran with no manifest and therefore deleted nothing — the
-     * fail-loud baseline case. Callers surface this so a skipped reconcile is
-     * never mistaken for "nothing to prune".
-     */
     skippedNoManifest: boolean;
 }
-/**
- * Remove resources that a prior sync installed and that are now gone from
- * source, from one agent@version home. Deletes nothing when no manifest exists.
- */
 export declare function pruneRemovedResources(input: PruneInput): PruneOutcome;
 export {};

package/dist/lib/staleness/prune.js

@@ -1,28 +1,8 @@
 import { getWriter, getDetector } from './registry.js';
-/**
- * Kinds prune reconciles. Restricted to the name-keyed file/dir resources whose
- * writer implements `remove()`. Deliberately excluded, each with a reason:
- *   - hooks — a version-home hook script is coupled to a settings.json /
- *     hooks.json REGISTRATION. Pruning the last hook to zero would delete the
- *     script but must also GC its registration in the same pass, and that lands
- *     in `src/lib/hooks/install.ts` — a Windows-portable-path surface the CI windows leg
- *     gates on. Split to RUSH-2456 so this PR stays Linux-only-green; hook FILES
- *     are still reconciled by the in-write orphan sweep (versions.ts, gated on
- *     `hooksToSync > 0`).
- *   - rules / permissions — synced as a wholesale rewrite (one composed file /
- *     the full allowlist), so a removed rule or group already drops out.
- *   - plugins — carry their own reconciliation via `cleanOrphanedPluginSkills`.
- *   - mcp — registered through each agent's CLI/config, a separate removal path.
- *   - subagents / workflows — no clean per-name inverse yet (multi-agent index
- *     finalize; native workflow trees); tracked for a follow-up.
- */
 export const PRUNABLE_KINDS = ['commands', 'skills'];
-/** Names the manifest recorded as installed for a kind (source-name keyed). */
 function manifestNames(manifest, kind) {
     switch (kind) {
         case 'commands': {
-            // Object keys are the source command names; writtenCommands carries any
-            // extra names the writer actually emitted (dual-write / command-skill).
             const names = new Set(Object.keys(manifest.commands ?? {}));
             for (const c of manifest.writtenCommands ?? [])
                 names.add(c);
@@ -34,10 +14,6 @@ function manifestNames(manifest, kind) {
 function emptyPruned() {
     return { commands: [], skills: [] };
 }
-/**
- * Remove resources that a prior sync installed and that are now gone from
- * source, from one agent@version home. Deletes nothing when no manifest exists.
- */
 export function pruneRemovedResources(input) {
     const { agent, version, versionHome, cwd, previousManifest, sourceNames } = input;
     if (!previousManifest) {
@@ -47,7 +23,6 @@ export function pruneRemovedResources(input) {
     for (const kind of PRUNABLE_KINDS) {
         const writer = getWriter(kind, agent);
         const detector = getDetector(kind, agent);
-        // No writer.remove (unsupported kind/agent) or no detector: nothing to do.
         if (!writer?.remove || !detector)
             continue;
         const installed = manifestNames(previousManifest, kind);
@@ -57,9 +32,9 @@ export function pruneRemovedResources(input) {
         const materialized = new Set(detector.list({ version, versionHome, cwd }));
         for (const name of installed) {
             if (stillInSource.has(name))
-                continue; // still provided by some layer
+                continue;
             if (!materialized.has(name))
-                continue; // already gone from the home
+                continue;
             const result = writer.remove({ version, versionHome, name, cwd });
             if (result.removed)
                 pruned[kind].push(name);

package/dist/lib/staleness/registry.d.ts

@@ -8,19 +8,9 @@ export { kindToCapability, ALL_RESOURCE_KINDS } from './writers/kinds.js';
 export type { ResourceWriter, WriteArgs, WriteResult, RemoveArgs, RemoveResult } from './writers/types.js';
 export type { ResourceDetector, DetectArgs } from './detectors/types.js';
 export type { RulesSelection } from './writers/rules.js';
-/** Per-kind selection payload. Most kinds are string[]; rules is special. */
 type SelectionFor<K extends ResourceKind> = K extends 'rules' ? RulesSelection : string[];
 export declare const WRITERS: Record<ResourceKind, Partial<Record<AgentId, ResourceWriter<any>>>>;
 export declare const DETECTORS: Record<ResourceKind, Partial<Record<AgentId, ResourceDetector>>>;
-/**
- * Verify every supported (agent, kind) pair has both a writer and a
- * detector. Deferred from module-import time to the first `getWriter` /
- * `getDetector` call to dodge the agents.ts ↔ versions.ts ↔ registry.ts
- * import cycle (the same one the lazy writer/detector maps work around).
- * Idempotent — runs at most once per process.
- */
 export declare function assertRegistryComplete(): void;
-/** Return the writer for (kind, agent), or undefined if unsupported. */
 export declare function getWriter<K extends ResourceKind>(kind: K, agent: AgentId): ResourceWriter<SelectionFor<K>> | undefined;
-/** Return the detector for (kind, agent), or undefined if unsupported. */
 export declare function getDetector(kind: ResourceKind, agent: AgentId): ResourceDetector | undefined;

package/dist/lib/staleness/registry.js

@@ -1,20 +1,3 @@
-/**
- * Writer + detector registry for resource sync.
- *
- * Two parallel maps keyed by (ResourceKind, AgentId). At module import time
- * (which fires once when the CLI boots) we verify that EVERY supported
- * (agent, kind) pair has both a writer and a detector. Missing entries
- * throw immediately — silent-skip bugs become startup errors.
- *
- *   - Adding a new agent? Either declare every supported kind with a writer
- *     here OR mark the kind `false` in `AgentConfig.capabilities`.
- *   - Adding a new kind? Declare it on every agent's capabilities and add a
- *     writer module.
- *
- * The capability matrix in `lib/agents.ts:AGENTS` is the single source of
- * truth for "is this (agent, kind) supported?". The assertion below maps the
- * matrix to required registry entries.
- */
 import { AGENTS } from '../agents.js';
 import { supports } from '../capabilities.js';
 import { ALL_RESOURCE_KINDS, kindToCapability, } from './writers/kinds.js';
@@ -61,27 +44,16 @@ export const DETECTORS = {
     plugins: pluginsDetectors,
     workflows: workflowsDetectors,
 };
-/**
- * Kinds excluded from the assertion. Skills + native-skills-dir agents are
- * the only legitimate gap — Gemini reads `~/.agents/skills/` natively, so
- * it deliberately has no per-version writer/detector. The orchestrator
- * handles that case by clearing the version-home skills dir before launch.
- * Anywhere else, a missing entry is a real bug.
- */
 function isExempt(agent, kind) {
+    // Native agent skills are managed outside this registry; no other capability is exempt.
     if (kind === 'skills' && AGENTS[agent].nativeAgentsSkillsDir)
         return true;
     return false;
 }
 let assertionFired = false;
-/**
- * Verify every supported (agent, kind) pair has both a writer and a
- * detector. Deferred from module-import time to the first `getWriter` /
- * `getDetector` call to dodge the agents.ts ↔ versions.ts ↔ registry.ts
- * import cycle (the same one the lazy writer/detector maps work around).
- * Idempotent — runs at most once per process.
- */
 export function assertRegistryComplete() {
+    // Validate lazily and once to avoid the agents.ts ↔ versions.ts ↔ registry.ts import cycle.
+    // Every advertised capability must bind both writer and detector or fail startup loudly.
     if (assertionFired)
         return;
     assertionFired = true;
@@ -111,12 +83,10 @@ export function assertRegistryComplete() {
             `mark the capability false in AGENTS.${missing[0].agent}.capabilities.`);
     }
 }
-/** Return the writer for (kind, agent), or undefined if unsupported. */
 export function getWriter(kind, agent) {
     assertRegistryComplete();
     return WRITERS[kind][agent];
 }
-/** Return the detector for (kind, agent), or undefined if unsupported. */
 export function getDetector(kind, agent) {
     assertRegistryComplete();
     return DETECTORS[kind][agent];

package/dist/lib/staleness/types.d.ts

@@ -1,50 +1,24 @@
-/**
- * Public types for the staleness library. The on-disk manifest shape stays
- * at `v: 1` for backward compatibility — see `src/lib/sync-manifest.ts` for
- * the loader/saver that consumes these.
- */
 import type { Fingerprint } from './fingerprint.js';
 export declare const MANIFEST_VERSION: 1;
-/** A single-file resource (commands, hooks, MCP server YAML, permission groups). */
 export interface FileEntry {
     source: Fingerprint;
 }
-/** A directory resource (skills, subagents, workflows). */
 export interface DirEntry {
-    /** Winning source dir, absolute. */
     dirPath: string;
-    /** All files inside the dir, sorted by absolute path. */
     files: Fingerprint[];
 }
-/** Rules section — fingerprints of every source file (rules.yaml + active subrules). */
 export interface RulesEntry {
     files: Record<string, FileEntry>;
 }
-/**
- * Permissions section — merged across layers (every group across every scope
- * contributes; same name first-wins user > system). Plus the active preset
- * env value, since preset selection changes which groups are applied.
- */
 export interface PermEntry {
     groups: Record<string, FileEntry>;
     permissionPreset: string | null;
 }
-/**
- * Plugin entry. Plugins have a complex layout (`.claude-plugin/plugin.json`
- * plus optional `skills/`, `commands/`, ...). We fingerprint the entire
- * plugin root, same shape as a DirEntry.
- */
 export type PluginEntry = DirEntry;
-/**
- * Full manifest. `workflows` and `plugins` are optional so older v1 files
- * stay loadable; missing fields are treated as empty maps — name-set diff
- * then triggers a single re-sync that fills them in.
- */
 export interface SyncManifest {
     v: typeof MANIFEST_VERSION;
     syncedAt: string;
     commands: Record<string, FileEntry>;
-    /** Command names the version writer emitted during the preceding full sync. */
     writtenCommands?: string[];
     skills: Record<string, DirEntry>;
     hooks: Record<string, FileEntry>;
@@ -54,15 +28,5 @@ export interface SyncManifest {
     subagents: Record<string, DirEntry>;
     workflows?: Record<string, DirEntry>;
     plugins?: Record<string, PluginEntry>;
-    /**
-     * Absolute paths of the artifacts the last full sync materialized in the
-     * version home (writer-reported — see `WriteResult.paths`). `isStale`
-     * treats a missing path as stale so a deleted resource is restored by a
-     * plain `agents sync`, not only `--force` (#2398). An absent field means a
-     * pre-upgrade manifest: it reads as stale once, and the resulting full sync
-     * establishes the baseline — same migration precedent as the optional
-     * `workflows`/`plugins` maps above. An empty array is a valid baseline
-     * ("nothing recorded to verify"), never a migration trigger.
-     */
     writtenTargets?: string[];
 }

package/dist/lib/staleness/types.js

@@ -1,6 +1 @@
-/**
- * Public types for the staleness library. The on-disk manifest shape stays
- * at `v: 1` for backward compatibility — see `src/lib/sync-manifest.ts` for
- * the loader/saver that consumes these.
- */
 export const MANIFEST_VERSION = 1;