@phnx-labs/agents-cli 1.18.0 → 1.18.2

package/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## Unreleased
+## 1.18.2
+
+**Teams**
+
+- Dropped `~/.agents/teams/config.json` entirely. It duplicated information agents-cli already has — agent commands, enabled flags, model defaults, provider endpoints — none of which the team runner was actually reading. Teams now discover agents via `listInstalledVersions()` (the same source `agents view` uses) and invoke them via the canonical `agents run` subcommand. One spawn path, one canonical exec module (`src/lib/exec.ts`). The deprecated `AGENT_COMMANDS`, `applyEditMode`, `applyFullMode`, `readConfig`, `writeConfig`, `setAgentEnabled`, `AgentConfig`, `SwarmConfig`, `ProviderConfig`, `ModelOverrides`, `ReadConfigResult`, and `EffortLevel` (the persistence-module copy) exports are removed from `@phnx-labs/agents-cli/teams`. Migration deletes both `~/.agents/teams/config.json` and the legacy `~/.agents/config.json`.
+- `~/.agents/teams/registry.json` moves to `~/.agents/.history/teams/registry.json` — it's per-machine runtime state (timestamps + absolute worktree paths) and shouldn't be synced across machines via `agents repo push`.
+- New `agents run --quiet` flag suppresses the rotation banner and `Running: …` preamble lines. Used by the team runner so stream-json events reach the parser without non-JSON preamble.
+
+**Dev builds**
+
+- The CLI auto-detects dev builds (version stamped `0.0.0-dev.<sha>` by `scripts/install.sh`, or invoked from a working tree where `<cli-dir>/../.git/` exists) and defaults `AGENTS_NO_AUTOPULL=1`, `AGENTS_SKIP_MIGRATION=1`, and `AGENTS_CLI_DISABLE_AUTO_UPDATE=1`. No more typing those three env vars on every iteration. Production installs (registry global, no `.git/` at package root) are unaffected.
+
+## 1.18.1
+
+**Fixes**
+
+- `scripts/build.sh` now sets mode `0o755` on every file declared in `package.json#bin` after `tsc` emits dist/. Newer npm versions preserve file mode from the published tarball and do NOT auto-chmod the bin target during `npm install -g`, so 1.18.0 shipped with mode-644 entrypoints. Users hit `zsh: permission denied: agents` after auto-update. Re-install to recover: `npm install -g @phnx-labs/agents-cli@latest`.
+- New `scripts/install.sh` builds the working tree as a side-by-side dev install at `$HOME/.local/agents-cli-dev/`, symlinked into `$HOME/.local/bin/agents`. The registry install is never touched — `agents --version` shows `0.0.0-dev.<sha>[-dirty]` when the dev build is on PATH.
+
+## 1.18.0
 
 **Plugins**
 

package/dist/commands/doctor.js

@@ -1,8 +1,8 @@
 import chalk from 'chalk';
 import { checkAllClis } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
-import { getAvailableResources, getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
-import { loadSyncManifest, isSyncStale } from '../lib/sync-manifest.js';
+import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
+import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
 import { diffVersionHooks, iterHooksCapableVersions } from '../lib/hooks.js';
@@ -17,13 +17,12 @@ function checkSyncStatus(cwd) {
         const version = getGlobalDefault(agent);
         if (!version)
             continue;
-        const manifest = loadSyncManifest(agent, version);
+        const manifest = loadManifest(agent, version);
         if (!manifest) {
             rows.push({ agent, version, status: 'never-synced' });
             continue;
         }
-        const available = getAvailableResources(cwd);
-        const stale = isSyncStale(manifest, available, agent, version, cwd);
+        const stale = isStale(manifest, agent, version, cwd);
         rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
     }
     return rows;
@@ -270,6 +269,21 @@ function renderTargetText(report, options) {
             : null,
     ].filter(Boolean).join(' ');
     console.log(chalk.gray(`  layers: ${layerStr}`));
+    // Staleness manifest verdict — single-line summary from the staleness
+    // library, sitting alongside the detailed per-resource diff below.
+    const manifest = loadManifest(report.agent, report.version);
+    if (!manifest) {
+        console.log(chalk.gray(`  manifest: ${chalk.gray('cold')} (never synced)`));
+    }
+    else {
+        const stale = isStale(manifest, report.agent, report.version, report.cwd);
+        if (stale) {
+            console.log(chalk.gray('  manifest: ') + chalk.yellow('stale') + chalk.gray(' (sources changed since last sync)'));
+        }
+        else {
+            console.log(chalk.gray('  manifest: ') + chalk.green('fresh'));
+        }
+    }
     console.log();
     for (const kind of DOCTOR_ALL_KINDS) {
         const rows = report.kinds[kind];

package/dist/commands/exec.js

@@ -51,6 +51,7 @@ export function registerRunCommand(program) {
         .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory)')
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude only, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
+        .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
         .option('--headless', 'Non-interactive mode (auto-enabled when prompt provided)', false)
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided')
         .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
@@ -249,17 +250,19 @@ Examples:
                     const resolved = await resolveRunVersion(agent, strategy, cwd);
                     if (resolved.version) {
                         version = resolved.version;
-                        if (resolved.rotation) {
+                        if (resolved.rotation && !options.quiet) {
                             const banner = formatRotationBanner(resolved.rotation, strategy);
                             process.stderr.write(chalk.gray(banner + '\n'));
                         }
                     }
-                    else {
+                    else if (!options.quiet) {
                         process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} found no usable ${agent} version; falling back to defaults\n`));
                     }
                 }
                 catch (err) {
-                    process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} skipped: ${err.message}\n`));
+                    if (!options.quiet) {
+                        process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} skipped: ${err.message}\n`));
+                    }
                 }
             }
         }
@@ -388,7 +391,9 @@ Examples:
             }
         }
         const cmd = buildExecCommand(execOptions);
-        process.stderr.write(chalk.gray(`Running: ${cmd.join(' ')}\n\n`));
+        if (!options.quiet) {
+            process.stderr.write(chalk.gray(`Running: ${cmd.join(' ')}\n\n`));
+        }
         try {
             let exitCode;
             if (fallback.length > 0) {

package/dist/index.js

@@ -23,6 +23,36 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, '..', 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
 const VERSION = packageJson.version;
+// Detect dev/working-tree builds and default the noisy startup steps off.
+// Three cases trip this:
+//   1. Dev install (scripts/install.sh) — package.json version stamped 0.0.0-dev.<sha>
+//   2. Running `node dist/index.js` from a working tree — repo root has .git/
+//   3. Running tsx/ts-node from src/ — also has .git/ at the repo root
+// For all three: skip auto-pull (no network noise + no surprise FF on the
+// system repo while iterating), skip migration (a buggy in-progress migration
+// must not scribble on the user's real ~/.agents/), and skip the update prompt
+// (the "0.0.0-dev -> 1.x.y" message is misleading). Each individual env var
+// can still be set explicitly to override (set to '0' to re-enable).
+const IS_DEV_BUILD = (() => {
+    if (VERSION.startsWith('0.0.0-dev'))
+        return true;
+    try {
+        const cliPath = process.argv[1] || '';
+        const repoRoot = path.dirname(path.dirname(cliPath));
+        return fs.existsSync(path.join(repoRoot, '.git'));
+    }
+    catch {
+        return false;
+    }
+})();
+if (IS_DEV_BUILD) {
+    if (process.env.AGENTS_NO_AUTOPULL === undefined)
+        process.env.AGENTS_NO_AUTOPULL = '1';
+    if (process.env.AGENTS_SKIP_MIGRATION === undefined)
+        process.env.AGENTS_SKIP_MIGRATION = '1';
+    if (process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE === undefined)
+        process.env.AGENTS_CLI_DISABLE_AUTO_UPDATE = '1';
+}
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
 import { registerRepoCommands } from './commands/repo.js';

package/dist/lib/hooks.js

@@ -51,6 +51,18 @@ function isManagedHookCommand(command, prefixes) {
     return false;
 }
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+/**
+ * Extensions that are NEVER hooks — docs, configuration, plain data. A file
+ * in hooks/ with one of these extensions is auxiliary content (e.g., the
+ * `promptcuts.yaml` data file read directly by the expand-promptcuts
+ * script, or the `README.md` that documents the hooks directory). They
+ * sometimes carry an exec bit by accident (older sync runs chmod 0o755'd
+ * everything) but they are not scripts.
+ */
+const NON_SCRIPT_EXTENSIONS = new Set([
+    '.md', '.markdown', '.rst', '.txt',
+    '.yaml', '.yml', '.json', '.toml', '.ini', '.conf',
+]);
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
     '.bash',
@@ -140,9 +152,15 @@ export function listHookEntriesFromDir(dir) {
     const entries = [];
     for (const [base, group] of grouped) {
         group.sort((a, b) => a.name.localeCompare(b.name));
-        const script = group.find((f) => f.isExec) ||
-            group.find((f) => SCRIPT_EXTENSIONS.has(f.ext.toLowerCase())) ||
-            group[0];
+        // A group is a hook only if it has an actual script: a script extension,
+        // OR an executable bit on a file whose extension is not a known data /
+        // docs type. Files like `README.md` (docs) or `promptcuts.yaml` (data
+        // the expand-promptcuts hook reads directly) sit alongside hooks but
+        // are NOT hooks themselves and must not surface in the hooks list
+        // anywhere — doctor, sync, view, or otherwise. Older sync runs may have
+        // chmod 0o755'd these files; an exec bit alone is not enough.
+        const script = group.find((f) => SCRIPT_EXTENSIONS.has(f.ext.toLowerCase())) ||
+            group.find((f) => f.isExec && !NON_SCRIPT_EXTENSIONS.has(f.ext.toLowerCase()));
         if (!script)
             continue;
         const data = group.find((f) => f !== script);

package/dist/lib/migrate.js

@@ -58,14 +58,14 @@ function deleteSystemPromptsJson() {
  * The teams persistence layer already reads the legacy path as a fallback;
  * moving it here keeps the canonical location consistent.
  */
+// Delete the legacy ~/.agents-system/config.json. This was the teams agent
+// registry, which no longer exists — `agents teams` discovers agents through
+// `listInstalledVersions` and invokes them through `agents run`.
 function migrateSystemConfigJson() {
     const src = path.join(SYSTEM_DIR, 'config.json');
-    const dest = path.join(USER_DIR, 'teams', 'config.json');
-    if (!fs.existsSync(src) || fs.existsSync(dest))
+    if (!fs.existsSync(src))
         return;
     try {
-        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
-        fs.copyFileSync(src, dest);
         fs.unlinkSync(src);
     }
     catch { /* best-effort */ }
@@ -375,20 +375,41 @@ function deleteUserPromptsJson() {
     catch { /* best-effort */ }
 }
 /**
- * Delete ~/.agents/config.json. The canonical teams config is at
- * ~/.agents/teams/config.json (teams/persistence.ts). If the canonical
- * file exists we just unlink the legacy copy; otherwise migrate first.
+ * Delete ~/.agents/teams/config.json. The teams subsystem no longer carries
+ * its own agent registry — agent discovery flows through `listInstalledVersions`
+ * (the same source `agents view` uses) and invocation flows through
+ * `agents run`. The on-disk file is pure dead state on existing installs.
+ */
+function deleteTeamsConfigJson() {
+    const f = path.join(USER_DIR, 'teams', 'config.json');
+    if (!fs.existsSync(f))
+        return;
+    try {
+        fs.unlinkSync(f);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents/teams/registry.json → ~/.agents/.history/teams/registry.json.
+ * The registry is per-machine runtime state (timestamps + absolute worktree
+ * paths) and belongs in the durable-runtime bucket, not at the user-root
+ * where `agents repo push` would sync it across machines.
+ */
+function moveTeamsRegistryToHistory() {
+    const src = path.join(USER_DIR, 'teams', 'registry.json');
+    const dest = path.join(HISTORY_DIR, 'teams', 'registry.json');
+    moveFileOnce(src, dest);
+}
+/**
+ * Delete ~/.agents/config.json. This was the legacy teams config location;
+ * the teams subsystem no longer carries a config file at all, so the legacy
+ * copy is simply removed.
  */
 function cleanupUserConfigJson() {
     const legacy = path.join(USER_DIR, 'config.json');
     if (!fs.existsSync(legacy))
         return;
-    const canonical = path.join(USER_DIR, 'teams', 'config.json');
     try {
-        if (!fs.existsSync(canonical)) {
-            fs.mkdirSync(path.dirname(canonical), { recursive: true, mode: 0o700 });
-            fs.copyFileSync(legacy, canonical);
-        }
         fs.unlinkSync(legacy);
     }
     catch { /* best-effort */ }
@@ -1455,6 +1476,8 @@ export async function runMigration() {
     migratePermissionSetsToPresets();
     deleteUserLinearJson();
     deleteUserPromptsJson();
+    deleteTeamsConfigJson();
+    moveTeamsRegistryToHistory();
     cleanupUserConfigJson();
     cleanupEmptyTopLevelRuns();
     foldUserHooksYamlIntoAgentsYaml();

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;