@phnx-labs/agents-cli 1.22.7 → 1.22.9

package/dist/lib/observe-aliases.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Observe-umbrella aliases (Phase 3 surface consolidation).
+ *
+ * Thin name → real command expansion. No store merge — feed / sessions / events
+ * remain the stores; these are doors that point at the right reader.
+ *
+ *   inbox    → feed                  (needs-you default)
+ *   timeline → feed --filter updates (agent progress stream)
+ *   roster   → sessions --active     (live agent roster)
+ *
+ * `audit` is NOT an alias here — `agents audit` is already the tamper-evident
+ * run-dispatch log. Ops trail = `agents events` (optionally `--audit`).
+ */
+export type ObserveAlias = 'inbox' | 'timeline' | 'roster';
+export declare const OBSERVE_ALIASES: readonly ObserveAlias[];
+export interface ObserveExpandResult {
+    /** argv for the real command (no program name): e.g. ['feed', '--filter', 'updates'] */
+    argv: string[];
+    /** One-line note for stderr (optional); empty when silent. */
+    note: string;
+}
+/** True when `rest` already carries a `--filter` / `--filter=…` flag. */
+export declare function hasFilterFlag(rest: readonly string[]): boolean;
+/** True when `rest` already carries `--active`. */
+export declare function hasActiveFlag(rest: readonly string[]): boolean;
+/**
+ * Expand an observe alias + remaining user args into the real command argv.
+ * Returns null when `alias` is not an observe alias.
+ */
+export declare function expandObserveAlias(alias: string, rest?: readonly string[]): ObserveExpandResult | null;

package/dist/lib/observe-aliases.js

@@ -0,0 +1,56 @@
+/**
+ * Observe-umbrella aliases (Phase 3 surface consolidation).
+ *
+ * Thin name → real command expansion. No store merge — feed / sessions / events
+ * remain the stores; these are doors that point at the right reader.
+ *
+ *   inbox    → feed                  (needs-you default)
+ *   timeline → feed --filter updates (agent progress stream)
+ *   roster   → sessions --active     (live agent roster)
+ *
+ * `audit` is NOT an alias here — `agents audit` is already the tamper-evident
+ * run-dispatch log. Ops trail = `agents events` (optionally `--audit`).
+ */
+export const OBSERVE_ALIASES = ['inbox', 'timeline', 'roster'];
+/** True when `rest` already carries a `--filter` / `--filter=…` flag. */
+export function hasFilterFlag(rest) {
+    return rest.some((a) => a === '--filter' || a.startsWith('--filter='));
+}
+/** True when `rest` already carries `--active`. */
+export function hasActiveFlag(rest) {
+    return rest.some((a) => a === '--active');
+}
+/**
+ * Expand an observe alias + remaining user args into the real command argv.
+ * Returns null when `alias` is not an observe alias.
+ */
+export function expandObserveAlias(alias, rest = []) {
+    const tail = [...rest];
+    switch (alias) {
+        case 'inbox':
+            return {
+                argv: ['feed', ...tail],
+                note: 'agents inbox → agents feed (needs-you inbox)',
+            };
+        case 'timeline': {
+            const argv = hasFilterFlag(tail)
+                ? ['feed', ...tail]
+                : ['feed', '--filter', 'updates', ...tail];
+            return {
+                argv,
+                note: 'agents timeline → agents feed --filter updates',
+            };
+        }
+        case 'roster': {
+            const argv = hasActiveFlag(tail)
+                ? ['sessions', ...tail]
+                : ['sessions', '--active', ...tail];
+            return {
+                argv,
+                note: 'agents roster → agents sessions --active',
+            };
+        }
+        default:
+            return null;
+    }
+}

package/dist/lib/placement.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+/** Where a job body executes. */
+export type PlacementKind = 'local' | 'device' | 'fleet' | 'cloud' | 'lease';
+/**
+ * Canonical placement object.
+ *
+ *   kind: local  — this machine
+ *   kind: device — named box or affinity pick (target: name | "auto")
+ *   kind: fleet  — pick one online device at fire time (routines)
+ *   kind: cloud  — vendor cloud dispatch
+ *   kind: lease  — disposable crabbox (target: optional backend)
+ */
+export interface Placement {
+    kind: PlacementKind;
+    /** Device/host name, "auto", lease backend, or undefined. */
+    target?: string;
+    /** Flag or path that produced this (errors / diagnostics). */
+    source: string;
+}
+/** Run-flag bag the placement parser understands. */
+export interface RunPlacementFlags {
+    where?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    lease?: string | boolean;
+    box?: string;
+}
+export declare class PlacementError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export declare function parseWhereSpec(raw: string, source?: string): Placement;
+/** First non-empty host-family flag value (host / device / on / computer). */
+export declare function hostFamilyTarget(flags: RunPlacementFlags): string | undefined;
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export declare function placementFromRunFlags(flags: RunPlacementFlags): Placement;
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export declare function expandPlacementToRunFlags(placement: Placement): Pick<RunPlacementFlags, 'host' | 'device' | 'lease' | 'box'>;
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export declare function placementFromHostStrategy(strategy: 'local' | 'host' | 'fleet' | 'cloud', host?: string): Placement;
+/** One-line human form for logs / help. */
+export declare function formatPlacement(p: Placement): string;
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export declare const PLACEMENT_MATRIX: string;

package/dist/lib/placement.js

@@ -0,0 +1,188 @@
+/**
+ * Placement — one model for "where does the body run?"
+ *
+ * The CLI grew several doors that all mean execution target:
+ *   run --host / --device / --lease / --box
+ *   routines --placement / --run-on / hostStrategy
+ *   monitors --run-on (body) vs --device (owner — NOT placement)
+ *   teams --device (teammate pin)
+ *   cloud run --provider host
+ *
+ * This module is the shared vocabulary. Old flags remain; --where is a
+ * thin alias on `agents run` that expands into them. Docs and help teach
+ * the matrix; stores stay separate (device registry, lease boxes, cloud).
+ *
+ * Owner (who may fire / evaluate) is NOT placement — see monitors.
+ */
+export class PlacementError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlacementError';
+    }
+}
+const KINDS = new Set(['local', 'device', 'fleet', 'cloud', 'lease', 'host']);
+/**
+ * Parse a `--where` / placement spec string.
+ *
+ * Accepted forms:
+ *   local
+ *   device[:name] | host[:name]   (bare name → device:<name>)
+ *   device:auto | auto | host:auto
+ *   fleet
+ *   cloud
+ *   lease[:backend]
+ */
+export function parseWhereSpec(raw, source = '--where') {
+    const spec = raw.trim();
+    if (!spec) {
+        throw new PlacementError(`${source} requires a value (local | device:<name> | auto | lease | cloud | fleet)`);
+    }
+    const lower = spec.toLowerCase();
+    if (lower === 'local')
+        return { kind: 'local', source };
+    if (lower === 'auto')
+        return { kind: 'device', target: 'auto', source };
+    if (lower === 'fleet')
+        return { kind: 'fleet', source };
+    if (lower === 'cloud')
+        return { kind: 'cloud', source };
+    if (lower === 'lease')
+        return { kind: 'lease', source };
+    const colon = spec.indexOf(':');
+    if (colon === -1) {
+        // Bare token that is not a reserved kind → device target.
+        if (KINDS.has(lower)) {
+            // "device" / "host" alone means device with no pin (invalid for run).
+            throw new PlacementError(`${source} ${spec}: name a target (device:<name>, device:auto) or use local|lease|cloud|fleet`);
+        }
+        return { kind: 'device', target: spec, source };
+    }
+    const head = spec.slice(0, colon).toLowerCase();
+    const tail = spec.slice(colon + 1).trim();
+    if (!tail) {
+        throw new PlacementError(`${source} ${spec}: missing target after ':'`);
+    }
+    if (head === 'device' || head === 'host') {
+        return { kind: 'device', target: tail, source };
+    }
+    if (head === 'lease') {
+        return { kind: 'lease', target: tail, source };
+    }
+    if (head === 'cloud') {
+        return { kind: 'cloud', target: tail, source };
+    }
+    if (head === 'fleet') {
+        return { kind: 'fleet', target: tail, source };
+    }
+    throw new PlacementError(`${source} ${spec}: unknown kind '${head}' (use local | device:<name> | auto | lease[:backend] | cloud | fleet)`);
+}
+/** First non-empty host-family flag value (host / device / on / computer). */
+export function hostFamilyTarget(flags) {
+    for (const v of [flags.host, flags.device, flags.on, flags.computer]) {
+        if (v)
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Resolve placement from run flags. `--where` wins only when no other
+ * placement flag is set; mixing is a PlacementError.
+ */
+export function placementFromRunFlags(flags) {
+    const where = flags.where?.trim();
+    const hostT = hostFamilyTarget(flags);
+    const hasLease = flags.lease !== undefined && flags.lease !== false;
+    const hasBox = !!flags.box;
+    const placementFlags = [];
+    if (where)
+        placementFlags.push('--where');
+    if (hostT)
+        placementFlags.push('--host/--device');
+    if (hasLease)
+        placementFlags.push('--lease');
+    if (hasBox)
+        placementFlags.push('--box');
+    if (placementFlags.length > 1) {
+        throw new PlacementError(`Conflicting placement flags: ${placementFlags.join(' + ')}. ` +
+            `Use one door — prefer --where (device:<name> | auto | lease | local).`);
+    }
+    if (where)
+        return parseWhereSpec(where, '--where');
+    if (hasBox)
+        return { kind: 'lease', target: flags.box, source: '--box' };
+    if (hasLease) {
+        const backend = typeof flags.lease === 'string' ? flags.lease : undefined;
+        return { kind: 'lease', target: backend, source: '--lease' };
+    }
+    if (hostT)
+        return { kind: 'device', target: hostT, source: '--host/--device' };
+    return { kind: 'local', source: 'default' };
+}
+/**
+ * Expand a resolved placement into the concrete run option fields the
+ * existing dispatch paths already understand. Pure — does not mutate input.
+ *
+ * `cloud` and `fleet` are not valid for a bare `agents run` (use `cloud run`
+ * / routines); they throw so callers fail loud.
+ */
+export function expandPlacementToRunFlags(placement) {
+    switch (placement.kind) {
+        case 'local':
+            return {};
+        case 'device':
+            if (!placement.target) {
+                throw new PlacementError(`${placement.source}: device placement needs a target (name or auto)`);
+            }
+            // Canonical host flag; --device is an alias of the same path.
+            return { host: placement.target };
+        case 'lease':
+            // --box reuses a warm slug; --where lease[:backend] / --lease provisions.
+            if (placement.source === '--box')
+                return { box: placement.target };
+            return placement.target ? { lease: placement.target } : { lease: true };
+        case 'fleet':
+            throw new PlacementError(`fleet placement is for routines (agents routines add … --placement fleet), not agents run. ` +
+                `Use --where device:auto for an affinity pick, or --where device:<name>.`);
+        case 'cloud':
+            throw new PlacementError(`cloud placement is agents cloud run (vendor cloud), not agents run. ` +
+                `For a disposable box use --where lease; for your fleet use --where device:<name>.`);
+    }
+}
+/** Map routines hostStrategy (+ optional host) onto the shared Placement. */
+export function placementFromHostStrategy(strategy, host) {
+    switch (strategy) {
+        case 'local':
+            return { kind: 'local', source: 'hostStrategy:local' };
+        case 'host':
+            return { kind: 'device', target: host, source: 'hostStrategy:host' };
+        case 'fleet':
+            return { kind: 'fleet', source: 'hostStrategy:fleet' };
+        case 'cloud':
+            return { kind: 'cloud', source: 'hostStrategy:cloud' };
+    }
+}
+/** One-line human form for logs / help. */
+export function formatPlacement(p) {
+    if (p.kind === 'local')
+        return 'local';
+    if (p.target)
+        return `${p.kind}:${p.target}`;
+    return p.kind;
+}
+/**
+ * Short matrix for help footers and docs. Keep in sync with 00-concepts.md.
+ */
+export const PLACEMENT_MATRIX = `
+  Intent                         Flag / path
+  ─────────────────────────────  ──────────────────────────────────────────
+  This machine                   (default)  or  --where local
+  Named fleet box                --where device:<name>   (= --host / --device)
+  Affinity pick (14d usage)      --where auto            (= --device auto)
+  Disposable cloud box           --where lease           (= --lease)
+  Reuse warm crabbox             --box <slug>
+  Routines: body on one box      --run-on <name> / --placement host
+  Routines: pick any online      --placement fleet
+  Vendor cloud task              agents cloud run …
+  Monitors: who evaluates        --device <owner>   (NOT body placement)
+  Monitors: where action runs    --run-on <host>
+`.trim();

package/dist/lib/profiles.d.ts

@@ -31,9 +31,10 @@ export interface Profile {
     preset?: string;
     provider?: string;
     /**
-     * Human-facing label for the harness — what `agents view` prints as the
-     * agent-type header, the same slot `AGENTS[id].name` fills for a native
-     * harness. Defaults to the profile name when unset.
+     * Stored for backward-compatible YAML parsing only — no longer read for
+     * display. `profileLabel()` always derives the display name from `name` via
+     * the vendor/brand table. Old YAML files that carry this key still parse
+     * correctly; it is simply ignored.
      */
     label?: string;
     /**
@@ -71,7 +72,7 @@ export interface Profile {
  */
 export interface ProfileSummary {
     name: string;
-    /** Human-facing header label — `label` when set, else the profile name. */
+    /** Human-facing header label — always derived from `name` via the vendor/brand table. */
     label: string;
     agent: AgentId;
     host: string;
@@ -125,8 +126,12 @@ export declare function profileModelEnvKey(profile: Profile): string | null;
  */
 export declare function profileAuthLabel(profile: Profile): string;
 /**
- * Header label for the harness — the slot `AGENTS[id].name` fills for a native
- * harness, so `agents view` can print custom and native harnesses the same way.
+ * Header label for the harness — derived from `profile.name` by splitting on
+ * `[-_]` and mapping each token through the vendor/brand table. Never reads
+ * the stored `label` field; old YAML files with a `label:` key are unaffected.
+ *
+ * Examples: `deepseek-flash` → `'DeepSeek Flash'`, `spark` → `'Spark'`,
+ * `deepseek_chat_v3` → `'DeepSeek Chat V3'`.
  */
 export declare function profileLabel(profile: Profile): string;
 /** Build a stable, machine-readable summary for list and view surfaces. */
@@ -153,8 +158,6 @@ export interface HostModelOptions {
     /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
     authEnvVar?: string;
     description?: string;
-    /** Human-facing header label; defaults to the harness name. */
-    label?: string;
 }
 /**
  * Build a custom-harness profile from a host CLI + model in one shot, without a
@@ -176,7 +179,6 @@ export interface ForkProfileOptions {
     authEnvVar?: string;
     /** Re-pin (or unpin, with an empty string) the host CLI version. */
     version?: string;
-    label?: string;
     description?: string;
 }
 /**
@@ -185,6 +187,26 @@ export interface ForkProfileOptions {
  * diverge from here and deleting the source never affects the fork.
  */
 export declare function forkProfile(source: Profile, name: string, opts?: ForkProfileOptions): Profile;
+/**
+ * Edit an existing profile in-place, applying overrides without changing its
+ * name or lineage. Reuses {@link forkProfile}'s validation and override logic
+ * (model swap, base-URL validation, auth repoint), then restores the original
+ * `forkedFrom` so an edit never self-references the profile.
+ *
+ * Note: this returns the updated `Profile` object but does NOT write it to
+ * disk — callers should follow up with `writeProfile(result)` if persistence
+ * is needed.
+ */
+export declare function editProfile(source: Profile, opts?: ForkProfileOptions): Profile;
+/**
+ * Rename a profile on disk, then rewrite `forkedFrom` in every other profile
+ * that pointed at the old name so lineage display never goes stale.
+ *
+ * Throws if `oldName` does not exist or `newName` already exists. There is no
+ * `--force` / overwrite path — a collision is a hard error directing the user
+ * to remove the target first.
+ */
+export declare function renameProfile(oldName: string, newName: string): void;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/profiles.js

@@ -199,11 +199,46 @@ export function profileAuthLabel(profile) {
     return provider;
 }
 /**
- * Header label for the harness — the slot `AGENTS[id].name` fills for a native
- * harness, so `agents view` can print custom and native harnesses the same way.
+ * Curated vendor/brand display names, matched case-insensitively per token.
+ * Entries with a space (e.g. 'Moonshot AI') are single-token → multi-word expansions.
+ */
+const VENDOR_TABLE = [
+    ['deepseek', 'DeepSeek'],
+    ['openai', 'OpenAI'],
+    ['anthropic', 'Anthropic'],
+    ['claude', 'Claude'],
+    ['grok', 'Grok'],
+    ['xai', 'xAI'],
+    ['gpt', 'GPT'],
+    ['meta', 'Meta'],
+    ['mistral', 'Mistral'],
+    ['mistralai', 'Mistral'],
+    ['qwen', 'Qwen'],
+    ['gemini', 'Gemini'],
+    ['moonshot', 'Moonshot AI'],
+    ['moonshotai', 'Moonshot AI'],
+    ['kimi', 'Kimi'],
+    ['cohere', 'Cohere'],
+    ['perplexity', 'Perplexity'],
+];
+function tokenToDisplayName(token) {
+    const lower = token.toLowerCase();
+    for (const [key, display] of VENDOR_TABLE) {
+        if (lower === key)
+            return display;
+    }
+    return token.charAt(0).toUpperCase() + token.slice(1);
+}
+/**
+ * Header label for the harness — derived from `profile.name` by splitting on
+ * `[-_]` and mapping each token through the vendor/brand table. Never reads
+ * the stored `label` field; old YAML files with a `label:` key are unaffected.
+ *
+ * Examples: `deepseek-flash` → `'DeepSeek Flash'`, `spark` → `'Spark'`,
+ * `deepseek_chat_v3` → `'DeepSeek Chat V3'`.
  */
 export function profileLabel(profile) {
-    return profile.label || profile.name;
+    return profile.name.split(/[-_]/).map(tokenToDisplayName).join(' ');
 }
 /** Build a stable, machine-readable summary for list and view surfaces. */
 export function profileSummary(profile) {
@@ -300,8 +335,6 @@ export function profileFromHostModel(name, host, model, opts = {}) {
         provider: opts.provider ?? host,
         forkedFrom: host,
     };
-    if (opts.label)
-        profile.label = opts.label;
     if (opts.provider && opts.authEnvVar) {
         profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
         profile.authOptional = false;
@@ -337,14 +370,6 @@ export function forkProfile(source, name, opts = {}) {
         description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
         forkedFrom: source.name,
     };
-    // `label` is the header `agents view` prints, so an inherited one would make
-    // the fork and its source visually identical — the ambiguity a per-harness
-    // block exists to remove. A fork carries a label only when it is given one;
-    // otherwise `profileLabel` falls back to the fork's own name.
-    if (opts.label)
-        forked.label = opts.label;
-    else
-        delete forked.label;
     // A fork that repoints the model or endpoint is no longer that preset — keep
     // the preset link only while the fork still matches what the preset defines.
     if (opts.model || opts.baseUrl)
@@ -360,6 +385,51 @@ export function forkProfile(source, name, opts = {}) {
     }
     return forked;
 }
+/**
+ * Edit an existing profile in-place, applying overrides without changing its
+ * name or lineage. Reuses {@link forkProfile}'s validation and override logic
+ * (model swap, base-URL validation, auth repoint), then restores the original
+ * `forkedFrom` so an edit never self-references the profile.
+ *
+ * Note: this returns the updated `Profile` object but does NOT write it to
+ * disk — callers should follow up with `writeProfile(result)` if persistence
+ * is needed.
+ */
+export function editProfile(source, opts = {}) {
+    const edited = forkProfile(source, source.name, opts);
+    // forkProfile sets forkedFrom = source.name; for an in-place edit that would
+    // be a self-reference. Restore the original lineage instead.
+    edited.forkedFrom = source.forkedFrom;
+    return edited;
+}
+/**
+ * Rename a profile on disk, then rewrite `forkedFrom` in every other profile
+ * that pointed at the old name so lineage display never goes stale.
+ *
+ * Throws if `oldName` does not exist or `newName` already exists. There is no
+ * `--force` / overwrite path — a collision is a hard error directing the user
+ * to remove the target first.
+ */
+export function renameProfile(oldName, newName) {
+    validateProfileName(newName);
+    if (!profileExists(oldName)) {
+        throw new Error(`Profile '${oldName}' not found.`);
+    }
+    if (profileExists(newName)) {
+        throw new Error(`Profile '${newName}' already exists; remove it first.`);
+    }
+    const profile = readProfile(oldName);
+    profile.name = newName;
+    writeProfile(profile);
+    deleteProfile(oldName);
+    // Rewrite forkedFrom in every other profile that referenced the old name.
+    for (const other of listProfiles()) {
+        if (other.name !== newName && other.forkedFrom === oldName) {
+            other.forkedFrom = newName;
+            writeProfile(other);
+        }
+    }
+}
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the

package/dist/lib/redact.js

@@ -2,6 +2,10 @@
  * Shared redaction helpers for text that may be exported or logged.
  */
 const SECRET_PATTERNS = [
+    // Local home paths identify operators and disclose internal filesystem layout.
+    // Keep the useful path suffix while masking the machine-specific home prefix.
+    [/(^|[\s,"'`(=:])\/(?:home|Users)\/[^/\s,"'`]+/g, '$1[HOME]'],
+    [/(^|[\s,"'`(=])[A-Z]:\\Users\\[^\\\s,"'`]+/gi, '$1[HOME]'],
     [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED_AWS_KEY]'],
     // GitHub: classic PATs (ghp_), OAuth (gho_), app/refresh/server tokens
     // (ghs_/ghr_), and fine-grained PATs (github_pat_). All share the 36-char

package/dist/lib/rotate.d.ts

@@ -8,6 +8,7 @@ import type { AgentId, RunStrategy } from './types.js';
 import type { FallbackEntry } from './exec.js';
 import { type AccountInfo, type CredentialPresence } from './agents.js';
 import { type UsageSnapshot } from './usage.js';
+import { type AuthVerdict } from './auth-health.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;
@@ -35,6 +36,18 @@ export interface RotateCandidate {
     usageMinutesToLimit: number | null;
     plan: string | null;
     signedIn: boolean;
+    /**
+     * Live auth-health verdict for this (agent, version) from the daemon's probe
+     * cache (`auth-health.ts`), or null when no probe row exists (cold cache, or a
+     * harness with no live-probe endpoint). `signedIn` only means "a credential
+     * file is present and its email decodes" — it cannot tell a good token from a
+     * revoked-but-unexpired one, so a server-rejected account reads
+     * `signedIn: true` but `authVerdict: 'revoked'`. Eligibility excludes a
+     * revoked account so rotation never launches into a doomed auth (see
+     * {@link readinessFromCandidate}). Fail-open: any non-revoked or null verdict
+     * does not gate — a stale/absent probe never blocks a launch.
+     */
+    authVerdict: AuthVerdict | null;
     lastActive: Date | null;
 }
 export interface RotateResult {
@@ -108,15 +121,17 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
- * 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).
+ * why. `signed_out` covers a missing usable credential; `revoked` is a token the
+ * server has actually rejected (401/403, from the live auth-health probe);
+ * `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).
  */
 export type AccountReadiness = {
     ready: true;
 } | {
     ready: false;
-    reason: 'rate_limited' | 'out_of_credits' | 'signed_out';
+    reason: 'rate_limited' | 'out_of_credits' | 'signed_out' | 'revoked';
     email: string | null;
 };
 /**