@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/events.d.ts

@@ -11,8 +11,9 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
+import { type ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;
@@ -30,6 +31,10 @@ export interface EventMeta {
     osUser: string;
     transport: 'local' | 'ssh';
     sshClientIp?: string;
+    /** Resolved actor id — which human/agent is behind this event (RUSH-2020). */
+    actor?: string;
+    /** Actor kind (`human`/`agent`). */
+    kind?: ActorKind;
 }
 export interface EventPayload {
     agent?: string;
@@ -196,6 +201,8 @@ export interface EventStats {
     byEvent: Record<string, number>;
     byModule: Record<string, number>;
     byUser: Record<string, number>;
+    /** Event counts grouped by resolved actor id (the human/agent behind them). */
+    byActor: Record<string, number>;
     fileCount: number;
     totalBytes: number;
 }

package/dist/lib/events.js

@@ -19,6 +19,7 @@ import { gzipSync, gunzipSync } from 'node:zlib';
 import { parseSshConnection } from './session/provenance.js';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { getUserAgentsDir } from './state.js';
+import { resolveActor } from './actor.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
 // import itself must stay side-effect free. Tests may override the exact path.
@@ -51,7 +52,7 @@ const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
-    'secrets.get', 'secrets.set', 'secrets.delete', 'secrets.rename',
+    'secrets.get', 'secrets.unlocked', 'secrets.set', 'secrets.delete', 'secrets.rename',
     'teams.create', 'teams.add', 'teams.start', 'teams.complete', 'teams.disband',
     'cloud.dispatch', 'cloud.complete', 'cloud.cancel', 'cloud.message',
     'version.install', 'version.switch', 'version.remove',
@@ -119,6 +120,7 @@ const SENSITIVE_PAYLOAD_KEY = /password|secret|token|api[-_]?key|auth/i;
 const RESERVED_META_KEYS = new Set([
     'ts', 'tz', 'tzName', 'hostname', 'platform', 'arch', 'pid', 'ppid',
     'event', 'level', 'caller', 'session', 'osUser', 'transport', 'sshClientIp',
+    'actor', 'kind',
 ]);
 function promptMarker(value) {
     const { prompt_length, prompt_sha256 } = redactPrompt(value);
@@ -276,10 +278,13 @@ function auditOrigin() {
         // Container/edge cases where the uid has no passwd entry.
     }
     const ssh = process.env.SSH_CONNECTION ? parseSshConnection(process.env.SSH_CONNECTION) : undefined;
+    const actor = resolveActor();
     _origin = {
         osUser,
         transport: ssh ? 'ssh' : 'local',
         ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+        actor: actor.id,
+        kind: actor.kind,
     };
     return _origin;
 }
@@ -693,6 +698,7 @@ export function stats(options = {}) {
     const byEvent = {};
     const byModule = {};
     const byUser = {};
+    const byActor = {};
     for (const r of records) {
         const lvl = r.level ?? levelFor(r.event);
         byLevel[lvl] = (byLevel[lvl] ?? 0) + 1;
@@ -701,6 +707,8 @@ export function stats(options = {}) {
             byModule[r.module] = (byModule[r.module] ?? 0) + 1;
         const user = `${r.osUser ?? '?'}@${r.hostname}`;
         byUser[user] = (byUser[user] ?? 0) + 1;
+        if (r.actor)
+            byActor[r.actor] = (byActor[r.actor] ?? 0) + 1;
     }
     let fileCount = 0;
     let totalBytes = 0;
@@ -723,6 +731,7 @@ export function stats(options = {}) {
         byEvent,
         byModule,
         byUser,
+        byActor,
         fileCount,
         totalBytes,
     };

package/dist/lib/exec.js

@@ -20,6 +20,7 @@ import { getShimsDir, getHistoryDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { writeSessionActorRecord } from './session/actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
 import { sessionIdMarkerLine } from './hosts/session-marker.js';
 import { recordRunName } from './session/run-names.js';
@@ -563,13 +564,6 @@ export const AGENT_COMMANDS = {
         },
         modelFlag: '--model',
     },
-    forge: {
-        base: ['forge'],
-        promptFlag: 'positional',
-        modeFlags: {
-            edit: [],
-        },
-    },
 };
 /**
  * Whether `agent` has a native resume form (Tier 1). Derived solely from the
@@ -904,15 +898,28 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
         // wrapper, not the agent binary — the active scan resolves that by
         // walking the candidate's ancestors (readAncestorSessionEntry).
         if (child.pid) {
+            const passthroughSessionId = extractSessionIdArg(rawArgs);
             writePidSessionEntry({
                 pid: child.pid,
                 agent,
-                sessionId: extractSessionIdArg(rawArgs),
+                sessionId: passthroughSessionId,
                 cwd,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
                 launchId,
                 terminalId: process.env.AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
+            // Durable sessionId -> actor record (RUSH-2019) so the scanner can attribute
+            // this session to a person after the pid dies. Best-effort; no-ops without id.
+            if (passthroughSessionId) {
+                writeSessionActorRecord({
+                    sessionId: passthroughSessionId,
+                    actor: resolveActor().id,
+                    initiatedBy: resolveActor().kind,
+                    startedAtMs: Date.now(),
+                });
+            }
         }
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
@@ -1059,6 +1066,8 @@ async function runInTmux(options, executable, args) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd,
+            actor: resolveActor().id,
+            initiatedBy: resolveActor().kind,
             // spawnAgent injected AGENT_LAUNCH_ID into options.env before delegating
             // here; record the same id so the hook (running under the pane-leaf agent
             // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
@@ -1068,6 +1077,14 @@ async function runInTmux(options, executable, args) {
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
+        if (options.sessionId) {
+            writeSessionActorRecord({
+                sessionId: options.sessionId,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
+                startedAtMs: Date.now(),
+            });
+        }
     }
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
@@ -1279,11 +1296,21 @@ async function spawnAgent(options) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
+            actor: resolveActor().id,
+            initiatedBy: resolveActor().kind,
             launchId,
             terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
+        if (options.sessionId) {
+            writeSessionActorRecord({
+                sessionId: options.sessionId,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
+                startedAtMs: Date.now(),
+            });
+        }
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');
         let budgetKilled = false;

package/dist/lib/feed-post.d.ts

@@ -1,4 +1,4 @@
-import { type ActivityEvent } from './activity.js';
+import { type ActivityEvent, type Attachment } from './activity.js';
 import { type PidSessionEntry } from './session/pid-registry.js';
 /** Soft cap so a runaway agent can't flood the activity lane with essays. */
 export declare const STATUS_POST_MAX_CHARS = 500;
@@ -7,8 +7,16 @@ export interface FeedPostInput {
     text: string;
     /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
     sessionId?: string;
+    /** Generic artifacts to attach: local paths (copied for durability) or URLs. */
+    attach?: string[];
     /** Override activity root (tests). */
     activityRoot?: string;
+    /**
+     * Override the attachments store root (tests). Local files are copied under
+     * `<attachmentsRoot>/<sessionId>/<updateId>/`. Defaults to
+     * `~/.agents/.history/attachments`.
+     */
+    attachmentsRoot?: string;
     /** Override env for identity resolution (tests). */
     env?: NodeJS.ProcessEnv;
     /** Override cwd stamp (defaults to process.cwd() / env). */
@@ -55,6 +63,25 @@ export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionI
 export declare function walkPidRegistry(startPid: number, getParent: (pid: number) => number | undefined, readEntry: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
 /** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
 export declare function parentPidOf(pid: number): number | undefined;
+/**
+ * Turn one `--attach` token into an {@link Attachment}. Remote URLs become
+ * `link` (or a media kind when the extension is unambiguous). Local files are
+ * classified by extension and, when `copyRoot` is set, copied under
+ * `<copyRoot>/<sessionId>/<updateId>/<basename>` so the link survives a worktree
+ * delete — the stored `href` then points at the durable copy. A missing local
+ * file is dropped (fail-open) rather than throwing.
+ */
+export declare function buildAttachment(token: string, ctx: {
+    copyRoot?: string;
+    sessionId: string;
+    updateId: string;
+}): Attachment | undefined;
+/** Classify + store every `--attach` token; empty/failed tokens are dropped. */
+export declare function buildAttachments(tokens: string[] | undefined, ctx: {
+    copyRoot?: string;
+    sessionId: string;
+    updateId: string;
+}): Attachment[];
 export declare function normalizeStatusText(text: string): string;
 /**
  * Append a `status.posted` milestone for the calling agent.

package/dist/lib/feed-post.js

@@ -15,7 +15,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, } from './activity.js';
+import { appendActivityEvent, projectFromCwd, } from './activity.js';
+import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
 import { isValidMailboxId } from './mailbox.js';
 import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
@@ -141,6 +142,104 @@ export function parentPidOf(pid) {
     }
     return undefined;
 }
+/** Extension → (kind, mediaType) for attachment classification. */
+const MEDIA_BY_EXT = {
+    '.png': { kind: 'image', mediaType: 'image/png' },
+    '.jpg': { kind: 'image', mediaType: 'image/jpeg' },
+    '.jpeg': { kind: 'image', mediaType: 'image/jpeg' },
+    '.gif': { kind: 'image', mediaType: 'image/gif' },
+    '.svg': { kind: 'image', mediaType: 'image/svg+xml' },
+    '.webp': { kind: 'image', mediaType: 'image/webp' },
+    '.wav': { kind: 'audio', mediaType: 'audio/wav' },
+    '.mp3': { kind: 'audio', mediaType: 'audio/mpeg' },
+    '.m4a': { kind: 'audio', mediaType: 'audio/mp4' },
+    '.aac': { kind: 'audio', mediaType: 'audio/aac' },
+    '.ogg': { kind: 'audio', mediaType: 'audio/ogg' },
+    '.flac': { kind: 'audio', mediaType: 'audio/flac' },
+    '.mp4': { kind: 'video', mediaType: 'video/mp4' },
+    '.mov': { kind: 'video', mediaType: 'video/quicktime' },
+    '.webm': { kind: 'video', mediaType: 'video/webm' },
+    '.mkv': { kind: 'video', mediaType: 'video/x-matroska' },
+};
+/** True when the token is an http(s) URL (a remote attachment / link). */
+function isRemoteUrl(token) {
+    return /^https?:\/\//i.test(token.trim());
+}
+function mediaForExt(ext) {
+    const hit = MEDIA_BY_EXT[ext.toLowerCase()];
+    return hit ? { kind: hit.kind, mediaType: hit.mediaType } : { kind: 'file' };
+}
+/** A short, filesystem-safe id grouping one post's copied attachments. */
+function newUpdateId(ts) {
+    const rand = Math.random().toString(36).slice(2, 8);
+    const stamp = ts.replace(/[^0-9]/g, '').slice(0, 14) || 'post';
+    return `${stamp}-${rand}`;
+}
+/**
+ * Turn one `--attach` token into an {@link Attachment}. Remote URLs become
+ * `link` (or a media kind when the extension is unambiguous). Local files are
+ * classified by extension and, when `copyRoot` is set, copied under
+ * `<copyRoot>/<sessionId>/<updateId>/<basename>` so the link survives a worktree
+ * delete — the stored `href` then points at the durable copy. A missing local
+ * file is dropped (fail-open) rather than throwing.
+ */
+export function buildAttachment(token, ctx) {
+    const value = token.trim();
+    if (!value)
+        return undefined;
+    if (isRemoteUrl(value)) {
+        const ext = path.extname(new URL(value).pathname);
+        const media = mediaForExt(ext);
+        const att = { kind: media.kind === 'file' ? 'link' : media.kind, href: value };
+        const name = path.basename(new URL(value).pathname);
+        if (name)
+            att.name = name;
+        if (media.mediaType)
+            att.mediaType = media.mediaType;
+        return att;
+    }
+    const abs = path.resolve(value);
+    let stat;
+    try {
+        stat = fs.statSync(abs);
+    }
+    catch {
+        return undefined; // dropped: local file does not exist
+    }
+    if (!stat.isFile())
+        return undefined;
+    const media = mediaForExt(path.extname(abs));
+    const name = path.basename(abs);
+    let href = abs;
+    if (ctx.copyRoot) {
+        try {
+            const destDir = path.join(ctx.copyRoot, ctx.sessionId, ctx.updateId);
+            fs.mkdirSync(destDir, { recursive: true });
+            const dest = path.join(destDir, name);
+            fs.copyFileSync(abs, dest);
+            href = dest;
+        }
+        catch {
+            href = abs; // copy failed: fall back to the original path
+        }
+    }
+    const att = { kind: media.kind, href, name, bytes: stat.size };
+    if (media.mediaType)
+        att.mediaType = media.mediaType;
+    return att;
+}
+/** Classify + store every `--attach` token; empty/failed tokens are dropped. */
+export function buildAttachments(tokens, ctx) {
+    if (!tokens?.length)
+        return [];
+    const out = [];
+    for (const token of tokens) {
+        const att = buildAttachment(token, ctx);
+        if (att)
+            out.push(att);
+    }
+    return out;
+}
 export function normalizeStatusText(text) {
     const collapsed = text.replace(/\s+/g, ' ').trim();
     if (!collapsed)
@@ -163,8 +262,15 @@ export function postFeedStatus(input) {
         throw new Error('No session id. Run from an agents-cli session '
             + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
     }
+    const ts = input.ts ?? new Date().toISOString();
+    const project = projectFromCwd(identity.cwd);
+    const attachments = buildAttachments(input.attach, {
+        copyRoot: input.attachmentsRoot ?? path.join(getHistoryDir(), 'attachments'),
+        sessionId: identity.sessionId,
+        updateId: newUpdateId(ts),
+    });
     const event = {
-        ts: input.ts ?? new Date().toISOString(),
+        ts,
         event: 'status.posted',
         sessionId: identity.sessionId,
         mailboxId: identity.mailboxId,
@@ -174,10 +280,12 @@ export function postFeedStatus(input) {
         agent: identity.agent,
         tool: 'feed.post',
         detail,
+        ...(project ? { project } : {}),
         ...(identity.pid !== undefined ? { pid: identity.pid } : {}),
         ...(identity.launchId ? { launchId: identity.launchId } : {}),
         ...(identity.terminalId ? { terminalId: identity.terminalId } : {}),
         ...(identity.tmuxPane ? { tmuxPane: identity.tmuxPane } : {}),
+        ...(attachments.length ? { attachments } : {}),
     };
     appendActivityEvent(event, input.activityRoot);
     return {

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

@@ -86,6 +86,19 @@ export declare function clonePackage(source: string): Promise<{
 }>;
 /** Get the short commit hash (8 chars) of the latest commit in a repo. */
 export declare function getRepoCommit(repoPath: string): Promise<string>;
+/** Compact, self-contained state of a git repo — branch, short HEAD, and a
+ *  dirty flag — for cross-device comparison (RUSH-2027). Synchronous and
+ *  best-effort: a non-repo or unreadable path yields `null` fields, never a
+ *  throw, so a device's `doctor --json` payload always serializes. */
+export interface RepoStateSnapshot {
+    branch: string | null;
+    head: string | null;
+    dirty: boolean;
+}
+/** Read {@link RepoStateSnapshot} for `repoPath` using plumbing commands so the
+ *  result is stable across git versions and never mutates the tree. Returns null
+ *  when the path is not a git worktree. */
+export declare function readRepoState(repoPath: string): RepoStateSnapshot | null;
 /**
  * Get the current GitHub username using gh CLI.
  * Returns null if gh is not installed or user is not authenticated.
@@ -235,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;
@@ -328,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;