@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/plugins/skills.js

@@ -16,6 +16,7 @@ import { capableAgents, isCapable } from '../capabilities.js';
 import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, getTrashSkillsDir } from '../state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { listCommandSkillsInVersion } from '../command-skills.js';
+import { pluginSkillDirs, listPluginSkillNames } from '../staleness/writers/sources.js';
 import { emit } from '../feed/events.js';
 const HOME = os.homedir();
 /** User-scoped skills dir (~/.agents/skills/). Used for installs. */
@@ -352,7 +353,14 @@ export function listCentralSkills() {
 }
 /**
  * Resolve a skill name to its source directory. Searches user dir first,
- * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ * then system dir, then extra repos, then plugin-bundled skills
+ * (`plugins/<plugin>/skills/<name>` under any trusted base). Returns null if no
+ * source has a SKILL.md.
+ *
+ * Crediting plugins here is load-bearing (PHNX-3185): a skill materialized from
+ * `plugins/design/skills/design` has a real source, so it must resolve — else
+ * `versionSkillMatches` finds no source and the skill reads as drifted, and
+ * {@link diffVersionSkills} classes it an orphan `prune cleanup` would delete.
  */
 export function resolveSkillSourcePath(skillName) {
     for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
@@ -365,6 +373,11 @@ export function resolveSkillSourcePath(skillName) {
         if (fs.existsSync(path.join(candidate, 'SKILL.md')))
             return candidate;
     }
+    for (const skillsDir of pluginSkillDirs()) {
+        const candidate = path.join(skillsDir, skillName);
+        if (fs.existsSync(path.join(candidate, 'SKILL.md')))
+            return candidate;
+    }
     return null;
 }
 /**
@@ -443,7 +456,10 @@ function versionSkillMatches(agent, version, skillName) {
  * Compare a version home's skills against central. Returns the reconciliation diff.
  */
 export function diffVersionSkills(agent, version) {
-    const available = new Set(listAllSkills());
+    // Plugin-provided skills (`plugins/<plugin>/skills`) are legitimate sources too, so a
+    // skill materialized from a plugin is NOT an orphan (PHNX-3185). Without this
+    // the detector offered to delete the entire plugin-installed skill library.
+    const available = new Set([...listAllSkills(), ...listPluginSkillNames({ agent })]);
     // Goose and other native ~/.agents/skills consumers read central storage
     // directly. They intentionally have no per-version copy to diff, so every
     // available central skill is already current for every supported version.

package/dist/lib/pty-server.d.ts

@@ -21,6 +21,20 @@ export { captureProcessStartTime };
  * (the authoritative code comes from node-pty's onExit).
  */
 export declare function buildSentinelCommand(shell: string, command: string): string;
+/**
+ * Turn a native-binding load failure into an actionable, platform-aware message.
+ *
+ * The binding is `@homebridge/node-pty-prebuilt-multiarch`'s `pty.node`. On Linux
+ * it is baked into the npm tarball and always present; on macOS/Windows it is
+ * fetched per host + Node ABI at install time by the package's `prebuild-install`
+ * postinstall. The common failure is a Node runtime whose ABI has no published
+ * prebuild (the PHNX-2740 darwin-arm64 case): `prebuild-install` finds nothing,
+ * the build-from-source fallback also fails, and the loader throws a bare
+ * `Cannot find module '.../pty.node'` / MODULE_NOT_FOUND with no clue what to do.
+ *
+ * Pure (returns the lines) so it can be unit-tested without spawning the server.
+ */
+export declare function describeNativePtyLoadFailure(err: unknown): string[];
 /**
  * Resolve the IPC endpoint for a given platform + PTY scratch dir. Pure so both
  * branches are testable without stubbing process.platform.

package/dist/lib/pty-server.js

@@ -88,6 +88,43 @@ export function buildSentinelCommand(shell, command) {
     }
     return `${command}; echo "${SENTINEL}:$?"`;
 }
+/**
+ * Turn a native-binding load failure into an actionable, platform-aware message.
+ *
+ * The binding is `@homebridge/node-pty-prebuilt-multiarch`'s `pty.node`. On Linux
+ * it is baked into the npm tarball and always present; on macOS/Windows it is
+ * fetched per host + Node ABI at install time by the package's `prebuild-install`
+ * postinstall. The common failure is a Node runtime whose ABI has no published
+ * prebuild (the PHNX-2740 darwin-arm64 case): `prebuild-install` finds nothing,
+ * the build-from-source fallback also fails, and the loader throws a bare
+ * `Cannot find module '.../pty.node'` / MODULE_NOT_FOUND with no clue what to do.
+ *
+ * Pure (returns the lines) so it can be unit-tested without spawning the server.
+ */
+export function describeNativePtyLoadFailure(err) {
+    const detail = err instanceof Error ? (err.stack || err.message) : String(err);
+    const abi = process.versions.modules;
+    const nodeVersion = process.version;
+    const platform = `${process.platform}-${process.arch}`;
+    const lines = [
+        `agents pty could not load its native terminal binding (@homebridge/node-pty-prebuilt-multiarch).`,
+        `  platform: ${platform}   node: ${nodeVersion} (ABI ${abi})`,
+        ``,
+        `The prebuilt binary for this platform + Node ABI is missing. On macOS/Windows`,
+        `it is downloaded at install time; a Node version newer than any published`,
+        `prebuild, or an install that skipped the postinstall, leaves it absent.`,
+        ``,
+        `Fix it by reinstalling so the native binding is fetched or built:`,
+        `  npm rebuild @homebridge/node-pty-prebuilt-multiarch   # rebuild for this Node`,
+        `  # or reinstall the CLI:  npm i -g @phnx-labs/agents-cli`,
+        `If your Node (ABI ${abi}) is newer than the shipped prebuilds, install an LTS`,
+        `Node and retry, or ensure a C++ toolchain is present for the source build.`,
+        ``,
+        `Underlying error:`,
+        ...detail.split('\n').map(l => `  ${l}`),
+    ];
+    return lines;
+}
 /** Get the PTY helper directory, creating it if needed. */
 function getPtyDir() {
     const dir = getPtyDirRoot();
@@ -181,9 +218,16 @@ export async function runPtyServer() {
     let nodePty;
     let XtermTerminal;
     try {
-        // The Homebridge multiarch fork of node-pty: API-identical (same 1.x N-API
-        // codebase) but ships prebuilt binaries for Linux glibc + musl, x64 + arm64
-        // (plus macOS/Windows), so no compiler is needed on Linux/Alpine/arm64.
+        // The Homebridge multiarch fork of node-pty (API-identical to the 1.x N-API
+        // upstream). Its npm tarball BAKES IN the Linux prebuilds (glibc + musl, every
+        // arch + Node ABI), so Linux never needs a compiler or a network fetch. The
+        // darwin-arm64 / win32 binaries are NOT in the tarball — they are downloaded
+        // per host+Node-ABI at install time by the package's own `prebuild-install`
+        // postinstall (gated by bun's `trustedDependencies`). That fetch fails when the
+        // running Node ABI is newer than any published prebuild (e.g. 0.13.1 shipped no
+        // darwin-arm64 above Node 24 / ABI 137, so Node 25/26 fell through to a
+        // build-from-source that also failed — PHNX-2740), leaving a raw MODULE_NOT_FOUND.
+        // Fail loud with the platform/ABI and a concrete remediation instead.
         nodePty = await import('@homebridge/node-pty-prebuilt-multiarch');
         // Handle ESM default export
         if (nodePty.default?.spawn)
@@ -205,8 +249,8 @@ export async function runPtyServer() {
         catch { }
     }
     catch (err) {
-        console.error('node-pty (@homebridge/node-pty-prebuilt-multiarch) is required for PTY support.');
-        console.error('Install: bun add @homebridge/node-pty-prebuilt-multiarch');
+        for (const line of describeNativePtyLoadFailure(err))
+            console.error(line);
         process.exit(1);
     }
     try {

package/dist/lib/refresh.d.ts

@@ -40,5 +40,14 @@ export interface RefreshOptions {
 export interface RefreshResult {
     /** User-facing sentences, one per refused resource, prefixed with the agent. */
     declined: string[];
+    /**
+     * The exact (agent, version) pairs this refresh reconciled — the set a
+     * post-reconcile verification must re-check for residual drift, so it never
+     * flags a version the reconcile never targeted (PHNX-3186).
+     */
+    reconciled: Array<{
+        agent: AgentId;
+        version: string;
+    }>;
 }
 export declare function refresh(options?: RefreshOptions): Promise<RefreshResult>;

package/dist/lib/refresh.js

@@ -58,6 +58,7 @@ export async function refresh(options = {}) {
     // Resources this pass refused to write, surfaced by the caller. An empty
     // synced list cannot also mean "declined and here is why" (RUSH-2700).
     const declined = [];
+    const reconciled = [];
     migratePromptcutsToRoot(agentsDir, quiet);
     const manifest = readManifest(agentsDir);
     if (!manifest) {
@@ -176,6 +177,7 @@ export async function refresh(options = {}) {
                     // Pass the already-built `available` so each version does not re-scan
                     // resource trees (RUSH-2320 #5).
                     const syncResult = syncResourcesToVersion(agentId, ver, selection, { available, ...(forceFullSync ? { force: true } : {}) });
+                    reconciled.push({ agent: agentId, version: ver });
                     if (syncResult.commands)
                         kinds.add('commands');
                     if (syncResult.skills)
@@ -353,5 +355,5 @@ export async function refresh(options = {}) {
         for (const reason of declined)
             log(`  ${chalk.yellow(reason)}`);
     }
-    return { declined };
+    return { declined, reconciled };
 }

package/dist/lib/routine-readiness.d.ts

@@ -10,7 +10,21 @@
  * authentication and Codex's native workspace-trust record before activation.
  */
 import type { JobConfig } from './scheduling/routines.js';
-import { type RoutineReadinessResult } from './routine-context.js';
+import { type RoutineReadinessResult, type RoutineReadiness } from './routine-context.js';
+/**
+ * Fire-time auth preflight: read the daemon-warmed auth-health cache for the
+ * exact (agent, version) a routine has resolved to run, and return an
+ * `agent_auth_failed` blocker when that account is provably signed out — so the
+ * daemon records a terminal `blocked` run (with the re-login repair) instead of
+ * spawning a doomed run that 401s and burns a session (PHNX-3415).
+ *
+ * Cache-only (no network, no prompt — the daemon refreshes the cache
+ * periodically and `fleet ping` writes it), and fails OPEN on a missing or
+ * non-blocking verdict so a stale/absent probe never wedges a routine. It is
+ * checked AFTER version rotation resolves the account (`launch.chain[0]`), so it
+ * judges the identity the run will actually use, never a rotated-past dead pin.
+ */
+export declare function fireTimeAuthReadiness(agent: string, version: string): RoutineReadiness | null;
 /**
  * Evaluate whether a routine is ready to activate on this box. `probeAgent`
  * defaults to "is a version of the routine's agent resolvable" via

package/dist/lib/routine-readiness.js

@@ -14,6 +14,8 @@ import * as path from 'path';
 import * as TOML from 'smol-toml';
 import { resolveJobExecutionContext, resolveHostStrategy } from './scheduling/routines.js';
 import { evaluateRoutineReadiness } from './routine-context.js';
+import { readAuthHealth } from './auth-health.js';
+import { machineId } from './machine-id.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './installations/versions.js';
 import { probeLocalFleetAuth } from './auth-health.js';
 import { resolveHostRunTarget } from './hosts/run-target.js';
@@ -21,6 +23,45 @@ import { hostIdentityArgs, sshTargetFor } from './hosts/types.js';
 import { probeHost } from './hosts/ready.js';
 import { sshExec, shellQuote } from './ssh-exec.js';
 import { encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './hosts/remote-cmd.js';
+/**
+ * Verdicts that make a FIRE-TIME auth preflight block the run: the last live
+ * probe found the account either server-rejected (`revoked`) or with no
+ * credential at all (`unconfigured` — the "Please run /login" / "no account
+ * signed in" case, which is the most common way a routine's dispatch account
+ * goes dead). Everything else fails OPEN: `rate_limited` is still authenticated,
+ * `expired` self-heals on the next refresh, `unverified` means signed-in but no
+ * live probe endpoint (codex/grok), and `error` is indeterminate — none of those
+ * should stop a fire. This is deliberately BROADER than {@link isDeadVerdict}
+ * (display-only, `revoked` alone): a signed-out account must block a fire, not
+ * just paint a red cell.
+ */
+function fireBlockingAuthVerdict(verdict) {
+    return verdict === 'revoked' || verdict === 'unconfigured';
+}
+/**
+ * Fire-time auth preflight: read the daemon-warmed auth-health cache for the
+ * exact (agent, version) a routine has resolved to run, and return an
+ * `agent_auth_failed` blocker when that account is provably signed out — so the
+ * daemon records a terminal `blocked` run (with the re-login repair) instead of
+ * spawning a doomed run that 401s and burns a session (PHNX-3415).
+ *
+ * Cache-only (no network, no prompt — the daemon refreshes the cache
+ * periodically and `fleet ping` writes it), and fails OPEN on a missing or
+ * non-blocking verdict so a stale/absent probe never wedges a routine. It is
+ * checked AFTER version rotation resolves the account (`launch.chain[0]`), so it
+ * judges the identity the run will actually use, never a rotated-past dead pin.
+ */
+export function fireTimeAuthReadiness(agent, version) {
+    const health = readAuthHealth(machineId(), agent, version);
+    if (!health || !fireBlockingAuthVerdict(health.verdict))
+        return null;
+    const who = health.account ? ` (${health.account})` : '';
+    return {
+        code: 'agent_auth_failed',
+        message: `the ${agent}${who} account is signed out — the last auth probe returned '${health.verdict}', so this run would fail authentication`,
+        repair: `agents run ${agent}@${version} -- login`,
+    };
+}
 /**
  * Evaluate whether a routine is ready to activate on this box. `probeAgent`
  * defaults to "is a version of the routine's agent resolvable" via

package/dist/lib/sandbox.d.ts

@@ -7,6 +7,7 @@
  * access to explicitly allowed paths.
  */
 import type { JobConfig } from './scheduling/routines.js';
+import type { AgentId } from './types.js';
 /**
  * Absolute path to this host's `gh` config directory (`hosts.yml` + `config.yml`),
  * or null when the host has never run `gh auth login`. Prefer `GH_CONFIG_DIR` when
@@ -28,7 +29,9 @@ export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<str
  */
 export declare function getJobHomePath(name: string): string;
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
-export declare function prepareJobHome(config: JobConfig): string;
+export declare function prepareJobHome(config: JobConfig, version?: string): string;
+/** Link only the selected harness login into the disposable routine HOME. */
+export declare function linkVersionAuth(overlayHome: string, agent: AgentId, version?: string): void;
 /**
  * Link this host's `gh` config directory into the disposable overlay so
  * `$HOME/.config/gh` resolves even when `GH_CONFIG_DIR` is unset. Mirrors

package/dist/lib/sandbox.js

@@ -12,6 +12,7 @@ import * as os from 'os';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
 import { safeJoin } from './paths.js';
 import { createLink } from './platform/index.js';
+import { getVersionHomePath } from './installations/versions.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -132,7 +133,7 @@ export function getJobHomePath(name) {
     return path.join(safeJoin(getRoutinesDir(), name), 'home');
 }
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
-export function prepareJobHome(config) {
+export function prepareJobHome(config, version) {
     const overlayHome = getJobHomePath(config.name);
     cleanJobHome(config.name);
     fs.mkdirSync(overlayHome, { recursive: true });
@@ -143,6 +144,7 @@ export function prepareJobHome(config) {
     }
     else if (config.agent === 'codex') {
         generateCodexConfig(overlayHome, config);
+        linkVersionAuth(overlayHome, 'codex', version);
     }
     else if (config.agent === 'cursor') {
         generateCursorConfig(overlayHome);
@@ -165,6 +167,33 @@ export function prepareJobHome(config) {
     }
     return overlayHome;
 }
+/** Link only the selected harness login into the disposable routine HOME. */
+export function linkVersionAuth(overlayHome, agent, version) {
+    if (!version)
+        return;
+    const versionHome = getVersionHomePath(agent, version);
+    const pairs = agent === 'claude'
+        ? [
+            [path.join(versionHome, '.claude', '.claude.json'), path.join(overlayHome, '.claude', '.claude.json')],
+            [path.join(versionHome, '.claude', '.credentials.json'), path.join(overlayHome, '.claude', '.credentials.json')],
+        ]
+        : agent === 'codex'
+            ? [[path.join(versionHome, '.codex', 'auth.json'), path.join(overlayHome, '.codex', 'auth.json')]]
+            : [];
+    for (const [source, target] of pairs) {
+        if (!fs.existsSync(source))
+            continue;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        try {
+            fs.rmSync(target, { force: true });
+        }
+        catch { /* absent */ }
+        try {
+            createLink(source, target);
+        }
+        catch { /* the harness fails auth loudly if linking is unavailable */ }
+    }
+}
 /**
  * Link this host's `gh` config directory into the disposable overlay so
  * `$HOME/.config/gh` resolves even when `GH_CONFIG_DIR` is unset. Mirrors