@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/crabbox/runtimes.js

@@ -1,17 +1,3 @@
-/**
- * Runtime detection + picker + credential-script builder for `agents run --lease`.
- *
- * The picker asks which coding-agent runtime(s) to provision on a leased box.
- * The default selection is whatever the user is currently signed into locally
- * (via `getAccountInfo`, the same source `agents view` uses). The chosen runtimes
- * drive both what gets installed on the box and which auth token file is copied
- * over — the token contents ride the uploaded `--script-stdin` body, never argv.
- *
- * SECURITY: copying a runtime's auth token to an ephemeral cloud box is a
- * credential transfer. It is strictly opt-in (a confirm prompt in the command
- * layer), the token never appears in argv/`ps`, and `--lease` one-shot runs tear
- * the box down afterward so the credential's lifetime is bounded by the run.
- */
 import * as os from 'os';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -37,11 +23,9 @@ export const LEASE_RUNTIMES = [
  * `--lease` (this module's `buildCredentialScript`) both refuse against it.
  */
 const NATIVE_OAUTH_RUNTIMES = new Set(LEASE_RUNTIMES.map((c) => c.id));
-/** True when `id` is a native OAuth / session login that MUST NOT be copied between devices (SING-1b). */
 export function isNativeOAuthRuntime(id) {
     return NATIVE_OAUTH_RUNTIMES.has(id);
 }
-/** The fail-loud message naming the forbidden runtimes and the portable path to use instead. */
 export function nativeOAuthTransferRefusal(nativeRuntimes) {
     return (`Refusing to copy native OAuth / session credentials to another device: ${nativeRuntimes.join(', ')}.\n` +
         `A rotating harness login copied across machines is invalidated on its next server-side token ` +
@@ -52,7 +36,6 @@ export function nativeOAuthTransferRefusal(nativeRuntimes) {
         `    agents accounts add <name> --provider <provider> --auth <api-key|setup-token>\n` +
         `    agents accounts sync <name> --device <host>`);
 }
-/** First existing candidate path under the real home, or null. */
 function findLocalCred(cred) {
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     for (const rel of cred.localCandidates) {
@@ -62,12 +45,10 @@ function findLocalCred(cred) {
                 return p;
         }
         catch {
-            /* unreadable — skip */
         }
     }
     return null;
 }
-/** Which lease-capable runtimes the user is signed into on this machine. */
 export async function detectSignedInRuntimes() {
     const out = [];
     for (const cred of LEASE_RUNTIMES) {
@@ -88,11 +69,6 @@ export async function detectSignedInRuntimes() {
     }
     return out;
 }
-/**
- * Interactive checkbox: which runtimes to provision on the box. Defaults to the
- * signed-in ones. Runtimes with no local credential are shown disabled.
- * `prompt` is injected so tests don't require a TTY.
- */
 export async function pickRuntimes(detected, prompt) {
     const choices = detected.map((d) => ({
         name: `${d.label}${d.email ? ` (${d.email})` : d.signedIn ? ' (signed in)' : ''}`,
@@ -105,28 +81,11 @@ export async function pickRuntimes(detected, prompt) {
     const { checkbox } = await import('@inquirer/prompts');
     return checkbox({ message: 'Provision which runtime(s) on the leased box?', choices });
 }
-/**
- * The lease runtime to provision for a headless run of `agentName`.
- *
- * When the agent is itself a lease-capable runtime (claude/codex/gemini/grok)
- * that IS the runtime to install. Otherwise fall back to the single signed-in
- * lease runtime (preferring claude), or null when none is signed in. This is the
- * non-interactive replacement for the runtime checkbox picker: `--lease` requires
- * a prompt, so it is headless by contract and must never block on a TTY.
- *
- * Profile-dispatch agents (kimi/deepseek) and custom workflow agents that run
- * under a non-obvious runtime are resolved separately — see RUSH-1725.
- */
 export function inferLeaseRuntime(agentName, detected) {
     const signedIn = detected.filter((d) => d.signedIn && d.credPath);
-    // The agent names a lease runtime directly: require that runtime to be signed
-    // in — never silently substitute a different one for an explicit `run <runtime>`
-    // (that would lease a billable box only to boot it "Not logged in"). Not signed
-    // in → null, so the caller exits with "sign into it locally first".
     if (LEASE_RUNTIMES.some((c) => c.id === agentName)) {
         return signedIn.find((d) => d.id === agentName)?.id ?? null;
     }
-    // Custom/workflow agent: fall back to the signed-in runtime (preferring claude).
     return signedIn.find((d) => d.id === 'claude')?.id ?? signedIn[0]?.id ?? null;
 }
 const PROFILE_AUTH_ENV_KEYS_BY_RUNTIME = {
@@ -143,7 +102,6 @@ const PROFILE_AUTH_ENV_KEYS_BY_RUNTIME = {
     codex: ['OPENAI_API_KEY'],
     grok: ['XAI_API_KEY', 'GROK_API_KEY'],
 };
-/** True when a profile already carries auth for its host runtime via env. */
 export function profileNeedsBaseRuntimeCredentials(agent, env, authEnvVar) {
     if (!LEASE_RUNTIMES.some((c) => c.id === agent))
         return false;
@@ -152,24 +110,14 @@ export function profileNeedsBaseRuntimeCredentials(agent, env, authEnvVar) {
     const keys = PROFILE_AUTH_ENV_KEYS_BY_RUNTIME[agent] ?? [];
     return !keys.some((key) => typeof env[key] === 'string' && env[key].trim() !== '');
 }
-// A long random sentinel makes an accidental (or malicious) collision with a
-// token's contents effectively impossible, so the quoted heredoc can never be
-// closed early by the credential body.
 const CRED_EOF = 'AGENTS_LEASE_CRED_EOF_9f3c1a7b5e2d4068';
-/** Build a quoted heredoc write to a path under the remote user's home. */
 export function buildHomeFileWriteScript(remote, contents) {
     const dir = path.posix.dirname(remote);
     const mkdir = dir && dir !== '.' ? `mkdir -p "$HOME/${dir}"\n` : '';
     return (`${mkdir}cat > "$HOME/${remote}" <<'${CRED_EOF}'\n${contents}${contents.endsWith('\n') ? '' : '\n'}${CRED_EOF}\n` +
         `chmod 600 "$HOME/${remote}"`);
 }
-/**
- * Where Claude Code reads its OAuth token on the box. `.claude.json` (the file
- * LEASE_RUNTIMES copies) is config/account-metadata ONLY — the actual token
- * lives here, so without it the box boots "Not logged in".
- */
 export const CLAUDE_TOKEN_REMOTE = '.claude/.credentials.json';
-/** True when `s` parses to a Claude keychain payload with an OAuth access token. */
 function isClaudeCredentialsBlob(s) {
     try {
         const p = JSON.parse(s);
@@ -179,27 +127,6 @@ function isClaudeCredentialsBlob(s) {
         return false;
     }
 }
-/**
- * The RAW wrapped Claude credential payload (`{"claudeAiOauth":{…}}`) to write to
- * the box's `~/.claude/.credentials.json`, or null if no signed-in token is found.
- *
- * On macOS the token is in the login Keychain, read SILENTLY via the standalone
- * `secrets` client's `getKeychainTokenSync` (the `/usr/bin/security … -w` path —
- * Claude's item trusts it, no Touch ID). A default native install uses the bare `Claude Code-credentials`
- * service; an agents-cli managed install (where `~/.claude` symlinks into a
- * versioned home) uses a hash-suffixed service, so we try the bare service first,
- * then enumerate installed version homes (preferring the account whose email
- * matches `preferEmail`, so the token matches the `.claude.json` config we copy).
- * Off macOS the local Claude CLI stores the wrapped rotating blob in
- * `.credentials.json` already. Read that file here with a shape check
- * (`claudeAiOauth.accessToken`). Do not reintroduce a shared helper that
- * also serves Rush Cloud dispatch — dispatch is email-only (SING-1b) and
- * the old `readClaudeCredentialsBlob` path was the #1767 TTY-banner leak
- * (RUSH-2359).
- *
- * The reader/service/version helpers are injected so unit tests never touch the
- * real Keychain.
- */
 export async function resolveClaudeCredentialsBlob(opts) {
     const readItem = opts?.readItem ?? getKeychainTokenSync;
     const service = opts?.service ?? getClaudeKeychainService;
@@ -216,21 +143,15 @@ export async function resolveClaudeCredentialsBlob(opts) {
         }
     };
     if (process.platform === 'darwin') {
-        // 1) Bare service — the default native (non-managed) install.
         const bare = tryRead(service(undefined));
         if (bare) {
             if (!opts?.preferEmail)
                 return bare;
-            // preferEmail is set — verify the bare service belongs to the right account
-            // before handing it back; on mismatch fall through to managed installs.
             const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
             const bareEmail = await accountEmail(realHome).catch(() => null);
             if (bareEmail === opts.preferEmail)
                 return bare;
-            // email mismatch — fall through
         }
-        // 2) Managed installs — hash-suffixed service keyed to each version home.
-        //    Prefer the version whose account email matches the copied config.
         let homes;
         try {
             homes = listVersions().map(versionHome);
@@ -249,9 +170,6 @@ export async function resolveClaudeCredentialsBlob(opts) {
         }
         return null;
     }
-    // Off darwin: the local Claude CLI stores the wrapped rotating blob on disk.
-    // Read it directly so a file-based setup-token (Rush Cloud dispatch) is not
-    // mistaken for a native OAuth login that SING-1b must refuse to copy.
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     const credsPath = path.join(home, '.claude', '.credentials.json');
     try {
@@ -262,28 +180,9 @@ export async function resolveClaudeCredentialsBlob(opts) {
         }
     }
     catch {
-        /* no readable credentials file */
     }
     return null;
 }
-/**
- * The credential-provisioning snippet for a `--lease` box.
- *
- * Every runtime this could serialize is a native OAuth / session login
- * (`LEASE_RUNTIMES`), and SING-1b forbids copying one to another device —
- * including an ephemeral leased box, whose refresh of a shared rotating token
- * invalidates every other holder. So this no longer writes a login: it REFUSES
- * (throws, steering to the portable `agents accounts` path) whenever a picked
- * runtime actually has a native credential to copy — signed in locally
- * (`credPath`), or a Claude OAuth blob supplied. A picked runtime with nothing to
- * copy is simply skipped, so `buildCredentialScript` returns `''` (a no-op box
- * bootstrap) rather than throwing on a not-signed-in runtime.
- */
-/**
- * The native OAuth runtimes among `picked` that actually have a credential to copy
- * — signed in locally (`credPath`) or a Claude OAuth blob supplied — i.e. the ones
- * a transfer would leak. A picked runtime with nothing to copy is not refused.
- */
 export function refusedNativeOAuthRuntimes(picked, detected, extras) {
     const byId = new Map(detected.map((d) => [d.id, d]));
     return picked.filter((id) => {
@@ -294,14 +193,8 @@ export function refusedNativeOAuthRuntimes(picked, detected, extras) {
         return hasLocalFile || hasClaudeToken;
     });
 }
-/**
- * Throw the SING-1b refusal if any picked runtime would transfer a native OAuth
- * login. Callers should invoke this at a FAIL-FAST point — before any expensive or
- * costly side effect (e.g. before `crabboxWarmup` leases a paid box) — so a refused
- * `--lease` never leaks infra, mirroring how `--copy-creds` refuses before it opens
- * an SSH connection.
- */
 export function assertNoNativeOAuthTransfer(picked, detected, extras) {
+    // Reject native OAuth before leasing a paid box; only durable worker credentials transfer.
     const refused = refusedNativeOAuthRuntimes(picked, detected, extras);
     if (refused.length > 0) {
         throw new Error(nativeOAuthTransferRefusal(refused));
@@ -309,8 +202,5 @@ export function assertNoNativeOAuthTransfer(picked, detected, extras) {
 }
 export function buildCredentialScript(picked, detected, extras) {
     assertNoNativeOAuthTransfer(picked, detected, extras);
-    // Past the refusal there is nothing to serialize — every runtime this handles is
-    // native OAuth, so a non-refused set has no credential to copy. (Always '' today;
-    // the shape stays general in case a non-native runtime is ever added.)
     return '';
 }

package/dist/lib/crabbox/setup-copy.d.ts

@@ -1,78 +1,21 @@
-/**
- * Setup-copy for `agents run --lease` (RUSH-1920), transport = PUSH-FROM-LOCAL.
- *
- * A fresh crabbox box has agents-cli installed but none of the caller's own
- * `~/.agents` config (skills, hooks, commands, MCP, profiles). This module
- * replicates the *git-tracked* subset of the LOCAL `~/.agents` onto the box:
- *
- *   1. `git -C <userAgentsDir> ls-files` — tracked files only. Tracked-only is
- *      the safety boundary: it excludes `.history/`, `.cache/`, `.system/` and
- *      any keychain-backed secrets by construction (those are gitignored), so no
- *      credential material is ever pushed.
- *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
- *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
- *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
- *   3. `agents sync --local` on the box so the copied config takes effect.
- *
- * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
- * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
- * filter belts-and-braces the tracked-only guarantee.
- *
- * This is a self-contained local function the command layer calls; it does NOT
- * ride the box-side bootstrap script (that only echoes the `copy-setup` progress
- * sentinel — see `buildBootstrapScript`).
- */
 interface CopySetupOptions {
-    /** crabbox box slug to push to — its per-lease ssh key does the auth. */
     slug: string;
-    /** Secrets bundle whose env the ssh/rsync children inherit (crabbox parity). */
     secretsBundle?: string;
-    /** Override the local `~/.agents` dir (defaults to `getUserAgentsDir()`). */
     userAgentsDir?: string;
-    /**
-     * Destination relative to the box user's home. Lease runs set this to their
-     * isolated home; other callers retain the historical `~/.agents/` target.
-     */
     remoteDir?: string;
-    /** Receives combined stdout/stderr of the rsync + refresh, if set. */
     onData?: (chunk: string) => void;
-    /**
-     * Run `agents sync --local` on the box after the push (default `true`). Set
-     * `false` when the caller runs the refresh itself in the box bootstrap — the
-     * lease path does this so the refresh runs AFTER the box installs agents-cli
-     * (this host-side push happens before the box boots agents-cli, so a host-side
-     * refresh here could not find the CLI).
-     */
     refresh?: boolean;
 }
 export interface CopySetupResult {
-    /** The tracked files enumerated for the push (post-exclusion). */
     files: string[];
-    /** rsync exit code, or null when the process failed to spawn. */
     pushExitCode: number | null;
-    /** `agents sync --local` exit code, or null when it was skipped/failed to spawn. */
     refreshExitCode: number | null;
 }
-/**
- * git-tracked files under `dir` (paths relative to `dir`), minus the never-copy
- * set. Returns `[]` when `dir` is not a git repo — a caller with no tracked
- * `~/.agents` simply copies nothing.
- */
 export declare function enumerateTrackedFiles(dir: string): string[];
-/**
- * Split crabbox's ssh argv (`['ssh', …opts, 'crabbox@host']`) into the `-e`
- * transport string (`ssh …opts`) and the `crabbox@host` endpoint. This is what
- * carries the per-lease identity key + known_hosts a raw ssh lacks.
- */
 export declare function sshTransportFromArgv(sshArgv: string[]): {
     rsh: string;
     host: string;
 };
-/**
- * rsync argv to push the tracked file set to `~/.agents` on the box. Reads the
- * NUL-separated list at `filesFrom` (`--from0`, matching `ls-files -z`) so paths
- * with spaces survive, and tunnels over crabbox's own ssh (`rsh`).
- */
 export declare function buildSetupRsyncArgs(opts: {
     rsh: string;
     host: string;
@@ -80,12 +23,5 @@ export declare function buildSetupRsyncArgs(opts: {
     source: string;
     remoteDir?: string;
 }): string[];
-/**
- * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
- * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
- * `agents sync --local` on the box. Refresh is skipped when the push fails or the
- * file set is empty (nothing to refresh). Never throws — surfaces failure through
- * the returned exit codes.
- */
 export declare function copySetupToBox(opts: CopySetupOptions): Promise<CopySetupResult>;
 export {};

package/dist/lib/crabbox/setup-copy.js

@@ -1,42 +1,11 @@
-/**
- * Setup-copy for `agents run --lease` (RUSH-1920), transport = PUSH-FROM-LOCAL.
- *
- * A fresh crabbox box has agents-cli installed but none of the caller's own
- * `~/.agents` config (skills, hooks, commands, MCP, profiles). This module
- * replicates the *git-tracked* subset of the LOCAL `~/.agents` onto the box:
- *
- *   1. `git -C <userAgentsDir> ls-files` — tracked files only. Tracked-only is
- *      the safety boundary: it excludes `.history/`, `.cache/`, `.system/` and
- *      any keychain-backed secrets by construction (those are gitignored), so no
- *      credential material is ever pushed.
- *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
- *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
- *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
- *   3. `agents sync --local` on the box so the copied config takes effect.
- *
- * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
- * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
- * filter belts-and-braces the tracked-only guarantee.
- *
- * This is a self-contained local function the command layer calls; it does NOT
- * ride the box-side bootstrap script (that only echoes the `copy-setup` progress
- * sentinel — see `buildBootstrapScript`).
- */
 import { spawn, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { getUserAgentsDir } from '../state.js';
 import { crabboxEnv, crabboxSshArgv } from './cli.js';
-/** Remote path (relative to the box user's home) the tracked config lands in. */
 const REMOTE_AGENTS_DIR = '.agents/';
-/** Top-level paths that must never be pushed, even if somehow tracked. */
 const NEVER_COPY = new Set(['.claude', '.claude.json']);
-/**
- * git-tracked files under `dir` (paths relative to `dir`), minus the never-copy
- * set. Returns `[]` when `dir` is not a git repo — a caller with no tracked
- * `~/.agents` simply copies nothing.
- */
 export function enumerateTrackedFiles(dir) {
     const r = spawnSync('git', ['-C', dir, 'ls-files', '-z'], { encoding: 'utf-8' });
     if (r.status !== 0 || !r.stdout)
@@ -49,21 +18,11 @@ export function enumerateTrackedFiles(dir) {
         return !NEVER_COPY.has(f) && !NEVER_COPY.has(top);
     });
 }
-/**
- * Split crabbox's ssh argv (`['ssh', …opts, 'crabbox@host']`) into the `-e`
- * transport string (`ssh …opts`) and the `crabbox@host` endpoint. This is what
- * carries the per-lease identity key + known_hosts a raw ssh lacks.
- */
 export function sshTransportFromArgv(sshArgv) {
     const host = sshArgv[sshArgv.length - 1];
-    const rsh = sshArgv.slice(0, -1).join(' '); // 'ssh -i <key> -o … -p 2222'
+    const rsh = sshArgv.slice(0, -1).join(' ');
     return { rsh, host };
 }
-/**
- * rsync argv to push the tracked file set to `~/.agents` on the box. Reads the
- * NUL-separated list at `filesFrom` (`--from0`, matching `ls-files -z`) so paths
- * with spaces survive, and tunnels over crabbox's own ssh (`rsh`).
- */
 export function buildSetupRsyncArgs(opts) {
     const remote = `${opts.host}:${opts.remoteDir ?? REMOTE_AGENTS_DIR}`;
     const source = opts.source.endsWith('/') ? opts.source : `${opts.source}/`;
@@ -85,21 +44,12 @@ function runStreaming(cmd, args, env, onData) {
         proc.on('close', (code) => resolve(code));
     });
 }
-/**
- * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
- * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
- * `agents sync --local` on the box. Refresh is skipped when the push fails or the
- * file set is empty (nothing to refresh). Never throws — surfaces failure through
- * the returned exit codes.
- */
 export async function copySetupToBox(opts) {
     const dir = opts.userAgentsDir ?? getUserAgentsDir();
     const files = enumerateTrackedFiles(dir);
     if (files.length === 0) {
         return { files, pushExitCode: null, refreshExitCode: null };
     }
-    // crabbox provisions a per-lease ssh key; a raw `ssh crabbox@ip` fails publickey.
-    // Ask crabbox for its exact ssh invocation and tunnel rsync through it.
     const sshArgv = crabboxSshArgv(opts.slug, { secretsBundle: opts.secretsBundle });
     if (!sshArgv) {
         return { files, pushExitCode: null, refreshExitCode: null };
@@ -125,13 +75,11 @@ export async function copySetupToBox(opts) {
                 return { files, pushExitCode: prepareExitCode, refreshExitCode: null };
             }
         }
-        // NUL-separated list, matching `buildSetupRsyncArgs`'s `--from0`.
         fs.writeFileSync(listPath, files.join('\0'), 'utf-8');
         const rsyncArgs = buildSetupRsyncArgs({ rsh, host, filesFrom: listPath, source: dir, remoteDir: opts.remoteDir });
         const pushExitCode = await runStreaming('rsync', rsyncArgs, env, opts.onData);
         let refreshExitCode = null;
         if (pushExitCode === 0 && opts.refresh !== false) {
-            // ssh <opts> crabbox@host bash -lc 'agents sync --local -y'
             const refreshArgs = [...sshArgv.slice(1), 'bash', '-lc', 'agents sync --local -y'];
             refreshExitCode = await runStreaming('ssh', refreshArgs, env, opts.onData);
         }

package/dist/lib/daemon/account-state-daemon-service.d.ts

@@ -1,36 +1,12 @@
-/**
- * Account-state services as supervised `PeriodicService`s (PHNX-3608).
- *
- * The daemon owns usage and authentication health as first-party device state.
- * This used to run its OWN two `setInterval` loops behind a `usageRunning` /
- * `authRunning` latch with NO deadline (`account-state-service.ts`, now removed):
- * a `runUsageRefreshTick` that hung on an unbounded provider await latched
- * `usageRunning = true` forever, so the usage cache froze for the daemon's whole
- * life while the service still looked healthy — the "12h usage-dark" root cause.
- *
- * Now usage and auth are TWO independent supervised services, each with its own
- * timer, per-tick deadline, AbortSignal, and — crucially — its own circuit
- * breaker (`AccountUsageService` = `account-state`, `AccountAuthService` =
- * `account-auth`). Keeping them separate means a run of usage-refresh failures
- * parks ONLY usage and never starves the slower auth refresh (they hit different
- * endpoints), matching the old design's independent loops. Each threads its
- * deadline AbortSignal into its refresh so the tick unwinds at the deadline
- * instead of blocking; the provider fetch is itself already bounded
- * (`AbortSignal.timeout` at the leaf), and the supervisor abandons + restarts a
- * hung tick regardless.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 import type { AuthProbeRow } from '../auth-health.js';
-/** Usage cache refresh cadence. */
 export declare const USAGE_STATE_TICK_MS = 60000;
-/** Fleet-auth refresh cadence — deliberately slower (rate-limited endpoint). */
 export declare const AUTH_STATE_TICK_MS: number;
 type AccountAuthRefresh = (signal: AbortSignal) => Promise<AuthProbeRow[] | void>;
 type AccountTransitionNotifier = (transition: DeadAccountTransition) => Promise<void>;
 interface DeadAccountTransition {
     agent: AuthProbeRow['agent'];
-    /** Display label (email / account name) — presentation only, never a key. */
     account: string;
     verdict: 'expired' | 'revoked';
 }
@@ -38,10 +14,6 @@ interface AccountAuthServiceOptions {
     stateFile?: string;
     notify?: AccountTransitionNotifier;
 }
-/**
- * Refresh the usage cache the `agents run` router reads. Independent circuit
- * breaker from auth — a persistently-failing usage endpoint parks only this.
- */
 export declare class AccountUsageService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs = 60000;
@@ -52,11 +24,6 @@ export declare class AccountUsageService extends BasePeriodicService {
     protected onStop(): Promise<void>;
     protected onTick(_ctx: DaemonContext, signal: AbortSignal): Promise<void>;
 }
-/**
- * Publish this host's fleet-status row and refresh auth health. Independent
- * circuit breaker from usage, and on a slower cadence (the auth verdict rides a
- * rate-limited endpoint).
- */
 export declare class AccountAuthService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;
@@ -70,21 +37,6 @@ export declare class AccountAuthService extends BasePeriodicService {
     protected onTick(_ctx: DaemonContext, signal: AbortSignal): Promise<void>;
 }
 export declare function publishAccountDaemonStateRows(rows: readonly AuthProbeRow[], userAgentsDir?: string): Promise<void>;
-/**
- * Detect live → expired/revoked transitions and deliver one owner-important
- * feed post each, through a persisted outbox:
- *
- * 1. Newly-dead accounts are ENQUEUED into `pending` and the state is written
- *    BEFORE any delivery is attempted — a crash or a failed sink can never
- *    strand a transition in the already-recorded `entries` with no retry.
- * 2. Every pending item (fresh and retried) is delivered; an item leaves
- *    `pending` only after its notifier resolves, and the state is written
- *    again. A crash in the narrow window between a successful post and that
- *    second write re-sends once — at-least-once, never zero.
- *
- * Delivery failures keep their outbox entries AND throw after the state is
- * durable, so the supervisor's circuit breaker still sees the unhealthy tick.
- */
 export declare function processAccountAuthTransitions(rows: readonly AuthProbeRow[], options?: {
     stateFile?: string;
     notify?: AccountTransitionNotifier;

package/dist/lib/daemon/account-state-daemon-service.js

@@ -1,24 +1,3 @@
-/**
- * Account-state services as supervised `PeriodicService`s (PHNX-3608).
- *
- * The daemon owns usage and authentication health as first-party device state.
- * This used to run its OWN two `setInterval` loops behind a `usageRunning` /
- * `authRunning` latch with NO deadline (`account-state-service.ts`, now removed):
- * a `runUsageRefreshTick` that hung on an unbounded provider await latched
- * `usageRunning = true` forever, so the usage cache froze for the daemon's whole
- * life while the service still looked healthy — the "12h usage-dark" root cause.
- *
- * Now usage and auth are TWO independent supervised services, each with its own
- * timer, per-tick deadline, AbortSignal, and — crucially — its own circuit
- * breaker (`AccountUsageService` = `account-state`, `AccountAuthService` =
- * `account-auth`). Keeping them separate means a run of usage-refresh failures
- * parks ONLY usage and never starves the slower auth refresh (they hit different
- * endpoints), matching the old design's independent loops. Each threads its
- * deadline AbortSignal into its refresh so the tick unwinds at the deadline
- * instead of blocking; the provider fetch is itself already bounded
- * (`AbortSignal.timeout` at the leaf), and the supervisor abandons + restarts a
- * hung tick regardless.
- */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { BasePeriodicService } from './service.js';
@@ -31,23 +10,12 @@ import { withFileLockAsync } from '../fs-atomic.js';
 import { machineId } from '../machine-id.js';
 import { getConfigValueAsync, isHeadedDeviceRole } from '../device-config.js';
 import { harnessWorkerIsPerDevice } from '../harness-auth-capabilities.js';
-/** Usage cache refresh cadence. */
 export const USAGE_STATE_TICK_MS = 60_000;
-/** Fleet-auth refresh cadence — deliberately slower (rate-limited endpoint). */
 export const AUTH_STATE_TICK_MS = 3 * 60_000;
-/** A hung refresh is abandoned at this deadline; a real sweep is far under it. */
 const REFRESH_DEADLINE_MS = 2 * 60_000;
 const NOTIFY_DEADLINE_MS = 30_000;
 const ACCOUNT_TRANSITIONS_FILE = 'account-auth-transitions.json';
-// Resolve the current CLI once at daemon startup. getCliLaunch performs sync
-// filesystem probes, so it must never run inside a service tick.
 const FEED_POST_LAUNCH = getCliLaunch([]);
-/**
- * A promise that rejects when `signal` aborts (immediately if already aborted),
- * so a tick can `Promise.race` its work against the supervisor's deadline and
- * unwind instead of blocking on an await that may never settle. The signal is
- * per-tick, so the once-listener is dropped with it — no cross-tick leak.
- */
 function abortRejection(signal, label) {
     return new Promise((_, reject) => {
         if (signal.aborted) {
@@ -57,10 +25,6 @@ function abortRejection(signal, label) {
         signal.addEventListener('abort', () => reject(new Error(label)), { once: true });
     });
 }
-/**
- * Refresh the usage cache the `agents run` router reads. Independent circuit
- * breaker from auth — a persistently-failing usage endpoint parks only this.
- */
 export class AccountUsageService extends BasePeriodicService {
     id = 'account-state';
     intervalMs = USAGE_STATE_TICK_MS;
@@ -79,11 +43,6 @@ export class AccountUsageService extends BasePeriodicService {
         ]);
     }
 }
-/**
- * Publish this host's fleet-status row and refresh auth health. Independent
- * circuit breaker from usage, and on a slower cadence (the auth verdict rides a
- * rate-limited endpoint).
- */
 export class AccountAuthService extends BasePeriodicService {
     id = 'account-auth';
     intervalMs = AUTH_STATE_TICK_MS;
@@ -122,9 +81,6 @@ export async function publishAccountDaemonStateRows(rows, userAgentsDir) {
     const role = (await getConfigValueAsync('role', { device })).value;
     const headed = isHeadedDeviceRole(role);
     const accountRows = [...collapseAccountRows(rows).values()].map((row) => ({
-        // The registered account id is the only stable identity: two accounts may
-        // share one email (different orgs), so the display label is never a key.
-        // Unregistered legacy homes have no registry id and fall back to the label.
         accountId: row.accountId ?? row.account ?? row.version,
         identityLabel: row.account,
         harness: row.agent,
@@ -163,9 +119,8 @@ export async function publishAccountDaemonStateRows(rows, userAgentsDir) {
         await fsp.rename(temp, file);
     });
 }
+// Registered account id is stable; only unregistered legacy homes fall back to the display label, so same-email named accounts remain distinct.
 function transitionKey(row) {
-    // Stable identity first (registered account id); the display label is the
-    // fallback for unregistered legacy homes, never the key for a named account.
     return `${row.agent}:${row.accountId ?? row.account ?? `version:${row.version}`}`;
 }
 function verdictRank(verdict) {
@@ -195,7 +150,6 @@ async function readTransitionState(file) {
     try {
         const parsed = JSON.parse(await fsp.readFile(file, 'utf-8'));
         if ((parsed.version === 1 || parsed.version === 2) && parsed.entries && typeof parsed.entries === 'object') {
-            // Version 1 files predate the outbox; they upgrade with an empty one.
             return { version: 2, entries: parsed.entries, pending: parsed.pending ?? {} };
         }
     }
@@ -212,21 +166,6 @@ async function writeTransitionState(file, state) {
     await fsp.writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
     await fsp.rename(temp, file);
 }
-/**
- * Detect live → expired/revoked transitions and deliver one owner-important
- * feed post each, through a persisted outbox:
- *
- * 1. Newly-dead accounts are ENQUEUED into `pending` and the state is written
- *    BEFORE any delivery is attempted — a crash or a failed sink can never
- *    strand a transition in the already-recorded `entries` with no retry.
- * 2. Every pending item (fresh and retried) is delivered; an item leaves
- *    `pending` only after its notifier resolves, and the state is written
- *    again. A crash in the narrow window between a successful post and that
- *    second write re-sends once — at-least-once, never zero.
- *
- * Delivery failures keep their outbox entries AND throw after the state is
- * durable, so the supervisor's circuit breaker still sees the unhealthy tick.
- */
 export async function processAccountAuthTransitions(rows, options = {}) {
     const file = options.stateFile ?? path.join(getDaemonDir(), ACCOUNT_TRANSITIONS_FILE);
     const notify = options.notify ?? postImportantAccountTransition;
@@ -248,7 +187,7 @@ export async function processAccountAuthTransitions(rows, options = {}) {
             };
         }
     }
-    // Durable BEFORE delivery: a pending entry survives a crash mid-notify.
+    // Persist the transition to the outbox before notifying; delete only after success for at-least-once delivery.
     await writeTransitionState(file, next);
     const delivered = [];
     const failures = [];

package/dist/lib/daemon/attention-notify-service.d.ts

@@ -28,23 +28,12 @@ import { type AttentionItem } from '../feed/attention.js';
 import { type DesktopNotification } from '../menubar/notify-desktop.js';
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
-/**
- * The banner for one attention item, or `undefined` when its kind does not
- * notify (`done` comes from the run process; `declared`/`review` are surfaced in
- * the feed, not as a native banner). Pure — the service and its test both build
- * through here, so what ships is what is asserted.
- */
 export declare function buildAttentionNotification(item: AttentionItem, session: ActiveSession): DesktopNotification | undefined;
 interface AttentionNotifyServiceOptions {
-    /** Live-session source (default: the real active-session query). Injected in tests. */
     getSessions?: () => Promise<ActiveSession[]>;
-    /** Notifier (default: the real desktop notifier). Injected in tests to capture posts. */
     notify?: (n: DesktopNotification) => void;
-    /** Feed store root (default: the real feed dir). Overridden in tests. */
     feedRoot?: string;
-    /** Notified-ledger dir (default: `<feedRoot>/notified`). Overridden in tests. */
     ledgerDir?: string;
-    /** Clock (default: `Date.now`). Injected in tests. */
     now?: () => number;
 }
 export declare class AttentionNotifyService extends BasePeriodicService {
@@ -61,7 +50,6 @@ export declare class AttentionNotifyService extends BasePeriodicService {
     protected onStart(_ctx: DaemonContext): Promise<void>;
     protected onStop(): Promise<void>;
     protected onTick(ctx: DaemonContext): Promise<void>;
-    /** Filesystem-safe sidecar name for an attention key (`host/session/generation`). */
     private ledgerPath;
     private hasNotified;
     private markNotified;