@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/auth-mint.d.ts

@@ -1,64 +1,25 @@
-/**
- * First-class setup-token mint + seed (PHNX-2364).
- *
- * Closes the mint-auth manual recipe: drive `claude setup-token` through an
- * injectable term driver (`lib/term-driver.ts`), capture a well-formed
- * `sk-ant-oat01-…` token (the #1767 ANSI-banner guard), and seed BOTH:
- *
- *   1. a named provider account (`agents accounts add` shape, policy never)
- *   2. the reserved FILE-BASED `auth` bundle keyed per-account email, which
- *      usage/probe reads (`resolveClaudeSetupToken`)
- *
- * Native rotating OAuth is never copied. Only this non-rotating class is
- * stored and optionally synced. Interactive mint is Claude-only; every other
- * harness fails loud with the command that actually provisions it.
- */
 import type { AgentId, Meta } from './types.js';
 import { type CredentialAccount } from './account-registry.js';
 import { type StorableCredentialKind } from './secrets-policy.js';
 import { type DriveOptions, type TermDriver } from './term-driver.js';
-/** Well-formed Claude setup-token as it appears inside a TTY blob. */
 export declare const CLAUDE_SETUP_TOKEN_CAPTURE_RE: RegExp;
 export interface MintFlow {
     harness: AgentId;
     provider: string;
     auth: 'setup-token' | 'api-key';
-    /** Interactive mint argv after HOME=… <bin>. Null when stdin-seed only or an api-key collection flow. */
     mintArgs: string[] | null;
-    /** api-key flows: the env var the collected key injects as on a worker (e.g. OPENAI_API_KEY). */
     apiKeyEnv?: string;
-    /** setup-token flows: authorize-URL and token patterns scraped from the term session. */
     verificationUrlRegex?: RegExp;
     tokenCapture?: RegExp;
 }
-/**
- * Durable-credential flows per harness. Only Claude exposes an interactive
- * setup-token MINT; every other harness's durable credential is a provider API
- * key, COLLECTED via `--api-key` or a prompt by `accounts add` (never derived
- * from OAuth). The api-key entries describe collection only — they have no
- * mint argv, and `mintAndSeed` refuses them with the `accounts add` pointer.
- * A token-less harness (kimi/antigravity) has no portable credential and logs
- * in per box (run it there and complete its native login).
- * The apiKeyEnv values are pinned to HARNESS_AUTH's `api-key:<ENV>` worker
- * kinds by auth-mint.test.ts — keep them in lockstep.
- */
 export declare const MINT_FLOWS: Record<string, MintFlow>;
-/** Harnesses with an interactive setup-token mint (api-key flows are collection, not mint). */
 export declare function listMintableHarnesses(): AgentId[];
 export declare function getMintFlow(harnessRaw: string): MintFlow;
 export declare function unmintableMessage(harness: string): string;
-/** Strip CSI / Fe ANSI so a #1767 TTY blob can be scanned for a real token. */
 export declare function stripAnsi(text: string): string;
-/**
- * Pull a single well-formed Claude setup-token out of a (possibly ANSI-wrapped)
- * screen. Returns null when none is present. Two distinct tokens fail loud —
- * guessing which one to seed is how a banner fragment becomes an auth header.
- */
 export declare function extractClaudeSetupToken(screen: string): string | null;
-/** First https URL on the screen, trailing punctuation stripped. */
 export declare function extractMintUrl(screen: string, flow: MintFlow): string | undefined;
 export declare function isEmail(value: string): boolean;
-/** Account-name slug of an email (`ada@example.com` → `ada-at-example.com`). */
 export declare function accountNameFromEmail(email: string): string;
 export declare function assertValidSetupToken(token: string): string;
 export interface ResolveMintIdentityInput {
@@ -70,27 +31,10 @@ export interface ResolvedMintIdentity {
     accountName: string;
     email: string;
 }
-/**
- * Resolve the named account + the email that keys the reserved `auth` bundle.
- * `--account` that looks like an email is the email; a name needs `--email` or
- * a locally signed-in `.claude.json`. Missing email fails loud — we must not
- * fall back to a bare shared key (that is the multi-account mix-up).
- */
 export declare function resolveMintIdentity(input: ResolveMintIdentityInput): ResolvedMintIdentity;
-/**
- * Write (or rotate) the reserved FILE-BASED `auth` bundle's per-account key.
- * Usage/probe ignores a keychain- or vault-backed bundle of this name, so a
- * wrong backend fails loud instead of looking like a successful mint.
- */
 export declare function seedReservedAuthToken(email: string, token: string): {
     key: string;
 };
-/**
- * The env var a harness's durable worker credential injects as on a worker
- * (claude's setup-token rides CLAUDE_CODE_OAUTH_TOKEN; api-key harnesses ride
- * their MINT_FLOWS apiKeyEnv). Throws for a harness with no portable worker
- * credential — kimi/antigravity log in per box.
- */
 export declare function workerCredentialEnv(harness: AgentId): string;
 /**
  * The reserved-store key for one account's worker credential:
@@ -122,26 +66,11 @@ export interface AdoptLegacyReservedItemsResult {
         message: string;
     }>;
 }
-/**
- * Adopt reserved-store keys written by 1.22.84–1.22.89 as bare file items (no
- * bundle record) into the file-backed bundle the daemon push reads. Every
- * `accounts add codex|grok|cursor` from those releases left its worker key in
- * that shape on the laptop, unpushable; the item name is the same in both
- * shapes, so adoption re-seeds the bundle from the raw value in place and
- * nothing already on a worker changes. Idempotent: a key the bundle already
- * carries is skipped. Local data repair only — it never talks to a peer.
- */
 export declare function adoptLegacyReservedStoreItems(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): AdoptLegacyReservedItemsResult;
-/**
- * Create or rotate the named provider account that `agents run --account` and
- * `agents accounts sync` consume. Existing account of a different kind fails
- * loud rather than silently overwriting an API key with a setup-token.
- */
 export declare function seedNamedAccount(name: string, token: string, flow: MintFlow): CredentialAccount;
 export interface MintDriveHooks {
     driver?: TermDriver;
     openUrl?: (url: string) => Promise<void>;
-    /** Asked once the authorize URL is on screen, when `--code` was not given. */
     readCode?: () => Promise<string | undefined>;
     drive?: DriveOptions;
 }
@@ -152,14 +81,8 @@ export interface DriveMintResult {
 }
 export interface DriveSetupTokenMintOpts extends MintDriveHooks {
     code?: string;
-    /** Suppress stdout progress so `--json` callers get a parseable blob. */
     json?: boolean;
 }
-/**
- * Drive `claude setup-token` in a term session: scrape the authorize URL, open it,
- * optionally paste `--code`, then capture the token with the #1767 guard.
- * Tears the session down on the way out (success, timeout, or throw).
- */
 export declare function driveSetupTokenMint(command: string, flow: MintFlow, opts?: DriveSetupTokenMintOpts): Promise<DriveMintResult>;
 export declare function buildMintCommand(flow: MintFlow, bin: string, home: string, env?: Record<string, string>): string;
 export declare function resolveMintInstallation(harness: AgentId): {
@@ -176,7 +99,6 @@ export interface MintAndSeedInput {
     open?: boolean;
     fleet?: boolean;
     devices?: string[];
-    /** Suppress progress prints so `--json` stdout stays machine-parseable. */
     json?: boolean;
     hooks?: MintDriveHooks;
 }
@@ -193,11 +115,6 @@ export interface MintAndSeedResult {
     rotated: boolean;
     fleet: FleetSyncRow[];
 }
-/**
- * End-to-end mint: resolve identity, obtain a token (stdin or term drive),
- * seed the named account + reserved auth bundle, optionally sync the fleet.
- * Never returns or logs the token.
- */
 export declare function mintAndSeed(input: MintAndSeedInput): Promise<MintAndSeedResult>;
 export declare function resolveSyncTargets(fleet: boolean, devices: string[]): Promise<string[]>;
 /**

package/dist/lib/auth-mint.js

@@ -11,28 +11,15 @@ import { loadDevices } from './devices/registry.js';
 import { isSelfHost } from './devices/self-host.js';
 import { assertCredentialTransportHostPinned, resolveHostSshTarget } from './hosts/credential-transport.js';
 import { resolveRemoteOsSync } from './hosts/remote-os.js';
-/** Well-formed Claude setup-token as it appears inside a TTY blob. */
 export const CLAUDE_SETUP_TOKEN_CAPTURE_RE = /sk-ant-oat01-[A-Za-z0-9_-]+/;
 const ACCOUNT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-/**
- * Durable-credential flows per harness. Only Claude exposes an interactive
- * setup-token MINT; every other harness's durable credential is a provider API
- * key, COLLECTED via `--api-key` or a prompt by `accounts add` (never derived
- * from OAuth). The api-key entries describe collection only — they have no
- * mint argv, and `mintAndSeed` refuses them with the `accounts add` pointer.
- * A token-less harness (kimi/antigravity) has no portable credential and logs
- * in per box (run it there and complete its native login).
- * The apiKeyEnv values are pinned to HARNESS_AUTH's `api-key:<ENV>` worker
- * kinds by auth-mint.test.ts — keep them in lockstep.
- */
 export const MINT_FLOWS = {
     claude: {
         harness: 'claude',
         provider: 'anthropic',
         auth: 'setup-token',
         mintArgs: ['setup-token'],
-        // Authorize URL printed by `claude setup-token` before it waits for a code.
         verificationUrlRegex: /(https:\/\/[^\s"'<>]+)/i,
         tokenCapture: CLAUDE_SETUP_TOKEN_CAPTURE_RE,
     },
@@ -42,7 +29,6 @@ export const MINT_FLOWS = {
     cursor: { harness: 'cursor', provider: 'cursor', auth: 'api-key', mintArgs: null, apiKeyEnv: 'CURSOR_API_KEY' },
     droid: { harness: 'droid', provider: 'factory', auth: 'api-key', mintArgs: null, apiKeyEnv: 'FACTORY_API_KEY' },
 };
-/** Harnesses with an interactive setup-token mint (api-key flows are collection, not mint). */
 export function listMintableHarnesses() {
     return Object.values(MINT_FLOWS).filter((f) => f.auth === 'setup-token').map((f) => f.harness);
 }
@@ -68,16 +54,11 @@ export function unmintableMessage(harness) {
         `API-key / pasted-token accounts use \`agents accounts add <name> --provider <provider> --auth api-key\`.`,
     ].join(' ');
 }
-/** Strip CSI / Fe ANSI so a #1767 TTY blob can be scanned for a real token. */
 export function stripAnsi(text) {
     return text.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
 }
-/**
- * Pull a single well-formed Claude setup-token out of a (possibly ANSI-wrapped)
- * screen. Returns null when none is present. Two distinct tokens fail loud —
- * guessing which one to seed is how a banner fragment becomes an auth header.
- */
 export function extractClaudeSetupToken(screen) {
+    // Capture exactly one clean token; terminal output must never be guessed into a credential.
     const text = stripAnsi(screen);
     const matches = text.match(new RegExp(CLAUDE_SETUP_TOKEN_CAPTURE_RE.source, 'g')) ?? [];
     const unique = [...new Set(matches.filter(isValidClaudeSetupToken))];
@@ -88,7 +69,6 @@ export function extractClaudeSetupToken(screen) {
     }
     return unique[0];
 }
-/** First https URL on the screen, trailing punctuation stripped. */
 export function extractMintUrl(screen, flow) {
     if (!flow.verificationUrlRegex)
         return undefined;
@@ -102,7 +82,6 @@ export function extractMintUrl(screen, flow) {
 export function isEmail(value) {
     return EMAIL_RE.test(value.trim());
 }
-/** Account-name slug of an email (`ada@example.com` → `ada-at-example.com`). */
 export function accountNameFromEmail(email) {
     const slug = email
         .trim()
@@ -121,13 +100,8 @@ export function assertValidSetupToken(token) {
     }
     return cleaned;
 }
-/**
- * Resolve the named account + the email that keys the reserved `auth` bundle.
- * `--account` that looks like an email is the email; a name needs `--email` or
- * a locally signed-in `.claude.json`. Missing email fails loud — we must not
- * fall back to a bare shared key (that is the multi-account mix-up).
- */
 export function resolveMintIdentity(input) {
+    // Worker credentials are per-account, so minting requires a concrete email identity.
     const accountRaw = input.account?.trim();
     const emailRaw = input.email?.trim();
     const fromHome = readClaudeAccountEmail(input.home);
@@ -162,11 +136,6 @@ export function resolveMintIdentity(input) {
         accountName = accountNameFromEmail(email);
     return { accountName, email };
 }
-/**
- * Write (or rotate) the reserved FILE-BASED `auth` bundle's per-account key.
- * Usage/probe ignores a keychain- or vault-backed bundle of this name, so a
- * wrong backend fails loud instead of looking like a successful mint.
- */
 export function seedReservedAuthToken(email, token) {
     const cleaned = assertValidSetupToken(token);
     const key = claudeAccountTokenKey(email);
@@ -203,12 +172,6 @@ export function seedReservedAuthToken(email, token) {
     invalidateClaudeSetupTokenCache();
     return { key };
 }
-/**
- * The env var a harness's durable worker credential injects as on a worker
- * (claude's setup-token rides CLAUDE_CODE_OAUTH_TOKEN; api-key harnesses ride
- * their MINT_FLOWS apiKeyEnv). Throws for a harness with no portable worker
- * credential — kimi/antigravity log in per box.
- */
 export function workerCredentialEnv(harness) {
     if (harness === 'claude')
         return 'CLAUDE_CODE_OAUTH_TOKEN';
@@ -239,22 +202,12 @@ export function workerCredentialStoreKey(harness, accountId) {
  * loud, since worker provisioning reads the file backend.
  */
 export function seedReservedStoreKey(harness, kind, key, value) {
+    // Reserved worker bundles are real file-backed policy-never stores, never rotating OAuth/session credentials.
     assertStorableCredentialKind(kind, harness);
     const name = reservedStoreName(harness);
     const cleaned = value.trim();
     if (!cleaned)
         throw new Error(`Empty ${kind} for reserved store '${name}' key ${key}.`);
-    // A `__<harness>__` reserved store is a real FILE-backed, policy-`never` bundle
-    // — the same shape as the legacy `auth` bundle — because the only transport to
-    // a worker is the ordinary bundle push (`syncReservedStores` →
-    // `pushBundleToHost`), which reads the store as a bundle and imports it
-    // remotely as one. It used to be written as a bare `store.set` item with no
-    // bundle record (the standalone rejected the `__`-wrapped name at the time), so
-    // the push could never read it and no worker received a Cursor/Codex/Grok key.
-    // The item name is unchanged (`agents-cli.secrets.__<harness>__.<KEY>`), so
-    // `readReservedCredential` and every worker that already holds the raw item
-    // keep resolving it. Requires -labs/secrets-cli >= 0.1.1 (reserved-shape
-    // bundle names).
     const item = secretsKeychainItem(name, key);
     try {
         if (bundleExistsSync(name)) {
@@ -286,25 +239,14 @@ export function seedReservedStoreKey(harness, kind, key, value) {
         return { bundle: name, key };
     }
     catch (err) {
-        // A standalone older than 0.1.1 rejects the `__<harness>__` bundle name and
-        // the client only sees a sanitized code. Name the real requirement instead
-        // of leaving `accounts add` to fail with `OPERATION_FAILED`.
         if (isSecretsClientError(err, 'OPERATION_FAILED')) {
             throw new Error(`Could not write the reserved store '${name}' as a bundle: ${err.message}. agents-cli needs @phnx-labs/secrets-cli 0.1.1 or newer, which accepts the __<harness>__ bundle name: npm i -g @phnx-labs/secrets-cli@latest`);
         }
         throw err;
     }
 }
-/**
- * Adopt reserved-store keys written by 1.22.84–1.22.89 as bare file items (no
- * bundle record) into the file-backed bundle the daemon push reads. Every
- * `accounts add codex|grok|cursor` from those releases left its worker key in
- * that shape on the laptop, unpushable; the item name is the same in both
- * shapes, so adoption re-seeds the bundle from the raw value in place and
- * nothing already on a worker changes. Idempotent: a key the bundle already
- * carries is skipped. Local data repair only — it never talks to a peer.
- */
 export function adoptLegacyReservedStoreItems(meta) {
+    // Local and idempotent: skip present keys, adopt legacy bare items into the file bundle, never contact peers, and report per-key failures.
     const result = { adopted: [], errors: [] };
     for (const account of listNativeAccounts(meta)) {
         const cred = account.workerCredential;
@@ -327,12 +269,8 @@ export function adoptLegacyReservedStoreItems(meta) {
     }
     return result;
 }
-/**
- * Create or rotate the named provider account that `agents run --account` and
- * `agents accounts sync` consume. Existing account of a different kind fails
- * loud rather than silently overwriting an API key with a setup-token.
- */
 export function seedNamedAccount(name, token, flow) {
+    // Never replace an existing account whose provider or auth kind differs.
     const cleaned = assertValidSetupToken(token);
     const existing = findAccount(name);
     if (!existing)
@@ -343,17 +281,13 @@ export function seedNamedAccount(name, token, flow) {
     setAccountSecret(name, cleaned);
     return existing;
 }
-/** Stdout progress for the mint path. `--json` / quiet: drop it (stderr errors stay). */
 function emitMintProgress(line, json) {
+    // Machine-readable stdout stays clean.
     if (!json)
         console.log(line);
 }
-/**
- * Drive `claude setup-token` in a term session: scrape the authorize URL, open it,
- * optionally paste `--code`, then capture the token with the #1767 guard.
- * Tears the session down on the way out (success, timeout, or throw).
- */
 export async function driveSetupTokenMint(command, flow, opts = {}) {
+    // The terminal is torn down on every path, and its token is returned only in memory, never logged.
     if (flow.auth !== 'setup-token' || !flow.tokenCapture) {
         throw new Error(`Harness '${flow.harness}' has no interactive mint command.`);
     }
@@ -365,7 +299,6 @@ export async function driveSetupTokenMint(command, flow, opts = {}) {
     const openUrl = opts.openUrl ?? (async (url) => {
         const shown = await showUrl(url);
         if (shown.via === 'none') {
-            // stderr: `--json` stdout stays parseable; the operator still gets the URL.
             console.error(`Could not open a browser — open this yourself:\n  ${url}`);
         }
     });
@@ -443,16 +376,10 @@ export function resolveMintInstallation(harness) {
         home: getVersionHomePath(harness, version),
     };
 }
-/**
- * End-to-end mint: resolve identity, obtain a token (stdin or term drive),
- * seed the named account + reserved auth bundle, optionally sync the fleet.
- * Never returns or logs the token.
- */
 export async function mintAndSeed(input) {
+    // Claude alone mints a durable setup token interactively; API-key flows collect keys and tokenless harnesses log in per box.
     const flow = getMintFlow(input.harness);
     const json = input.json === true;
-    // An injected term driver is a complete substitute for exec'ing the local
-    // binary, so the install lookup is only required on the real drive path.
     const install = input.token
         ? null
         : input.hooks?.driver
@@ -512,7 +439,6 @@ export async function resolveSyncTargets(fleet, devices) {
     const registry = await loadDevices();
     const known = Object.keys(registry);
     if (named.length) {
-        // A self host in --device is skipped, not an error; an unknown name is.
         const unknown = named.filter((d) => !known.includes(d) && !isSelfHost(d));
         if (unknown.length) {
             throw new Error(`Unknown device${unknown.length === 1 ? '' : 's'} '${unknown.join("', '")}'. Register with \`agents devices\` or omit --device.`);
@@ -578,9 +504,6 @@ async function syncMintedBundles(accountName, device) {
  */
 export function hasMintedSetupToken() {
     try {
-        // The registry is the account bundles behind the standalone `secrets` CLI, so
-        // this read is as reachable — or as unreachable — as the auth-bundle read
-        // below and sits inside the same guard.
         const records = Object.values(readAccountRegistry().accounts);
         const setup = records.filter((a) => a.auth === 'setup-token' && a.provider === 'anthropic');
         if (setup.length) {

package/dist/lib/auto-pull-worker.d.ts

@@ -1,11 +1 @@
-/**
- * Detached worker entry point for background sync. See auto-pull.ts for the public API.
- *
- * For the system repo: fast-forward pull (safe — repo is read-only locally).
- * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
- * CLI surfaces on its next invocation.
- *
- * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
- * Lock mtime under 5 min => skip (another invocation already in flight).
- */
 export {};

package/dist/lib/auto-pull-worker.js

@@ -1,26 +1,8 @@
-/**
- * Detached worker entry point for background sync. See auto-pull.ts for the public API.
- *
- * For the system repo: fast-forward pull (safe — repo is read-only locally).
- * For the user repo + enabled extras: `git fetch` + write a status marker the foreground
- * CLI surfaces on its next invocation.
- *
- * Per-repo lock files at ~/.agents/.system/.fetch/<alias>.lock prevent concurrent fetches.
- * Lock mtime under 5 min => skip (another invocation already in flight).
- */
 import * as fs from 'fs';
 import { simpleGit } from 'simple-git';
 import { tryAutoPullSystemRepo, isGitRepo } from './git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath, markDetachedSyncComplete, SYNC_LOCK_TTL_MS, } from './auto-pull.js';
-/**
- * Background auto-pull of ~/.agents/.system/ is off by default. When enabled it
- * silently fast-forwards a tracked source tree that the CLI then reads as a
- * source of skills, hooks, install manifests, and commands — anyone with push
- * access to that upstream gets remote code execution on every user the next
- * time they invoke a command that loads a system resource. Operators that
- * really want the convenience can set AGENTS_AUTO_PULL=1.
- */
 const ENABLE_AUTO_PULL = process.env.AGENTS_AUTO_PULL === '1';
 function ensureFetchDir() {
     const dir = getFetchCacheDir();
@@ -28,7 +10,7 @@ function ensureFetchDir() {
         try {
             fs.mkdirSync(dir, { recursive: true });
         }
-        catch { /* ignore */ }
+        catch { }
     }
     return dir;
 }
@@ -41,7 +23,6 @@ function tryAcquireLock(alias) {
             return false;
     }
     catch {
-        /* no lock yet */
     }
     try {
         fs.writeFileSync(lock, String(process.pid));
@@ -56,13 +37,13 @@ function touchLock(alias) {
     try {
         fs.utimesSync(lockFilePath(alias), now, now);
     }
-    catch { /* lock gone; nothing to extend */ }
+    catch { }
 }
 function releaseLock(alias) {
     try {
         fs.unlinkSync(lockFilePath(alias));
     }
-    catch { /* ignore */ }
+    catch { }
 }
 function writeStatusMarker(marker) {
     ensureFetchDir();
@@ -70,7 +51,6 @@ function writeStatusMarker(marker) {
         fs.writeFileSync(statusFilePath(marker.alias), JSON.stringify(marker));
     }
     catch {
-        /* best-effort */
     }
 }
 async function notifyRepo(target) {
@@ -100,17 +80,9 @@ async function processTarget(target) {
     try {
         if (target.mode === 'pull') {
             if (!ENABLE_AUTO_PULL) {
-                // Demote to a fetch + notify; the user still sees ahead/behind on the
-                // next foreground CLI invocation, but the source tree is never mutated
-                // by a detached worker.
                 await notifyRepo(target);
             }
             else {
-                // Verify origin is the EXPECTED system remote before fast-forwarding —
-                // the system repo ships hooks that run as shell, so a pull from a
-                // repointed origin is RCE. An unexpected origin is refused, not pulled
-                // (PHNX-2957). The detached worker has no terminal to warn on; the
-                // foreground `agents use` path surfaces the refusal to the operator.
                 await tryAutoPullSystemRepo(target.dir);
             }
         }
@@ -119,28 +91,17 @@ async function processTarget(target) {
         }
     }
     catch {
-        /* network / git failures are non-fatal */
     }
     finally {
         releaseLock(target.alias);
     }
 }
-/**
- * macOS only: fetch the floor AGI Menu release into the verified cache when the
- * installed helper is behind it and no bundle ships with this install, so the
- * next foreground invocation's network-free self-heal has a source to install
- * from (`sourceAppPath` candidate 4). Same lock discipline as the repo targets.
- */
 async function prefetchMenubarHelperTarget() {
     if (process.platform !== 'darwin')
         return;
     const alias = 'menubar-helper';
     if (!tryAcquireLock(alias))
         return;
-    // The zip fetch may run up to 15 min (helper-download.ts) while the lock
-    // reads as stale after SYNC_LOCK_TTL_MS, and the download lands through one
-    // shared partial file — so keep the lock's mtime fresh for as long as this
-    // worker is actually fetching, or a second worker races onto the same bytes.
     const heartbeat = setInterval(() => touchLock(alias), SYNC_LOCK_TTL_MS / 2);
     heartbeat.unref();
     try {
@@ -148,7 +109,6 @@ async function prefetchMenubarHelperTarget() {
         await prefetchMenubarHelper();
     }
     catch {
-        /* network / verification failures are non-fatal; the next cycle retries */
     }
     finally {
         clearInterval(heartbeat);
@@ -171,13 +131,8 @@ async function main() {
         }
     }
     await Promise.all([...targets.map(processTarget), prefetchMenubarHelperTarget()]);
-    // Stamp the cycle so the next foreground CLI invocation can skip the ~7ms
-    // detached spawn for SYNC_LOCK_TTL_MS (RUSH-2324). Written even when every
-    // target was lock-skipped or the target list was empty — "nothing to do"
-    // is still a completed cycle.
     markDetachedSyncComplete();
 }
 main().catch(() => {
-    /* swallow — detached worker must never crash the parent's terminal */
     process.exit(0);
 });

package/dist/lib/auto-pull.d.ts

@@ -1,33 +1,6 @@
-/**
- * Background sync for tracked git repos:
- *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
- *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
- *     as a "Repo updates" section instead of printing to stderr on every command.
- *     Pulling is left to the user via `agents repo pull`.
- *
- * Public API:
- *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
- *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
- *   shouldSkipDetachedSync() — parent-side recency gate (RUSH-2324).
- *   markDetachedSyncComplete() — worker stamps a completed cycle for the parent gate.
- */
-/**
- * Shared 5-minute recency window for per-repo locks (worker) and the parent
- * spawn gate (RUSH-2324). Worker skips a repo when its lock mtime is younger
- * than this; the parent skips the entire detached spawn when a recent cycle
- * completed or every existing lock is still within the window.
- */
 export declare const SYNC_LOCK_TTL_MS: number;
-/** Per-repo lock file path. mtime acts as a recency check. */
 export declare function lockFilePath(alias: string, fetchDir?: string): string;
-/** Per-repo status marker path (for user/extras only). */
 export declare function statusFilePath(alias: string, fetchDir?: string): string;
-/**
- * Stamp written at the end of every detached-worker cycle (including the
- * no-target / all-locks-skipped path). Parent `spawnDetachedSync` stats this
- * one file instead of forking a child on every ordinary CLI invocation.
- */
 export declare function lastSyncStampPath(fetchDir?: string): string;
 export interface FetchStatusMarker {
     alias: string;
@@ -37,44 +10,7 @@ export interface FetchStatusMarker {
     branch: string;
     fetchedAt: number;
 }
-/**
- * Whether the parent should skip forking the detached auto-pull worker.
- *
- * True when either:
- *   1. `.last-sync` exists and its mtime is within {@link SYNC_LOCK_TTL_MS}
- *      (a prior cycle completed recently — the common warm path), or
- *   2. the fetch dir has at least one `*.lock` and every lock is still within
- *      the same window (a worker is mid-flight, or a cycle left locks that
- *      still count as fresh).
- *
- * False (spawn) when the stamp is missing/stale and there are no fresh locks
- * — including a missing fetch dir and an empty one. Cheap: one `stat` or one
- * `readdir` + a few `stat`s; never spawns and never reads git.
- *
- * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
- *   production getFetchCacheDir() path.
- * @param now - Override the clock (for tests).
- * @param ttlMs - Override the recency window (for tests).
- */
 export declare function shouldSkipDetachedSync(fetchDir?: string, now?: number, ttlMs?: number): boolean;
-/**
- * Record that a detached-worker cycle finished (success, empty targets, or
- * every repo skipped by its lock). Best-effort; a failed write just means the
- * next foreground invocation will re-spawn the worker.
- */
 export declare function markDetachedSyncComplete(fetchDir?: string): void;
-/** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
 export declare function spawnDetachedSync(fetchDir?: string): void;
-/**
- * Read all current status markers and return those where the local repo is
- * behind upstream. Markers are NOT deleted — they persist until the next
- * background fetch overwrites them with fresh data.
- *
- * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
- * repo-behind warnings in one place instead of printing to stderr on every
- * command.
- *
- * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
- *   production getFetchCacheDir() path.
- */
 export declare function readRepoBehindMarkers(fetchDir?: string): FetchStatusMarker[];