@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/startup/command-registry.d.ts

@@ -37,21 +37,19 @@ export declare const loadCli: ModuleLoader;
 export declare const loadSubagents: ModuleLoader;
 export declare const loadPlugins: ModuleLoader;
 export declare const loadWorkflows: ModuleLoader;
-export declare const loadWorktree: ModuleLoader;
 export declare const loadVersions: ModuleLoader;
 export declare const loadUpdate: ModuleLoader;
 export declare const loadImport: ModuleLoader;
-export declare const loadExport: ModuleLoader;
 export declare const loadPackages: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
 export declare const loadResume: ModuleLoader;
+export declare const loadOpen: ModuleLoader;
 export declare const loadReconnect: ModuleLoader;
 export declare const loadFork: ModuleLoader;
-export declare const loadDefaults: ModuleLoader;
-export declare const loadSet: ModuleLoader;
+export declare const loadConfig: ModuleLoader;
 export declare const loadModels: ModuleLoader;
 export declare const loadModes: ModuleLoader;
 export declare const loadPrune: ModuleLoader;
@@ -65,12 +63,9 @@ export declare const loadProfiles: ModuleLoader;
 export declare const loadHarness: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
 export declare const loadLogin: ModuleLoader;
-export declare const loadWallet: ModuleLoader;
-export declare const loadHelper: ModuleLoader;
 export declare const loadMenubar: ModuleLoader;
 export declare const loadBeta: ModuleLoader;
 export declare const loadSync: ModuleLoader;
-export declare const loadLock: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
@@ -88,32 +83,29 @@ export declare const loadTmux: ModuleLoader;
 export declare const loadWatchdog: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
-export declare const loadHosts: ModuleLoader;
-export declare const loadLease: ModuleLoader;
 export declare const loadLogs: ModuleLoader;
 export declare const loadEvents: ModuleLoader;
 export declare const loadSsh: ModuleLoader;
-export declare const loadPull: ModuleLoader;
-export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;
 export declare const loadSetup: ModuleLoader;
 export declare const loadUninstall: ModuleLoader;
 export declare const loadUpgrade: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
+export declare const loadTickets: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadSend: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
 export declare const loadMailboxes: ModuleLoader;
 export declare const loadServe: ModuleLoader;
-export declare const loadShare: ModuleLoader;
+export declare const loadArtifacts: ModuleLoader;
 export declare const loadAudit: ModuleLoader;
-export declare const loadWebhook: ModuleLoader;
-export declare const loadFunnel: ModuleLoader;
+export declare const loadWebhooks: ModuleLoader;
 export declare const loadHumans: ModuleLoader;
 export declare const loadAccounts: ModuleLoader;
 export declare const loadDaemon: ModuleLoader;
+export declare const loadCp: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -150,6 +142,16 @@ export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;
  * registered command tree so a new command can never drift out of it.
  */
 export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
+/**
+ * Former top-level names that must NOT auto-correct (edit-distance 1) into a
+ * live command. Without this a pruned surface silently misroutes: the typed
+ * name is gone, the spellchecker finds a neighbour, and the CLI runs something
+ * 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).
+ */
+export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 /** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
 export declare function isKnownTopLevelCommand(name: string): boolean;
 /**

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

@@ -39,21 +39,19 @@ export const loadCli = async () => (await import('../../commands/cli.js')).regis
 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 loadWorktree = async () => (await import('../../commands/worktree.js')).registerWorktreeCommands;
 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 loadExport = async () => (await import('../../commands/export.js')).registerExportCommand;
 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 loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
-export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
+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;
@@ -67,12 +65,9 @@ export const loadProfiles = async () => (await import('../../commands/profiles.j
 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 loadWallet = async () => (await import('../../commands/wallet.js')).registerWalletCommands;
-export const loadHelper = async () => (await import('../../commands/helper.js')).registerHelperCommand;
 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 loadLock = async () => (await import('../../commands/lock.js')).registerLockCommand;
 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;
@@ -91,32 +86,31 @@ export const loadTmux = async () => (await import('../../commands/tmux.js')).reg
 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 loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
-export const loadLease = async () => (await import('../../commands/lease.js')).registerLeaseCommand;
 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 loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
-export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
 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;
-export const loadShare = async () => (await import('../../commands/share.js')).registerShareCommands;
+// 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 loadWebhook = async () => (await import('../../commands/webhook.js')).registerWebhookCommand;
-export const loadFunnel = async () => (await import('../../commands/funnel.js')).registerFunnelCommand;
+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
@@ -166,7 +160,6 @@ export const COMMAND_LOADERS = {
     subagents: [loadSubagents],
     plugins: [loadPlugins],
     workflows: [loadWorkflows],
-    worktree: [loadWorktree],
     add: [loadVersions],
     use: [loadVersions],
     list: [loadVersions],
@@ -176,24 +169,18 @@ export const COMMAND_LOADERS = {
     update: [loadUpdate],
     prune: [loadVersions, loadPrune],
     import: [loadImport],
-    export: [loadExport],
     registry: [loadPackages],
     search: [loadPackages],
     install: [loadPackages],
-    // packages.ts also registers `publish` at top level (commands/packages.ts:435).
-    // It was missing here, so `agents publish` only worked via the unknown-command
-    // fallback that registers the whole tree — and the --host router could not see
-    // it as a real command at all (RUSH-2022).
-    publish: [loadPackages],
     routines: [loadRoutines],
     monitors: [loadMonitors],
     projects: [loadProjects],
     run: [loadRun],
     resume: [loadResume],
+    open: [loadOpen],
     reconnect: [loadReconnect],
     fork: [loadFork],
-    defaults: [loadDefaults],
-    set: [loadSet],
+    config: [loadConfig],
     models: [loadModels],
     modes: [loadModes],
     trash: [loadTrash],
@@ -202,20 +189,15 @@ export const COMMAND_LOADERS = {
     apply: [loadApply],
     status: [loadStatus],
     snapshot: [loadSnapshot],
-    profile: [loadProfiles],
     profiles: [loadProfiles],
     harness: [loadHarness],
     harnesses: [loadHarness],
     secrets: [loadSecrets],
     login: [loadLogin],
     logout: [loadLogin],
-    whoami: [loadLogin],
-    wallet: [loadWallet],
-    helper: [loadHelper],
     menubar: [loadMenubar],
     beta: [loadBeta],
     sync: [loadSync],
-    lock: [loadLock],
     'refresh-rules': [loadRefreshRules],
     factory: [loadFactory],
     usage: [loadUsage],
@@ -233,8 +215,6 @@ export const COMMAND_LOADERS = {
     watchdog: [loadWatchdog],
     browser: [loadBrowser],
     computer: [loadComputer],
-    hosts: [loadHosts],
-    lease: [loadLease],
     logs: [loadLogs],
     events: [loadEvents],
     ssh: [loadSsh],
@@ -242,8 +222,6 @@ export const COMMAND_LOADERS = {
     // `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],
-    pull: [loadPull],
-    push: [loadPush],
     // `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.
@@ -256,6 +234,7 @@ export const COMMAND_LOADERS = {
     // Observe-umbrella alias of sessions --active (same lazy module).
     roster: [loadSessions],
     teams: [loadTeams],
+    tickets: [loadTickets],
     cloud: [loadCloud],
     message: [loadMessage],
     send: [loadSend],
@@ -267,15 +246,15 @@ export const COMMAND_LOADERS = {
     mailboxes: [loadMailboxes],
     mailbox: [loadMailboxes],
     serve: [loadServe],
-    share: [loadShare],
-    // `unshare` is a top-level convenience alias of `share delete` (see
+    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: [loadShare],
+    unshare: [loadArtifacts],
     audit: [loadAudit],
-    webhook: [loadWebhook],
-    funnel: [loadFunnel],
+    webhooks: [loadWebhooks],
     humans: [loadHumans],
     daemon: [loadDaemon],
+    cp: [loadCp],
 };
 /**
  * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
@@ -309,6 +288,16 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
     ...Object.keys(COMMAND_LOADERS),
     ...INLINE_COMMAND_NAMES,
 ]);
+/**
+ * Former top-level names that must NOT auto-correct (edit-distance 1) into a
+ * live command. Without this a pruned surface silently misroutes: the typed
+ * name is gone, the spellchecker finds a neighbour, and the CLI runs something
+ * 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).
+ */
+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 function isKnownTopLevelCommand(name) {
     return KNOWN_TOP_LEVEL_COMMANDS.has(name);

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

@@ -19,4 +19,14 @@
  * 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`).
+ *
+ * Split out from {@link detectDevBuild} because a caller holding only a version
+ * string — a fleet rollout reading `agents --version` off a remote box — cannot
+ * run signal 2 (it needs that machine's filesystem), and must not re-spell the
+ * stamp prefix.
+ */
+export declare function isDevVersionStamp(version: string): boolean;
 export declare function detectDevBuild(argv1: string, version: string): boolean;

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

@@ -21,8 +21,20 @@ import * as path from 'path';
  * 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`).
+ *
+ * Split out from {@link detectDevBuild} because a caller holding only a version
+ * string — a fleet rollout reading `agents --version` off a remote box — cannot
+ * run signal 2 (it needs that machine's filesystem), and must not re-spell the
+ * stamp prefix.
+ */
+export function isDevVersionStamp(version) {
+    return version.startsWith('0.0.0-dev');
+}
 export function detectDevBuild(argv1, version) {
-    if (version.startsWith('0.0.0-dev'))
+    if (isDevVersionStamp(version))
         return true;
     try {
         const cliPath = fs.realpathSync(argv1 || '');

package/dist/lib/startup/spellcheck.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Top-level command spellcheck (RUSH-2329).
+ *
+ * Candidates are plain strings from KNOWN_TOP_LEVEL_COMMANDS — never the live
+ * commander registry — so an unknown / typo'd invocation does not pay for
+ * registerAllEagerCommands (~250-330ms of dynamic import + module eval).
+ */
+/** Calculate the Levenshtein edit distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Closest top-level command name by Levenshtein distance.
+ * Iterates candidates in first-seen order so ties break the same way as the
+ * historical registerAllEagerCommands registration order (RUSH-2329).
+ */
+export declare function closestTopLevelCommand(unknown: string, candidates: Iterable<string>): {
+    closest: string | null;
+    minDist: number;
+};

package/dist/lib/startup/spellcheck.js

@@ -0,0 +1,45 @@
+/**
+ * Top-level command spellcheck (RUSH-2329).
+ *
+ * Candidates are plain strings from KNOWN_TOP_LEVEL_COMMANDS — never the live
+ * commander registry — so an unknown / typo'd invocation does not pay for
+ * registerAllEagerCommands (~250-330ms of dynamic import + module eval).
+ */
+/** Calculate the Levenshtein edit distance between two strings. */
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array(m + 1)
+        .fill(null)
+        .map(() => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] =
+                a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+/**
+ * Closest top-level command name by Levenshtein distance.
+ * Iterates candidates in first-seen order so ties break the same way as the
+ * historical registerAllEagerCommands registration order (RUSH-2329).
+ */
+export function closestTopLevelCommand(unknown, candidates) {
+    let closest = null;
+    let minDist = Infinity;
+    for (const cmd of candidates) {
+        const dist = levenshtein(unknown, cmd);
+        if (dist < minDist) {
+            minDist = dist;
+            closest = cmd;
+        }
+    }
+    return { closest, minDist };
+}

package/dist/lib/state.d.ts

@@ -29,7 +29,7 @@ export declare function getHumansFilePath(): string;
  * Header prepended to every agents.yaml the CLI writes (central and per-device
  * docs). Carries the yaml-language-server schema hint so editors validate the
  * file against `schema/agents-yaml.schema.json`. Exported so
- * `lib/device-config.ts` writes a sibling device's doc with the same header.
+ * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
 export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
@@ -140,6 +140,8 @@ export declare function getPackagesDir(): string;
 export declare function getRoutinesDir(): string;
 /** Path to named project definitions (~/.agents/projects/). */
 export declare function getProjectsDir(): string;
+/** Path to daemon config directory (~/.agents/daemon/). Holds service toggles. */
+export declare function getDaemonConfigDir(): string;
 /**
  * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
  * one-off triggers for agents/workflows/commands/routines, layered the same way
@@ -164,12 +166,12 @@ export declare function getSystemWebhooksDir(): string;
  * or null when no project `.agents/` is found by walking up from cwd.
  *
  * Project routines participate in `list`/`view` for inspection always. Daemon
- * firing requires an explicit opt-in via `agents routines enable-project`
- * (writes `meta.routines.projects`); after opt-in, `agents routines sync`
- * materialises them into the user layer with `source:` provenance so the
- * daemon (which loads user + system only) can fire them safely. A project's
- * own `agents.yaml` `routines.enable: true` is a documentation signal only —
- * it does not auto-enable firing. See `lib/routines-project.ts`.
+ * firing requires `agents routines enable <name>`, which materialises the
+ * routine into the user layer with `source:` provenance (so the daemon, which
+ * loads user + system only, can see it) and turns on the device flag in one
+ * step. Enablement lives solely in `meta.deviceRoutines`; a project YAML's own
+ * `enabled:` field never turns firing on, so a cloned repo cannot auto-run.
+ * See `lib/routines-project.ts`.
  */
 export declare function getProjectRoutinesDir(cwd?: string): string | null;
 /**
@@ -182,6 +184,16 @@ export declare function getProjectWebhooksDir(cwd?: string): string | null;
 export declare function getRunsDir(): string;
 /** Path to monitor YAML definitions (~/.agents/monitors/). */
 export declare function getMonitorsDir(): string;
+/**
+ * Path to built-in monitor definitions shipped in the system repo
+ * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
+ * listMonitors()/readMonitor(): a monitor shipped here is available on every
+ * install, and a user monitor of the same name overrides it. A built-in with no
+ * `enabled:` field is opt-in — it stays disabled until the user enables it,
+ * which materializes a user copy (writes never touch this pull-only mirror). The
+ * directory need not exist.
+ */
+export declare function getSystemMonitorsDir(): string;
 /** Path to the durable per-monitor state-diff store + fire history
  * (~/.agents/.history/monitors/). */
 export declare function getMonitorsHistoryDir(): string;
@@ -238,7 +250,7 @@ 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 device auto-launch preference file — which registered devices are eligible/preferred for Factory's auto-host selection. Per-machine, same dir as the registry. */
+/** 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). */
 export declare function getDevicesAutoLaunchPath(): 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;
@@ -266,7 +278,22 @@ export declare function getPerfDir(): string;
 export declare function getPerfDbPath(): string;
 /** Path to the hook-shim NDJSON spool drained into perf.db on open. */
 export declare function getPerfSpoolPath(): string;
-/** Path to per-process runtime state (~/.agents/.cache/state/). */
+/**
+ * Path to per-process runtime state (~/.agents/.cache/state/).
+ *
+ * `AGENTS_STATE_DIR` redirects it in tests — the same test-isolation escape
+ * hatch as `AGENTS_DEVICES_DIR` / `AGENTS_LOGS_DIR`, and resolved at call time
+ * for the same reason (a suite pins it after this module is imported).
+ *
+ * Without it the suite writes into the operator's LIVE state. Concretely: the
+ * device registry and ignore-list already redirect via `AGENTS_DEVICES_DIR`, so
+ * under test both read empty — and any code path reaching
+ * `reconcilePendingSentinels` then computed "every tailnet node is new" and
+ * wrote those sentinels into the real `devices-pending/`, which is exactly what
+ * the menu bar renders. Running the suite on a dev machine surfaced all 20
+ * tailnet nodes as NEW DEVICES, including registered and explicitly ignored
+ * ones, and looked like the operator's ignore list had been lost.
+ */
 export declare function getRuntimeStateDir(): string;
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */
 export declare function getCompanionDir(): string;