@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/staleness/checkers/mcp.d.ts

@@ -1,12 +1,3 @@
-/**
- * MCP server staleness — one `.yaml`/`.yml` file per server, first-wins
- * across project > user > system > extras. Name is the `name:` field inside
- * the YAML, NOT the filename (per `getAvailableResources`).
- *
- * We delegate name/path discovery to `listMcpServerConfigs(cwd)` which
- * already handles parsing — keeps a single source of truth for "what counts
- * as a discoverable MCP server."
- */
 import type { FileEntry } from '../types.js';
 import type { TypedResourceChecker } from './types.js';
 export declare const mcpChecker: TypedResourceChecker<FileEntry>;

package/dist/lib/staleness/checkers/mcp.js

@@ -1,12 +1,3 @@
-/**
- * MCP server staleness — one `.yaml`/`.yml` file per server, first-wins
- * across project > user > system > extras. Name is the `name:` field inside
- * the YAML, NOT the filename (per `getAvailableResources`).
- *
- * We delegate name/path discovery to `listMcpServerConfigs(cwd)` which
- * already handles parsing — keeps a single source of truth for "what counts
- * as a discoverable MCP server."
- */
 import { fingerprintFile, isFileStale } from '../fingerprint.js';
 import { listMcpServerConfigs } from '../../mcp.js';
 function indexByName(cwd) {

package/dist/lib/staleness/checkers/permissions.d.ts

@@ -1,15 +1,3 @@
-/**
- * Permissions staleness — every `groups/*.yaml` across user + system
- * contributes to the merged permission set (project layer not consulted by
- * the current sync writer). First-wins on name collision (user > system).
- *
- * The active preset env value (`AGENTS_PERMISSION_PRESET`) is part of the
- * fingerprint too — preset selection changes which groups get applied to
- * the agent config, so a preset switch without a content change still
- * counts as stale.
- */
 import type { PermEntry } from '../types.js';
-/** Build the permissions section of the manifest. */
 export declare function buildPermissions(): PermEntry;
-/** True when the stored permissions section no longer matches current state. */
 export declare function isPermissionsStale(stored: PermEntry): boolean;

package/dist/lib/staleness/checkers/permissions.js

@@ -1,19 +1,8 @@
-/**
- * Permissions staleness — every `groups/*.yaml` across user + system
- * contributes to the merged permission set (project layer not consulted by
- * the current sync writer). First-wins on name collision (user > system).
- *
- * The active preset env value (`AGENTS_PERMISSION_PRESET`) is part of the
- * fingerprint too — preset selection changes which groups get applied to
- * the agent config, so a preset switch without a content change still
- * counts as stale.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getUserPermissionsDir, getPermissionsDir } from '../../state.js';
 import { fingerprintFile, isFileStale } from '../fingerprint.js';
 import { getActivePermissionPresetName } from '../../permissions.js';
-/** Walk user + system permissions/groups/. First-wins user > system on names. */
 function collectPermissionGroupFiles() {
     const seen = new Map();
     for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
@@ -37,7 +26,6 @@ function collectPermissionGroupFiles() {
     }
     return Object.fromEntries(seen);
 }
-/** Build the permissions section of the manifest. */
 export function buildPermissions() {
     const groupFiles = collectPermissionGroupFiles();
     const groups = {};
@@ -51,7 +39,6 @@ export function buildPermissions() {
         permissionPreset: getActivePermissionPresetName(),
     };
 }
-/** True when the stored permissions section no longer matches current state. */
 export function isPermissionsStale(stored) {
     if (stored.permissionPreset !== getActivePermissionPresetName())
         return true;

package/dist/lib/staleness/checkers/plugins.d.ts

@@ -1,11 +1,3 @@
-/**
- * Plugins staleness — one directory per plugin, marker file is
- * `.claude-plugin/plugin.json`. First-wins across project > user > system
- * > extras. Fingerprints the entire plugin root (skills, commands, hooks,
- * etc. live INSIDE the plugin dir, so a content fingerprint covers them).
- *
- * Not tracked in v1 manifests; same one-time re-sync trade-off as workflows.
- */
 import type { PluginEntry } from '../types.js';
 import type { TypedResourceChecker } from './types.js';
 export declare const pluginsChecker: TypedResourceChecker<PluginEntry>;

package/dist/lib/staleness/checkers/plugins.js

@@ -1,11 +1,3 @@
-/**
- * Plugins staleness — one directory per plugin, marker file is
- * `.claude-plugin/plugin.json`. First-wins across project > user > system
- * > extras. Fingerprints the entire plugin root (skills, commands, hooks,
- * etc. live INSIDE the plugin dir, so a content fingerprint covers them).
- *
- * Not tracked in v1 manifests; same one-time re-sync trade-off as workflows.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { firstWinsLayers, listAcrossLayers, resolveByName } from '../layers.js';

package/dist/lib/staleness/checkers/rules.d.ts

@@ -1,18 +1,3 @@
-/**
- * Rules staleness — composed from a layered `rules.yaml` preset definition
- * plus per-layer `subrules/<name>.md` fragments. Fingerprints exactly the
- * source files that contribute to the active preset's composed output.
- *
- * Bug-fixed from v1: the old `resolveRuleFile` looked for `rules/<preset>.md`,
- * a path that never exists (presets live in `rules.yaml`, fragments live in
- * `subrules/`). That made the rules section always report stale. This module
- * uses `composeRulesFromState` to discover the actual source file set per
- * preset/cwd, so freshness reflects real source changes.
- *
- * Special-cased vs. the other checkers: agent + version are needed to read
- * the active preset, so this module doesn't conform to ResourceChecker. The
- * aggregator wires it up explicitly.
- */
 import type { AgentId } from '../../types.js';
 import type { RulesEntry } from '../types.js';
 export declare function buildRules(agent: AgentId, version: string, cwd: string): RulesEntry;

package/dist/lib/staleness/checkers/rules.js

@@ -1,18 +1,3 @@
-/**
- * Rules staleness — composed from a layered `rules.yaml` preset definition
- * plus per-layer `subrules/<name>.md` fragments. Fingerprints exactly the
- * source files that contribute to the active preset's composed output.
- *
- * Bug-fixed from v1: the old `resolveRuleFile` looked for `rules/<preset>.md`,
- * a path that never exists (presets live in `rules.yaml`, fragments live in
- * `subrules/`). That made the rules section always report stale. This module
- * uses `composeRulesFromState` to discover the actual source file set per
- * preset/cwd, so freshness reflects real source changes.
- *
- * Special-cased vs. the other checkers: agent + version are needed to read
- * the active preset, so this module doesn't conform to ResourceChecker. The
- * aggregator wires it up explicitly.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { fingerprintFile, isFileStale } from '../fingerprint.js';
@@ -27,16 +12,9 @@ function rulesDirForLayer(scope, cwd) {
         return getUserRulesDir();
     if (scope === 'system')
         return getResolvedRulesDir();
-    // extra: first registered extra repo's rules dir. The composer doesn't
-    // disambiguate multi-extra rules.yaml today, so we don't either.
     const extras = getEnabledExtraRepos();
     return extras.length > 0 ? path.join(extras[0].dir, 'rules') : null;
 }
-/**
- * Resolve the set of source files contributing to the active preset's output.
- * Keys are relative paths within the rules dir (stable across machines).
- * Values are absolute current paths.
- */
 function activeSources(agent, version, cwd) {
     const result = {};
     let compose;
@@ -54,12 +32,8 @@ function activeSources(agent, version, cwd) {
             result['rules.yaml'] = yamlPath;
     }
     for (const sub of compose.subrules) {
-        // Key off the actual source path so dir-form subrules (subrules/<name>/rule.md)
-        // and flat ones (subrules/<name>.md) both fingerprint the file that really
-        // contributes to the output, not a hard-coded `.md` that may not exist.
         if (sub.subruleDir) {
             result[`subrules/${sub.name}/rule.md`] = sub.sourcePath;
-            // Fingerprint hooks.yaml too so editing a hook re-syncs the rules section.
             const hooksFile = path.join(sub.subruleDir, 'hooks.yaml');
             if (fs.existsSync(hooksFile))
                 result[`subrules/${sub.name}/hooks.yaml`] = hooksFile;

package/dist/lib/staleness/checkers/skills.d.ts

@@ -1,7 +1,3 @@
-/**
- * Skills staleness — one directory per skill (must contain SKILL.md),
- * first-wins across project > user > system > extras.
- */
 import type { DirEntry } from '../types.js';
 import type { TypedResourceChecker } from './types.js';
 export declare const skillsChecker: TypedResourceChecker<DirEntry>;

package/dist/lib/staleness/checkers/skills.js

@@ -1,7 +1,3 @@
-/**
- * Skills staleness — one directory per skill (must contain SKILL.md),
- * first-wins across project > user > system > extras.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { firstWinsLayers, listAcrossLayers, resolveByName } from '../layers.js';

package/dist/lib/staleness/checkers/subagents.d.ts

@@ -1,12 +1,3 @@
-/**
- * Subagents staleness — one directory per subagent (must contain AGENT.md),
- * first-wins across project > user > system > extras.
- *
- * Bug-fixed from v1: the old manifest derived its name list from
- * `listInstalledSubagents()` which only walks user + system. With project
- * subagents in `available.subagents`, the name-set diff always flipped to
- * "stale". This checker walks all four layers consistently.
- */
 import type { DirEntry } from '../types.js';
 import type { TypedResourceChecker } from './types.js';
 export declare const subagentsChecker: TypedResourceChecker<DirEntry>;

package/dist/lib/staleness/checkers/subagents.js

@@ -1,12 +1,3 @@
-/**
- * Subagents staleness — one directory per subagent (must contain AGENT.md),
- * first-wins across project > user > system > extras.
- *
- * Bug-fixed from v1: the old manifest derived its name list from
- * `listInstalledSubagents()` which only walks user + system. With project
- * subagents in `available.subagents`, the name-set diff always flipped to
- * "stale". This checker walks all four layers consistently.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { firstWinsLayers, listAcrossLayers, resolveByName } from '../layers.js';

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

@@ -1,43 +1,9 @@
-/**
- * Contract every resource staleness checker implements. Each checker owns
- * the layer-resolution and entry-shape rules for one resource type. The
- * aggregator in `../index.ts` doesn't know any of those details — it just
- * calls these three methods.
- *
- * Why three methods (not just "isStale"):
- *   - `listNames`   feeds both the manifest writer (what to record) and the
- *     name-set diff (`stored` vs. `current` reveals adds/removes).
- *   - `build`       produces the entry for a single name; called per name
- *     after listing. Pure — no comparison logic.
- *   - `isFresh`     checks one stored entry against current state; called
- *     when the name set already matches and we need content-level certainty.
- *
- * The `unknown` entry type is intentional — each checker round-trips its
- * own concrete shape through JSON (commands/hooks/mcp use FileEntry; skills
- * /subagents/workflows/plugins use DirEntry; rules/permissions use their
- * own composite entries).
- */
 export interface ResourceChecker {
-    /** Stable identifier; matches the manifest field name. */
     readonly type: string;
-    /** Names of every resource currently available across this checker's layers. */
     listNames(cwd: string): string[];
-    /**
-     * Build a manifest entry for one name. Returns null when no source file is
-     * found — the aggregator drops nulls so name-set diff stays accurate.
-     */
     build(name: string, cwd: string): unknown | null;
-    /**
-     * Check whether a stored entry still reflects current source. Called only
-     * after the name-set already matches. Returns true when fresh, false when
-     * the entry should trigger a re-sync.
-     */
     isFresh(name: string, stored: unknown, cwd: string): boolean;
 }
-/**
- * Helper for checkers whose entry shape varies. Strict-typed convenience
- * wrapper that callers can use to avoid `unknown` casts in their own code.
- */
 export interface TypedResourceChecker<TEntry> extends ResourceChecker {
     build(name: string, cwd: string): TEntry | null;
     isFresh(name: string, stored: TEntry, cwd: string): boolean;

package/dist/lib/staleness/checkers/types.js

@@ -1,20 +1 @@
-/**
- * Contract every resource staleness checker implements. Each checker owns
- * the layer-resolution and entry-shape rules for one resource type. The
- * aggregator in `../index.ts` doesn't know any of those details — it just
- * calls these three methods.
- *
- * Why three methods (not just "isStale"):
- *   - `listNames`   feeds both the manifest writer (what to record) and the
- *     name-set diff (`stored` vs. `current` reveals adds/removes).
- *   - `build`       produces the entry for a single name; called per name
- *     after listing. Pure — no comparison logic.
- *   - `isFresh`     checks one stored entry against current state; called
- *     when the name set already matches and we need content-level certainty.
- *
- * The `unknown` entry type is intentional — each checker round-trips its
- * own concrete shape through JSON (commands/hooks/mcp use FileEntry; skills
- * /subagents/workflows/plugins use DirEntry; rules/permissions use their
- * own composite entries).
- */
 export {};

package/dist/lib/staleness/checkers/workflows.d.ts

@@ -1,10 +1,3 @@
-/**
- * Workflows staleness — one directory per workflow (must contain
- * WORKFLOW.md), first-wins across project > user > system > extras.
- *
- * Not tracked in v1 manifests; treated as a new section that's empty on old
- * files, which causes one re-sync (filling the field) and then steady-state.
- */
 import type { DirEntry } from '../types.js';
 import type { TypedResourceChecker } from './types.js';
 export declare const workflowsChecker: TypedResourceChecker<DirEntry>;

package/dist/lib/staleness/checkers/workflows.js

@@ -1,10 +1,3 @@
-/**
- * Workflows staleness — one directory per workflow (must contain
- * WORKFLOW.md), first-wins across project > user > system > extras.
- *
- * Not tracked in v1 manifests; treated as a new section that's empty on old
- * files, which causes one re-sync (filling the field) and then steady-state.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { firstWinsLayers, listAcrossLayers, resolveByName } from '../layers.js';

package/dist/lib/staleness/detectors/commands.js

@@ -1,10 +1,3 @@
-/**
- * Commands detector — mirrors the command dispatch in versions.ts. Inspects the version home,
- * returns command names. Honors the commands-as-skills marker for skills-only
- * agents (Kimi, Codex >= 0.117.0, …), treats the native file as authoritative
- * for dual-write targets (the skill copy is deliberately absent on a name
- * collision), and scans `{agentDir}/<commandsSubdir>/` for native-only targets.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, MANAGED_AGENT_IDS, agentConfigDirName } from '../../agents.js';
@@ -27,20 +20,10 @@ function buildCommandsDetector(agent) {
             const nativeCommands = fs.readdirSync(commandsDir)
                 .filter(f => f.endsWith(ext))
                 .map(f => f.replace(new RegExp(`\\${ext}$`), ''));
-            // For a dual-write target the native file is the authoritative record that
-            // the command synced. The skill copy is derived, and
-            // installCommandSkillToVersion deliberately writes none when a real skill
-            // source already owns the name -- requiring both copies reported those
-            // commands missing forever and drove an `agents refresh` loop no sync could
-            // clear. This also matches `agents doctor`/`prune`, which read the
-            // unfiltered listCommandsInVersionHome.
             return nativeCommands;
         },
     };
 }
-// Detector registration mirrors writers/commands.ts — skills-capable agents
-// with no native command-file dir convert commands to skills by default; only
-// agents with their own slash-command runtime (nativeCommandRuntime) opt out.
 export const commandsDetectors = lazyAgentMap(() => {
     const m = {};
     for (const id of MANAGED_AGENT_IDS) {

package/dist/lib/staleness/detectors/hooks.js

@@ -1,7 +1,3 @@
-/**
- * Hooks detector — names of hook scripts materialized in the version home
- * whose contents match the central source. Mirrors versions.ts:391-421.
- */
 import * as fs from 'fs';
 import { agentConfigDirName } from '../../agents.js';
 import * as path from 'path';
@@ -45,7 +41,6 @@ function buildHooksDetector(agent) {
             for (const hook of installed) {
                 const src = resolveHookSource(hook);
                 if (!src) {
-                    // True orphan — count as accounted for.
                     synced.push(hook);
                     continue;
                 }
@@ -54,7 +49,7 @@ function buildHooksDetector(agent) {
                         synced.push(hook);
                     }
                 }
-                catch { /* read failure → not synced */ }
+                catch { }
             }
             return synced;
         },

package/dist/lib/staleness/detectors/mcp.js

@@ -1,7 +1,3 @@
-/**
- * MCP detector — parses the agent's canonical MCP config in the version home
- * and returns server names. Mirrors versions.ts:432-443.
- */
 import * as fs from 'fs';
 import { capableAgents } from '../../capabilities.js';
 import { getMcpConfigPathForHome, parseMcpConfig } from '../../agents.js';

package/dist/lib/staleness/detectors/permissions.js

@@ -1,15 +1,3 @@
-/**
- * Permissions detector — inspects the agent's native permission storage and
- * reports the permission GROUP names that have been applied.
- *
- * For claude/opencode the detector intersects with discovered groups (a group
- * is "applied" if any of its allow/deny rules are present). For Codex /
- * Antigravity / Grok the on-disk format is lossy — once any group has been
- * applied the storage doesn't carry per-group provenance back, so we report
- * "all known groups applied" when any permission artifact is present. This
- * matches the existing behavior in versions.ts:445-518 (extended to the
- * agents that were previously silent-skipped).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as TOML from 'smol-toml';
@@ -35,7 +23,6 @@ function buildClaudeDetector() {
                 const applied = [];
                 for (const group of groups) {
                     const built = buildPermissionsFromGroups([group.name]);
-                    // Empty groups (header files) count as synced when anything is applied.
                     if (built.allow.length === 0 && (!built.deny || built.deny.length === 0)) {
                         applied.push(group.name);
                         continue;
@@ -74,7 +61,7 @@ function buildCodexDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -95,7 +82,7 @@ function buildOpenCodeDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -117,7 +104,7 @@ function buildAntigravityDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -137,7 +124,7 @@ function buildGrokDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -157,7 +144,7 @@ function buildKimiDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -177,7 +164,7 @@ function buildCursorDetector() {
                 if (allow + deny > 0)
                     return discoverPermissionGroups().map(g => g.name);
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -197,7 +184,7 @@ function buildDroidDetector() {
                 if (hasAllow || hasDeny)
                     return discoverPermissionGroups().map(g => g.name);
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -219,7 +206,7 @@ function buildOpenClawDetector() {
                     return discoverPermissionGroups().map(g => g.name);
                 }
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -243,7 +230,7 @@ function buildCopilotDetector() {
                 if (hasApprovals || hasDirectories)
                     return discoverPermissionGroups().map(g => g.name);
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };
@@ -263,7 +250,7 @@ function buildHermesDetector() {
                 if (hasAllow || hasDeny)
                     return discoverPermissionGroups().map(g => g.name);
             }
-            catch { /* parse fail */ }
+            catch { }
             return [];
         },
     };

package/dist/lib/staleness/detectors/rules.js

@@ -1,9 +1,3 @@
-/**
- * Rules detector — reports whether the composed instructions file exists in
- * the version home. Uses the active rules preset name as the detected
- * "resource name" so the diff stays meaningful (one preset = one synced
- * name, mirroring what getAvailableResources surfaces under `memory`).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from '../../agents.js';

package/dist/lib/staleness/detectors/skills.d.ts

@@ -1,4 +1,3 @@
 import type { ResourceDetector } from './types.js';
-/** Exported for unit tests (RUSH-2320 #2). Production callers: list() below. */
 export declare function skillDirsMatch(src: string, dest: string): boolean;
 export declare const skillsDetectors: Partial<Record<"claude" | "codex" | "cursor" | "opencode" | "openclaw" | "copilot" | "amp" | "goose" | "antigravity" | "grok" | "kimi" | "droid" | "hermes" | "muse" | "warp", ResourceDetector>>;

package/dist/lib/staleness/detectors/skills.js

@@ -1,7 +1,3 @@
-/**
- * Skills detector — names of skill directories materialized in the version
- * home that match the central source content. Mirrors versions.ts:359-389.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName } from '../../agents.js';
@@ -9,7 +5,6 @@ import { capableAgents } from '../../capabilities.js';
 import { resolveSkillSource } from '../writers/sources.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
 const SKILL_COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
-/** Exported for unit tests (RUSH-2320 #2). Production callers: list() below. */
 export function skillDirsMatch(src, dest) {
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
@@ -26,11 +21,6 @@ export function skillDirsMatch(src, dest) {
                 return false;
         }
         else {
-            // Stat-first (RUSH-2320 #2): size mismatch is a definitive miss with no
-            // content reads. Do NOT treat equal mtimes as equal content — src and
-            // dest are different trees (version home vs source), and copyFileSync
-            // does not preserve mtime, so mtime equality is accidental and unsafe.
-            // Content compare only when sizes match.
             let srcStat;
             let destStat;
             try {
@@ -42,7 +32,7 @@ export function skillDirsMatch(src, dest) {
             }
             if (srcStat.size !== destStat.size)
                 return false;
-            if (fs.readFileSync(srcPath, 'utf-8') !== fs.readFileSync(destPath, 'utf-8'))
+            if (!fs.readFileSync(srcPath).equals(fs.readFileSync(destPath)))
                 return false;
         }
     }
@@ -63,7 +53,6 @@ function buildSkillsDetector(agent) {
             for (const name of installed) {
                 const src = resolveSkillSource(name);
                 if (!src) {
-                    // True orphan — no source. Still count so cleanup knows it's accounted for.
                     synced.push(name);
                     continue;
                 }

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

@@ -1,18 +1,8 @@
-/**
- * Per-(kind, agent) detector contract.
- *
- * A detector inspects a version home and reports which resource names of a
- * given kind are materialized there. The aggregator at
- * `getActuallySyncedResources` calls one detector per kind/agent pair to build
- * the "what is actually on disk" view, which is then diffed against
- * "what is available" to drive the resource prompt in `agents view`.
- */
 import type { AgentId } from '../../types.js';
 import type { ResourceKind } from '../writers/kinds.js';
 export interface DetectArgs {
     version: string;
     versionHome: string;
-    /** Working directory — needed by detectors that resolve project state. */
     cwd: string;
 }
 export interface ResourceDetector {

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

@@ -1,9 +1,3 @@
-/**
- * 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.
- */
-/** Fingerprint of a single source file. */
 export interface Fingerprint {
     path: string;
     mtime: number;
@@ -11,21 +5,8 @@ export interface Fingerprint {
     sha256: string;
 }
 export declare function sha256(content: string): string;
-/** Fingerprint a single file. Returns null when the file is unreadable. */
 export declare function fingerprintFile(filePath: string): Fingerprint | null;
-/**
- * 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 declare function fingerprintDir(dirPath: string): Fingerprint[];
-/** Hot-path file staleness: stat-only when mtime+size match, sha256 on miss. */
 export declare function isFileStale(stored: Fingerprint, currentPath: string): boolean;
-/**
- * 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 declare function isDirStale(storedDirPath: string, storedFiles: Fingerprint[], currentDirPath: string): boolean;
-/** True if two sorted-or-unsorted name sets differ. */
 export declare function nameSetDiffers(a: string[], b: string[]): boolean;