@crvouga/dev-fleet 0.1.0 → 0.3.0

package/bootstrap/global-config.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   statSync,
   writeFileSync,
 } from 'node:fs';
@@ -48,17 +49,23 @@ export function assertManagedConfig(dir: string): void {
   }
 }
 
+/** What `publishGlobalConfig` writes to config.toml, given what is there. */
+function publishedConfig(root: string, previous: string | undefined): string {
+  return (
+    MARKER +
+    withTrustedPaths(
+      readFileSync(join(root, 'mise.toml'), 'utf8'),
+      trustedPaths(previous)
+    )
+  );
+}
+
 export function publishGlobalConfig(dir: string, root = workspaceRoot): void {
   assertManagedConfig(dir);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, 'config.toml');
   const previous = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
-  const config =
-    MARKER +
-    withTrustedPaths(
-      readFileSync(join(root, 'mise.toml'), 'utf8'),
-      trustedPaths(previous)
-    );
+  const config = publishedConfig(root, previous);
   if (previous !== config) writeFileSync(path, config);
   cpSync(join(root, 'mise.lock'), join(dir, 'mise.lock'), {
     filter: changedFile,
@@ -71,6 +78,57 @@ export function publishGlobalConfig(dir: string, root = workspaceRoot): void {
     });
 }
 
+/**
+ * How the global mise configuration stands against what this revision
+ * publishes. On a fleet machine it belongs to dev-fleet: a project pins its
+ * tools in its own mise.toml and never publishes a global one.
+ *
+ * - `published`: dev-fleet's marker, this revision's pins and lock
+ * - `missing`: there is no global config.toml
+ * - `replaced`: another owner (or nobody's marker) wrote it
+ * - `changed`: dev-fleet's marker, but not this revision's content
+ */
+export type GlobalConfigStanding =
+  'published' | 'missing' | 'replaced' | 'changed';
+
+export function globalConfigStanding(
+  dir: string,
+  root = workspaceRoot
+): GlobalConfigStanding {
+  const path = join(dir, 'config.toml');
+  if (!existsSync(path)) return 'missing';
+  const current = readFileSync(path, 'utf8');
+  if (!current.startsWith(MARKER)) return 'replaced';
+  const same = (source: string, target: string): boolean =>
+    existsSync(target) && readFileSync(source).equals(readFileSync(target));
+  const sidecars = join(root, '.mise/locks');
+  const locks = existsSync(sidecars)
+    ? (readdirSync(sidecars, { recursive: true }) as string[])
+        .map((name) => join('.mise/locks', name))
+        .filter((name) => statSync(join(root, name)).isFile())
+    : [];
+  // Paths trusted on the machine are kept by every publish, in any order;
+  // the agent worktree roots must be among them.
+  const TRUSTED = /^trusted_config_paths\s*=.*\n/m;
+  const trusted = trustedPaths(current);
+  let listed: unknown;
+  try {
+    listed = (Bun.TOML.parse(current) as { settings?: Record<string, unknown> })
+      .settings?.['trusted_config_paths'];
+  } catch {
+    listed = undefined;
+  }
+  const unchanged =
+    Array.isArray(listed) &&
+    trusted.every((path) => listed.includes(path)) &&
+    current.replace(TRUSTED, '') ===
+      publishedConfig(root, current).replace(TRUSTED, '') &&
+    ['mise.lock', ...locks].every((name) =>
+      same(join(root, name), join(dir, name))
+    );
+  return unchanged ? 'published' : 'changed';
+}
+
 /**
  * The managed roots plus any entries already in the published config, so a
  * local `mise settings add trusted_config_paths ...` survives the next publish.

package/bootstrap/install-launcher.sh

@@ -3,5 +3,8 @@
 set -eu
 root=${1:-$(cd "$(dirname "$0")/.." && pwd)}
 [ -x "$root/bootstrap/devfleet" ] || exit 1
+# Only ever a checkout: an installed package sits wherever a package manager
+# put it and may be gone tomorrow.
+[ -e "$root/.git" ] || { echo 'The devfleet launcher links to a checkout of dev-fleet; fleet-sync installs it.' >&2; exit 1; }
 mkdir -p "$HOME/.local/bin"
 ln -sfn "$root/bootstrap/devfleet" "$HOME/.local/bin/devfleet"

package/bootstrap/native-t3.ts

@@ -19,6 +19,7 @@ interface Configuration {
     t3_version: string;
     t3_linux_x64_sha256: string;
     t3_linux_arm64_sha256: string;
+    t3_darwin_arm64_sha256?: string;
     t3_desktop_amd64_sha256: string;
     t3_desktop_arm64_sha256: string;
   };
@@ -52,20 +53,27 @@ export function managedT3Desktop() {
   ) as Configuration;
   return desktopT3Artifact(config, process.arch);
 }
-export function nativeT3Artifact(config: Configuration, architecture: string) {
-  if (!['x64', 'arm64'].includes(architecture))
-    throw new Error('Unsupported T3 architecture.');
+/** The pinned server archive: Ubuntu workers on either architecture, and
+ * the manager (macOS on Apple silicon, the only macOS build upstream ships).
+ */
+export function nativeT3Artifact(
+  config: Configuration,
+  architecture: string,
+  platform: string = 'linux'
+) {
+  const sha256 = (<Record<string, string | undefined>>{
+    'linux-x64': config.vars.t3_linux_x64_sha256,
+    'linux-arm64': config.vars.t3_linux_arm64_sha256,
+    'darwin-arm64': config.vars.t3_darwin_arm64_sha256,
+  })[`${platform}-${architecture}`];
+  if (sha256 === undefined) throw new Error('Unsupported T3 architecture.');
   const version = config.vars.t3_version;
-  const sha256 =
-    architecture === 'x64'
-      ? config.vars.t3_linux_x64_sha256
-      : config.vars.t3_linux_arm64_sha256;
   if (
     !/^\d+\.\d+\.\d+(?:-nightly\.\d{8}\.\d+)?$/.test(version) ||
     !/^[a-f0-9]{64}$/.test(sha256)
   )
     throw new Error('Invalid T3 pin.');
-  const name = `t3-${version}-linux-${architecture}`;
+  const name = `t3-${version}-${platform}-${architecture}`;
   return {
     version,
     sha256,
@@ -77,18 +85,21 @@ export function managedT3(): { path: string; version: string } {
   const config = Bun.TOML.parse(
     readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
   ) as Configuration;
-  const artifact = nativeT3Artifact(config, process.arch);
+  const artifact = nativeT3Artifact(config, process.arch, process.platform);
   return {
     path: join(homedir(), '.local/share/personal/tools', artifact.name, 't3'),
     version: artifact.version,
   };
 }
+/** Installs the pinned, checksum-verified server archive on a worker and on
+ * the manager, so both run the T3 version the fleet pins.
+ */
 export async function installNativeT3(): Promise<void> {
-  if (process.platform !== 'linux') return;
+  if (!['linux', 'darwin'].includes(process.platform)) return;
   const config = Bun.TOML.parse(
     readFileSync(join(workspaceRoot, 'mise.toml'), 'utf8')
   ) as Configuration;
-  const artifact = nativeT3Artifact(config, process.arch);
+  const artifact = nativeT3Artifact(config, process.arch, process.platform);
   const root = join(homedir(), '.local/share/personal/tools');
   const archive = join(root, `${artifact.name}.tar.gz`);
   mkdirSync(root, { recursive: true, mode: 0o700 });

package/bootstrap/npm.ts

@@ -162,7 +162,11 @@ export function plan(state: State): Step[] {
     {
       id: 'tag',
       title: `Tag ${seedTag} on the commit that was published`,
-      done: state.tagRemote,
+      // npm recorded no commit for a seed published without one, so there is
+      // nothing to tag: the Release workflow then counts from the newest
+      // version on npm (bootstrap/release-version.ts).
+      done:
+        state.tagRemote || (state.published && state.publishedCommit === null),
       blocked: null,
     },
   ];
@@ -204,9 +208,13 @@ function publishSeed(exec: Exec, target: Target): boolean {
     );
     const file = join(checkout, 'package.json');
     const manifest = JSON.parse(readFileSync(file, 'utf8')) as object;
+    // As the Release workflow does: the package names the commit it is.
+    const gitHead = exec
+      .capture(['git', 'rev-parse', 'HEAD'], checkout)
+      .stdout.trim();
     writeFileSync(
       file,
-      `${JSON.stringify({ ...manifest, version: SEED_VERSION }, null, 2)}\n`
+      `${JSON.stringify({ ...manifest, version: SEED_VERSION, gitHead }, null, 2)}\n`
     );
     return exec.interactive(['npm', 'publish', '--access', 'public'], checkout);
   } finally {

package/bootstrap/release-version.ts

@@ -0,0 +1,157 @@
+/**
+ * Prints the version the Release workflow should publish for `HEAD`, or
+ * nothing when there is nothing to release (the reason goes to stderr).
+ *
+ * The newest `vX.Y.Z` tag is the last release. Without one, the newest
+ * version on npm is: it was published by hand before the workflow tagged
+ * anything, and npm may not have recorded its commit, so every commit up to
+ * `HEAD` counts. Commits since the last release pick the bump, Conventional
+ * Commits style:
+ *
+ *   `feat!:` / `BREAKING CHANGE:`  major (minor while the major is 0)
+ *   `feat:`                         minor
+ *   anything else                   patch
+ *
+ * Exits 1 when nothing can be released because publishing was never set up
+ * (no tag and nothing on npm), so the Release workflow does not report a
+ * skipped release as a success.
+ *
+ *   bun bootstrap/release-version.ts
+ */
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Git {
+  /** Run git and return stdout, or null when it exits non-zero. */
+  (args: string[]): string | null;
+}
+
+export type Decision =
+  | { release: true; version: string; previous: string }
+  | { release: false; reason: string; setup?: true };
+
+const TAG = /^v(\d+)\.(\d+)\.(\d+)$/;
+const BREAKING_SUBJECT = /^\w+(\([^)]*\))?!:/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+const FEATURE = /^feat(\([^)]*\))?:/;
+
+export type Bump = 'major' | 'minor' | 'patch';
+
+export function bumpFor(messages: string[]): Bump {
+  let bump: Bump = 'patch';
+  for (const message of messages) {
+    const subject = message.split('\n', 1)[0]!.trim();
+    if (BREAKING_SUBJECT.test(subject) || BREAKING_FOOTER.test(message))
+      return 'major';
+    if (FEATURE.test(subject)) bump = 'minor';
+  }
+  return bump;
+}
+
+export function bumpVersion(tag: string, bump: Bump): string {
+  const match = TAG.exec(tag);
+  if (!match) throw new Error(`Not a release tag: ${tag}`);
+  const [major, minor, patch] = match.slice(1).map(Number) as [
+    number,
+    number,
+    number,
+  ];
+  if (bump === 'major' && major > 0) return `${major + 1}.0.0`;
+  if (bump === 'patch') return `${major}.${minor}.${patch + 1}`;
+  return `${major}.${minor + 1}.0`;
+}
+
+export function latestTag(git: Git): string | null {
+  const tags = git(['tag', '--list', 'v*', '--sort=-v:refname']) ?? '';
+  return (
+    tags
+      .split('\n')
+      .map((tag) => tag.trim())
+      .find((tag) => TAG.test(tag)) ?? null
+  );
+}
+
+/** The newest stable `X.Y.Z` of these npm versions, or null. */
+export function newestPublished(versions: string[]): string | null {
+  const stable = versions
+    .filter((version) => TAG.test(`v${version}`))
+    .map((version) => version.split('.').map(Number) as number[]);
+  stable.sort((a, b) => b[0]! - a[0]! || b[1]! - a[1]! || b[2]! - a[2]!);
+  return stable[0]?.join('.') ?? null;
+}
+
+/**
+ * `published` is the newest stable version on npm, or null when the package
+ * is not there.
+ */
+export function decide(git: Git, published: string | null = null): Decision {
+  const tag = latestTag(git);
+  if (!tag && !published)
+    return {
+      release: false,
+      setup: true,
+      reason:
+        'No vX.Y.Z tag and nothing on npm yet: run `bun run bootstrap` once first.',
+    };
+  const previous = tag ?? `v${published}`;
+  if (tag && git(['merge-base', '--is-ancestor', 'HEAD', tag]) !== null)
+    return { release: false, reason: `HEAD is already in ${tag}.` };
+  const log =
+    git(['log', '--format=%B%x00', tag ? `${tag}..HEAD` : 'HEAD']) ?? '';
+  const messages = log
+    .split('\0')
+    .map((message) => message.trim())
+    .filter(Boolean);
+  if (messages.length === 0)
+    return { release: false, reason: `No commits since ${previous}.` };
+  return {
+    release: true,
+    version: bumpVersion(previous, bumpFor(messages)),
+    previous,
+  };
+}
+
+const system: Git = (args) => {
+  const result = spawnSync('git', args, { encoding: 'utf8' });
+  return result.status === 0 ? (result.stdout ?? '') : null;
+};
+
+/** The versions of the package on npm; empty when it is not there. */
+function npmVersions(): string[] {
+  const name = (
+    JSON.parse(
+      readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf8')
+    ) as { name: string }
+  ).name;
+  const result = spawnSync('npm', ['view', name, 'versions', '--json'], {
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return [];
+  const versions: unknown = JSON.parse(result.stdout || '[]');
+  return Array.isArray(versions)
+    ? versions.filter((v): v is string => typeof v === 'string')
+    : typeof versions === 'string'
+      ? [versions]
+      : [];
+}
+
+if (import.meta.main) {
+  const decision = decide(system, newestPublished(npmVersions()));
+  const summary = process.env['GITHUB_STEP_SUMMARY'];
+  const note = (line: string) => {
+    if (summary) appendFileSync(summary, `${line}\n`);
+  };
+  if (decision.release) {
+    console.error(`${decision.previous} -> v${decision.version}`);
+    note(`Releasing v${decision.version} (after ${decision.previous}).`);
+    console.log(decision.version);
+  } else if (decision.setup) {
+    console.error(`::error::${decision.reason}`);
+    note(`**Nothing was released.** ${decision.reason}`);
+    process.exitCode = 1;
+  } else {
+    console.error(decision.reason);
+    note(`Nothing to release: ${decision.reason}`);
+  }
+}

package/cliproxy/README.md

@@ -146,7 +146,7 @@ devfleet cliproxy inference responses EXACT_CODEX_MODEL_ID
 devfleet cliproxy inference messages EXACT_CLAUDE_MODEL_ID
 ```
 
-Codex uses the upstream device-code flow. Remote callback flows may require the documented dashboard callback flow or temporary SSH loopback forwarding; callback ports are not exposed by default. This pinned version has no generic Gemini CLI login flag; use its supported dashboard/API-key integration. Provider rules still govern permissible account use.
+`devfleet fleet-accounts --add|--relogin|--remove` wraps these and propagates the result to every node; a login writes into a staging directory and only a complete credential is moved in. Codex uses the upstream device-code flow. Remote callback flows may require the documented dashboard callback flow or temporary SSH loopback forwarding; callback ports are not exposed by default. This pinned version has no generic Gemini CLI login flag; use its supported dashboard/API-key integration. Provider rules still govern permissible account use.
 
 **Account routing.** Credential files are the only list of accounts. `ops declared` (run by every fleet-sync) gives each Claude, Codex and Antigravity credential the model prefix `<type>-<email>` through the proxy's management API (`scripts/accounts.py`; a credential file is never edited directly). A request for `<type>-<email>/<model>` is served only by that account, and `/v1/models` lists those ids, which is how every fleet node discovers the accounts to offer in T3. Nothing in Git names an account.
 
@@ -167,7 +167,7 @@ python3 cliproxy/clients/bootstrap.py --validate
 
 Enter the inference key at the hidden prompt. It is available in Vault `secret/personal/prd:CLIPROXY_FLEET_CLIENT_API_KEY`; dashboard login uses `CLIPROXY_FLEET_MANAGEMENT_KEY`. Secrets never appear in command arguments. Keys are saved mode 0600 and loaded only into child environments. Give runners separate revocable inference keys where needed, never provider OAuth credentials or the admin key.
 
-Codex uses custom-provider CLI overrides and Responses HTTP/SSE. Claude uses its supported base URL/auth-token variables and an explicit Claude model. OpenCode uses its config-file override, with separate Responses and Anthropic SDK providers. Once Claude is authenticated, rerun with `--claude-model MODEL_ID`; otherwise the Claude launcher fails with an explicit setup requirement. Native client config files are preserved. Use plain native clients during a proxy outage.
+Codex uses custom-provider CLI overrides and Responses HTTP/SSE. Claude uses its supported base URL/auth-token variables and an explicit Claude model. OpenCode uses its config-file override, with separate Responses and Anthropic SDK providers. Once Claude is authenticated, rerun with `--claude-model MODEL_ID`; otherwise the Claude launcher fails with an explicit setup requirement. Native client config files are preserved. Fleet nodes never fall back to native clients: provider accounts exist only on the proxy (see [docs/accounts.md](../docs/accounts.md)), and during a proxy outage every relayed launcher retries for about a minute, then reports "proxy unreachable".
 
 Run bootstrap from a repository checkout containing `clients/launcher.py`; detached downloaded bootstrap files are unsupported. Bootstrap is idempotent and refuses unrelated launcher collisions. `--uninstall` removes launcher links while retaining private settings for deliberate cleanup. On Windows run inside WSL; native PowerShell launchers are not provided. Validate from each actual machine and target repository because OpenCode merges project settings.
 
@@ -187,7 +187,7 @@ Vault login is interactive with hidden input; its token is restricted locally an
 
 Encrypted cloud checkpoints run every 15 minutes (legacy systemd adds up to 30 seconds jitter). A checkpoint never stops, pauses or restarts the stack: agents use the proxy around the clock, and a stopped connector fails every request. The capture copies the live state and keeps the copy only if no state file changed while it was taken (retrying a few times); a stack that never holds still fails that backup. A failed capture, restart, upload or retention operation records failure and never advances the success marker. Retention keeps the latest 96 snapshots plus 7 daily, 5 weekly and 12 monthly. Weekly integrity checks read 10% of stored data; `check-full` reads all data. Monitoring fails when the last successful checkpoint is older than 45 minutes. Failures are visible in `cliproxy status` (and `launchctl print gui/$UID/LABEL` or systemd); off-machine checks also run through the CLI proxy health workflow described below.
 
-R2 checkpoints are the durable recovery source for config, provider OAuth/account state and the dedicated Tailscale identity. Local state is a working cache with asynchronous durability: normally up to approximately 15 minutes plus upload duration can be lost, and an outage can extend that indefinitely. Run a successful manual checkpoint after important login/config changes or before moving machines. Provider refresh-token invalidation can still require a fresh provider login after recovering an older checkpoint. This is a single-writer deployment, with operator fencing of the previous node; there is no distributed lease or active-active support.
+R2 checkpoints are the durable recovery source for config, provider OAuth/account state and the dedicated Tailscale identity. Local state is a working cache with asynchronous durability: normally up to approximately 15 minutes plus upload duration can be lost, and an outage can extend that indefinitely. Run a successful manual checkpoint after important login/config changes or before moving machines. Provider refresh-token invalidation can still require a fresh provider login after recovering an older checkpoint. Each checkpoint records a digest of every refresh token, so `restore-verify RESTORED --newest NEWEST` names exactly the accounts that need one. This is a single-writer deployment, with operator fencing of the previous node; there is no distributed lease or active-active support.
 
 Checkpoints include only allowlisted runtime state, endpoint intent, repository identity and source revision metadata. GitHub supplies code; Vault supplies client/admin keys, the encryption password and current cloud credentials. Vault/tunnel tokens, local secret files, logs, prior config copies, status files and executable source are excluded. Config and OAuth files themselves contain secrets and remain encrypted in R2. Local capture/restore directories are private plaintext caches, deleted after normal completion. Abandoned generated `checkpoint-*` and `restore-*` directories under `recovery/` expire after 24 hours. Cleanup runs under the operation lock before each backup operation, so active local captures/restores cannot be collected. Unknown/manual rollback directories are preserved. Restic runs without a persistent local metadata cache.
 

package/cliproxy/scripts/accounts.py

@@ -36,3 +36,219 @@ def pending(auths):
         if wanted and data.get('prefix') != wanted:
             result.append((path.name, wanted))
     return result
+
+
+# ── Account state ────────────────────────────────────────────────────────────
+#
+# One state per credential, from its file (never a token, only whether one is
+# there and when the access token expires) and from the proxy's management
+# API, which knows about refreshes, cooldowns and disabled credentials.
+
+STATES = ('usable', 'cooling-down', 'needs-login', 'refresh-failing', 'removed')
+
+# A refresh the provider refused for good: only a new sign-in helps.
+REJECTED = re.compile(r'invalid_grant|invalid_token|unauthorized|revoked|refresh token (?:is )?(?:invalid|expired|rejected|reused)', re.I)
+
+
+def _instant(value):
+    """Seconds since the epoch from an ISO 8601 string or a number, or None."""
+    import datetime
+    if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0:
+        return float(value) / (1000 if value > 1e11 else 1)
+    if isinstance(value, str) and value and not value.startswith('0001-'):
+        try:
+            parsed = datetime.datetime.fromisoformat(value.replace('Z', '+00:00'))
+        except ValueError:
+            return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=datetime.timezone.utc)
+        return parsed.timestamp()
+    return None
+
+
+def iso(seconds):
+    import datetime
+    return datetime.datetime.fromtimestamp(seconds, datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def classify(credential, entry, now):
+    """(state, until): `credential` is the auth file, `entry` what the
+    management API says about it (None when it does not list it). `until` is
+    when a cooldown clears, as epoch seconds, or None."""
+    entry = entry or {}
+    if entry.get('disabled') is True or credential.get('disabled') is True:
+        return 'removed', None
+    message = str(entry.get('status_message') or entry.get('last_error') or '')
+    expires = _instant(credential.get('expired') or credential.get('expiry'))
+    expired = expires is not None and expires <= now
+    has_refresh = bool(credential.get('refresh_token'))
+    if REJECTED.search(message) or (expired and not has_refresh):
+        return 'needs-login', None
+    if entry.get('status') == 'error' and 'refresh' in message.lower():
+        return ('needs-login' if expired else 'refresh-failing'), None
+    quota = entry.get('quota') if isinstance(entry.get('quota'), dict) else {}
+    until = max(
+        [t for t in (_instant(entry.get('next_retry_after')),
+                     _instant(quota.get('next_recover_at'))) if t is not None and t > now]
+        or [0]
+    )
+    if until or entry.get('unavailable') is True or quota.get('exceeded') is True:
+        return 'cooling-down', (until or None)
+    return 'usable', None
+
+
+def credentials(auths):
+    """[(file name, credential)] for every readable credential, in a stable
+    order: by provider, then sign-in email, then file name. Each provider's
+    accounts are numbered in this order, the same order every node lists
+    them in (src/agents/accounts.ts), so an index means one account
+    everywhere."""
+    found = []
+    for path in pathlib.Path(auths).glob('*.json'):
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, ValueError):
+            continue
+        if isinstance(data, dict) and isinstance(data.get('type'), str):
+            found.append((path.name, data))
+    email = lambda data: data.get('email') if isinstance(data.get('email'), str) else ''
+    return sorted(found, key=lambda item: (item[1]['type'], email(item[1]), item[0]))
+
+
+def roster(auths, entries=(), now=None):
+    """Every provider account: provider, opaque index (1, 2, … per provider),
+    label, state and, while cooling down, when it clears. `entries` is the
+    management API's list of auth files. Never a token."""
+    import time
+    now = time.time() if now is None else now
+    by_name = {e.get('name'): e for e in entries if isinstance(e, dict)}
+    counters = {}
+    result = []
+    for name, credential in credentials(auths):
+        provider = credential['type']
+        counters[provider] = counters.get(provider, 0) + 1
+        state, until = classify(credential, by_name.get(name), now)
+        email = credential.get('email')
+        result.append({
+            'provider': provider,
+            'index': counters[provider],
+            'label': email if isinstance(email, str) else provider + '-' + str(counters[provider]),
+            'prefix': prefix(provider, email),
+            'state': state,
+            'until': iso(until) if until else None,
+            'file': name,
+        })
+    return result
+
+
+def version(accounts):
+    """The roster version: a digest of the non-secret metadata of the accounts
+    every node offers (their routing prefixes). Every node computes the same
+    digest from the proxy's model list (src/accounts/roster.ts)."""
+    import hashlib
+    prefixes = sorted({a['prefix'] for a in accounts if a.get('prefix') and a.get('state') != 'removed'})
+    return hashlib.sha256('\n'.join(prefixes).encode()).hexdigest()[:16]
+
+
+def public(accounts):
+    """The roster as reported: no file name."""
+    return [{k: v for k, v in a.items() if k != 'file'} for a in accounts]
+
+
+def find(accounts, provider, index):
+    """The one account `provider` `index` names, or None."""
+    for account in accounts:
+        if account['provider'] == provider and account['index'] == index:
+            return account
+    return None
+
+
+# ── Sign-in, re-login and removal ────────────────────────────────────────────
+#
+# A login writes into a staging directory, never into the auth directory. Only
+# a complete credential (readable JSON with a type) is moved in, with one
+# rename, so an interrupted login leaves no half-written auth file.
+
+def staging(auths):
+    return pathlib.Path(auths).parent / 'auths-staging'
+
+
+def begin(auths):
+    """A fresh, empty staging directory; leftovers of an interrupted login are
+    discarded."""
+    import shutil
+    stage = staging(auths)
+    shutil.rmtree(stage, ignore_errors=True)
+    stage.mkdir(mode=0o700, parents=True)
+    return stage
+
+
+def adopt(stage, auths, replace=None):
+    """Moves every complete credential from `stage` into `auths` and returns
+    their file names. `replace` (a file name) is the credential a re-login
+    signs in again: it is replaced by the new one in the same rename. The
+    staging directory is removed whatever happens."""
+    import os
+    import shutil
+    stage, auths = pathlib.Path(stage), pathlib.Path(auths)
+    adopted = []
+    try:
+        complete = []
+        for path in sorted(stage.glob('*.json')):
+            try:
+                data = json.loads(path.read_text())
+            except (OSError, ValueError):
+                continue
+            if isinstance(data, dict) and isinstance(data.get('type'), str):
+                complete.append(path)
+        if replace and len(complete) != 1:
+            raise ValueError('A re-login must produce exactly one credential')
+        for path in complete:
+            target = auths / (replace or path.name)
+            os.chmod(path, 0o600)
+            os.replace(path, target)
+            adopted.append(target.name)
+        if replace and adopted and adopted[0] != replace:
+            (auths / replace).unlink(missing_ok=True)
+        return adopted
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
+
+
+def remove(auths, provider, index):
+    """Deletes the credential of one account; returns its file name."""
+    account = find(roster(auths), provider, index)
+    if account is None:
+        raise ValueError('No such account')
+    (pathlib.Path(auths) / account['file']).unlink()
+    return account['file']
+
+
+# ── Refresh tokens across checkpoints ────────────────────────────────────────
+#
+# Providers rotate refresh tokens. Each checkpoint records a short digest of
+# every credential's refresh token (never the token). After a restore, a
+# credential whose digest differs from the newest checkpoint's carries a
+# token the provider has already replaced: that account needs a new login.
+
+def token_digests(auths):
+    import hashlib
+    digests = {}
+    for name, credential in credentials(auths):
+        token = credential.get('refresh_token')
+        if isinstance(token, str) and token:
+            digests[name] = hashlib.sha256(token.encode()).hexdigest()[:16]
+    return digests
+
+
+def stale_after_restore(auths, newest):
+    """[(provider, index)] of the restored accounts whose refresh token is
+    older than the one `newest` (the token digests of the newest checkpoint)
+    records."""
+    current = token_digests(auths)
+    stale = []
+    for account in roster(auths):
+        name = account['file']
+        if name in newest and name in current and current[name] != newest[name]:
+            stale.append((account['provider'], account['index']))
+    return stale

package/cliproxy/scripts/checkpoint.py

@@ -127,11 +127,39 @@ def copy_state(root, target):
             shutil.copyfile(source, destination)
     shutil.copyfile(root / "INSTALLATION.json", target / "INSTALLATION.json")
     (target / "CHECKPOINT.json").write_text(
-        json.dumps({"version": 1, "files": hashes(target)}) + "\n"
+        json.dumps(
+            {
+                "version": 1,
+                "files": hashes(target),
+                "tokens": _accounts().token_digests(target / "state/runtime/auths"),
+            }
+        )
+        + "\n"
     )
     validate(target)
 
 
+def _accounts():
+    """accounts.py beside this file, however this module was loaded."""
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(
+        "accounts", pathlib.Path(__file__).resolve().parent / "accounts.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def stale_accounts(restored, newest):
+    """[(provider, index)] of the accounts in the restored checkpoint
+    `restored` whose refresh token the provider has since replaced, judged
+    against the manifest of the newest checkpoint `newest`. Restoring the
+    newest checkpoint itself finds none."""
+    tokens = json.loads((newest / "CHECKPOINT.json").read_text()).get("tokens") or {}
+    return _accounts().stale_after_restore(restored / "state/runtime/auths", tokens)
+
+
 def capture(root, target, attempts=6, sleep=time.sleep):
     """Copies the state of the running stack without ever stopping it: agents
     use the proxy around the clock, and a stopped connector fails every one of

package/cliproxy/scripts/cli.py

@@ -21,7 +21,7 @@ root = cliproxy_host.default_root().resolve()
 args = sys.argv[1:]
 if not args or args[0] in ["help", "--help", "-h"]:
     print(
-        "Usage: devfleet cliproxy COMMAND\nCommands: install [--revision REV|--rollback|--dry-run|--prepare-only], audit, public-endpoint [enable|start|disable|verify], status, start, stop, restart, health, models, logs, validate, apply FILE, add-account PROVIDER, inference PROTOCOL MODEL, model-health [--profile liveness|readiness|light|nightly|manual] [--suite core|cursor|all] [--target live|mock], model-suite (same flags; defaults to nightly), backup, gc, snapshots, check, check-full, restore SNAPSHOT EMPTY_DIRECTORY, restore-cache --previous-node-stopped, vault-login, recover, recover-node NEW_DIRECTORY [--vault-token-file FILE], verify-recovery, portable-login, activate, drain"
+        "Usage: devfleet cliproxy COMMAND\nCommands: install [--revision REV|--rollback|--dry-run|--prepare-only], audit, public-endpoint [enable|start|disable|verify], status, start, stop, restart, health, models, logs, validate, apply FILE, add-account PROVIDER, relogin PROVIDER INDEX, remove-account PROVIDER INDEX, accounts [--json], client-keys, issue-key|rotate-key|retire-key|revoke-key NODE, inference PROTOCOL MODEL, model-health [--profile liveness|readiness|light|nightly|manual] [--suite core|cursor|all] [--target live|mock], model-suite (same flags; defaults to nightly), backup, gc, snapshots, check, check-full, restore SNAPSHOT EMPTY_DIRECTORY, restore-cache --previous-node-stopped, vault-login, recover, recover-node NEW_DIRECTORY [--vault-token-file FILE], verify-recovery, portable-login, activate, drain"
     )
     sys.exit(0)
 command, *rest = args