@phnx-labs/agents-cli 1.22.57 → 1.22.58

package/dist/lib/doctor-diff.js

@@ -29,9 +29,11 @@ import { discoverPlugins, marketplaceSpecForName } from './plugins/plugins.js';
 import { pluginInstallDir, repairableManifestFields } from './plugins/plugin-marketplace.js';
 import { markdownToToml } from './convert.js';
 import { listCommandsInVersionHome, getVersionCommandsDir, listPluginCommandNames } from './commands.js';
-import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
+import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName, skillSourceExists, readSkillSourceCommandMarker } from './command-skills.js';
+import { trustedSkillRoots } from './staleness/writers/sources.js';
 import { gooseCommandMatches, gooseCommandsDir } from './goose-commands.js';
 import { supports } from './capabilities.js';
+import { isDirectoryDoc } from './resources.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './plugins/skills.js';
 import { listHookEntriesFromDir } from './hooks/install.js';
 import { getResourceInventory } from './resource-inventory.js';
@@ -115,16 +117,46 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
             if (!entry.isFile() || !entry.name.endsWith('.md'))
                 continue;
             const name = entry.name.replace(/\.md$/, '');
+            // Directory docs (README/AGENTS/CLAUDE/GEMINI) live in commands/ but are
+            // documentation, not commands. `discoverCommands` and `resolveResource`
+            // both refuse them, so the sync writer never installs them — mirror that
+            // here or every one false-reports as a missing command no sync can clear.
+            if (isDirectoryDoc('commands', name))
+                continue;
             if (sourceByName.has(name))
                 continue;
             sourceByName.set(name, { layer: base.layer, path: path.join(base.path, entry.name), alias: base.alias });
         }
     }
+    // The trusted skill roots the commands-as-skills writer consults to decide
+    // whether a real skill of the same name already owns a command's target slot.
+    const skillRoots = asSkill ? trustedSkillRoots() : [];
     const rows = [];
     const seen = new Set();
     for (const [name, src] of sourceByName) {
         seen.add(name);
         if (!installed.has(name)) {
+            // Command-as-skill agents (codex >= 0.117, kimi): when a real skill of the
+            // same name exists in the sources, the skill wins the shared
+            // `skills/<name>/` slot and `installCommandSkillToVersion` deliberately
+            // writes no command wrapper (versions.ts keeps the real skill in
+            // skillsToSync and overwrites any wrapper). The command's behavior is
+            // provided by that same-named skill, so it is NOT missing drift — reporting
+            // it so drove an unclearable "N missing" loop (PHNX-3186). Mirror the
+            // writer's skip predicate exactly: a skill source of this name whose
+            // `agents_command` marker is not this command (a real skill, or a different
+            // command).
+            if (asSkill && skillSourceExists(name, skillRoots) && readSkillSourceCommandMarker(name, skillRoots) !== name) {
+                rows.push({
+                    kind: 'commands',
+                    name,
+                    status: 'ok',
+                    source: src.layer,
+                    sourcePath: src.path,
+                    detail: 'provided by same-named skill',
+                });
+                continue;
+            }
             rows.push({ kind: 'commands', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
@@ -180,6 +212,11 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     for (const name of installed) {
         if (seen.has(name))
             continue;
+        // Directory docs are excluded from the source scan above; a leftover copy in
+        // the home is not a command orphan — leave it out of the command diff
+        // entirely rather than flip it to a spurious `extra` row.
+        if (isDirectoryDoc('commands', name))
+            continue;
         if (pluginCommands.has(name))
             continue;
         const extraHome = asSkill
@@ -421,11 +458,15 @@ function diffRules(agent, version, cwd, excludeProject = false) {
     const versionHome = getVersionHomePath(agent, version);
     const configDir = path.join(versionHome, agentConfigDirName(agent));
     const sourcesByName = listRulesNames(cwd, excludeProject);
-    // Files actually present in the version home.
+    // Files actually present in the version home. Include *.md siblings AND the
+    // agent's own instructions filename even when it is not *.md — cursor's rules
+    // file is `.cursorrules`, so an `.md`-only scan never saw it and reported the
+    // AGENTS rule `missing` on every sync, a phantom no reconcile could clear
+    // (PHNX-3186).
     const homeFiles = new Set();
     if (fs.existsSync(configDir)) {
         for (const f of fs.readdirSync(configDir)) {
-            if (!f.endsWith('.md'))
+            if (!f.endsWith('.md') && f !== agentConfig.instructionsFile)
                 continue;
             homeFiles.add(f);
         }
@@ -537,14 +578,38 @@ export function describePluginDrift(central, mirrorDir) {
         parts.push(`${mVer}→${cVer}`);
     if (mManifest && repairableManifestFields(mManifest).length > 0)
         parts.push('invalid manifest');
+    const centralSkills = listPluginSkillDirs(central.root);
     const mirrorSkills = new Set(listPluginSkillDirs(mirrorDir));
-    const missSkills = listPluginSkillDirs(central.root).filter((s) => !mirrorSkills.has(s)).sort();
+    const missSkills = centralSkills.filter((s) => !mirrorSkills.has(s)).sort();
+    const centralCmds = listPluginCommandFiles(central.root);
     const mirrorCmds = new Set(listPluginCommandFiles(mirrorDir));
-    const missCmds = listPluginCommandFiles(central.root).filter((c) => !mirrorCmds.has(c)).sort();
+    const missCmds = centralCmds.filter((c) => !mirrorCmds.has(c)).sort();
     if (missSkills.length)
         parts.push(`missing skill${missSkills.length > 1 ? 's' : ''}: ${missSkills.join(', ')}`);
     if (missCmds.length)
         parts.push(`missing command${missCmds.length > 1 ? 's' : ''}: ${missCmds.join(', ')}`);
+    // Content drift of a skill/command that exists in BOTH — the mirror kept the
+    // dir/file but its bytes went stale (PHNX-2955: a skill edit landed on origin
+    // and was pulled into central, but the per-version marketplace copy was never
+    // refreshed, so agents kept executing the OLD skill text while `plugins list`
+    // and `doctor` reported it `everywhere`/`ok`). Presence alone missed this; a
+    // content compare is what turns a stale mirror into a reportable `diff`.
+    const staleSkills = centralSkills
+        .filter((s) => mirrorSkills.has(s))
+        .filter((s) => !dirsContentMatch(path.join(central.root, 'skills', s), path.join(mirrorDir, 'skills', s)))
+        .sort();
+    const staleCmds = centralCmds
+        .filter((c) => mirrorCmds.has(c))
+        .filter((c) => {
+        const a = readSafe(path.join(central.root, 'commands', `${c}.md`));
+        const b = readSafe(path.join(mirrorDir, 'commands', `${c}.md`));
+        return a == null || b == null || normalize(a) !== normalize(b);
+    })
+        .sort();
+    if (staleSkills.length)
+        parts.push(`stale skill${staleSkills.length > 1 ? 's' : ''}: ${staleSkills.join(', ')}`);
+    if (staleCmds.length)
+        parts.push(`stale command${staleCmds.length > 1 ? 's' : ''}: ${staleCmds.join(', ')}`);
     return parts.length ? parts.join(', ') : null;
 }
 function diffPlugins(agent, version, cwd) {
@@ -622,8 +687,13 @@ export function diffVersionResources(agent, version, options = {}) {
         empty.mcp = diffPresenceOnly('mcp', available.mcp, synced.mcp);
     if (requested.has('permissions'))
         empty.permissions = diffPresenceOnly('permissions', available.permissions, synced.permissions);
-    if (requested.has('subagents'))
-        empty.subagents = diffPresenceOnly('subagents', available.subagents, synced.subagents);
+    // Subagents are version-gated (e.g. kimi >= 0.29.0). A version below the floor
+    // is never written any subagent by the sync writer, so counting the source
+    // ones as "missing" is phantom drift no sync can clear (PHNX-3186). Zero the
+    // available set when unsupported; a stale installed copy still surfaces `extra`.
+    if (requested.has('subagents')) {
+        empty.subagents = diffPresenceOnly('subagents', supports(agent, 'subagents', version).ok ? available.subagents : [], synced.subagents);
+    }
     if (requested.has('plugins'))
         empty.plugins = diffPlugins(agent, version, cwd);
     if (requested.has('promptcuts'))

package/dist/lib/fleet/manifest.d.ts

@@ -33,3 +33,20 @@ export interface ResolveContext {
  * sync scopes, and `login: skip` are still returned (probe/report only).
  */
 export declare function resolveDesired(manifest: FleetManifest, ctx: ResolveContext): DeviceDesired[];
+/**
+ * The message to print when a reconcile resolved zero target devices.
+ *
+ * An explicitly empty roster (`fleet.devices: {}` — the default on a fresh box)
+ * is the ACTIONABLE case: the engine ran fine, there is simply nothing declared
+ * to converge, so name the empty key and how to fill it. A gray "nothing to
+ * apply" there reads like the command is dead — the exact confusion that made
+ * `apply` look like a broken command during the RUSH-2981 surface review
+ * (PHNX-3422). Any OTHER zero-target case (a `devices: all` fleet with no online
+ * peers, or an explicit roster whose every name was unresolved — off-tailnet,
+ * ignored, or a typo, the only names `resolveDesired` drops) already had its
+ * reason surfaced above, so it stays a plain note.
+ */
+export declare function emptyTargetsMessage(manifest: FleetManifest): {
+    style: 'hint' | 'plain';
+    lines: string[];
+};

package/dist/lib/fleet/manifest.js

@@ -169,3 +169,29 @@ export function resolveDesired(manifest, ctx) {
     }
     return out;
 }
+/**
+ * The message to print when a reconcile resolved zero target devices.
+ *
+ * An explicitly empty roster (`fleet.devices: {}` — the default on a fresh box)
+ * is the ACTIONABLE case: the engine ran fine, there is simply nothing declared
+ * to converge, so name the empty key and how to fill it. A gray "nothing to
+ * apply" there reads like the command is dead — the exact confusion that made
+ * `apply` look like a broken command during the RUSH-2981 surface review
+ * (PHNX-3422). Any OTHER zero-target case (a `devices: all` fleet with no online
+ * peers, or an explicit roster whose every name was unresolved — off-tailnet,
+ * ignored, or a typo, the only names `resolveDesired` drops) already had its
+ * reason surfaced above, so it stays a plain note.
+ */
+export function emptyTargetsMessage(manifest) {
+    const rosterEmpty = manifest.devices !== 'all' && Object.keys(manifest.devices).length === 0;
+    if (rosterEmpty) {
+        return {
+            style: 'hint',
+            lines: [
+                'fleet.devices is empty — nothing to converge.',
+                'Declare a roster in agents.yaml: `fleet: { devices: all }` for every online box, or name them (`fleet: { devices: { <name>: {} } }`), then re-run.',
+            ],
+        };
+    }
+    return { style: 'plain', lines: ['No target devices — nothing to apply.'] };
+}

package/dist/lib/hooks/install.d.ts

@@ -334,21 +334,37 @@ export declare function parseHookManifest(opts?: {
 }): Record<string, ManifestHook>;
 export declare function selectHookManifest(manifest: Record<string, ManifestHook>, selected: string[]): Record<string, ManifestHook>;
 /**
- * Hook script files present on disk that no manifest entry declares — "dead"
- * hooks. The registrar only wires manifest-declared hooks into an agent's
- * native config (settings.json / config.toml), matching the installed file to a
- * manifest entry by script basename. So a file whose basename matches no
- * manifest `script:` is never registered: it occupies the hooks dir and shows
- * up in listings, but no lifecycle event ever fires it.
+ * Hook files present in a version home but absent from every configured
+ * SOURCE — genuine orphans left behind by a removed/renamed source hook.
+ *
+ * The definition is deliberately source-based, not manifest-based (PHNX-2693).
+ * Sync copies EVERY source hook file into a version home — registered hooks AND
+ * the helper / test / benchmark scripts that sit alongside them — but only the
+ * registered ones appear in `parseHookManifest`. Diffing installed names against
+ * the manifest therefore flagged every source-present-but-unregistered file
+ * (e.g. `permission-handler`, `verify-work-state`, `*_test`, `benchmark_*`) as
+ * an orphan, so `agents prune cleanup` offered to trash ~1000 in-use files. An
+ * installed hook is only truly orphaned when NO configured source still carries
+ * a file of that name — which is exactly what the `prune`/`doctor` help already
+ * promised ("present in a version home but missing from every configured
+ * source").
  *
  * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
- * installed hook names and the manifest's script paths.
+ * installed hook names and the source hook script paths.
+ */
+export declare function unmanagedHookNames(installedHookNames: string[], sourceHookScripts: string[]): string[];
+/**
+ * Every hook script path across the resolved SOURCE roots — user
+ * (`~/.agents/hooks`), system (`~/.agents/.system/hooks`), and each enabled
+ * extra repo's `hooks/` — grouped the same way sync materializes them
+ * ({@link listHookEntriesFromDir}, which also descends one-level event-group
+ * dirs). This is the set an installed hook must be absent from to count as an
+ * orphan.
  */
-export declare function unmanagedHookNames(installedHookNames: string[], manifestScripts: string[]): string[];
+export declare function listResolvedSourceHookScripts(): string[];
 /**
- * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
- * Reads the merged hook manifest silently — a diagnostic must not emit the
- * shadow/override warnings the registrar path prints.
+ * The orphan hooks (see {@link unmanagedHookNames}) sitting in one version home:
+ * installed hook files whose name matches no file in any configured source root.
  */
 export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version: string): string[];
 /**

package/dist/lib/hooks/install.js

@@ -1594,33 +1594,58 @@ export function selectHookManifest(manifest, selected) {
     return Object.fromEntries(Object.entries(manifest).filter(([name, hook]) => selectedHooks.has(name) || selectedHooks.has(path.basename(hook.script))));
 }
 /**
- * Hook script files present on disk that no manifest entry declares — "dead"
- * hooks. The registrar only wires manifest-declared hooks into an agent's
- * native config (settings.json / config.toml), matching the installed file to a
- * manifest entry by script basename. So a file whose basename matches no
- * manifest `script:` is never registered: it occupies the hooks dir and shows
- * up in listings, but no lifecycle event ever fires it.
+ * Hook files present in a version home but absent from every configured
+ * SOURCE — genuine orphans left behind by a removed/renamed source hook.
+ *
+ * The definition is deliberately source-based, not manifest-based (PHNX-2693).
+ * Sync copies EVERY source hook file into a version home — registered hooks AND
+ * the helper / test / benchmark scripts that sit alongside them — but only the
+ * registered ones appear in `parseHookManifest`. Diffing installed names against
+ * the manifest therefore flagged every source-present-but-unregistered file
+ * (e.g. `permission-handler`, `verify-work-state`, `*_test`, `benchmark_*`) as
+ * an orphan, so `agents prune cleanup` offered to trash ~1000 in-use files. An
+ * installed hook is only truly orphaned when NO configured source still carries
+ * a file of that name — which is exactly what the `prune`/`doctor` help already
+ * promised ("present in a version home but missing from every configured
+ * source").
  *
  * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
- * installed hook names and the manifest's script paths.
+ * installed hook names and the source hook script paths.
+ */
+export function unmanagedHookNames(installedHookNames, sourceHookScripts) {
+    const inSource = new Set(sourceHookScripts.map((s) => path.basename(s).replace(/\.[^.]+$/, '')));
+    return installedHookNames.filter((name) => !inSource.has(name)).sort();
+}
+/**
+ * Every hook script path across the resolved SOURCE roots — user
+ * (`~/.agents/hooks`), system (`~/.agents/.system/hooks`), and each enabled
+ * extra repo's `hooks/` — grouped the same way sync materializes them
+ * ({@link listHookEntriesFromDir}, which also descends one-level event-group
+ * dirs). This is the set an installed hook must be absent from to count as an
+ * orphan.
  */
-export function unmanagedHookNames(installedHookNames, manifestScripts) {
-    const managed = new Set(manifestScripts.map((s) => path.basename(s).replace(/\.[^.]+$/, '')));
-    return installedHookNames.filter((name) => !managed.has(name)).sort();
+export function listResolvedSourceHookScripts() {
+    const roots = [
+        getUserHooksDir(),
+        getSystemHooksDir(),
+        ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'hooks')),
+    ];
+    const scripts = [];
+    for (const root of roots) {
+        for (const entry of listHookEntriesFromDir(root))
+            scripts.push(entry.scriptPath);
+    }
+    return scripts;
 }
 /**
- * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
- * Reads the merged hook manifest silently — a diagnostic must not emit the
- * shadow/override warnings the registrar path prints.
+ * The orphan hooks (see {@link unmanagedHookNames}) sitting in one version home:
+ * installed hook files whose name matches no file in any configured source root.
  */
 export function listUnmanagedHooksInVersionHome(agent, version) {
     if (!AGENTS[agent].supportsHooks)
         return [];
-    const scripts = Object.values(parseHookManifest({ warn: false }))
-        .map((h) => h.script)
-        .filter((s) => typeof s === 'string');
     const installed = listHooksInVersionHome(agent, version).map((e) => e.name);
-    return unmanagedHookNames(installed, scripts);
+    return unmanagedHookNames(installed, listResolvedSourceHookScripts());
 }
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.