@phnx-labs/agents-cli 1.22.58 → 1.22.59

package/dist/commands/view.js

@@ -4,7 +4,7 @@ import { termLink } from '../lib/format.js';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, accountDisplayLabel, getAllCliStates, getUnmanagedCliState, getAccountInfo, credentialPresence, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { ambientClaudeToken, loginHint } from '../lib/signin-badge.js';
 import { machineId } from '../lib/machine-id.js';
 import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
@@ -24,7 +24,7 @@ import { listNativeAccounts } from '../lib/account-registry.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
-import { getConfiguredRunStrategy } from '../lib/accounting/rotate.js';
+import { getConfiguredRunStrategy, isLaunchableSignedIn } from '../lib/accounting/rotate.js';
 import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { resolveConfiguredModel } from '../lib/models.js';
 import { listProfiles, profileExists, profileSummary, readProfile } from '../lib/profiles.js';
@@ -1293,6 +1293,11 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
             isolated: isVersionIsolated(agentId, version),
             isIsolatedDefault: getIsolatedDefault(agentId) === version,
             signedIn: info.signedIn,
+            // The strict per-version launch truth (vs the display `signedIn` above,
+            // which inherits the active/global HOME login). The same primitive
+            // `collectRunCandidates` uses locally, so remote `--device auto` placement
+            // is gated on identical launchability (PHNX-3466).
+            launchable: isLaunchableSignedIn(info.signedIn, credentialPresence(agentId, home)),
             authVerdict: authCache[authCacheKey(host, agentId, version)]?.verdict ?? null,
             email: info.email,
             accountId: info.accountId,

package/dist/lib/auto-pull-worker.js

@@ -10,7 +10,7 @@
  */
 import * as fs from 'fs';
 import { simpleGit } from 'simple-git';
-import { tryAutoPull, isGitRepo } from './git.js';
+import { tryAutoPullSystemRepo, isGitRepo } from './git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath, markDetachedSyncComplete, SYNC_LOCK_TTL_MS, } from './auto-pull.js';
 /**
@@ -99,7 +99,12 @@ async function processTarget(target) {
                 await notifyRepo(target);
             }
             else {
-                await tryAutoPull(target.dir);
+                // Verify origin is the EXPECTED system remote before fast-forwarding —
+                // the system repo ships hooks that run as shell, so a pull from a
+                // repointed origin is RCE. An unexpected origin is refused, not pulled
+                // (PHNX-2957). The detached worker has no terminal to warn on; the
+                // foreground `agents use` path surfaces the refusal to the operator.
+                await tryAutoPullSystemRepo(target.dir);
             }
         }
         else {

package/dist/lib/cloud/rush.d.ts

@@ -5,6 +5,13 @@
  * Requires the Rush GitHub App installed on the target repo.
  */
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, ImageAttachment, SkillRef } from './types.js';
+/**
+ * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
+ * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * expires_at is treated as non-expired so tokens written without an expiry
+ * still work. Pass yamlPath to override the default path in tests.
+ */
+export declare function isRushSessionValid(yamlPath?: string): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
 export interface AccountManifestEntry {
     version: string;

package/dist/lib/cloud/rush.js

@@ -16,6 +16,29 @@ import { getAccountInfo } from '../agents.js';
 import { selectBalancedVersion } from '../accounting/rotate.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+/**
+ * Returns true when ~/.rush/user.yaml exists, carries an access_token, and
+ * the token has not passed its expires_at timestamp (Unix seconds). A missing
+ * expires_at is treated as non-expired so tokens written without an expiry
+ * still work. Pass yamlPath to override the default path in tests.
+ */
+export function isRushSessionValid(yamlPath = USER_YAML) {
+    try {
+        if (!fs.existsSync(yamlPath))
+            return false;
+        const raw = fs.readFileSync(yamlPath, 'utf-8');
+        const data = yaml.parse(raw);
+        if (!data?.session?.access_token)
+            return false;
+        const expiresAt = data.session.expires_at;
+        if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Read the Rush session access token from ~/.rush/user.yaml. */
 function readToken() {
     if (!fs.existsSync(USER_YAML)) {
@@ -27,6 +50,11 @@ function readToken() {
     if (!token) {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
+    const expiresAt = data.session?.expires_at;
+    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+        const expiredAt = new Date(expiresAt * 1000).toISOString();
+        throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
+    }
     return token;
 }
 /** Read the user's email from the Rush session config, if available. */
@@ -203,7 +231,7 @@ export class RushCloudProvider {
     name = 'Rush Cloud';
     capabilities() {
         return {
-            available: fs.existsSync(USER_YAML),
+            available: isRushSessionValid(),
             dispatch: true,
             status: true,
             list: true,

package/dist/lib/daemon/daemon.d.ts

@@ -215,6 +215,28 @@ export declare function anchorDaemonCwd(): string | null;
  * root is stable (or could not be resolved).
  */
 export declare function warnEphemeralDaemonRoot(resolveBin?: () => string): string | null;
+/**
+ * Test-home tripwire (PHNX-2545). The routines/daemon test suite spawns real
+ * `agents __daemon-run` processes against an isolated /tmp HOME. If that HOME
+ * override fails to reach the child — an `env: {...process.env}` spawn that
+ * forgot to set it, a login shell that reset HOME — the daemon resolves its
+ * state dir under the operator's REAL home and its scheduler/watchdog then tick
+ * against shared production state. That is the exact leak the ticket reports:
+ * real test daemons found alive on a fleet box, each a second live scheduler
+ * racing the legitimate one, in violation of the execution-singularity spec.
+ *
+ * A test that spawns a daemon sets AGENTS_DAEMON_TEST_HOME to the isolated home
+ * it provisioned. When that marker is present, this daemon's resolved state dir
+ * MUST sit under it; otherwise the daemon refuses to boot — failing loud before
+ * it claims an instance, writes a pid, or fires a single tick (the throw is
+ * caught in index.ts's `__daemon-run` handler, logged, and exits non-zero) —
+ * rather than running in the wrong directory against the real host. In
+ * production the marker is never set, so this is a no-op there.
+ *
+ * `daemonDir`/`testHome` are injectable so the pure guard is unit-testable
+ * without spawning a process; the defaults read the live daemon dir and env.
+ */
+export declare function assertTestDaemonHome(daemonDir?: string, testHome?: string | undefined): void;
 export declare function runDaemon(): Promise<void>;
 /**
  * Write a launchd plist or systemd unit with owner-only permissions atomically.

package/dist/lib/daemon/daemon.js

@@ -705,6 +705,40 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
         return null;
     }
 }
+/**
+ * Test-home tripwire (PHNX-2545). The routines/daemon test suite spawns real
+ * `agents __daemon-run` processes against an isolated /tmp HOME. If that HOME
+ * override fails to reach the child — an `env: {...process.env}` spawn that
+ * forgot to set it, a login shell that reset HOME — the daemon resolves its
+ * state dir under the operator's REAL home and its scheduler/watchdog then tick
+ * against shared production state. That is the exact leak the ticket reports:
+ * real test daemons found alive on a fleet box, each a second live scheduler
+ * racing the legitimate one, in violation of the execution-singularity spec.
+ *
+ * A test that spawns a daemon sets AGENTS_DAEMON_TEST_HOME to the isolated home
+ * it provisioned. When that marker is present, this daemon's resolved state dir
+ * MUST sit under it; otherwise the daemon refuses to boot — failing loud before
+ * it claims an instance, writes a pid, or fires a single tick (the throw is
+ * caught in index.ts's `__daemon-run` handler, logged, and exits non-zero) —
+ * rather than running in the wrong directory against the real host. In
+ * production the marker is never set, so this is a no-op there.
+ *
+ * `daemonDir`/`testHome` are injectable so the pure guard is unit-testable
+ * without spawning a process; the defaults read the live daemon dir and env.
+ */
+export function assertTestDaemonHome(daemonDir = getDaemonDir(), testHome = process.env.AGENTS_DAEMON_TEST_HOME) {
+    if (!testHome)
+        return;
+    const root = path.resolve(testHome);
+    const dir = path.resolve(daemonDir);
+    if (dir !== root && !dir.startsWith(root + path.sep)) {
+        const msg = `Daemon test-home tripwire (PHNX-2545): AGENTS_DAEMON_TEST_HOME is ${root}, but this ` +
+            `daemon's state dir resolved to ${dir} — the isolated HOME override did not reach this ` +
+            `__daemon-run child, so it would schedule against the real host. Refusing to start.`;
+        log('ERROR', msg);
+        throw new Error(msg);
+    }
+}
 // ---------------------------------------------------------------------------
 // Module-level periodic maintenance helpers (RUSH-2422)
 //
@@ -720,6 +754,11 @@ export function warnEphemeralDaemonRoot(resolveBin = getAgentsBinPath) {
 // below. runBrokerSelfHeal was moved into SecretsBrokerService (RUSH-3193 P2).
 // ---------------------------------------------------------------------------
 export async function runDaemon() {
+    // PHNX-2545 test-home tripwire — FIRST, before this daemon claims an instance,
+    // writes a pid, or fires any tick. A test-spawned daemon that lost its isolated
+    // HOME override must refuse to run against the operator's real state rather than
+    // schedule against the real host. No-op in production (the marker is never set).
+    assertTestDaemonHome();
     // Single-instance guard (last-wins, SING-11): a direct `agents __daemon-run`
     // (manual, or a service-manager restart racing a live predecessor) EVICTS the
     // incumbent and becomes the survivor. claimDaemonInstance returns false only

package/dist/lib/daemon/session-index-service.js

@@ -11,7 +11,7 @@
  * and deadline instead.
  */
 import { BasePeriodicService } from './service.js';
-import { runSessionIndexWarmTick } from '../daemon-ticks.js';
+import { runDeferredToolIndex, runSessionIndexWarmTick } from '../daemon-ticks.js';
 /** Matches the historical inline interval (daemon.ts SESSION_INDEX_WARM_TICK_MS). */
 const SESSION_INDEX_WARM_TICK_MS = 20_000;
 /** Hard cap per tick — well above a healthy incremental scan, short enough that a hang never freezes the service for long. */
@@ -36,5 +36,13 @@ export class SessionIndexService extends BasePeriodicService {
             ctx.log('INFO', 'session-index warm: skipped, another process holds the scan claim');
         else if (indexed > 0)
             ctx.log('INFO', `session-index warm: indexed ${indexed} transcript(s)`);
+        // Deferred tool-index pass (PHNX-3411): fill tool_scan_ledger rows for
+        // harnesses whose scanner produces no events. Runs only when the warm tick
+        // claimed the scan lock (i.e. we are the active indexer this tick).
+        if (claimed) {
+            const { indexed: toolIndexed } = await runDeferredToolIndex();
+            if (toolIndexed > 0)
+                ctx.log('INFO', `session-index deferred: tool-indexed ${toolIndexed} transcript(s)`);
+        }
     }
 }

package/dist/lib/daemon-ticks.d.ts

@@ -121,3 +121,18 @@ export declare function runSessionIndexWarmTick(): Promise<{
     indexed: number;
     claimed: boolean;
 }>;
+/**
+ * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
+ *
+ * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
+ * metadata — no events. Calling parseSession for those on the warm tick wedges
+ * the Node event loop when the transcript is large and active (observed: several
+ * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
+ * the gap: it queries recently-active kimi/grok sessions and calls
+ * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
+ * sessions and applies byte/file budget caps so no large transcript monopolises
+ * the tick.
+ */
+export declare function runDeferredToolIndex(): Promise<{
+    indexed: number;
+}>;

package/dist/lib/daemon-ticks.js

@@ -185,3 +185,29 @@ export async function runSessionIndexWarmTick() {
         return { indexed: 0, claimed: false };
     return { indexed: scanned, claimed: true };
 }
+/**
+ * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
+ *
+ * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
+ * metadata — no events. Calling parseSession for those on the warm tick wedges
+ * the Node event loop when the transcript is large and active (observed: several
+ * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
+ * the gap: it queries recently-active kimi/grok sessions and calls
+ * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
+ * sessions and applies byte/file budget caps so no large transcript monopolises
+ * the tick.
+ */
+export async function runDeferredToolIndex() {
+    const { querySessionsForDeferredToolIndex } = await import('./session/db.js');
+    const { ensureToolIndex } = await import('./session/tool-index.js');
+    // Feed the 200 most-recently-active kimi/grok sessions; ensureToolIndex skips
+    // any whose tool_scan_ledger stamp is current.
+    const sessions = querySessionsForDeferredToolIndex(200);
+    if (sessions.length === 0)
+        return { indexed: 0 };
+    const coverage = await ensureToolIndex(sessions, {
+        maxFiles: 20,
+        maxBytes: 20 * 1024 * 1024, // 20 MB — bounds one tick even on large transcripts
+    });
+    return { indexed: coverage.indexedFiles };
+}

package/dist/lib/device-config.d.ts

@@ -194,7 +194,11 @@ export declare function devicesPinningBrowserProfile(profile: string): Array<{
 export declare function listConfiguredDeviceRoles(roster?: string[]): Record<string, ConfiguredDeviceRole>;
 /** The configured automatic-placement pool mode. Unset means `workers`. */
 export declare function autoPoolMode(): AutoPoolMode;
-/** A device's auto-launch flags, as read by Factory's launch ranking. */
+/**
+ * A device's auto-launch flags, read by the automatic-placement pool
+ * (`filterAutoPool` drops `enabled: false`; `pickBestDevice` boosts
+ * `preferred: true` — see `lib/devices/pool.ts`) and by the menu-bar snapshot.
+ */
 export interface AutoLaunchPreference {
     enabled?: boolean;
     preferred?: boolean;

package/dist/lib/device-config.js

@@ -294,7 +294,7 @@ export const CONFIG_KEYS = [
         visibility: 'shared',
         type: 'bool',
         defaultValue: true,
-        description: 'Whether AGI EXT auto-launch may pick this device (default on).',
+        description: 'Whether `--device auto` (run, teams, AGI EXT) may pick this device (default on). Off drops it from every automatic-placement path.',
     },
     {
         name: 'auto-launch.preferred',
@@ -303,7 +303,7 @@ export const CONFIG_KEYS = [
         visibility: 'shared',
         type: 'bool',
         defaultValue: false,
-        description: 'Boost this device in AGI EXT auto-launch ranking (default off).',
+        description: 'Boost this device in `--device auto` ranking (default off) — picked ahead of load-equal peers when eligible.',
     },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */

package/dist/lib/devices/health.js

@@ -145,8 +145,12 @@ export function parseProbeOutput(host, stdout, fetchedAt) {
  * numbers, mirroring how garbage POSIX output degrades. */
 export function parseWinProbeOutput(host, stdout, fetchedAt) {
     const m = stdout.match(/AGWINSTAT load=([0-9.]*) freeKb=([0-9]+) totalKb=([0-9]+) ncpu=([0-9]+)(?: diskFreeKb=([0-9.]+) diskTotalKb=([0-9.]+))?/);
+    // Unparseable output still means the probe RAN — the box answered, we just
+    // could not read it. Stamp specsFetchedAt anyway so a hardware-fact carry
+    // forward (retainHardwareFacts, RUSH-3096) has a real observation moment
+    // instead of undefined.
     if (!m)
-        return { host, reachable: true, fetchedAt };
+        return { host, reachable: true, fetchedAt, specsFetchedAt: fetchedAt };
     const loadPercent = m[1] === '' ? undefined : parseFloat(m[1]);
     const freeKb = parseInt(m[2], 10);
     const totalKb = parseInt(m[3], 10);

package/dist/lib/devices/pool.d.ts

@@ -16,12 +16,20 @@
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
  * | marked `personal` / `desktop` | never, under either state |
+ * | `auto-launch.enabled` off | never, whatever its role or the mode |
  *
- * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * `auto.pool all` turns the WORKER allowlist off; `personal` and `desktop` stay
  * excluded, because a box the user sits at (personal) or a headed always-on
  * release/credential box (desktop) is marked precisely so agents stay off it.
+ *
+ * A device the operator turned off with `agents devices disable <name>`
+ * (`auto-launch.enabled` = false) is dropped here too — one operator switch,
+ * one place, so `disable` removes a box from EVERY automatic-placement path
+ * (run/teams/ssh auto), not just one surface. Its sibling
+ * `auto-launch.preferred` does not narrow the pool; it BOOSTS a member in the
+ * ranker ({@link autoLaunchPreferredSet}, applied by `pickBestDevice`).
  */
-import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
+import { type AutoLaunchPreference, type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 export interface AutoPoolOptions {
     /** Pool mode; defaults to the configured `auto.pool`. */
     mode?: AutoPoolMode;
@@ -34,6 +42,14 @@ export interface AutoPoolOptions {
      * {@link listConfiguredDeviceRoles}.
      */
     roster?: string[];
+    /**
+     * Auto-launch flags by device name; defaults to the fleet-shared block for
+     * the roster (or the pool). A device whose `enabled` is `false` is dropped
+     * from the pool. Inject `{}` in a pure unit test to keep the rule off disk,
+     * exactly as `roles: {}` does for the role rule. See
+     * {@link loadAutoLaunchPreferences}.
+     */
+    autoLaunch?: Record<string, AutoLaunchPreference>;
 }
 /**
  * Narrow a candidate host list to the devices automatic placement may pick.
@@ -44,6 +60,13 @@ export interface AutoPoolOptions {
  * quietly widening back to the full fleet.
  */
 export declare function filterAutoPool(pool: string[], opts?: AutoPoolOptions): string[];
+/**
+ * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
+ * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
+ * a preference never removes a device: an eligible non-preferred box is still
+ * picked when no preferred one is available.
+ */
+export declare function autoLaunchPreferredSet(pool: string[], opts?: AutoPoolOptions): Set<string>;
 /** True when this host is one automatic placement may pick. */
 export declare function isAutoPoolMember(host: string, opts?: AutoPoolOptions): boolean;
 /** Device names explicitly marked `worker`, in registry order. */

package/dist/lib/devices/pool.js

@@ -16,12 +16,20 @@
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
  * | marked `personal` / `desktop` | never, under either state |
+ * | `auto-launch.enabled` off | never, whatever its role or the mode |
  *
- * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * `auto.pool all` turns the WORKER allowlist off; `personal` and `desktop` stay
  * excluded, because a box the user sits at (personal) or a headed always-on
  * release/credential box (desktop) is marked precisely so agents stay off it.
+ *
+ * A device the operator turned off with `agents devices disable <name>`
+ * (`auto-launch.enabled` = false) is dropped here too — one operator switch,
+ * one place, so `disable` removes a box from EVERY automatic-placement path
+ * (run/teams/ssh auto), not just one surface. Its sibling
+ * `auto-launch.preferred` does not narrow the pool; it BOOSTS a member in the
+ * ranker ({@link autoLaunchPreferredSet}, applied by `pickBestDevice`).
  */
-import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
+import { autoPoolMode, listConfiguredDeviceRoles, loadAutoLaunchPreferences, } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';
 /**
  * Roles that automatic placement never picks, whatever the pool mode.
@@ -44,7 +52,10 @@ export function filterAutoPool(pool, opts = {}) {
     const roles = opts.roles ?? listConfiguredDeviceRoles(opts.roster ?? pool);
     const byHost = new Map(Object.entries(roles).map(([name, role]) => [normalizeHost(name), role]));
     const roleOf = (host) => byHost.get(normalizeHost(host));
+    const disabled = disabledAutoLaunchSet(pool, opts);
     const eligible = pool.filter((host) => {
+        if (disabled.has(normalizeHost(host)))
+            return false;
         const role = roleOf(host);
         return role === undefined || !NEVER_AUTO.has(role);
     });
@@ -56,6 +67,25 @@ export function filterAutoPool(pool, opts = {}) {
         return eligible;
     return eligible.filter((host) => roleOf(host) === 'worker');
 }
+/** Normalized hosts the operator turned off with `auto-launch.enabled` = false. */
+function disabledAutoLaunchSet(pool, opts) {
+    const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
+    return new Set(Object.entries(prefs)
+        .filter(([, pref]) => pref.enabled === false)
+        .map(([name]) => normalizeHost(name)));
+}
+/**
+ * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
+ * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
+ * a preference never removes a device: an eligible non-preferred box is still
+ * picked when no preferred one is available.
+ */
+export function autoLaunchPreferredSet(pool, opts = {}) {
+    const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
+    return new Set(Object.entries(prefs)
+        .filter(([, pref]) => pref.preferred === true)
+        .map(([name]) => normalizeHost(name)));
+}
 /** True when this host is one automatic placement may pick. */
 export function isAutoPoolMember(host, opts = {}) {
     return filterAutoPool([host], opts).length > 0;

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

@@ -63,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())) {
@@ -419,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))

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