@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/fleet/apply.d.ts

@@ -1,48 +1,14 @@
-/**
- * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
- * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
- * the real fleet over SSH and is verified end-to-end against live devices.
- *
- * Flow per device: probe → install/upgrade agents-cli → add missing agents →
- * sync config → propagate login. Every step reuses an existing primitive
- * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
- */
 import type { DeviceProfile } from '../devices/registry.js';
 import type { RemoteBackend } from '../secrets-types.js';
 import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
-/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export declare function agentIdOf(spec: string): string;
-/**
- * The explicit pinned version of a spec, or undefined for an id-level spec.
- * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
- * `claude@all` all return undefined (the label channels install-latest / are
- * expanded upstream, so they diff at id granularity, not per-version).
- */
 export declare function pinnedVersion(spec: string): string | undefined;
-/** True when any spec in the roster pins an explicit version (needs a version probe). */
 export declare function rosterNeedsVersions(desired: DeviceDesired[]): boolean;
-/**
- * Expand any `<agent>@all` spec into one pinned spec per version installed on the
- * source, so `--agent claude@all` replicates THIS machine's exact version set.
- * `versionsOf` returns the source's installed versions for an agent id. Every
- * other spec passes through unchanged; the result is de-duplicated in order.
- * Throws if `@all` names an agent with no installed versions here (nothing to
- * replicate — a clear misconfig, not a silent no-op).
- */
 export declare function expandAllSpecs(specs: string[], versionsOf: (id: string) => string[]): string[];
-/**
- * Parse `agents view --json` (the all-agents array form) into a map of agent id
- * -> installed version strings. Tolerant: returns undefined on any parse failure
- * so a version-pinned spec falls back to id-level presence rather than crashing.
- */
 export declare function parseInstalledVersions(stdout: string): Record<string, string[]> | undefined;
-/** Source-side auth availability, computed once from `snapshotAuth`. */
 export interface SourceAuth {
-    /** Agent ids the source has a readable, propagatable credential file for. */
     available: Set<string>;
-    /** Agent ids whose source auth is device-bound (macOS keychain). */
     bound: Set<string>;
-    /** The captured file payloads, keyed by agent. */
     filesByAgent: Map<string, AuthFilePayload[]>;
 }
 /**
@@ -53,30 +19,20 @@ export interface SourceAuth {
  */
 export declare function fleetSecretsBundles(declared: string[] | undefined): string[];
 interface DiffContext {
-    /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
     sourceAuth: SourceAuth;
-    /** Secrets-bundle names the profile declares. */
     secretsBundles?: string[];
     /** `--provision-secrets`. OFF by default: pushing a bundle moves credential
      *  VALUES to another machine, so it is opted into per invocation and never
      *  defaulted from the shared `agents.yaml` (RUSH-1968). */
     provisionSecrets?: boolean;
-    /** Is this device's host key pinned? Injected so `decideSecretPush` stays pure
-     *  and its refusals are testable against real known_hosts fixtures with no
-     *  network. Absent = treated as unpinned, i.e. refuse. */
     isHostPinned?: (device: string) => boolean;
-    /** `--force`: push a declared bundle even when the device already has it. */
     forceSecrets?: boolean;
 }
-/** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
-/** Why a declared bundle is or is not pushed to one device. */
 interface SecretPushDecision {
     push: boolean;
-    /** Where it would land on the remote. Only meaningful when `push`. */
     backend: RemoteBackend;
-    /** Set when `push` is false — rendered as the `needs-secret` reminder. */
     reason: string;
 }
 /**
@@ -109,26 +65,10 @@ interface SecretPushDecision {
  */
 export declare function decideSecretPush(bundle: string, desired: DeviceDesired, probe: DeviceProbe, ctx: DiffContext): SecretPushDecision;
 interface ProbeOptions {
-    /** Also fetch per-agent installed versions (one extra `agents view --json`
-     * round-trip). Enable only when the plan has a version-pinned spec. */
     withVersions?: boolean;
-    /** Also fetch which secrets bundles the device already has (one extra
-     *  `agents secrets list --json`). Enable only when the manifest declares
-     *  bundles and provisioning is on — same cost discipline as `withVersions`. */
     withSecrets?: boolean;
 }
-/** Probe one device: reachability + agents-cli version + installed agent ids
- * (and, when `withVersions`, the installed version strings per agent). */
 export declare function probeDevice(device: DeviceProfile, opts?: ProbeOptions): DeviceProbe;
-/**
- * Narrow a remote `secrets list --json` payload to `name -> updated_at`.
- *
- * Exported and pure so the parse is unit-tested against real payload shapes with
- * no live fleet. Returns `{}` rather than throwing on anything unexpected: the
- * remote runs its own agents-cli version, and a parse failure must degrade to
- * "unknown, so push" — never to "present, so skip", which would silently leave a
- * device unprovisioned.
- */
 export declare function parseRemoteBundles(stdout: string): Record<string, string>;
 export interface ApplyStep {
     kind: FleetAction['kind'];
@@ -145,13 +85,9 @@ interface ExecContext {
     targetCliVersion: string;
     source: string;
     sourceAuth: SourceAuth;
-    /** Set for a dry run — probe + plan only, execute nothing. */
     dryRun?: boolean;
 }
-/** Run a pool of async tasks with a concurrency cap, preserving input order. */
 export declare function pool<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-/** Reconcile every device row in parallel (capped). */
 export declare function runFleetApply(rows: DeviceDiff[], nameToProfile: Map<string, DeviceProfile>, ctx: ExecContext, concurrency?: number): Promise<DeviceApplyResult[]>;
-/** Default home for source snapshots (overridable in tests). */
 export declare function sourceHome(): string;
 export {};

package/dist/lib/fleet/apply.js

@@ -1,12 +1,3 @@
-/**
- * Reconcile engine for `agents apply`. The diff (`diffFleet`) is pure and unit-
- * tested; execution (`probeDevice`, `reconcileDevice`, `runFleetApply`) drives
- * the real fleet over SSH and is verified end-to-end against live devices.
- *
- * Flow per device: probe → install/upgrade agents-cli → add missing agents →
- * sync config → propagate login. Every step reuses an existing primitive
- * (`readyProbe`, `bootstrapAgentsCli`, `buildRemoteAgentsInvocation`, `sshExec`).
- */
 import * as os from 'os';
 import { pushBundleToHost } from '../secrets-client.js';
 import { AUTH_STORE_ALIAS, inspectReservedAuthBundle, isReservedBundleName } from '../secrets-policy.js';
@@ -15,16 +6,9 @@ import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { sshExec } from '../ssh-exec.js';
 import { hasPortableAuthFiles } from './auth-sync.js';
-/** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export function agentIdOf(spec) {
     return spec.split('@')[0].trim();
 }
-/**
- * The explicit pinned version of a spec, or undefined for an id-level spec.
- * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
- * `claude@all` all return undefined (the label channels install-latest / are
- * expanded upstream, so they diff at id granularity, not per-version).
- */
 export function pinnedVersion(spec) {
     const at = spec.indexOf('@');
     if (at < 0)
@@ -34,18 +18,9 @@ export function pinnedVersion(spec) {
         return undefined;
     return v;
 }
-/** True when any spec in the roster pins an explicit version (needs a version probe). */
 export function rosterNeedsVersions(desired) {
     return desired.some((d) => d.agents.some((s) => pinnedVersion(s) !== undefined));
 }
-/**
- * Expand any `<agent>@all` spec into one pinned spec per version installed on the
- * source, so `--agent claude@all` replicates THIS machine's exact version set.
- * `versionsOf` returns the source's installed versions for an agent id. Every
- * other spec passes through unchanged; the result is de-duplicated in order.
- * Throws if `@all` names an agent with no installed versions here (nothing to
- * replicate — a clear misconfig, not a silent no-op).
- */
 export function expandAllSpecs(specs, versionsOf) {
     const out = [];
     for (const spec of specs) {
@@ -65,11 +40,6 @@ export function expandAllSpecs(specs, versionsOf) {
     }
     return [...new Set(out)];
 }
-/**
- * Parse `agents view --json` (the all-agents array form) into a map of agent id
- * -> installed version strings. Tolerant: returns undefined on any parse failure
- * so a version-pinned spec falls back to id-level presence rather than crashing.
- */
 export function parseInstalledVersions(stdout) {
     try {
         const arr = JSON.parse(stdout);
@@ -103,7 +73,6 @@ export function fleetSecretsBundles(declared) {
     }
     return out;
 }
-/** Pure: desired vs probed -> per-device diff + flat action list. */
 export function diffFleet(desired, probes, ctx) {
     const devices = [];
     const actions = [];
@@ -118,17 +87,12 @@ export function diffFleet(desired, probes, ctx) {
         const loginBlocked = [];
         const secretsNeeded = [];
         if (probe.reachable) {
-            // agents-cli presence.
             if (!probe.cliVersion) {
                 rowActions.push({ device: d.device, kind: 'install-cli', detail: `install agents-cli ${ctx.targetCliVersion}` });
             }
             else if (probe.cliVersion !== ctx.targetCliVersion) {
                 rowActions.push({ device: d.device, kind: 'upgrade-cli', detail: `agents-cli ${probe.cliVersion} -> ${ctx.targetCliVersion}` });
             }
-            // agents. A version-pinned spec (`claude@2.1.170`, or an expanded
-            // `claude@all` member) is present only when that exact version is on the
-            // device; a bare/latest spec diffs at id granularity. So `--agent claude@all`
-            // installs every missing version even when some claude is already there.
             for (const spec of d.agents) {
                 const id = agentIdOf(spec);
                 const want = pinnedVersion(spec);
@@ -139,21 +103,11 @@ export function diffFleet(desired, probes, ctx) {
                     rowActions.push({ device: d.device, kind: 'add-agent', agent: id, spec, detail: `install ${spec}` });
                 }
             }
-            // config.
             if (d.sync.length > 0) {
                 rowActions.push({ device: d.device, kind: 'sync-config', detail: `sync config (${d.sync.join(', ')})` });
             }
-            // login — per agent id, not per spec: `claude@all` names one id many times,
-            // but a login is established once per agent (its credential is version-shared).
             if (d.login === 'sync') {
                 for (const id of [...new Set(d.agents.map(agentIdOf))]) {
-                    // SING-1b: a native OAuth / session login MUST NOT be copied between
-                    // devices — a rotating token invalidates the fleet on its next refresh
-                    // (droid/WorkOS collapsed 10 boxes to 1 overnight). `apply` therefore no
-                    // longer propagates any login; it surfaces per-box login / portable
-                    // provider-account guidance for every agent that has a login to
-                    // establish. An agent with no portable login file, or a source that
-                    // isn't signed in, is silently skipped the same on every OS.
                     if (hasPortableAuthFiles(id)) {
                         loginBlocked.push(id);
                         rowActions.push({
@@ -165,18 +119,6 @@ export function diffFleet(desired, probes, ctx) {
                     }
                 }
             }
-            // secrets. Declared once at the manifest level, so every reachable device
-            // is considered. Historically this was ALWAYS a manual reminder — "surfaced,
-            // never pushed" — and that gap is a direct cause of RUSH-1968: an operator
-            // who needed secrets on a worker box had no supported path, so they
-            // hand-exported the file store's master key across the fleet instead.
-            //
-            // It is now pushable, but only deliberately. `--provision-secrets` is off by
-            // default and is a FLAG, not a manifest field: `agents.yaml` is shared, and
-            // a file-level default would mean someone else's `apply -y` silently ships
-            // credential values — the same shape of accident this ticket is about.
-            // Everything the gate refuses stays a `needs-secret` reminder, so nothing
-            // is ever silently skipped.
             if (ctx.secretsBundles && ctx.secretsBundles.length > 0) {
                 for (const bundle of ctx.secretsBundles) {
                     const decision = decideSecretPush(bundle, d, probe, ctx);
@@ -239,24 +181,11 @@ export function decideSecretPush(bundle, desired, probe, ctx) {
     if (!probe.reachable) {
         return { push: false, backend, reason: manual };
     }
-    // Already there? Skip — otherwise every `apply` re-resolves the bundle, and a
-    // resolve can prompt for Touch ID, so a converged fleet would nag on every run.
-    //
-    // Known limitation, stated rather than hidden: this compares PRESENCE (and
-    // carries `updated_at` for a future content check). It is a timestamp
-    // heuristic, not a content hash — a bundle whose VALUES changed locally still
-    // reads as present. `--force` is the way to overwrite regardless.
-    // hasOwnProperty, NOT `in`: `in` walks the prototype chain, so a bundle named
-    // `toString` / `constructor` / `valueOf` would read as present on an EMPTY map
-    // and be silently skipped — leaving that device unprovisioned, the worse of the
-    // two errors this gate can make.
     if (!ctx.forceSecrets && probe.remoteBundles
         && Object.prototype.hasOwnProperty.call(probe.remoteBundles, bundle)) {
         return { push: false, backend, reason: `secrets bundle '${bundle}' already present on ${device} — pass --force to overwrite` };
     }
     if (!ctx.isHostPinned?.(device)) {
-        // Same bar as `exec --copy-creds`: never ship credential values to a host
-        // whose key we have not pinned.
         return {
             push: false,
             backend,
@@ -265,16 +194,12 @@ export function decideSecretPush(bundle, desired, probe, ctx) {
     }
     return { push: true, backend, reason: '' };
 }
-// ---- execution (real SSH; verified end-to-end, not unit-mocked) ----
 function osHint(platform) {
     return platform === 'windows' ? 'windows' : undefined;
 }
-/** POSIX login shells often miss the shims dir; inject it (mirrors doctor). */
 function remoteEnv(platform) {
     return platform === 'windows' ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
 }
-/** Probe one device: reachability + agents-cli version + installed agent ids
- * (and, when `withVersions`, the installed version strings per agent). */
 export function probeDevice(device, opts) {
     let target;
     try {
@@ -298,7 +223,6 @@ export function probeDevice(device, opts) {
             installed = Object.entries(map).filter(([, e]) => e?.installed).map(([k]) => k);
         }
         catch {
-            /* agents-cli present but doctor output unparsable — treat as no agents */
         }
     }
     let installedVersions;
@@ -310,8 +234,6 @@ export function probeDevice(device, opts) {
     }
     let remoteBundles;
     if (opts?.withSecrets) {
-        // Metadata only — `secrets list --json` returns names + timestamps and never
-        // values, which is why this is safe to run across the fleet.
         const listCmd = buildRemoteAgentsInvocation(['secrets', 'list', '--json'], undefined, hint, remoteEnv(device.platform));
         const lres = sshExec(target, listCmd, { timeoutMs: 30000, multiplex: true, extraSshArgs });
         if (lres.code === 0)
@@ -327,15 +249,6 @@ export function probeDevice(device, opts) {
         remoteBundles,
     };
 }
-/**
- * Narrow a remote `secrets list --json` payload to `name -> updated_at`.
- *
- * Exported and pure so the parse is unit-tested against real payload shapes with
- * no live fleet. Returns `{}` rather than throwing on anything unexpected: the
- * remote runs its own agents-cli version, and a parse failure must degrade to
- * "unknown, so push" — never to "present, so skip", which would silently leave a
- * device unprovisioned.
- */
 export function parseRemoteBundles(stdout) {
     try {
         const parsed = JSON.parse(stdout);
@@ -344,10 +257,6 @@ export function parseRemoteBundles(stdout) {
             : Array.isArray(parsed?.bundles)
                 ? parsed.bundles
                 : [];
-        // Null-prototype: a remote-supplied name is used as a KEY here, so `{}` would
-        // let `__proto__` hit the prototype setter instead of becoming an own
-        // property (and then read back as absent). It also means the presence check
-        // cannot see inherited names.
         const out = Object.create(null);
         for (const row of rows) {
             if (!row || typeof row !== 'object')
@@ -356,9 +265,6 @@ export function parseRemoteBundles(stdout) {
             const name = typeof r.name === 'string' ? r.name : undefined;
             if (!name)
                 continue;
-            // `updatedAt` is the real field name in `secrets list --json` — verified
-            // against a live payload, not assumed. `updated_at` is accepted too so an
-            // older remote is not silently recorded with an empty timestamp.
             const ts = typeof r.updatedAt === 'string' ? r.updatedAt
                 : typeof r.updated_at === 'string' ? r.updated_at
                     : '';
@@ -370,7 +276,6 @@ export function parseRemoteBundles(stdout) {
         return {};
     }
 }
-/** Execute one device's planned actions in order. Real SSH — no mocks. */
 async function reconcileDevice(row, device, ctx) {
     if (!row.probe.reachable) {
         return { device: row.device, ok: false, steps: [], note: row.probe.note ?? 'unreachable' };
@@ -388,24 +293,18 @@ async function reconcileDevice(row, device, ctx) {
     const extraSshArgs = deviceIdentityArgs(device);
     let ok = true;
     const sshAgents = (args, input) => sshExec(target, buildRemoteAgentsInvocation(args, undefined, hint, env), { timeoutMs: 300000, multiplex: true, input, extraSshArgs });
-    // 1. agents-cli install/upgrade.
     const cliAction = row.actions.find((a) => a.kind === 'install-cli' || a.kind === 'upgrade-cli');
     if (cliAction) {
         const r = bootstrapAgentsCli(target, ctx.targetCliVersion, hint, extraSshArgs);
         steps.push({ kind: cliAction.kind, ok: r.ok, detail: cliAction.detail });
         ok = ok && r.ok;
     }
-    // 2. agents. Every add-agent action carries the full spec (set in diffFleet);
-    // install it directly rather than re-parsing the human-readable detail string.
     for (const a of row.actions.filter((x) => x.kind === 'add-agent')) {
         const spec = a.spec;
         const r = sshAgents(['add', spec, '--yes']);
         steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
         ok = ok && r.code === 0;
     }
-    // 3. config sync — one `agents sync <scope>` per declared scope. Each scope is
-    // a positional repo target (system/user/project/alias); a bare `agents sync`
-    // would ignore the profile's declared scopes entirely.
     if (row.actions.some((a) => a.kind === 'sync-config')) {
         const scopes = row.desired.sync.length > 0 ? row.desired.sync : [''];
         let syncOk = true;
@@ -416,22 +315,10 @@ async function reconcileDevice(row, device, ctx) {
         steps.push({ kind: 'sync-config', ok: syncOk, detail: `sync config (${row.desired.sync.join(', ') || 'default'})` });
         ok = ok && syncOk;
     }
-    // 4. Native login materialization does not exist. Every agent that needs a login is surfaced as
-    // `needs-login` (per-box login / portable-account guidance) in the diff above.
-    // 5. secrets provisioning — LAST, and deliberately so. It is the most
-    // sensitive mutation apply performs (credential VALUES crossing to another
-    // machine), so every lower-risk step above is already recorded before we
-    // touch it: a failure here never obscures what did land.
-    //
-    // Resolve ONCE per device even for several bundles is not possible (a resolve
-    // is per bundle), but each bundle resolves once and pushes once — the read can
-    // prompt, so it must not repeat.
     const pushSecrets = row.actions.filter((a) => a.kind === 'push-secret');
     for (const action of pushSecrets) {
         const bundle = action.bundle;
         if (!bundle) {
-            // A push-secret action without a bundle name is a planner bug, not a
-            // recoverable state — fail loud rather than push nothing and report ok.
             steps.push({ kind: 'push-secret', ok: false, detail: 'push-secret action carried no bundle name' });
             ok = false;
             continue;
@@ -441,10 +328,6 @@ async function reconcileDevice(row, device, ctx) {
             const out = await pushBundleToHost(bundle, target, {
                 remoteBackend: backend,
                 operation: `fleet apply ${row.device}`,
-                // No passphrase, ever, from this path. On the file backend the remote
-                // auto-provisions its OWN machine-local key, which is the entire point:
-                // each box gets an unshared at-rest key instead of the fleet-wide shared
-                // secret RUSH-1968 is about.
             });
             steps.push({
                 kind: 'push-secret',
@@ -456,24 +339,18 @@ async function reconcileDevice(row, device, ctx) {
             ok = ok && out.ok;
         }
         catch (e) {
-            // A local resolve failure (locked store, missing bundle, multi-line value)
-            // is reported per bundle rather than aborting the whole device.
             steps.push({ kind: 'push-secret', ok: false, detail: `secrets '${bundle}': ${e.message}` });
             ok = false;
         }
     }
-    // Surface blocked logins as (non-fatal) informational steps.
     for (const blocked of row.loginBlocked) {
         steps.push({ kind: 'needs-login', ok: false, detail: `${blocked} needs a manual login (\`agents ssh ${row.device} -- ${blocked}\`)` });
     }
-    // Surface declared secrets bundles as (non-fatal) manual-recreate reminders —
-    // values are keychain-local, never captured or pushed.
     for (const bundle of row.secretsNeeded) {
         steps.push({ kind: 'needs-secret', ok: false, detail: `secrets bundle '${bundle}' must exist on ${row.device} (\`agents ssh ${row.device} -- secrets create ${bundle}\`)` });
     }
     return { device: row.device, ok, steps };
 }
-/** Run a pool of async tasks with a concurrency cap, preserving input order. */
 export async function pool(items, limit, fn) {
     const results = new Array(items.length);
     let next = 0;
@@ -488,7 +365,6 @@ export async function pool(items, limit, fn) {
     await Promise.all(workers);
     return results;
 }
-/** Reconcile every device row in parallel (capped). */
 export async function runFleetApply(rows, nameToProfile, ctx, concurrency = 6) {
     return pool(rows, concurrency, async (row) => {
         const profile = nameToProfile.get(row.device);
@@ -497,7 +373,6 @@ export async function runFleetApply(rows, nameToProfile, ctx, concurrency = 6) {
         return reconcileDevice(row, profile, ctx);
     });
 }
-/** Default home for source snapshots (overridable in tests). */
 export function sourceHome() {
     return os.homedir();
 }

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

@@ -1,65 +1,17 @@
-/**
- * Native-login inventory for `agents apply`.
- * Native OAuth/session files are identified only to report device readiness;
- * agents-cli never serializes or materializes them on another device.
- *
- * Honest boundary: on macOS, claude and antigravity keep their tokens in the
- * login keychain, ACL-bound to the harness process — unreadable by us. Those are
- * classified `bound` and surfaced for a one-time manual login, never faked.
- */
 import type { AuthSnapshotResult } from './types.js';
-/** A portable credential file location, relative to $HOME. */
 interface AuthFileSpec {
     rel: string;
     mode: number;
 }
-/**
- * Verified portable auth-file locations per agent (home-relative). Sourced from
- * live inspection of a Linux fleet box + the agent registry. Agents absent here
- * have no portable credential file we can propagate.
- */
 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 `usage.ts` for the per-machine-login policy.
- */
 export declare const SINGLE_USE_ROTATING_REFRESH_AGENTS: ReadonlySet<string>;
-/**
- * Whether `agent`'s login may be copied between machines by `apply`. Always
- * **false** now (RUSH-2527): every `FLEET_AUTH_FILES` entry is a native,
- * rotating OAuth / session login, and the fleet-auth contract forbids copying any
- * of them between devices (`docs/specifications.md` SING-1b) — not just the
- * single-use-rotating subset (`SINGLE_USE_ROTATING_REFRESH_AGENTS`) that first
- * motivated this gate. `apply` therefore never propagates a login; it surfaces
- * per-box login / portable-account guidance instead. `snapshotAuth` reads no
- * credential file as a result, so a native login never leaves its origin box.
- * The `agent` parameter is retained for the stable call signature.
- */
 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;
 export interface SnapshotOptions {
-    /** Home directory to read credential files from. */
     home: string;
-    /** Platform of the source machine (`process.platform`). */
     platform: NodeJS.Platform;
 }
-/**
- * Capture portable credential files for the given agents from a source home.
- * Returns the readable file payloads plus the list of agents whose auth is
- * device-bound (macOS keychain) and therefore cannot be captured. Agents that
- * are simply not signed in (no file on disk) are silently omitted — nothing to
- * propagate, not an error.
- */
 export declare function snapshotAuth(agents: string[], opts: SnapshotOptions): AuthSnapshotResult;
 export {};

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

@@ -1,19 +1,5 @@
-/**
- * Native-login inventory for `agents apply`.
- * Native OAuth/session files are identified only to report device readiness;
- * agents-cli never serializes or materializes them on another device.
- *
- * Honest boundary: on macOS, claude and antigravity keep their tokens in the
- * login keychain, ACL-bound to the harness process — unreadable by us. Those are
- * classified `bound` and surfaced for a one-time manual login, never faked.
- */
 import * as fs from 'fs';
 import * as path from 'path';
-/**
- * Verified portable auth-file locations per agent (home-relative). Sourced from
- * live inspection of a Linux fleet box + the agent registry. Agents absent here
- * have no portable credential file we can propagate.
- */
 export const FLEET_AUTH_FILES = {
     claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
     codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
@@ -26,57 +12,26 @@ export const FLEET_AUTH_FILES = {
     ],
     antigravity: [{ rel: '.gemini/antigravity-cli/antigravity-oauth-token', mode: 0o600 }],
 };
-/** 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 `usage.ts` for the per-machine-login policy.
- */
 export const SINGLE_USE_ROTATING_REFRESH_AGENTS = new Set(['droid']);
-/**
- * Whether `agent`'s login may be copied between machines by `apply`. Always
- * **false** now (RUSH-2527): every `FLEET_AUTH_FILES` entry is a native,
- * rotating OAuth / session login, and the fleet-auth contract forbids copying any
- * of them between devices (`docs/specifications.md` SING-1b) — not just the
- * single-use-rotating subset (`SINGLE_USE_ROTATING_REFRESH_AGENTS`) that first
- * motivated this gate. `apply` therefore never propagates a login; it surfaces
- * per-box login / portable-account guidance instead. `snapshotAuth` reads no
- * credential file as a result, so a native login never leaves its origin box.
- * The `agent` parameter is retained for the stable call signature.
- */
 export function isCredentialSafeToPropagate(_agent) {
     return false;
 }
-/** 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 hasPortableAuthFiles(agent) && isCredentialSafeToPropagate(agent);
 }
-/**
- * Capture portable credential files for the given agents from a source home.
- * Returns the readable file payloads plus the list of agents whose auth is
- * device-bound (macOS keychain) and therefore cannot be captured. Agents that
- * are simply not signed in (no file on disk) are silently omitted — nothing to
- * propagate, not an error.
- */
 export function snapshotAuth(agents, opts) {
     const files = [];
     const bound = [];
     for (const agent of agents) {
         const specs = FLEET_AUTH_FILES[agent];
         if (!specs)
-            continue; // no portable file — caller surfaces separately if desired
+            continue;
         if (!isCredentialSafeToPropagate(agent))
-            continue; // single-use rotating refresh tokens are never copied
+            continue;
         if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
             bound.push(agent);
             continue;
@@ -88,11 +43,11 @@ export function snapshotAuth(agents, opts) {
                 stat = fs.statSync(abs);
             }
             catch {
-                continue; // not signed in for this agent — nothing to carry
+                continue;
             }
             if (!stat.isFile())
                 continue;
-            const content = fs.readFileSync(abs); // follows symlinks into version homes
+            const content = fs.readFileSync(abs);
             files.push({
                 agent,
                 rel: spec.rel,

package/dist/lib/fleet/capture.d.ts

@@ -1,35 +1,9 @@
-/**
- * Serialize the live environment into a `fleet:` manifest.
- *
- * `captureFleet` is PURE — it takes the previous manifest plus already-gathered
- * inputs (device names, per-device agent specs, browser profiles, secret-bundle
- * names, routine names) and returns the new manifest. All I/O (registry read,
- * `agents secrets`/`routines` enumeration, YAML write) happens in the command
- * (`commands/fleet-capture.ts`); keeping this pure makes the privacy contract —
- * NAMES ONLY, never IPs/usernames — trivially unit-testable.
- *
- * Additive by design: it merges OVER an existing manifest and never clobbers a
- * hand-authored per-device override (`agents:` you set by hand wins over a
- * captured one). The captured roster reflects live state, so it becomes the
- * source of truth for WHICH devices exist.
- */
 import type { FleetManifest, FleetDefaults } from './types.js';
 export interface CaptureInputs {
-    /** Registered device names to record (the roster — names only). */
     devices: string[];
-    /** Optional per-device agent specs (e.g. from `--from-pins`), keyed by name. */
     agentsByDevice?: Record<string, string[]>;
-    /** Fleet defaults to seed when the manifest has none (source's own agents). */
     defaults?: FleetDefaults;
-    /** Secrets-bundle NAMES to ensure exist (values stay in the keychain). */
     secretsBundles?: string[];
-    /** Routine NAMES that should be active on the fleet. */
     routines?: string[];
 }
-/**
- * Build the new `fleet:` manifest from the previous one and captured inputs.
- * Pure — no SSH, no filesystem, no registry. The returned object carries device
- * names + desired state only; a caller that serializes it to YAML can assert no
- * address/username ever appears.
- */
 export declare function captureFleet(prev: FleetManifest | undefined, inputs: CaptureInputs): FleetManifest;