@phnx-labs/agents-cli 1.18.1 → 1.18.3

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

@@ -0,0 +1,44 @@
+/**
+ * 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

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,10 @@
+/**
+ * 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

@@ -0,0 +1,37 @@
+/**
+ * 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';
+import { fingerprintDir, isDirStale } from '../fingerprint.js';
+function isWorkflowDir(full) {
+    try {
+        return fs.statSync(full).isDirectory() && fs.existsSync(path.join(full, 'WORKFLOW.md'));
+    }
+    catch {
+        return false;
+    }
+}
+export const workflowsChecker = {
+    type: 'workflows',
+    listNames(cwd) {
+        return listAcrossLayers(firstWinsLayers(cwd), 'workflows', (_, full) => isWorkflowDir(full));
+    },
+    build(name, cwd) {
+        const resolved = resolveByName(firstWinsLayers(cwd), path.join('workflows', name), isWorkflowDir);
+        if (!resolved)
+            return null;
+        return { dirPath: resolved.path, files: fingerprintDir(resolved.path) };
+    },
+    isFresh(name, stored, cwd) {
+        const resolved = resolveByName(firstWinsLayers(cwd), path.join('workflows', name), isWorkflowDir);
+        if (!resolved)
+            return false;
+        return !isDirStale(stored.dirPath, stored.files, resolved.path);
+    },
+};

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

@@ -0,0 +1,38 @@
+/**
+ * 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;
+    size: number;
+    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;
+/**
+ * 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).
+ */
+export declare function walkDirPaths(dirPath: string): string[];
+/** True if two sorted-or-unsorted name sets differ. */
+export declare function nameSetDiffers(a: string[], b: string[]): boolean;

package/dist/lib/staleness/fingerprint.js

@@ -0,0 +1,154 @@
+/**
+ * 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);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return { path: filePath, mtime: stat.mtimeMs, size: stat.size, sha256: sha256(content) };
+    }
+    catch {
+        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/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',
+    '.gitignore',
+    '.venv',
+    '__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) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (FINGERPRINT_SKIP.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile()) {
+                const fp = fingerprintFile(full);
+                if (fp)
+                    results.push(fp);
+            }
+        }
+    }
+    walk(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;
+    try {
+        const stat = fs.statSync(currentPath);
+        if (stat.mtimeMs === stored.mtime && stat.size === stored.size)
+            return false;
+        return sha256(fs.readFileSync(currentPath, 'utf-8')) !== stored.sha256;
+    }
+    catch {
+        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;
+    const currentPaths = walkDirPaths(currentDirPath);
+    if (currentPaths.length !== storedFiles.length)
+        return true;
+    for (let i = 0; i < currentPaths.length; i++) {
+        const stored = storedFiles[i];
+        const cur = currentPaths[i];
+        if (stored.path !== cur)
+            return true;
+        try {
+            const stat = fs.statSync(cur);
+            if (stat.mtimeMs === stored.mtime && stat.size === stored.size)
+                continue;
+            if (sha256(fs.readFileSync(cur, 'utf-8')) !== stored.sha256)
+                return true;
+        }
+        catch {
+            return true;
+        }
+    }
+    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).
+ */
+export function walkDirPaths(dirPath) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (FINGERPRINT_SKIP.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                results.push(full);
+        }
+    }
+    walk(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;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.some((n, i) => n !== sortedB[i]);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ *
+ * `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;
+export declare function buildManifest(agent: AgentId, version: string, cwd: string): 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

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ *
+ * `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';
+import { commandsChecker } from './checkers/commands.js';
+import { skillsChecker } from './checkers/skills.js';
+import { hooksChecker } from './checkers/hooks.js';
+import { mcpChecker } from './checkers/mcp.js';
+import { subagentsChecker } from './checkers/subagents.js';
+import { workflowsChecker } from './checkers/workflows.js';
+import { pluginsChecker } from './checkers/plugins.js';
+import { buildPermissions, isPermissionsStale } from './checkers/permissions.js';
+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' },
+    { checker: hooksChecker, field: 'hooks' },
+    { checker: mcpChecker, field: 'mcp' },
+    { checker: subagentsChecker, field: 'subagents' },
+    { checker: workflowsChecker, field: 'workflows' },
+    { checker: pluginsChecker, field: 'plugins' },
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+function manifestPath(agent, version) {
+    return path.join(getVersionsDir(), agent, version, 'home', '.sync-manifest.json');
+}
+export function loadManifest(agent, version) {
+    const p = manifestPath(agent, version);
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (raw.v !== MANIFEST_VERSION)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveManifest(agent, version, manifest) {
+    const p = manifestPath(agent, version);
+    const tmp = p + '.tmp';
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+        fs.renameSync(tmp, p);
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+    }
+}
+export function buildManifest(agent, version, cwd) {
+    const manifest = {
+        v: MANIFEST_VERSION,
+        syncedAt: new Date().toISOString(),
+        commands: {},
+        skills: {},
+        hooks: {},
+        rules: { files: {} },
+        mcp: {},
+        permissions: { groups: {}, permissionPreset: null },
+        subagents: {},
+        workflows: {},
+        plugins: {},
+    };
+    for (const { checker, field } of STANDARD_CHECKERS) {
+        const target = manifest[field];
+        for (const name of checker.listNames(cwd)) {
+            const entry = checker.build(name, cwd);
+            if (entry !== null)
+                target[name] = entry;
+        }
+    }
+    manifest.rules = buildRules(agent, version, cwd);
+    manifest.permissions = buildPermissions();
+    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] ?? {});
+        const currentNames = checker.listNames(cwd);
+        if (nameSetDiffers(Object.keys(storedMap), currentNames))
+            return true;
+        for (const name of currentNames) {
+            const entry = storedMap[name];
+            if (entry === undefined)
+                return true;
+            if (!checker.isFresh(name, entry, cwd))
+                return true;
+        }
+    }
+    if (isPermissionsStale(manifest.permissions))
+        return true;
+    if (isRulesStale(manifest.rules, agent, version, cwd))
+        return true;
+    return false;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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/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

@@ -0,0 +1,100 @@
+/**
+ * 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/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)
+        return cached;
+    const layers = [];
+    const project = getProjectAgentsDir(cwd);
+    if (project)
+        layers.push({ scope: 'project', base: project });
+    layers.push({ scope: 'user', base: getUserAgentsDir() });
+    layers.push({ scope: 'system', base: getAgentsDir() });
+    for (const extra of getEnabledExtraRepos()) {
+        layers.push({ scope: 'extra', base: extra.dir, alias: extra.alias });
+    }
+    firstWinsCache.set(cwd, layers);
+    return layers;
+}
+/** Hooks-only: layers excluding project (security exclusion). */
+export function hookLayers() {
+    if (hookLayersCache)
+        return hookLayersCache;
+    const layers = [];
+    layers.push({ scope: 'user', base: getUserAgentsDir() });
+    layers.push({ scope: 'system', base: getAgentsDir() });
+    for (const extra of getEnabledExtraRepos()) {
+        layers.push({ scope: 'extra', base: extra.dir, alias: extra.alias });
+    }
+    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);
+        if (predicate(full))
+            return { path: full, layer };
+    }
+    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) {
+        const dir = path.join(layer.base, relative);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (name.startsWith('.'))
+                continue;
+            if (!filter(name, path.join(dir, name)))
+                continue;
+            seen.add(name);
+        }
+    }
+    return Array.from(seen);
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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>;
+    skills: Record<string, DirEntry>;
+    hooks: Record<string, FileEntry>;
+    rules: RulesEntry;
+    mcp: Record<string, FileEntry>;
+    permissions: PermEntry;
+    subagents: Record<string, DirEntry>;
+    workflows?: Record<string, DirEntry>;
+    plugins?: Record<string, PluginEntry>;
+}
+export type ResourceType = 'commands' | 'skills' | 'hooks' | 'mcp' | 'rules' | 'subagents' | 'workflows' | 'plugins' | 'permissions';

package/dist/lib/staleness/types.js

@@ -0,0 +1,6 @@
+/**
+ * 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;

package/dist/lib/state.d.ts

@@ -125,6 +125,8 @@ export declare function getSessionsDbPath(): string;
 export declare function getTeamsDir(): string;
 /** Path to teams execution history (~/.agents/.history/teams/agents/). */
 export declare function getTeamsAgentsDir(): string;
+/** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
+export declare function getTeamsRegistryPath(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */