@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/startup/command-registry.js

@@ -1,283 +1,26 @@
-/**
- * Lazy command registry.
- *
- * The CLI entry point (src/index.ts) used to statically import every command
- * module and call its `registerXCommand(program)` on every invocation. That
- * loaded the entire command tree (~50 modules) before the first line of output,
- * dominating cold-start latency.
- *
- * This module maps each user-typed top-level command name to a thunk that
- * dynamically imports ONLY the module(s) that command needs. Fast commands
- * (`--version`, `view`, ...) now pay for just the one module they use; the full
- * tree is loaded only on the rare slow paths (unknown-command spellcheck, bare
- * help) via `registerAllEagerCommands` in src/index.ts.
- *
- * Parity is non-negotiable: the name -> loader map below mirrors exactly which
- * module registers which top-level command on `main`. Multi-command modules
- * (versions, packages) map several names to the same loader; `prune` needs BOTH
- * versions (which creates `prune <specs...>`) and prune.js (which attaches the
- * `cleanup` subcommand to it), in that order — see commands/prune.ts.
- */
-import { Command } from 'commander';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { configureRootCommand } from './root-command.js';
-// One loader per command module. Each dynamically imports the module and hands
-// back its register function. Kept as named consts so src/index.ts can compose
-// them into the exact main-branch registration order for the slow path.
-export const loadView = async () => (await import('../../commands/view.js')).registerViewCommand;
-export const loadInspect = async () => (await import('../../commands/inspect.js')).registerInspectCommand;
-export const loadFeedback = async () => (await import('../../commands/feedback.js')).registerFeedbackCommand;
-export const loadCommands = async () => (await import('../../commands/commands.js')).registerCommandsCommands;
-export const loadHooks = async () => (await import('../../commands/hooks.js')).registerHooksCommands;
-export const loadSkills = async () => (await import('../../commands/skills.js')).registerSkillsCommands;
-export const loadRules = async () => (await import('../../commands/rules.js')).registerRulesCommands;
-export const loadMemory = async () => (await import('../../commands/memory.js')).registerMemoryCommands;
-export const loadPermissions = async () => (await import('../../commands/permissions.js')).registerPermissionsCommands;
-export const loadMcp = async () => (await import('../../commands/mcp.js')).registerMcpCommands;
-export const loadCli = async () => (await import('../../commands/cli.js')).registerCliCommands;
-export const loadSubagents = async () => (await import('../../commands/subagents.js')).registerSubagentsCommands;
-export const loadPlugins = async () => (await import('../../commands/plugins.js')).registerPluginsCommands;
-export const loadWorkflows = async () => (await import('../../commands/workflows.js')).registerWorkflowsCommands;
-export const loadVersions = async () => (await import('../../commands/versions.js')).registerVersionsCommands;
-export const loadUpdate = async () => (await import('../../commands/update.js')).registerUpdateCommand;
-export const loadImport = async () => (await import('../../commands/import.js')).registerImportCommand;
-export const loadPackages = async () => (await import('../../commands/packages.js')).registerPackagesCommands;
-export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
-export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
-export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
-export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
-export const loadResume = async () => (await import('../../commands/resume.js')).registerResumeCommand;
-export const loadOpen = async () => (await import('../../commands/open.js')).registerOpenCommand;
-export const loadReconnect = async () => (await import('../../commands/reconnect.js')).registerReconnectCommand;
-export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
-export const loadConfig = async () => (await import('../../commands/config.js')).registerConfigCommand;
-export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
-export const loadModes = async () => (await import('../../commands/modes.js')).registerModesCommand;
-export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
-export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
-export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
-export const loadDoctor = async () => (await import('../../commands/doctor.js')).registerDoctorCommand;
-export const loadApply = async () => (await import('../../commands/apply.js')).registerApplyCommand;
-export const loadStatus = async () => (await import('../../commands/status.js')).registerStatusCommand;
-export const loadSnapshot = async () => (await import('../../commands/snapshot.js')).registerSnapshotCommand;
-export const loadProfiles = async () => (await import('../../commands/profiles.js')).registerProfilesCommands;
-export const loadHarness = async () => (await import('../../commands/harness.js')).registerHarnessCommands;
-export const loadSecrets = async () => (await import('../../commands/secrets.js')).registerSecretsCommands;
-export const loadLogin = async () => (await import('../../commands/login.js')).registerLoginCommands;
-export const loadMenubar = async () => (await import('../../commands/menubar.js')).registerMenubarCommands;
-export const loadBeta = async () => (await import('../../commands/beta.js')).registerBetaCommands;
-export const loadSync = async () => (await import('../../commands/sync.js')).registerSyncCommand;
-export const loadRefreshRules = async () => (await import('../../commands/refresh-rules.js')).registerRefreshRulesCommand;
-export const loadFactory = async () => (await import('../../commands/factory.js')).registerFactoryCommands;
-export const loadUsage = async () => (await import('../../commands/usage.js')).registerUsageCommand;
-export const loadCost = async () => (await import('../../commands/cost.js')).registerCostCommand;
-export const loadInsights = async () => (await import('../../commands/insights.js')).registerInsightsCommand;
-export const loadPerf = async () => (await import('../../commands/perf.js')).registerPerfCommand;
-export const loadBench = async () => (await import('../../commands/bench.js')).registerBenchCommand;
-// Thin deprecated alias of `agents insights mix` — no second mix implementation.
-export const loadTrends = async () => (await import('../../commands/trends.js')).registerTrendsCommand;
-export const loadOutput = async () => (await import('../../commands/output.js')).registerOutputCommand;
-export const loadBudget = async () => (await import('../../commands/budget.js')).registerBudgetCommand;
-export const loadAlias = async () => (await import('../../commands/alias.js')).registerAliasCommand;
-export const loadMine = async () => (await import('../../commands/mine.js')).registerMineCommand;
-export const loadPty = async () => (await import('../../commands/pty.js')).registerPtyCommands;
-export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
-export const loadWatchdog = async () => (await import('../../commands/watchdog.js')).registerWatchdogCommand;
-export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
-export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
-export const loadLogs = async () => (await import('../../commands/logs.js')).registerLogsCommand;
-export const loadEvents = async () => (await import('../../commands/events.js')).registerEventsCommand;
-export const loadSsh = async () => (await import('../../commands/ssh.js')).registerSshCommands;
-export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
-export const loadSetup = async () => (await import('../../commands/setup.js')).registerSetupCommand;
-export const loadUninstall = async () => (await import('../../commands/uninstall.js')).registerUninstallCommands;
-export const loadUpgrade = async () => (await import('../../commands/upgrade.js')).registerUpgradeCommand;
-export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
-export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
-export const loadTickets = async () => (await import('../../commands/tickets.js')).registerTicketsCommand;
-export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
-export const loadMessage = async () => (await import('../../commands/message.js')).registerMessageCommand;
-export const loadSend = async () => (await import('../../commands/send.js')).registerSendCommand;
-export const loadFeed = async () => (await import('../../commands/feed.js')).registerFeedCommand;
-export const loadMailboxes = async () => (await import('../../commands/mailboxes.js')).registerMailboxesCommand;
-export const loadServe = async () => (await import('../../commands/serve.js')).registerServeCommand;
-// Registers the `artifacts` group (with `share` + `setup` under it) AND the
-// top-level `unshare` alias — see commands/artifacts.ts.
-export const loadArtifacts = async () => (await import('../../commands/artifacts.js')).registerArtifactsCommands;
-export const loadAudit = async () => (await import('../../commands/audit.js')).registerAuditCommands;
-export const loadWebhooks = async () => (await import('../../commands/webhook.js')).registerWebhooksCommand;
-export const loadHumans = async () => (await import('../../commands/humans.js')).registerHumansCommands;
-export const loadAccounts = async () => (await import('../../commands/accounts.js')).registerAccountsCommand;
-export const loadDaemon = async () => (await import('../../commands/daemon.js')).registerDaemonCommand;
-export const loadCp = async () => (await import('../../commands/cp.js')).registerCpCommand;
-/**
- * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
- * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
- * conventions at module top-level, lazy registration just before parse), so they
- * inherit the root's custom help formatter rather than getting the per-command
- * recursive pass. Keeping that ordering preserves their `--help` output exactly.
- */
-// `roster` is an observe-umbrella alias of `sessions --active` — same module,
-// same SQLite stack, same post-help registration order as sessions.
-export const LAZY_COMMAND_NAMES = new Set([
-    'sessions',
-    'resume',
-    'reconnect',
-    'roster',
-    'teams',
-    'cloud',
-    'message',
-    'serve',
-]);
-/**
- * User-typed top-level command name -> ordered list of module loaders to run.
- *
- * Most names map to a single loader. The exceptions encode real coupling on main:
- *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
- *  - `registry`/`search`/`install` all come from the packages module.
- *  - `trash` and `restore` are separate registrars in the trash module.
- *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
- *    (which finds that command and attaches the `cleanup` subcommand).
- *
- * Inline deprecated aliases (memory/perms/exec/jobs/cron) and the inline
- * `upgrade` command are NOT here — they are closures over entry-point state and
- * are handled directly in src/index.ts.
- */
-export const COMMAND_LOADERS = {
-    accounts: [loadAccounts],
-    view: [loadView],
-    inspect: [loadInspect],
-    feedback: [loadFeedback],
-    commands: [loadCommands],
-    hooks: [loadHooks],
-    skills: [loadSkills],
-    rules: [loadRules],
-    memory: [loadMemory],
-    permissions: [loadPermissions],
-    mcp: [loadMcp],
-    clis: [loadCli],
-    subagents: [loadSubagents],
-    plugins: [loadPlugins],
-    workflows: [loadWorkflows],
-    add: [loadVersions],
-    use: [loadVersions],
-    list: [loadVersions],
-    remove: [loadVersions],
-    rm: [loadVersions],
-    purge: [loadVersions],
-    update: [loadUpdate],
-    prune: [loadVersions, loadPrune],
-    import: [loadImport],
-    registry: [loadPackages],
-    search: [loadPackages],
-    install: [loadPackages],
-    routines: [loadRoutines],
-    monitors: [loadMonitors],
-    projects: [loadProjects],
-    run: [loadRun],
-    resume: [loadResume],
-    open: [loadOpen],
-    reconnect: [loadReconnect],
-    fork: [loadFork],
-    config: [loadConfig],
-    models: [loadModels],
-    modes: [loadModes],
-    trash: [loadTrash],
-    restore: [loadRestore],
-    doctor: [loadDoctor],
-    apply: [loadApply],
-    status: [loadStatus],
-    snapshot: [loadSnapshot],
-    profiles: [loadProfiles],
-    harness: [loadHarness],
-    harnesses: [loadHarness],
-    secrets: [loadSecrets],
-    login: [loadLogin],
-    logout: [loadLogin],
-    menubar: [loadMenubar],
-    beta: [loadBeta],
-    sync: [loadSync],
-    'refresh-rules': [loadRefreshRules],
-    factory: [loadFactory],
-    usage: [loadUsage],
-    cost: [loadCost],
-    insights: [loadInsights],
-    perf: [loadPerf],
-    bench: [loadBench],
-    trends: [loadTrends],
-    output: [loadOutput],
-    budget: [loadBudget],
-    alias: [loadAlias],
-    mine: [loadMine],
-    pty: [loadPty],
-    tmux: [loadTmux],
-    watchdog: [loadWatchdog],
-    browser: [loadBrowser],
-    computer: [loadComputer],
-    logs: [loadLogs],
-    events: [loadEvents],
-    ssh: [loadSsh],
-    devices: [loadSsh],
-    // `fleet` is a commander alias of `devices` (see commands/ssh.ts); list it so
-    // lazy registration loads the devices tree when the user types `agents fleet`.
-    fleet: [loadSsh],
-    // `repos` is the canonical command name; `repo` remains a convenience alias
-    // (see commands/repo.ts). List both so lazy registration loads the tree
-    // whichever the user types.
-    repos: [loadRepo],
-    repo: [loadRepo],
-    setup: [loadSetup],
-    uninstall: [loadUninstall],
-    upgrade: [loadUpgrade],
-    sessions: [loadSessions],
-    // Observe-umbrella alias of sessions --active (same lazy module).
-    roster: [loadSessions],
-    teams: [loadTeams],
-    tickets: [loadTickets],
-    cloud: [loadCloud],
-    message: [loadMessage],
-    send: [loadSend],
-    notify: [loadSend],
-    feed: [loadFeed],
-    // Observe-umbrella aliases of feed / feed --filter updates.
-    inbox: [loadFeed],
-    timeline: [loadFeed],
-    mailboxes: [loadMailboxes],
-    mailbox: [loadMailboxes],
-    serve: [loadServe],
-    artifacts: [loadArtifacts],
-    // `unshare` is a top-level convenience alias of `artifacts share delete` (see
-    // commands/share.ts) — same module, registered as its own program.command().
-    unshare: [loadArtifacts],
-    audit: [loadAudit],
-    webhooks: [loadWebhooks],
-    humans: [loadHumans],
-    daemon: [loadDaemon],
-    cp: [loadCp],
-};
-/**
- * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
- * registered inline in src/index.ts — closures over entry-point state (the
- * deprecated aliases and tombstones) plus the internal command. They are
- * real commands, so anything that asks "does this command exist?" must count them.
- */
+const LOADED_COMMAND_NAMES = [
+    'accounts', 'view', 'inspect', 'feedback', 'commands', 'hooks', 'skills', 'rules', 'memory',
+    'permissions', 'mcp', 'clis', 'subagents', 'plugins', 'workflows', 'add', 'use', 'list',
+    'remove', 'rm', 'purge', 'update', 'prune', 'import', 'registry', 'search', 'install',
+    'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
+    'models', 'modes', 'trash', 'restore', 'doctor', 'apply', 'status',
+    'route', 'harness', 'harnesses', 'secrets', 'menubar', 'beta', 'sync',
+    'refresh-rules', 'factory', 'usage', 'insights', 'perf', 'trends',
+    'alias', 'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
+    'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
+    'teams', 'tickets', 'cloud', 'message', 'send', 'notify', 'feed', 'inbox',
+    'timeline', 'mailboxes', 'mailbox', 'serve', 'artifacts', 'unshare', 'audit', 'webhooks',
+    'humans', 'daemon',
+];
 const INLINE_COMMAND_NAMES = [
-    'perms', // deprecated alias -> permissions
-    'exec', // deprecated alias -> run
-    'jobs', // deprecated alias -> routines
-    'cron', // deprecated alias -> routines
-    'check', // tombstone -> doctor --check
-    'resources', // tombstone -> view --merged
-    'hq', // tombstone
-    '_internal',
+    'perms', 'exec', 'jobs', 'cron', 'check', 'resources', 'hq', '_internal',
 ];
 /**
  * Every top-level command name the CLI answers to — the loader table plus the
  * inline aliases/tombstones above. This is the "does this command exist?"
  * predicate for code that runs BEFORE commander parses, most importantly the
- * `--host`/`--device` router (lib/hosts/passthrough.ts): without it a typo'd
- * command carrying `--host` reported a flag-support error instead of
+ * `--device` router (lib/hosts/passthrough.ts): without it a typo'd
+ * command carrying `--device` reported a flag-support error instead of
  * `unknown command` (RUSH-2022).
  *
  * Commander sub-aliases (`sessions ls`, `teams rm`, …) are deliberately absent —
@@ -285,7 +28,7 @@ const INLINE_COMMAND_NAMES = [
  * registered command tree so a new command can never drift out of it.
  */
 export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
-    ...Object.keys(COMMAND_LOADERS),
+    ...LOADED_COMMAND_NAMES,
     ...INLINE_COMMAND_NAMES,
 ]);
 /**
@@ -295,35 +38,27 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * the user never asked for instead of saying the command is gone.
  *
  * `set` moved under `agents models`/`agents config` (RUSH-2579); `share` moved
- * under `agents artifacts share` (RUSH-2580).
+ * under `agents artifacts share` (RUSH-2580). login/logout/budget/bench/mine/
+ * cost/output/profiles/snapshot/cp/resume/roster moved under nested homes
+ * (cli-surface-consolidate).
  */
-export const RETIRED_TOP_LEVEL_COMMANDS = new Set(['webhook', 'set', 'share']);
-/** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
+export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
+    'webhook',
+    'login',
+    'logout',
+    'budget',
+    'bench',
+    'mine',
+    'cost',
+    'output',
+    'profiles',
+    'snapshot',
+    'cp',
+    'resume',
+    'roster',
+    'set',
+    'share',
+]);
 export function isKnownTopLevelCommand(name) {
     return KNOWN_TOP_LEVEL_COMMANDS.has(name);
 }
-/**
- * Register every module in {@link COMMAND_LOADERS} onto one fresh program and
- * return it — the full public command tree, deduped by loader identity so a
- * loader mapped to several names (e.g. `add`/`use`/`list` -> versions) runs once.
- *
- * Off the hot path only: the command-index generator (`scripts/gen-command-index.ts`)
- * and the tests build the tree from this. Startup never calls it — src/index.ts
- * registers just the one requested command via `registerEagerForRequest`. The
- * inline aliases/tombstones ({@link INLINE_COMMAND_NAMES}) are NOT included: they
- * are closures over entry-point state that src/index.ts registers directly.
- */
-export async function buildFullCommandTree() {
-    const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8'));
-    const program = configureRootCommand(new Command(), 'agents', packageJson.version);
-    const done = new Set();
-    for (const loaders of Object.values(COMMAND_LOADERS)) {
-        for (const loader of loaders) {
-            if (done.has(loader))
-                continue;
-            done.add(loader);
-            (await loader())(program);
-        }
-    }
-    return program;
-}

package/dist/lib/startup/dev-build.d.ts

@@ -1,24 +1,3 @@
-/**
- * Decide whether the CLI is running from a source checkout (a "dev build") vs an
- * installed package. Dev builds suppress autopull / migrations / auto-update so
- * iterating on the repo never mutates the user's real setup.
- *
- * Two signals:
- *   1. A `0.0.0-dev*` version stamp (scripts/install.sh dev installs).
- *   2. Running out of an actual agents-cli git checkout.
- *
- * Signal 2 must be precise. The naive check —
- * `existsSync(dirname(dirname(argv[1])) + '/.git')` — false-positives badly:
- *   - npm-global bins are symlinks. `/opt/homebrew/bin/agents` →
- *     `…/node_modules/@phnx-labs/agents-cli/dist/index.js`. Without resolving the
- *     symlink, `dirname(dirname())` walks to `/opt/homebrew`, which is **itself a
- *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
- *     and had migrations + the menu-bar self-heal silently disabled.
- *
- * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
- * actually be the agents-cli package (its package.json `name`), not some
- * unrelated ancestor that happens to be version-controlled.
- */
 /**
  * Whether a version string is the `0.0.0-dev.<sha>[-dirty]` stamp
  * `scripts/install.sh` writes for a side-by-side dev install (`install.sh:61`).

package/dist/lib/startup/dev-build.js

@@ -17,10 +17,22 @@ import * as path from 'path';
  *     git repo** (Homebrew). So every Homebrew-node user looked like a dev build
  *     and had migrations + the menu-bar self-heal silently disabled.
  *
- * Fix: resolve the symlink with realpath, then require the `.git`'s repo root to
- * actually be the agents-cli package (its package.json `name`), not some
- * unrelated ancestor that happens to be version-controlled.
+ * Fix: resolve the symlink with realpath and require the resolved package root's
+ * own package.json `name` to actually be the agents-cli package, before ever
+ * looking for `.git`.
+ *
+ * That package root does not always hold `.git` itself, though — this repo is a
+ * monorepo where the package lives at `apps/cli` and `.git` sits one level
+ * higher, at the true repo root. `.git` is therefore searched for in a SMALL,
+ * bounded set of ancestors above the package root (see
+ * `DEV_BUILD_GIT_ANCESTOR_DEPTH`), not just the package root itself — a source
+ * checkout run via tsx/ts-node from `apps/cli/src/` or built to
+ * `apps/cli/dist/` must still be recognized. The bound keeps this well short of
+ * an unrelated ancestor repo: a real Homebrew npm-global install's package root
+ * sits 3 directories below `/opt/homebrew` (`lib/node_modules/@phnx-labs/…`),
+ * so a depth of 2 finds this repo's `.git` while staying short of Homebrew's.
  */
+const DEV_BUILD_GIT_ANCESTOR_DEPTH = 2;
 /**
  * Whether a version string is the `0.0.0-dev.<sha>[-dirty]` stamp
  * `scripts/install.sh` writes for a side-by-side dev install (`install.sh:61`).
@@ -38,14 +50,23 @@ export function detectDevBuild(argv1, version) {
         return true;
     try {
         const cliPath = fs.realpathSync(argv1 || '');
-        const repoRoot = path.dirname(path.dirname(cliPath));
-        if (!fs.existsSync(path.join(repoRoot, '.git')))
-            return false;
-        const pkgPath = path.join(repoRoot, 'package.json');
+        const packageRoot = path.dirname(path.dirname(cliPath));
+        const pkgPath = path.join(packageRoot, 'package.json');
         if (!fs.existsSync(pkgPath))
             return false;
         const name = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))?.name;
-        return name === '@phnx-labs/agents-cli';
+        if (name !== '@phnx-labs/agents-cli')
+            return false;
+        let dir = packageRoot;
+        for (let depth = 0; depth <= DEV_BUILD_GIT_ANCESTOR_DEPTH; depth++) {
+            if (fs.existsSync(path.join(dir, '.git')))
+                return true;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return false; // reached the filesystem root
+            dir = parent;
+        }
+        return false;
     }
     catch {
         return false;

package/dist/lib/state.d.ts

@@ -47,6 +47,16 @@ export declare function getUserAgentsDir(): string;
  * @deprecated Use getUserAgentsDir() directly.
  */
 export declare function getOptionalUserAgentsDir(): string | null;
+/**
+ * True when `agentsPath` is a reserved `.agents` root that must never be
+ * treated as a project layer: the user repo (~/.agents), the system repo
+ * (~/.agents/.system), or a git checkout of either canonical DotAgents repo.
+ * `getProjectAgentsDir` skips these while walking up; direct-cwd callers
+ * (`compileRulesForProject`) consult the same predicate so `$HOME` — whose
+ * `.agents/rules` is the user layer itself — can never compile as a
+ * "project" (RUSH-2725).
+ */
+export declare function isReservedAgentsDir(agentsPath: string): boolean;
 /** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export declare function getProjectAgentsDir(startPath?: string): string | null;
 /** Return all .agents/ directories in scope: project, user, then system. */
@@ -250,8 +260,15 @@ export declare function getTeamsRegistryPath(): string;
 export declare function getDevicesRegistryPath(): string;
 /** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
 export declare function getDevicesIgnoredPath(): string;
-/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the central `fleet.devices.<name>.config` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
+/** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the per-device doc `config:` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export declare function getDevicesAutoLaunchPath(): string;
+/** Path to THIS machine's agent pins — the `agents:` global defaults and
+ * `isolatedAgents:` pointers. Each pin names a version installed on THIS
+ * machine, so it is machine-local runtime state and lives beside the device
+ * registry under `.history/devices/` (untracked) — NOT in the tracked
+ * per-device doc, where auto-written pins caused commit churn on every
+ * `agents use` / install. Read at call time like the other devices-dir paths. */
+export declare function getDevicePinsPath(): string;
 /** Dir of "pending device" sentinels (~/.agents/.cache/state/devices-pending/) — one empty-ish file per newly-discovered, not-yet-approved tailnet node. Written by the daemon probe, read by the menu-bar helper (mirrors the attention sentinel dir). */
 export declare function getDevicesPendingDir(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
@@ -373,6 +390,7 @@ export declare function getDeviceMetaPath(): string;
  * Gitignored (under .history/) and regenerable; never synced.
  */
 export declare function getVersionResourcesPath(): string;
+export declare function withMetaLock<T>(fn: () => T): T;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *