@phnx-labs/agents-cli 1.22.56 → 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/exec.d.ts

@@ -502,49 +502,10 @@ export type TmuxWrapDecision =
     kind: 'undurable';
 };
 /**
- * Decide whether to run an interactive agent INSIDE a detached tmux session on
- * the shared socket (then attach the current TTY) instead of a bare spawn.
- *
- * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
- * unique `%pane` handle so `agents sessions --active` can tell co-located
- * agents apart and `agents focus` re-attaches without forking, plus scrollback
- * and mouse at the operator's keyboard. Off means OFF, for local and remote
- * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
- * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
- * when one exists and resumes the harness session from disk when it does not.
- * The RUSH-3125 forced remote wrap conflated durability with that preference
- * and surprised every operator who had explicitly left tmux off.
- *
- * One case still wraps regardless: a followed remote run whose launcher has
- * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
- * the detached pane is the run's only interface, not an ergonomics choice.
- *
- * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
- * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
- * escape hatch that silently stopped applying over `--device` would be worse
- * than the bare run the user asked for.
- *
- * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
+ * Tmux is opt-in except when a TTY-less remote launch would otherwise have no
+ * interface. Explicit per-run opt-outs always win.
  */
 export declare function resolveTmuxWrap(ctx: TmuxWrapContext): TmuxWrapDecision;
-/**
- * Build the shell command that runs an agent inside a tmux pane with the exact
- * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
- * K=V … <agent> <args…>` so:
- *   - `env` materializes the full agent env INTO the pane, independent of the
- *     (possibly stale, shared) tmux server environment — additive, so tmux's own
- *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
- *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
- *     `#{pane_pid}`, clean signal delivery on detach/kill).
- * Keys are filtered to valid identifiers so exported shell functions
- * (`BASH_FUNC_*%%`) can't make `env` choke.
- *
- * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
- * the KEY names. The env map here carries resolved secrets bundles (options.env),
- * so the real string would embed secret VALUES — which get persisted verbatim
- * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
- * real values; the stored/informational copy uses the redacted form (RUSH-1758).
- */
 /**
  * True when `options.sessionId` is an id the HARNESS actually received, and so a
  * real, resumable handle — rather than one the launcher generated for its own
@@ -562,6 +523,10 @@ export declare function resolveTmuxWrap(ctx: TmuxWrapContext): TmuxWrapDecision;
  * or this reports a genuine id as fabricated.
  */
 export declare function isHarnessKnownSessionId(agent: AgentId, sessionId: string | undefined, resume: boolean | undefined): boolean;
+/**
+ * Build the pane command without inheriting stale tmux-server env. Redacted
+ * copies keep secret values out of persisted SessionMeta commands.
+ */
 export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
     redactEnvValues?: boolean;
     envFile?: string;

package/dist/lib/exec.js

@@ -1241,29 +1241,8 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
     return code === 0 && stdout.trim() === '0';
 }
 /**
- * Decide whether to run an interactive agent INSIDE a detached tmux session on
- * the shared socket (then attach the current TTY) instead of a bare spawn.
- *
- * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
- * unique `%pane` handle so `agents sessions --active` can tell co-located
- * agents apart and `agents focus` re-attaches without forking, plus scrollback
- * and mouse at the operator's keyboard. Off means OFF, for local and remote
- * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
- * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
- * when one exists and resumes the harness session from disk when it does not.
- * The RUSH-3125 forced remote wrap conflated durability with that preference
- * and surprised every operator who had explicitly left tmux off.
- *
- * One case still wraps regardless: a followed remote run whose launcher has
- * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
- * the detached pane is the run's only interface, not an ergonomics choice.
- *
- * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
- * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
- * escape hatch that silently stopped applying over `--device` would be worse
- * than the bare run the user asked for.
- *
- * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
+ * Tmux is opt-in except when a TTY-less remote launch would otherwise have no
+ * interface. Explicit per-run opt-outs always win.
  */
 export function resolveTmuxWrap(ctx) {
     // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
@@ -1297,24 +1276,6 @@ export function resolveTmuxWrap(ctx) {
         return ctx.remoteDispatch ? { kind: 'undurable' } : { kind: 'bare' };
     return { kind: 'wrap' };
 }
-/**
- * Build the shell command that runs an agent inside a tmux pane with the exact
- * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
- * K=V … <agent> <args…>` so:
- *   - `env` materializes the full agent env INTO the pane, independent of the
- *     (possibly stale, shared) tmux server environment — additive, so tmux's own
- *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
- *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
- *     `#{pane_pid}`, clean signal delivery on detach/kill).
- * Keys are filtered to valid identifiers so exported shell functions
- * (`BASH_FUNC_*%%`) can't make `env` choke.
- *
- * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
- * the KEY names. The env map here carries resolved secrets bundles (options.env),
- * so the real string would embed secret VALUES — which get persisted verbatim
- * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
- * real values; the stored/informational copy uses the redacted form (RUSH-1758).
- */
 /**
  * True when `options.sessionId` is an id the HARNESS actually received, and so a
  * real, resumable handle — rather than one the launcher generated for its own
@@ -1338,6 +1299,10 @@ export function isHarnessKnownSessionId(agent, sessionId, resume) {
         return true;
     return agent === 'claude';
 }
+/**
+ * Build the pane command without inheriting stale tmux-server env. Redacted
+ * copies keep secret values out of persisted SessionMeta commands.
+ */
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     // envFile: source the values instead of inlining them, so no VALUE ever lands

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

@@ -152,6 +152,15 @@ export declare function getCurrentBranch(repoPath: string): Promise<string>;
  * repo" as a requested source before adopting it.
  */
 export declare function canonicalGitRemote(url: string): string;
+/**
+ * True when a git remote URL (any transport form: ssh, https, scp-style) points
+ * at the system DotAgents repo — {@link DEFAULT_SYSTEM_REPO}'s current slug OR
+ * its `phnx-labs/.agents` rename target (PHNX-3394), which
+ * {@link canonicalGitRemote} folds onto it via {@link RENAMED_REMOTE_ALIASES}.
+ * Pure string check with no git spawn, so it is unit-testable off a live
+ * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
+ */
+export declare function isSystemRepoRemote(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;
 /**
@@ -354,7 +363,10 @@ export declare function adoptUserRepoIfNeeded(dir: string, opts?: {
     needsUrl?: boolean;
 }) | null>;
 /**
- * Check if the repo's origin points to the system repo.
+ * Check if the repo's origin points to the system repo — `phnx-labs/.agents-system`
+ * or its GitHub rename target `phnx-labs/.agents` (PHNX-3394), across any
+ * transport form. Reads the dir's origin and delegates the match to the pure
+ * {@link isSystemRepoRemote}.
  */
 export declare function isSystemRepoOrigin(dir: string): Promise<boolean>;
 /**

package/dist/lib/git.js

@@ -498,7 +498,7 @@ export async function getCurrentBranch(repoPath) {
  * repo" as a requested source before adopting it.
  */
 export function canonicalGitRemote(url) {
-    return url
+    const canonical = url
         .trim()
         .replace(/\/+$/, '') // trailing slashes first, so a trailing-slash-after-.git still strips
         .replace(/\.git$/i, '')
@@ -506,6 +506,36 @@ export function canonicalGitRemote(url) {
         .replace(/^[^@/]+@/, '') // strip user@ (git@, ssh user)
         .replace(':', '/') // scp-style host:owner/repo → host/owner/repo (first colon only)
         .toLowerCase();
+    // Fold a renamed repo's old name onto its new one so both compare equal
+    // everywhere (see RENAMED_REMOTE_ALIASES).
+    return RENAMED_REMOTE_ALIASES[canonical] ?? canonical;
+}
+/**
+ * Git remotes that denote the SAME repository under an old and a new name,
+ * keyed by canonical `host/owner/repo`. `phnx-labs/.agents-system` was renamed
+ * to `phnx-labs/.agents` on GitHub (PHNX-3394); {@link DEFAULT_SYSTEM_REPO}
+ * still points at the pre-rename slug (GitHub's own redirect makes that
+ * resolve fine), so folding the new name onto it here means both compare equal
+ * everywhere remotes are compared: {@link sameGitRemote} (repo adoption),
+ * {@link isSystemRepoRemote} (the system-origin check), and the
+ * DotAgents-layer classifier in state.ts.
+ */
+const RENAMED_REMOTE_ALIASES = {
+    'github.com/phnx-labs/.agents': 'github.com/phnx-labs/.agents-system',
+};
+/**
+ * True when a git remote URL (any transport form: ssh, https, scp-style) points
+ * at the system DotAgents repo — {@link DEFAULT_SYSTEM_REPO}'s current slug OR
+ * its `phnx-labs/.agents` rename target (PHNX-3394), which
+ * {@link canonicalGitRemote} folds onto it via {@link RENAMED_REMOTE_ALIASES}.
+ * Pure string check with no git spawn, so it is unit-testable off a live
+ * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
+ */
+export function isSystemRepoRemote(remote) {
+    if (!remote)
+        return false;
+    const c = canonicalGitRemote(remote);
+    return c === canonicalGitRemote(`https://github.com/${systemRepoSlug(DEFAULT_SYSTEM_REPO)}`);
 }
 /** True when two git remote URLs point at the same repo across transport forms. */
 export function sameGitRemote(a, b) {
@@ -1062,18 +1092,17 @@ export async function adoptUserRepoIfNeeded(dir, opts = {}) {
     return adoptRepoInPlace(dir, url);
 }
 /**
- * Check if the repo's origin points to the system repo.
+ * Check if the repo's origin points to the system repo — `phnx-labs/.agents-system`
+ * or its GitHub rename target `phnx-labs/.agents` (PHNX-3394), across any
+ * transport form. Reads the dir's origin and delegates the match to the pure
+ * {@link isSystemRepoRemote}.
  */
 export async function isSystemRepoOrigin(dir) {
     try {
         const git = simpleGit(dir);
         const remotes = await git.getRemotes(true);
         const origin = remotes.find(r => r.name === 'origin');
-        if (!origin?.refs?.fetch)
-            return false;
-        const url = origin.refs.fetch.toLowerCase();
-        const currentSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO).toLowerCase();
-        return url.includes(currentSlug);
+        return isSystemRepoRemote(origin?.refs?.fetch);
     }
     catch {
         /* not a git repo or no remotes */

package/dist/lib/harness/adapter.d.ts

@@ -44,13 +44,13 @@ export interface ExecConfigEnvCtx {
     /** resolveInteractive(options) — computed once by the caller. */
     interactive: boolean;
     /**
-     * The role marked on THIS machine (worker | personal | undefined), resolved
-     * once by the caller from selfConfiguredDeviceRole(). A `personal` device is
-     * the user's own interactive box: it holds a real per-version login and the
-     * credential decision MUST defer to it for EVERY run — interactive OR headless
-     * — never the worker-only setup-token (RUSH-2395). Injected as a plain value
-     * (not imported) to keep the adapter import-leaf. Absent/undefined is treated
-     * as non-personal (worker-equivalent).
+     * The role marked on THIS machine (worker | personal | desktop | undefined),
+     * resolved once by the caller from selfConfiguredDeviceRole(). A headed device
+     * (`personal` or `desktop` — see isHeadedDeviceRole) holds a real per-version
+     * login and the credential decision MUST defer to it for EVERY run — interactive
+     * OR headless — never the worker-only setup-token (RUSH-2395). Injected as a
+     * plain value (not imported) to keep the adapter import-leaf. Absent/undefined
+     * is treated as non-headed (worker-equivalent).
      */
     deviceRole?: ConfiguredDeviceRole;
     /**

package/dist/lib/harness/adapters/claude.js

@@ -1,5 +1,6 @@
 import * as path from 'path';
 import { stripForeignConfigDir } from '../adapter.js';
+import { isHeadedDeviceRole } from '../../device-config.js';
 export const claudeAdapter = {
     id: 'claude',
     applyExecConfigEnv(result, ctx) {
@@ -47,8 +48,8 @@ export const claudeAdapter = {
         // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
         // Claude Code, which reads its own ACL-trusted login item without a prompt and
         // asks a present human to log in only if the login is missing.
-        const personalDevice = ctx.deviceRole === 'personal';
-        if (ctx.interactive || personalDevice) {
+        const headedDevice = isHeadedDeviceRole(ctx.deviceRole);
+        if (ctx.interactive || headedDevice) {
             // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
             // headless agent's shell inherits that agent's injected value via
             // sanitizeProcessEnv(process.env) and would keep authenticating as it,

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.