@phnx-labs/agents-cli 1.20.78 → 1.20.83

package/dist/lib/fleet/apply.js

@@ -12,7 +12,7 @@ import { sshTargetFor } from '../devices/connect.js';
 import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { sshExec } from '../ssh-exec.js';
-import { isPropagatableAgent, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './auth-sync.js';
+import { isPropagatableAgent, hasPortableAuthFiles, isCredentialSafeToPropagate, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './auth-sync.js';
 /** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export function agentIdOf(spec) {
     return spec.split('@')[0].trim();
@@ -148,6 +148,13 @@ export function diffFleet(desired, probes, ctx) {
                     if (canPushLogin(id, probe.platform, ctx.sourceAuth)) {
                         rowActions.push({ device: d.device, kind: 'push-login', agent: id, detail: `propagate ${id} login` });
                     }
+                    else if (hasPortableAuthFiles(id) && !isCredentialSafeToPropagate(id)) {
+                        // Single-use rotating refresh tokens (e.g. droid/WorkOS) must never be
+                        // copied across boxes — the first refresh invalidates every other copy.
+                        // Surface per-machine login guidance instead of silently propagating.
+                        loginBlocked.push(id);
+                        rowActions.push({ device: d.device, kind: 'needs-login', agent: id, detail: `${id} login uses a single-use rotating refresh token — log in on ${d.device} itself` });
+                    }
                     else if (isPropagatableAgent(id) &&
                         (ctx.sourceAuth.bound.has(id) || (probe.platform === 'macos' && KEYCHAIN_BOUND_ON_MAC.has(id)))) {
                         // A login-propagation candidate we still can't push: the source token

package/dist/lib/fleet/auth-sync.d.ts

@@ -27,6 +27,23 @@ interface AuthFileSpec {
 export declare const FLEET_AUTH_FILES: Record<string, AuthFileSpec[]>;
 /** Agents whose macOS credentials live in the ACL-bound login keychain. */
 export declare const KEYCHAIN_BOUND_ON_MAC: ReadonlySet<string>;
+/**
+ * Agents whose OAuth credentials rely on single-use refresh tokens that rotate
+ * server-side on every exchange. Copying these credential files across machines
+ * is fatal: the first refresh on any box invalidates every other holder's token,
+ * collapsing the fleet to a single working login (droid/WorkOS collapsed 10 boxes
+ * to 1 overnight — RUSH-1958). Add any newly-discovered single-use-rotation
+ * harness here; the predicate below is the one place the propagation decision is
+ * made. See also `remote-login.ts` and `usage.ts` for the per-machine-login policy.
+ */
+export declare const SINGLE_USE_ROTATING_REFRESH_AGENTS: ReadonlySet<string>;
+/** True when `agent`'s portable credential file(s) are safe to copy between
+ *  machines. Single-use rotating refresh tokens are never safe; keychain-bound
+ *  tokens are handled separately by the caller via {@link KEYCHAIN_BOUND_ON_MAC}. */
+export declare function isCredentialSafeToPropagate(agent: string): boolean;
+/** True when the agent stores credentials in portable files we can read. This
+ *  does NOT mean it is safe to propagate — check {@link isCredentialSafeToPropagate}. */
+export declare function hasPortableAuthFiles(agent: string): boolean;
 /** Which agents `apply` can propagate auth for at all. */
 export declare function isPropagatableAgent(agent: string): boolean;
 /**
@@ -48,7 +65,7 @@ export interface LoginFlow {
     /**
      * The exact command that starts the login flow on the remote box, run as
      * `ssh -tt <box> <loginCommand>`. Bare `<cli>` for agents whose device flow
-     * starts on launch (droid, kimi, gemini, antigravity), `<cli> login` for
+     * starts on launch (droid, kimi, antigravity), `<cli> login` for
      * codex/grok, `<cli> auth login` for opencode.
      */
     loginCommand: string;

package/dist/lib/fleet/auth-sync.js

@@ -23,7 +23,6 @@ import * as path from 'path';
 export const FLEET_AUTH_FILES = {
     claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
     codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
-    gemini: [{ rel: '.gemini/oauth_creds.json', mode: 0o600 }],
     grok: [{ rel: '.grok/auth.json', mode: 0o600 }],
     kimi: [{ rel: '.kimi-code/credentials/kimi-code.json', mode: 0o600 }],
     opencode: [{ rel: '.local/share/opencode/auth.json', mode: 0o600 }],
@@ -35,9 +34,30 @@ export const FLEET_AUTH_FILES = {
 };
 /** Agents whose macOS credentials live in the ACL-bound login keychain. */
 export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
+/**
+ * Agents whose OAuth credentials rely on single-use refresh tokens that rotate
+ * server-side on every exchange. Copying these credential files across machines
+ * is fatal: the first refresh on any box invalidates every other holder's token,
+ * collapsing the fleet to a single working login (droid/WorkOS collapsed 10 boxes
+ * to 1 overnight — RUSH-1958). Add any newly-discovered single-use-rotation
+ * harness here; the predicate below is the one place the propagation decision is
+ * made. See also `remote-login.ts` and `usage.ts` for the per-machine-login policy.
+ */
+export const SINGLE_USE_ROTATING_REFRESH_AGENTS = new Set(['droid']);
+/** True when `agent`'s portable credential file(s) are safe to copy between
+ *  machines. Single-use rotating refresh tokens are never safe; keychain-bound
+ *  tokens are handled separately by the caller via {@link KEYCHAIN_BOUND_ON_MAC}. */
+export function isCredentialSafeToPropagate(agent) {
+    return !SINGLE_USE_ROTATING_REFRESH_AGENTS.has(agent);
+}
+/** True when the agent stores credentials in portable files we can read. This
+ *  does NOT mean it is safe to propagate — check {@link isCredentialSafeToPropagate}. */
+export function hasPortableAuthFiles(agent) {
+    return agent in FLEET_AUTH_FILES;
+}
 /** Which agents `apply` can propagate auth for at all. */
 export function isPropagatableAgent(agent) {
-    return agent in FLEET_AUTH_FILES;
+    return hasPortableAuthFiles(agent) && isCredentialSafeToPropagate(agent);
 }
 /** The success-file for an agent — the primary portable credential (first spec). */
 function successFileFor(agent) {
@@ -107,14 +127,6 @@ export const FLEET_LOGIN_FLOWS = {
         flowType: 'loopback',
         successFile: successFileFor('antigravity'),
     },
-    // gemini: bare `gemini`, Google login on launch. Not characterized as a
-    // device-code flow (typically loopback) and no captured pattern — mark unknown
-    // so it is flagged non-remotable rather than mis-driven.
-    gemini: {
-        loginCommand: 'gemini',
-        flowType: 'unknown',
-        successFile: successFileFor('gemini'),
-    },
     // opencode: `opencode auth login`. No captured pattern — unknown/non-remotable.
     opencode: {
         loginCommand: 'opencode auth login',
@@ -144,7 +156,9 @@ export function snapshotAuth(agents, opts) {
     for (const agent of agents) {
         const specs = FLEET_AUTH_FILES[agent];
         if (!specs)
-            continue; // not propagatable — caller surfaces separately if desired
+            continue; // no portable file — caller surfaces separately if desired
+        if (!isCredentialSafeToPropagate(agent))
+            continue; // single-use rotating refresh tokens are never copied
         if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
             bound.push(agent);
             continue;

package/dist/lib/fleet/remote-login.js

@@ -9,6 +9,11 @@
  * each verification URL + user code, and surfacing them all in ONE local browser
  * page so the human enters codes back-to-back instead of babysitting N terminals.
  *
+ * The propagation gate lives in `auth-sync.ts`: {@link isCredentialSafeToPropagate}
+ * and {@link SINGLE_USE_ROTATING_REFRESH_AGENTS} are the single place where the
+ * "is this credential safe to copy?" decision is made, shared by `agents apply`
+ * and any other propagation path.
+ *
  * Layering — pure vs I/O, so the valuable logic is unit-testable without SSH:
  *  - `scrapeLogin` / `classifyLoginFlow` / `selectLoginTargets` /
  *    `buildRemoteLoginSshCommand` / `buildDashboardHtml` are PURE.

package/dist/lib/git.d.ts

@@ -248,20 +248,6 @@ export declare function displayHomePath(dir: string): string;
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
-/**
- * Auto-commit the machine's OWN generated per-device meta file
- * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
- *
- * That file is committed + synced (so every machine can introspect every other
- * machine's pins), but each box rewrites its own copy whenever a pin changes —
- * leaving the tree perpetually dirty and wedging `agents repo pull` (which
- * refuses a dirty tree). This durably commits just that one path (explicit
- * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
- * untouched and still (correctly) block the pull. No-op when the meta path isn't
- * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
- * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
- */
-export declare function commitOwnDeviceMeta(dir: string, metaAbs?: string): Promise<string | null>;
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;
@@ -341,3 +327,17 @@ export declare function tryAutoPull(dir: string): Promise<{
     pulled: boolean;
     error?: string;
 }>;
+/**
+ * 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
+ * dir is not a git repo, has no upstream configured, or git errors.
+ *
+ * Used by `agents doctor` to flag a source layer (`~/.agents`, `~/.agents/.system`)
+ * that is reconciled against stale truth. Staleness relative to origin is a
+ * background auto-pull concern; this surfaces the same fact synchronously in the
+ * per-version verdict.
+ */
+export declare function commitsBehindUpstream(dir: string): {
+    behind: number;
+    branch: string;
+} | null;

package/dist/lib/git.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
-import { getPackageLocalPath, getDeviceMetaPath } from './state.js';
+import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
@@ -803,48 +803,13 @@ export function displayHomePath(dir) {
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
-/**
- * Auto-commit the machine's OWN generated per-device meta file
- * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
- *
- * That file is committed + synced (so every machine can introspect every other
- * machine's pins), but each box rewrites its own copy whenever a pin changes —
- * leaving the tree perpetually dirty and wedging `agents repo pull` (which
- * refuses a dirty tree). This durably commits just that one path (explicit
- * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
- * untouched and still (correctly) block the pull. No-op when the meta path isn't
- * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
- * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
- */
-export async function commitOwnDeviceMeta(dir, metaAbs = getDeviceMetaPath()) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedMeta = path.resolve(metaAbs);
-    if (resolvedMeta !== resolvedDir && !resolvedMeta.startsWith(resolvedDir + path.sep)) {
-        return null; // meta lives outside this repo — not ours to commit here
-    }
-    const rel = path.relative(resolvedDir, resolvedMeta).split(path.sep).join('/');
-    try {
-        const git = simpleGit(dir);
-        const status = await git.status();
-        const dirty = status.files.some((f) => f.path === rel);
-        if (!dirty)
-            return null;
-        await git.add([rel]);
-        const machine = path.basename(path.dirname(resolvedMeta));
-        await git.commit(`chore(devices): snapshot ${machine} agent pins`, [rel]);
-        return rel;
-    }
-    catch {
-        return null; // best-effort — never let this block the pull path
-    }
-}
 export async function pullRepo(dir) {
     try {
         const git = simpleGit(dir);
         // A rebase left in progress by an earlier run must be reported as itself.
         // Without this the dirty-tree guard below claims "Blocked by local changes",
         // which is both wrong and actively harmful advice mid-rebase on a detached
-        // HEAD. Checked BEFORE commitOwnDeviceMeta so we never commit into one.
+        // HEAD.
         // Ask git where the state dirs live rather than assuming `<dir>/.git/` is a
         // directory. In a worktree `.git` is a FILE containing `gitdir: <path>`, so
         // path.join(dir, '.git', 'rebase-merge') can never exist and the check would
@@ -874,9 +839,6 @@ export async function pullRepo(dir) {
                     `  git rebase --abort      # to discard the attempt`,
             };
         }
-        // Commit this machine's own device-meta first so a per-machine pin change
-        // never wedges the pull. Genuine edits elsewhere still block below.
-        await commitOwnDeviceMeta(dir);
         const status = await git.status();
         if (!status.isClean()) {
             return {
@@ -934,10 +896,8 @@ export async function pullRepo(dir) {
         }
         try {
             // Rebase, not --ff-only. Fast-forward refuses ANY divergence, conflict or
-            // not, so a single local commit — including the one commitOwnDeviceMeta
-            // makes just above — permanently wedged the pull with nothing actually in
-            // conflict. Every device carries its own devices/<host>/ path, so those
-            // replay cleanly. Matches syncRepoGit (below) and this function's own doc.
+            // not, so a single local commit permanently wedged the pull with nothing
+            // actually in conflict. Matches syncRepoGit (below) and this function's doc.
             //
             // Pull the RESOLVED tracking ref, not `branch`: when the local branch has
             // no tracking config the block above falls back to origin's default head,
@@ -1211,3 +1171,40 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
+/**
+ * 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
+ * dir is not a git repo, has no upstream configured, or git errors.
+ *
+ * Used by `agents doctor` to flag a source layer (`~/.agents`, `~/.agents/.system`)
+ * that is reconciled against stale truth. Staleness relative to origin is a
+ * background auto-pull concern; this surfaces the same fact synchronously in the
+ * per-version verdict.
+ */
+export function commitsBehindUpstream(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    const run = (args) => {
+        try {
+            return execFileSync('git', ['-C', dir, ...args], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                encoding: 'utf8',
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    // Name of the upstream ref (e.g. `origin/main`) for the human-readable message.
+    const branch = run(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    if (!branch)
+        return null;
+    // `--count HEAD..@{upstream}` = commits on upstream not yet in HEAD = behind.
+    const raw = run(['rev-list', '--count', 'HEAD..@{upstream}']);
+    if (raw === null)
+        return null;
+    const behind = parseInt(raw, 10);
+    if (!Number.isFinite(behind))
+        return null;
+    return { behind, branch };
+}

package/dist/lib/hooks.d.ts

@@ -21,12 +21,41 @@ export declare function resolveHookScriptPath(script: string): string | null;
  * os.homedir()/path.sep at the call site.
  */
 export declare function toPortableCommand(absPath: string, home?: string, sep?: string): string;
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export declare function deduplicateVersionHookCommands(commands: string[], activeVersionHome: string): string[];
 import type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
     scriptPath: string;
     dataFile?: string;
 };
+export interface VersionHookCopy {
+    agent: AgentId;
+    version: string;
+    name: string;
+    path: string;
+    hash: string;
+    active: boolean;
+}
+export interface DuplicateVersionHook {
+    agent: AgentId;
+    name: string;
+    kind: 'duplicate' | 'drift';
+    authoritative: VersionHookCopy;
+    copies: VersionHookCopy[];
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
 /**
  * List hook entries in a single directory, grouping script + data files by
  * basename. Exported so doctor-diff can reuse the same grouping the sync path
@@ -59,6 +88,48 @@ export declare function getVersionHooksDir(agent: AgentId, version: string): str
  * List hook entries in a specific version home.
  */
 export declare function listHooksInVersionHome(agent: AgentId, version: string): HookEntry[];
+export interface HookWiringIssue {
+    /** Hook name (script basename minus extension). */
+    name: string;
+    /** Native lifecycle event the hook should be wired to (Stop, PreToolUse, …). */
+    event: string;
+    /** Matcher group the hook belongs to under `event` (`''` = the catch-all
+     *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
+     *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
+    matcher: string;
+    /** The command settings.json should reference for this hook under `event`. */
+    command: string;
+}
+export interface HookWiringReport {
+    /** Whether this agent's hook config format is understood by the inspector. */
+    supported: boolean;
+    /** Absolute path of the settings file inspected (when supported). */
+    settingsPath?: string;
+    /** Number of hooks the manifest says should be wired for this version. */
+    expected?: number;
+    /** settings.json does not exist — nothing declared can be wired. */
+    settingsMissing?: boolean;
+    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    settingsUnparseable?: boolean;
+    /** Hooks whose file is present/resolvable but that are NOT referenced in the
+     *  event array settings.json should carry them in. */
+    unwired: HookWiringIssue[];
+}
+/**
+ * Verify that every hook the manifest says should be wired for a (claude|droid)
+ * version is actually REFERENCED in that version's native settings.json — not
+ * merely present as a file on disk.
+ *
+ * `agents doctor` compares hook FILES against source (see diffHooks in
+ * doctor-diff.ts) but never checks the wiring, so a hook whose script is
+ * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
+ * array reads as "ok" while it never fires. This closes that blind spot.
+ *
+ * Read-only by construction: it mirrors registerHooksForClaude's command
+ * resolution WITHOUT the shim-generation / chmod side effects that
+ * resolveHookCommand performs, so it never mutates the version home.
+ */
+export declare function checkVersionHookWiring(agent: AgentId, version: string): HookWiringReport;
 export interface VersionHookDiff {
     agent: AgentId;
     version: string;