@phnx-labs/agents-cli 1.20.68 → 1.20.70

package/dist/lib/rotate.d.ts

@@ -11,6 +11,8 @@ import { type UsageSnapshot } from './usage.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;
+    accountKey: string | null;
+    accountLabel: string;
     email: string | null;
     /**
      * Per-org usage/quota key (e.g. `claude:org=<orgUuid>`) — the unit rate
@@ -21,7 +23,9 @@ export interface RotateCandidate {
     usageKey: string | null;
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
-    authValid: boolean;
+    usageError: string | null;
+    plan: string | null;
+    signedIn: boolean;
     lastActive: Date | null;
 }
 export interface RotateResult {
@@ -58,7 +62,7 @@ export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: str
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
- * why. `signed_out` covers no-email / invalid-auth; `rate_limited` and
+ * why. `signed_out` covers a missing usable credential; `rate_limited` and
  * `out_of_credits` name the throttle. Used to pre-warn on a version-pinned
  * teammate whose account rotation won't route around (a pin IS the target).
  */
@@ -71,7 +75,7 @@ export type AccountReadiness = {
 };
 /**
  * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
- * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * + canonical signed-in state, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
  * disagree with what rotation would actually do. The `reason` combines the two
  * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
  * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
@@ -100,17 +104,16 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and not currently
+ * Eligibility: signed in according to AccountInfo and not currently
  * rate-limited — no blocking window (session OR weekly) at 100%, matching the
  * `agents view` badge; or the local cached status is usable when no live
  * snapshot exists. Note the split: eligibility considers the session window
  * (a session-maxed account can't run now), but the capacity *weight* above is
  * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
- * Dedupe: when multiple versions share an email, collapse to one candidate
- * per email (the least-recently-active version). Prevents two parallel pods
- * from "balancing" to different versions but hitting the same Anthropic
- * account and both 429ing.
+ * Dedupe: when multiple versions share a usage/account identity, collapse to
+ * one candidate (the least-recently-active version). The org-scoped usage key
+ * wins over email so same-email personal and Team accounts remain distinct.
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
@@ -122,6 +125,7 @@ export declare function pickBalancedCandidate(candidates: RotateCandidate[]): Ro
  * usage headroom.
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
+export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
 /**
  * Pick a healthy version for `agent` using weighted random by remaining
  * capacity. See `pickBalancedCandidate` for algorithm details.

package/dist/lib/rotate.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { getAccountInfo } from './agents.js';
+import { accountDisplayLabel, getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
@@ -65,14 +65,10 @@ export function setGlobalRunStrategy(agent, strategy) {
     writeMeta(meta);
 }
 function isRotationEligible(candidate) {
-    return !!candidate.email
-        && candidate.authValid
-        && hasUsageAvailable(candidate);
+    return candidate.signedIn && hasUsageAvailable(candidate);
 }
 function isAvailableEligible(candidate) {
-    return !!candidate.email
-        && candidate.authValid
-        && hasUsageAvailable(candidate);
+    return isRotationEligible(candidate);
 }
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
@@ -95,7 +91,7 @@ function hasUsageAvailable(candidate) {
 }
 /**
  * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
- * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * + canonical signed-in state, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
  * disagree with what rotation would actually do. The `reason` combines the two
  * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
  * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
@@ -104,7 +100,7 @@ function hasUsageAvailable(candidate) {
  * reported while the account is actually serving requests.
  */
 export function readinessFromCandidate(candidate) {
-    if (!candidate.email || !candidate.authValid) {
+    if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
     if (hasUsageAvailable(candidate)) {
@@ -162,7 +158,7 @@ function compareCandidates(a, b) {
  * key; fall back to email only when no usage identity is available.
  */
 function candidateIdentity(c) {
-    return c.usageKey ?? c.email;
+    return c.usageKey ?? c.accountKey ?? c.email ?? `${c.agent}@${c.version}`;
 }
 function dedupeAndSortCandidates(candidates) {
     const byIdentity = new Map();
@@ -189,17 +185,16 @@ function dedupeAndSortCandidates(candidates) {
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and not currently
+ * Eligibility: signed in according to AccountInfo and not currently
  * rate-limited — no blocking window (session OR weekly) at 100%, matching the
  * `agents view` badge; or the local cached status is usable when no live
  * snapshot exists. Note the split: eligibility considers the session window
  * (a session-maxed account can't run now), but the capacity *weight* above is
  * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
- * Dedupe: when multiple versions share an email, collapse to one candidate
- * per email (the least-recently-active version). Prevents two parallel pods
- * from "balancing" to different versions but hitting the same Anthropic
- * account and both 429ing.
+ * Dedupe: when multiple versions share a usage/account identity, collapse to
+ * one candidate (the least-recently-active version). The org-scoped usage key
+ * wins over email so same-email personal and Team accounts remain distinct.
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
@@ -278,12 +273,11 @@ export function pickAvailableCandidate(candidates, preferredVersion) {
         : undefined;
     return { picked: preferred ?? sorted[0], healthy: sorted, excluded };
 }
-async function collectRunCandidates(agent) {
+export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
     const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
-        // `info.email` (from .claude.json's oauthAccount) is the auth heuristic.
         // We used to additionally call isClaudeAuthValid(home), which reads
         // "Claude Code-credentials-<hash>" from the system keychain. That item is
         // written by Claude Code itself with its own process in the ACL, so our
@@ -291,15 +285,17 @@ async function collectRunCandidates(agent) {
         // one per installed version, every time `agents run` cold-starts. If
         // claude's stored token has actually expired, the spawned agent detects
         // it at its own startup and re-auths; that's the correct UX.
-        const authValid = info.email != null;
         return {
             agent,
             version,
             home,
             info,
+            accountKey: info.accountKey,
+            accountLabel: accountDisplayLabel(info),
             email: info.email,
             usageStatus: info.usageStatus,
-            authValid,
+            plan: info.plan,
+            signedIn: info.signedIn,
             lastActive: info.lastActive,
         };
     }));
@@ -311,10 +307,13 @@ async function collectRunCandidates(agent) {
     })));
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
-        const usageSnapshot = usageKey
-            ? usageByKey.get(usageKey)?.snapshot ?? null
-            : null;
-        return { ...candidate, usageKey, usageSnapshot };
+        const usage = usageKey ? usageByKey.get(usageKey) : undefined;
+        return {
+            ...candidate,
+            usageKey,
+            usageSnapshot: usage?.snapshot ?? null,
+            usageError: usage?.error ?? null,
+        };
     });
 }
 /**

package/dist/lib/session/fork.d.ts

@@ -0,0 +1,32 @@
+import type { SessionMeta } from './types.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export declare const FORKABLE_AGENTS: readonly ["claude"];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export declare function isForkableAgent(agent: string): boolean;
+/** Outcome of a successful fork. */
+export interface ForkResult {
+    /** The new session's full id. */
+    newId: string;
+    /** The new session's short id (first 8 chars), for display/resume. */
+    shortId: string;
+    /** Absolute path of the copied transcript. */
+    filePath: string;
+    /** The label applied to the fork. */
+    label: string;
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export declare function forkSession(source: SessionMeta, opts?: {
+    name?: string;
+    now?: string;
+}): ForkResult;

package/dist/lib/session/fork.js

@@ -0,0 +1,101 @@
+/**
+ * Session forking — branch an existing conversation into a new, independent
+ * session that can be continued separately, leaving the original untouched.
+ *
+ * `resume` continues the SAME conversation (same id, same file — it appends).
+ * `fork` copies the transcript under a FRESH session id, so continuing the fork
+ * diverges from the original instead of mutating it. This is the "git branch"
+ * of conversations.
+ *
+ * v1 supports Claude, whose session id IS its `<id>.jsonl` filename and which
+ * resumes natively via `--resume`. A fork is therefore: copy the transcript to
+ * a new-uuid filename in the same directory, rewrite the embedded `sessionId`
+ * on each line, register the new session in the index, and label it. Other
+ * agents (codex single-file; grok/kimi multi-file; opencode DB-only) are a
+ * natural follow-up and are refused up front for now.
+ */
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { upsertSession } from './db.js';
+import { recordRunName } from './run-names.js';
+/** Agents that `fork` can branch today (see the module doc for why). */
+export const FORKABLE_AGENTS = ['claude'];
+/** Whether a session's agent can be forked by {@link forkSession}. */
+export function isForkableAgent(agent) {
+    return FORKABLE_AGENTS.includes(agent);
+}
+/**
+ * Rewrite the per-line `sessionId` field of a Claude JSONL transcript to a new
+ * id. Claude resolves a conversation by its filename, so this is belt-and-braces
+ * (keeps the in-file id consistent with the new filename); malformed lines are
+ * passed through untouched.
+ */
+function rewriteSessionId(transcript, newId) {
+    return transcript
+        .split('\n')
+        .map((line) => {
+        if (!line.trim())
+            return line;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.sessionId === 'string') {
+                obj.sessionId = newId;
+                return JSON.stringify(obj);
+            }
+            return line;
+        }
+        catch {
+            return line;
+        }
+    })
+        .join('\n');
+}
+/**
+ * Fork a Claude session into a new, independent one.
+ *
+ * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
+ * embedded session id, registers the new session in the index, and records a
+ * `--name`-style label. Returns the new ids/path. Throws if the source
+ * transcript is missing.
+ *
+ * @param source  The resolved metadata of the session being forked.
+ * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
+ * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ */
+export function forkSession(source, opts = {}) {
+    if (!fs.existsSync(source.filePath)) {
+        throw new Error(`transcript not found for session ${source.shortId}: ${source.filePath}`);
+    }
+    const newId = randomUUID();
+    const shortId = newId.slice(0, 8);
+    const dir = path.dirname(source.filePath);
+    const filePath = path.join(dir, `${newId}.jsonl`);
+    const transcript = fs.readFileSync(source.filePath, 'utf-8');
+    const rewritten = rewriteSessionId(transcript, newId);
+    fs.writeFileSync(filePath, rewritten);
+    const original = source.label || source.topic || source.shortId;
+    const label = opts.name || `fork of ${original}`;
+    // Label sidecar (seeds the DB label; survives rescans until an agent title
+    // supersedes it), mirroring `agents run --name`.
+    recordRunName({ sessionId: newId, name: label, agent: source.agent, cwd: source.cwd });
+    // Register the new session so it resolves immediately (by `agents resume`,
+    // `agents sessions`, etc.) without waiting for the next scan.
+    const stamp = opts.now ?? new Date().toISOString();
+    const meta = {
+        ...source,
+        id: newId,
+        shortId,
+        filePath,
+        label,
+        timestamp: stamp,
+        lastActivity: stamp,
+        // The fork has not opened its own PR / team; drop origin-specific refs.
+        prUrl: undefined,
+        prNumber: undefined,
+        teamOrigin: undefined,
+        spawnedTeam: undefined,
+    };
+    upsertSession(meta, rewritten);
+    return { newId, shortId, filePath, label };
+}

package/dist/lib/startup/command-registry.d.ts

@@ -45,6 +45,7 @@ export declare const loadDaemon: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
 export declare const loadRun: ModuleLoader;
+export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadModels: ModuleLoader;
 export declare const loadPrune: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -23,6 +23,7 @@ export const loadDaemon = async () => (await import('../../commands/daemon.js'))
 export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
+export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
 export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
@@ -126,6 +127,7 @@ export const COMMAND_LOADERS = {
     routines: [loadRoutines],
     monitors: [loadMonitors],
     run: [loadRun],
+    fork: [loadFork],
     defaults: [loadDefaults],
     models: [loadModels],
     trash: [loadTrash],

package/dist/lib/usage.d.ts

@@ -184,6 +184,29 @@ export interface DroidBillingLimitsResponse {
         } | null;
     } | null;
 }
+/**
+ * Live auth probes — the same authenticated GET the usage fetchers above do,
+ * but surfacing the raw HTTP status instead of swallowing 401/expired to null.
+ * These back `agents fleet ping` and the fleet auth-health cache: completing a
+ * real request is the only proof a token is accepted. The local "signed in"
+ * flag cannot tell a revoked-but-unexpired token from a good one. Classification
+ * of the returned status into a verdict lives in lib/auth-health.ts (kept there
+ * so it stays pure/testable and to avoid an import cycle).
+ */
+export interface ProviderProbe {
+    /** HTTP status of the probe request, or null when no request was made (missing/expired token) or the request threw. */
+    status: number | null;
+    /** Local credential state observed before the request. */
+    token: 'present' | 'missing' | 'expired';
+    /** Network/parse error message when status is null but a token was present. */
+    error?: string;
+}
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export declare function probeClaudeStatus(home?: string, cliVersion?: string | null): Promise<ProviderProbe>;
+/** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
+export declare function probeKimiStatus(home?: string): Promise<ProviderProbe>;
+/** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
+export declare function probeDroidStatus(home?: string): Promise<ProviderProbe>;
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no

package/dist/lib/usage.js

@@ -609,6 +609,90 @@ async function getDroidUsageInfo(options) {
         return { snapshot: null, error: null };
     }
 }
+/** Probe Claude's OAuth token against the usage endpoint. Refreshes an expired access token (safe for Claude). */
+export async function probeClaudeStatus(home, cliVersion) {
+    const oauth = await loadClaudeOauth(home);
+    if (!oauth?.accessToken)
+        return { status: null, token: 'missing' };
+    let access = null;
+    try {
+        access = await getClaudeAccessToken(oauth, home);
+    }
+    catch {
+        access = null;
+    }
+    // Fall back to the stored (possibly stale) token so the server returns the
+    // real verdict — a 401 here IS the revoked/expired signal we want to surface.
+    const bearer = access || oauth.accessToken.trim();
+    try {
+        const response = await fetch(CLAUDE_USAGE_URL, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${bearer}`,
+                'Content-Type': 'application/json',
+                'anthropic-beta': CLAUDE_OAUTH_BETA_HEADER,
+                'User-Agent': getClaudeUserAgent(cliVersion),
+            },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Kimi's OAuth token against the /usages endpoint. Never refreshes (single-use rotation — see getKimiUsageInfo). */
+export async function probeKimiStatus(home) {
+    const credPath = resolveKimiCredentialPath(home);
+    if (!credPath)
+        return { status: null, token: 'missing' };
+    let accessToken;
+    let expiresAt = null;
+    try {
+        const cred = JSON.parse(fs.readFileSync(credPath, 'utf-8'));
+        accessToken = typeof cred?.access_token === 'string' ? cred.access_token : undefined;
+        expiresAt = typeof cred?.expires_at === 'number' ? cred.expires_at : null;
+    }
+    catch {
+        return { status: null, token: 'missing' };
+    }
+    if (!accessToken)
+        return { status: null, token: 'missing' };
+    if (expiresAt !== null && Date.now() / 1000 >= expiresAt)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(KIMI_USAGES_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Probe Droid's WorkOS token against the billing-limits endpoint. Never refreshes (single-use rotation — see getDroidUsageInfo). */
+export async function probeDroidStatus(home) {
+    const cred = decryptDroidAuthPayload(home || os.homedir());
+    const accessToken = cred?.access_token;
+    if (typeof accessToken !== 'string' || !accessToken)
+        return { status: null, token: 'missing' };
+    const exp = decodeJwtPayload(accessToken)?.exp;
+    if (typeof exp === 'number' && Date.now() / 1000 >= exp)
+        return { status: null, token: 'expired' };
+    try {
+        const response = await fetch(DROID_USAGE_URL, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${accessToken}`, Accept: 'application/json' },
+            signal: AbortSignal.timeout(8000),
+        });
+        return { status: response.status, token: 'present' };
+    }
+    catch (err) {
+        return { status: null, token: 'present', error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Normalize the Factory billing-limits payload into the common UsageWindow
  * shape. Orgs on the legacy (non token-rate-limit) billing model have no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.68",
+  "version": "1.20.70",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",