@phnx-labs/agents-cli 1.18.1 → 1.18.3

package/dist/lib/shims.d.ts

@@ -50,8 +50,10 @@ export interface ConflictInfo {
  *        (two-repo split: system = shipped defaults, user = operational state).
  *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
  *        .oauth_token file on Linux (keychain-less sandbox fallback).
+ *   v11 — when no default is set or the configured version is not installed,
+ *         interactively propose the latest already-installed version.
  */
-export declare const SHIM_SCHEMA_VERSION = 10;
+export declare const SHIM_SCHEMA_VERSION = 11;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -173,8 +173,10 @@ async function promptConflictStrategy(conflictInfos) {
  *        (two-repo split: system = shipped defaults, user = operational state).
  *   v9 — claude shim exports CLAUDE_CODE_OAUTH_TOKEN from per-version
  *        .oauth_token file on Linux (keychain-less sandbox fallback).
+ *   v11 — when no default is set or the configured version is not installed,
+ *         interactively propose the latest already-installed version.
  */
-export const SHIM_SCHEMA_VERSION = 10;
+export const SHIM_SCHEMA_VERSION = 11;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 /**
@@ -281,6 +283,31 @@ find_project_agents_dir() {
   return 1
 }
 
+# Find the latest installed version by numeric component comparison.
+# Handles both semver (2.1.138) and date-based (2026.5.7) version strings.
+find_latest_installed() {
+  local versions_dir="$AGENTS_USER_DIR/.history/versions/$AGENT"
+  [ -d "$versions_dir" ] || return
+  ls "$versions_dir" 2>/dev/null | awk '
+    BEGIN { best="" }
+    {
+      cur = $0
+      n = split(cur, a, /[^0-9]+/)
+      m = split(best, b, /[^0-9]+/)
+      maxn = (n > m) ? n : m
+      winner = cur
+      for (i=1; i<=maxn; i++) {
+        ai = (i<=n) ? a[i]+0 : 0
+        bi = (i<=m) ? b[i]+0 : 0
+        if (ai > bi) { winner=cur; break }
+        if (ai < bi) { winner=best; break }
+      }
+      best = winner
+    }
+    END { print best }
+  '
+}
+
 # Try project version first, then global default
 VERSION=$(find_project_version)
 VERSION_SOURCE="project"
@@ -290,9 +317,32 @@ if [ -z "$VERSION" ]; then
 fi
 
 if [ -z "$VERSION" ]; then
-  echo "agents: no version of $AGENT configured" >&2
-  echo "Run: agents add $AGENT@<version>" >&2
-  exit 1
+  LATEST=$(find_latest_installed)
+  if [ -n "$LATEST" ]; then
+    echo "agents: no default set for $AGENT — found $AGENT@$LATEST installed" >&2
+    if [ -t 2 ]; then
+      printf "  Set as default and continue? [Y/n] " >&2
+      read -r _ans </dev/tty
+      case "$_ans" in
+        ""|y|Y)
+          agents use "$AGENT" "$LATEST" >/dev/null 2>&1
+          VERSION="$LATEST"
+          VERSION_SOURCE="default"
+          ;;
+        *)
+          echo "  Run: agents use $AGENT <version>" >&2
+          exit 1
+          ;;
+      esac
+    else
+      echo "  Run: agents use $AGENT <version>" >&2
+      exit 1
+    fi
+  else
+    echo "agents: no version of $AGENT configured" >&2
+    echo "  Run: agents add $AGENT@<version>" >&2
+    exit 1
+  fi
 fi
 
 VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
@@ -329,9 +379,33 @@ if [ ! -x "$BINARY" ]; then
       exit 1
     fi
   else
-    echo "agents: $AGENT@$VERSION not installed" >&2
-    echo "Run: agents add $AGENT@$VERSION" >&2
-    exit 1
+    LATEST=$(find_latest_installed)
+    if [ -n "$LATEST" ] && [ "$LATEST" != "$VERSION" ]; then
+      echo "agents: $AGENT@$VERSION not installed — found $AGENT@$LATEST installed" >&2
+      if [ -t 2 ]; then
+        printf "  Switch default to $AGENT@$LATEST and continue? [Y/n] " >&2
+        read -r _ans </dev/tty
+        case "$_ans" in
+          ""|y|Y)
+            agents use "$AGENT" "$LATEST" >/dev/null 2>&1
+            VERSION="$LATEST"
+            VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
+            BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
+            ;;
+          *)
+            echo "  Run: agents add $AGENT@$VERSION" >&2
+            exit 1
+            ;;
+        esac
+      else
+        echo "  Run: agents add $AGENT@$VERSION" >&2
+        exit 1
+      fi
+    else
+      echo "agents: $AGENT@$VERSION not installed" >&2
+      echo "  Run: agents add $AGENT@$VERSION" >&2
+      exit 1
+    fi
   fi
 fi
 

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

@@ -0,0 +1,7 @@
+/**
+ * Commands staleness — one `.md` file per command, first-wins across
+ * project > user > system > extras.
+ */
+import type { FileEntry } from '../types.js';
+import type { TypedResourceChecker } from './types.js';
+export declare const commandsChecker: TypedResourceChecker<FileEntry>;

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

@@ -0,0 +1,27 @@
+/**
+ * Commands staleness — one `.md` file per command, first-wins across
+ * project > user > system > extras.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { firstWinsLayers, listAcrossLayers, resolveByName } from '../layers.js';
+import { fingerprintFile, isFileStale } from '../fingerprint.js';
+export const commandsChecker = {
+    type: 'commands',
+    listNames(cwd) {
+        return listAcrossLayers(firstWinsLayers(cwd), 'commands', (name) => name.endsWith('.md')).map((n) => n.replace(/\.md$/, ''));
+    },
+    build(name, cwd) {
+        const resolved = resolveByName(firstWinsLayers(cwd), path.join('commands', `${name}.md`), (p) => fs.existsSync(p));
+        if (!resolved)
+            return null;
+        const fp = fingerprintFile(resolved.path);
+        return fp ? { source: fp } : null;
+    },
+    isFresh(name, stored, cwd) {
+        const resolved = resolveByName(firstWinsLayers(cwd), path.join('commands', `${name}.md`), (p) => fs.existsSync(p));
+        if (!resolved)
+            return false;
+        return !isFileStale(stored.source, resolved.path);
+    },
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Hooks staleness — one executable file per hook. Project layer is EXCLUDED
+ * by design: a cloned public repo with `.agents/hooks/foo` must not plant a
+ * hook that fires next time the user runs an agent inside it (see
+ * `src/lib/versions.ts:1832-1836`). Only user + system + extras count.
+ *
+ * Auxiliary files (README.md, promptcuts.yaml) live in hooks/ but are not
+ * hooks — the executable bit on the source distinguishes them. This matches
+ * the filter in `getAvailableResources`.
+ */
+import type { FileEntry } from '../types.js';
+import type { TypedResourceChecker } from './types.js';
+export declare const hooksChecker: TypedResourceChecker<FileEntry>;

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

@@ -0,0 +1,63 @@
+/**
+ * Hooks staleness — one executable file per hook. Project layer is EXCLUDED
+ * by design: a cloned public repo with `.agents/hooks/foo` must not plant a
+ * hook that fires next time the user runs an agent inside it (see
+ * `src/lib/versions.ts:1832-1836`). Only user + system + extras count.
+ *
+ * Auxiliary files (README.md, promptcuts.yaml) live in hooks/ but are not
+ * hooks — the executable bit on the source distinguishes them. This matches
+ * the filter in `getAvailableResources`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { hookLayers, listAcrossLayers, resolveByName } from '../layers.js';
+import { fingerprintFile, isFileStale } from '../fingerprint.js';
+/** Extensions that are NEVER hooks — docs, configuration, plain data. */
+const NON_SCRIPT_EXTENSIONS = new Set([
+    '.md', '.markdown', '.rst', '.txt',
+    '.yaml', '.yml', '.json', '.toml', '.ini', '.conf',
+]);
+/** Extensions that explicitly mark a file as a script regardless of exec bit. */
+const SCRIPT_EXTENSIONS = new Set([
+    '.sh', '.bash', '.zsh',
+    '.py', '.js', '.ts', '.mjs', '.cjs',
+    '.rb', '.pl', '.ps1',
+]);
+function isHookScript(full) {
+    try {
+        const stat = fs.statSync(full);
+        if (!stat.isFile())
+            return false;
+        const ext = path.extname(full).toLowerCase();
+        if (SCRIPT_EXTENSIONS.has(ext))
+            return true;
+        // Otherwise require exec bit AND a non-data extension. Older sync runs
+        // chmod 0o755'd everything including `promptcuts.yaml` / `README.md`,
+        // so exec bit alone can't be trusted.
+        if ((stat.mode & 0o111) === 0)
+            return false;
+        return !NON_SCRIPT_EXTENSIONS.has(ext);
+    }
+    catch {
+        return false;
+    }
+}
+export const hooksChecker = {
+    type: 'hooks',
+    listNames(_cwd) {
+        return listAcrossLayers(hookLayers(), 'hooks', (_, full) => isHookScript(full));
+    },
+    build(name, _cwd) {
+        const resolved = resolveByName(hookLayers(), path.join('hooks', name), isHookScript);
+        if (!resolved)
+            return null;
+        const fp = fingerprintFile(resolved.path);
+        return fp ? { source: fp } : null;
+    },
+    isFresh(name, stored, _cwd) {
+        const resolved = resolveByName(hookLayers(), path.join('hooks', name), isHookScript);
+        if (!resolved)
+            return false;
+        return !isFileStale(stored.source, resolved.path);
+    },
+};

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

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

@@ -0,0 +1,38 @@
+/**
+ * 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) {
+    const map = new Map();
+    for (const cfg of listMcpServerConfigs(cwd)) {
+        if (!map.has(cfg.name))
+            map.set(cfg.name, cfg.path);
+    }
+    return map;
+}
+export const mcpChecker = {
+    type: 'mcp',
+    listNames(cwd) {
+        return Array.from(indexByName(cwd).keys());
+    },
+    build(name, cwd) {
+        const src = indexByName(cwd).get(name);
+        if (!src)
+            return null;
+        const fp = fingerprintFile(src);
+        return fp ? { source: fp } : null;
+    },
+    isFresh(name, stored, cwd) {
+        const src = indexByName(cwd).get(name);
+        if (!src)
+            return false;
+        return !isFileStale(stored.source, src);
+    },
+};

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

@@ -0,0 +1,17 @@
+/**
+ * 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';
+/** Walk user + system permissions/groups/. First-wins user > system on names. */
+export declare function collectPermissionGroupFiles(): Record<string, string>;
+/** 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

@@ -0,0 +1,73 @@
+/**
+ * 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. */
+export function collectPermissionGroupFiles() {
+    const seen = new Map();
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const groupsDir = path.join(baseDir, 'groups');
+        let entries;
+        try {
+            entries = fs.readdirSync(groupsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                continue;
+            const name = entry.name.replace(/\.(yaml|yml)$/, '');
+            if (!seen.has(name))
+                seen.set(name, path.join(groupsDir, entry.name));
+        }
+    }
+    return Object.fromEntries(seen);
+}
+/** Build the permissions section of the manifest. */
+export function buildPermissions() {
+    const groupFiles = collectPermissionGroupFiles();
+    const groups = {};
+    for (const [name, filePath] of Object.entries(groupFiles)) {
+        const fp = fingerprintFile(filePath);
+        if (fp)
+            groups[name] = { source: fp };
+    }
+    return {
+        groups,
+        permissionPreset: getActivePermissionPresetName(),
+    };
+}
+/** True when the stored permissions section no longer matches current state. */
+export function isPermissionsStale(stored) {
+    if (stored.permissionPreset !== getActivePermissionPresetName())
+        return true;
+    const currentGroups = collectPermissionGroupFiles();
+    const storedNames = Object.keys(stored.groups).sort();
+    const currentNames = Object.keys(currentGroups).sort();
+    if (storedNames.length !== currentNames.length)
+        return true;
+    for (let i = 0; i < storedNames.length; i++) {
+        if (storedNames[i] !== currentNames[i])
+            return true;
+    }
+    for (const [name, filePath] of Object.entries(currentGroups)) {
+        const entry = stored.groups[name];
+        if (!entry || isFileStale(entry.source, filePath))
+            return true;
+    }
+    return false;
+}

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

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * 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;
+export declare function isRulesStale(stored: RulesEntry, agent: AgentId, version: string, cwd: string): boolean;

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

@@ -0,0 +1,86 @@
+/**
+ * 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';
+import { composeRulesFromState } from '../../rules/compose.js';
+import { getActiveRulesPreset, getUserRulesDir, getResolvedRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../../state.js';
+function rulesDirForLayer(scope, cwd) {
+    if (scope === 'project') {
+        const proj = getProjectAgentsDir(cwd);
+        return proj ? path.join(proj, 'rules') : null;
+    }
+    if (scope === 'user')
+        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;
+    try {
+        const preset = getActiveRulesPreset(agent, version);
+        compose = composeRulesFromState({ preset, cwd });
+    }
+    catch {
+        return result;
+    }
+    const yamlDir = rulesDirForLayer(compose.presetLayer, cwd);
+    if (yamlDir) {
+        const yamlPath = path.join(yamlDir, 'rules.yaml');
+        if (fs.existsSync(yamlPath))
+            result['rules.yaml'] = yamlPath;
+    }
+    for (const sub of compose.subrules) {
+        result[`subrules/${sub.name}.md`] = sub.sourcePath;
+    }
+    return result;
+}
+export function buildRules(agent, version, cwd) {
+    const files = {};
+    for (const [key, srcPath] of Object.entries(activeSources(agent, version, cwd))) {
+        const fp = fingerprintFile(srcPath);
+        if (fp)
+            files[key] = { source: fp };
+    }
+    return { files };
+}
+export function isRulesStale(stored, agent, version, cwd) {
+    const current = activeSources(agent, version, cwd);
+    const storedKeys = Object.keys(stored.files).sort();
+    const currentKeys = Object.keys(current).sort();
+    if (storedKeys.length !== currentKeys.length)
+        return true;
+    for (let i = 0; i < storedKeys.length; i++) {
+        if (storedKeys[i] !== currentKeys[i])
+            return true;
+    }
+    for (const [key, srcPath] of Object.entries(current)) {
+        const entry = stored.files[key];
+        if (!entry || isFileStale(entry.source, srcPath))
+            return true;
+    }
+    return false;
+}

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

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

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

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

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

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