@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/devices/stats-cache.d.ts

@@ -8,12 +8,8 @@ import type { DeviceProfile } from './registry.js';
  * rewrites the cache, unreachable boxes included).
  */
 export declare const STATS_STALE_MS: number;
-/** Static hardware totals are valid for seven days. */
-export declare const SPECS_STALE_MS: number;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
-/** True when cached core, RAM-total, and disk-total facts remain current. */
-export declare function isFreshDeviceSpecs(stats: DeviceStats, now?: number): boolean;
 /**
  * Carry a device's last successfully-probed hardware facts onto a row whose
  * probe just came back unreachable (RUSH-3096).
@@ -54,8 +50,6 @@ export interface FleetStatsResult {
 export interface LoadFleetStatsOptions {
     /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
     forceRefresh?: boolean;
-    /** Read only static hardware facts, whose cache lifetime is seven days. */
-    specsOnly?: boolean;
     /** Device name of THIS machine — always probed locally (no ssh), never cached-served. */
     selfName?: string;
     /** Injectable probes + cache IO for tests (default to the real ssh/local/disk ones). */

package/dist/lib/devices/stats-cache.js

@@ -37,17 +37,10 @@ const CACHE_FILE = '.fleet-stats.json';
  * rewrites the cache, unreachable boxes included).
  */
 export const STATS_STALE_MS = 3 * 60_000;
-/** Static hardware totals are valid for seven days. */
-export const SPECS_STALE_MS = 7 * 24 * 60 * 60_000;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export function isFreshDeviceStats(stats, now = Date.now()) {
     return now - stats.fetchedAt <= STATS_STALE_MS;
 }
-/** True when cached core, RAM-total, and disk-total facts remain current. */
-export function isFreshDeviceSpecs(stats, now = Date.now()) {
-    const fetchedAt = stats.specsFetchedAt ?? stats.fetchedAt;
-    return now - fetchedAt <= SPECS_STALE_MS;
-}
 /**
  * Carry a device's last successfully-probed hardware facts onto a row whose
  * probe just came back unreachable (RUSH-3096).
@@ -141,13 +134,13 @@ export async function loadFleetStats(devices, opts = {}) {
     const toProbe = [];
     let servedFromCache = false;
     for (const d of devices) {
-        if (d.name === self && !opts.specsOnly) {
+        if (d.name === self) {
             // This machine is always probed locally — cheap, no ssh, always live.
             toProbe.push(d);
             continue;
         }
         const cached = opts.forceRefresh ? undefined : cache[d.name];
-        const cacheFresh = cached && (opts.specsOnly ? isFreshDeviceSpecs(cached, now) : isFreshDeviceStats(cached, now));
+        const cacheFresh = cached && isFreshDeviceStats(cached, now);
         if (cached && cacheFresh) {
             stats.set(d.name, cached);
             servedFromCache = true;

package/dist/lib/doctor-diff.d.ts

@@ -82,6 +82,20 @@ export interface VersionResourceReport {
      *  probe), not the pure diff — undefined when uncomputed. */
     sourceBehind?: SourceLayerBehind[];
 }
+/**
+ * True when `filePath` is a git symlink that was CHECKED OUT AS A PLAIN TEXT
+ * FILE — the shape git produces on a client without symlink support (Windows
+ * without Developer Mode, `core.symlinks=false`). Such a file holds exactly the
+ * link target (a relative path, no trailing newline) instead of the pointed-to
+ * content. `lstat().isSymbolicLink()` is FALSE for it, so callers that only
+ * skip real symlinks (e.g. the rules/permissions alias files CLAUDE.md /
+ * GEMINI.md, which are symlinks to AGENTS.md in the repo) wrongly treat it as
+ * an independent resource that no sync can ever reconcile (PHNX-3187). The
+ * signal is unambiguous: a whole file with no newline whose entire content
+ * resolves to an existing sibling path. Real markdown rule files always contain
+ * newlines, so this never false-positives on genuine content.
+ */
+export declare function isCheckedOutSymlink(filePath: string): boolean;
 /**
  * Describe how a version's marketplace MIRROR of a plugin diverges from its
  * central source — the detail presence-only checks miss. Surfaces a stale mirror

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';
@@ -61,6 +63,42 @@ function readSafe(file) {
 function fileExists(p) {
     return !!p && fs.existsSync(p) && !fs.lstatSync(p).isSymbolicLink();
 }
+/**
+ * True when `filePath` is a git symlink that was CHECKED OUT AS A PLAIN TEXT
+ * FILE — the shape git produces on a client without symlink support (Windows
+ * without Developer Mode, `core.symlinks=false`). Such a file holds exactly the
+ * link target (a relative path, no trailing newline) instead of the pointed-to
+ * content. `lstat().isSymbolicLink()` is FALSE for it, so callers that only
+ * skip real symlinks (e.g. the rules/permissions alias files CLAUDE.md /
+ * GEMINI.md, which are symlinks to AGENTS.md in the repo) wrongly treat it as
+ * an independent resource that no sync can ever reconcile (PHNX-3187). The
+ * signal is unambiguous: a whole file with no newline whose entire content
+ * resolves to an existing sibling path. Real markdown rule files always contain
+ * newlines, so this never false-positives on genuine content.
+ */
+export function isCheckedOutSymlink(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    // A git symlink blob is the bare target with no newline; any newline means
+    // this is real file content, not a link.
+    if (content.length === 0 || content.length > 255 || /[\r\n]/.test(content))
+        return false;
+    const target = content.trim();
+    if (!target)
+        return false;
+    const resolved = path.resolve(path.dirname(filePath), target);
+    try {
+        return fs.statSync(resolved).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function findFirst(candidates) {
     for (const c of candidates) {
         if (fileExists(c.path) || (fs.existsSync(c.path) && fs.lstatSync(c.path).isDirectory())) {
@@ -115,16 +153,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 +248,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
@@ -382,8 +455,13 @@ function listRulesNames(cwd, excludeProject = false) {
         for (const file of entries) {
             if (!file.endsWith('.md') || file === RULES_DOC_FILENAME)
                 continue;
-            const stat = fs.lstatSync(path.join(base.path, file));
-            if (stat.isSymbolicLink())
+            const filePath = path.join(base.path, file);
+            const stat = fs.lstatSync(filePath);
+            // Skip the CLAUDE.md / GEMINI.md alias symlinks — both when they are real
+            // symlinks (posix) and when git checked them out as plain text files
+            // (Windows), so they are never mistaken for independent rule sources the
+            // writer can't produce (PHNX-3187).
+            if (stat.isSymbolicLink() || isCheckedOutSymlink(filePath))
                 continue;
             const name = file.replace(/\.md$/, '');
             if (out.has(name))
@@ -421,11 +499,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 +619,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 +728,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/git.d.ts

@@ -161,6 +161,21 @@ export declare function canonicalGitRemote(url: string): string;
  * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
  */
 export declare function isSystemRepoRemote(remote: string | null | undefined): boolean;
+/**
+ * True when `remote` is the origin the system repo is EXPECTED to track on this
+ * machine, honouring an operator's `AGENTS_SYSTEM_REPO` override.
+ *
+ * The system repo ships hooks that register as shell `command` strings run on
+ * every tool event, and its checkout auto-fast-forwards from origin — so a
+ * fast-forward from an origin the operator never chose is remote code execution
+ * on the next command that loads a system resource (PHNX-2957). This is the
+ * pinning predicate every auto-pull of the system repo gates on: pull only when
+ * origin is the canonical {@link isSystemRepoRemote} repo, or the exact
+ * `AGENTS_SYSTEM_REPO` the operator pointed at instead. Anything else — a
+ * repointed origin, a fork, an unset-then-swapped remote — is refused, not
+ * pulled. Pure string check; no git spawn.
+ */
+export declare function isExpectedSystemRepoRemote(remote: string | null | undefined): boolean;
 /** True when two git remote URLs point at the same repo across transport forms. */
 export declare function sameGitRemote(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
@@ -500,6 +515,29 @@ export declare function tryAutoPull(dir: string): Promise<{
     pulled: boolean;
     error?: string;
 }>;
+/** Result of {@link tryAutoPullSystemRepo}. `refused` is set only when the pull
+ *  was blocked because origin is not the expected system remote. */
+export interface SystemRepoPullResult {
+    pulled: boolean;
+    error?: string;
+    /** True when origin is present but is NOT the expected system remote; no
+     *  fast-forward was attempted. `actualRemote` names what was found. */
+    refused?: boolean;
+    /** The origin fetch URL that was examined (present when a remote exists). */
+    actualRemote?: string;
+}
+/**
+ * Auto-pull the system repo ONLY after verifying its origin is the expected
+ * system remote (PHNX-2957). The system repo ships hooks that run as shell on
+ * tool events, so fast-forwarding it from an unexpected/repointed origin is
+ * remote code execution. An origin that fails {@link isExpectedSystemRepoRemote}
+ * is REFUSED loud (`refused: true`), never pulled — the canonical system repo
+ * (or an operator's `AGENTS_SYSTEM_REPO`) still fast-forwards exactly as before.
+ *
+ * A system dir with no origin at all is a plain no-op (`pulled: false`), not a
+ * refusal — there is nothing to pull from and nothing to distrust.
+ */
+export declare function tryAutoPullSystemRepo(dir: string): Promise<SystemRepoPullResult>;
 /**
  * How many commits `dir`'s checked-out branch is behind its upstream, read from
  * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the

package/dist/lib/git.js

@@ -537,6 +537,33 @@ export function isSystemRepoRemote(remote) {
     const c = canonicalGitRemote(remote);
     return c === canonicalGitRemote(`https://github.com/${systemRepoSlug(DEFAULT_SYSTEM_REPO)}`);
 }
+/**
+ * True when `remote` is the origin the system repo is EXPECTED to track on this
+ * machine, honouring an operator's `AGENTS_SYSTEM_REPO` override.
+ *
+ * The system repo ships hooks that register as shell `command` strings run on
+ * every tool event, and its checkout auto-fast-forwards from origin — so a
+ * fast-forward from an origin the operator never chose is remote code execution
+ * on the next command that loads a system resource (PHNX-2957). This is the
+ * pinning predicate every auto-pull of the system repo gates on: pull only when
+ * origin is the canonical {@link isSystemRepoRemote} repo, or the exact
+ * `AGENTS_SYSTEM_REPO` the operator pointed at instead. Anything else — a
+ * repointed origin, a fork, an unset-then-swapped remote — is refused, not
+ * pulled. Pure string check; no git spawn.
+ */
+export function isExpectedSystemRepoRemote(remote) {
+    if (!remote)
+        return false;
+    const override = process.env.AGENTS_SYSTEM_REPO?.trim();
+    if (override) {
+        // The override is a source spec (`gh:owner/repo`) or a full clone URL. Match
+        // the GitHub-slug form the setup path clones, and the raw spec itself, so a
+        // non-GitHub override URL still verifies.
+        return (sameGitRemote(remote, `https://github.com/${systemRepoSlug(override)}`) ||
+            sameGitRemote(remote, override.replace(/^gh:/, '')));
+    }
+    return isSystemRepoRemote(remote);
+}
 /** True when two git remote URLs point at the same repo across transport forms. */
 export function sameGitRemote(a, b) {
     if (!a || !b)
@@ -1665,6 +1692,37 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
+/**
+ * Auto-pull the system repo ONLY after verifying its origin is the expected
+ * system remote (PHNX-2957). The system repo ships hooks that run as shell on
+ * tool events, so fast-forwarding it from an unexpected/repointed origin is
+ * remote code execution. An origin that fails {@link isExpectedSystemRepoRemote}
+ * is REFUSED loud (`refused: true`), never pulled — the canonical system repo
+ * (or an operator's `AGENTS_SYSTEM_REPO`) still fast-forwards exactly as before.
+ *
+ * A system dir with no origin at all is a plain no-op (`pulled: false`), not a
+ * refusal — there is nothing to pull from and nothing to distrust.
+ */
+export async function tryAutoPullSystemRepo(dir) {
+    if (!isGitRepo(dir))
+        return { pulled: false };
+    let remote;
+    try {
+        const git = simpleGit(dir);
+        const remotes = await git.getRemotes(true);
+        remote = remotes.find(r => r.name === 'origin')?.refs?.fetch;
+    }
+    catch {
+        return { pulled: false };
+    }
+    if (!remote)
+        return { pulled: false };
+    if (!isExpectedSystemRepoRemote(remote)) {
+        return { pulled: false, refused: true, actualRemote: remote };
+    }
+    const res = await tryAutoPull(dir);
+    return { ...res, actualRemote: remote };
+}
 /**
  * How many commits `dir`'s checked-out branch is behind its upstream, read from
  * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the

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.

package/dist/lib/hosts/ready.d.ts

@@ -100,6 +100,14 @@ export interface ViewAgentAccountEligibility {
  * --json`. A picker may route to a signed-out version because launching it is
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
+ *
+ * The sign-in gate reads the per-version `launchable` field — the strict
+ * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
+ * by the SAME launchability the local candidate uses (`collectRunCandidates` →
+ * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
+ * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
+ * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
+ * pre-fix behavior, so a rolling fleet does not regress.
  */
 export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;

package/dist/lib/hosts/ready.js

@@ -213,6 +213,14 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
  * --json`. A picker may route to a signed-out version because launching it is
  * the login flow, but it must not route to a device whose every signed-in
  * account is throttled.
+ *
+ * The sign-in gate reads the per-version `launchable` field — the strict
+ * per-version launch truth (`isLaunchableSignedIn`) — so a remote box is judged
+ * by the SAME launchability the local candidate uses (`collectRunCandidates` →
+ * `isLaunchableSignedIn`), not the display `signedIn` that inherits the
+ * active/global HOME login and passes a box that dies at spawn (PHNX-3466). An
+ * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
+ * pre-fix behavior, so a rolling fleet does not regress.
  */
 export function viewAgentAccountEligibility(view, agent) {
     try {
@@ -223,12 +231,15 @@ export function viewAgentAccountEligibility(view, agent) {
         const verdicts = (row.versions ?? []).flatMap((version) => {
             if (typeof version.signedIn !== 'boolean')
                 return [];
+            // Prefer the strict per-version launch signal; fall back to the display
+            // `signedIn` for an older remote CLI that does not emit `launchable`.
+            const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
             const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
             const authBlocked = version.authVerdict !== null
                 && version.authVerdict !== undefined
                 && isDeadVerdict(version.authVerdict);
-            const ready = version.signedIn && !authBlocked && !throttled;
-            return [{ ready, pickerEligible: ready || !version.signedIn || authBlocked }];
+            const ready = launchable && !authBlocked && !throttled;
+            return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
         if (verdicts.length === 0)
             return { signedIn: undefined, pickerEligible: undefined };