@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/isolation-boundary-report.d.ts

@@ -1,10 +1,3 @@
 import { IsolationBoundaryError } from './installations/shims.js';
-/**
- * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
- * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
- * trace. The remedy is always the same shape, because the protection is derived from
- * the isolated copies themselves: drop them and the agent is ordinary again.
- */
 export declare function explainIsolationBoundary(err: IsolationBoundaryError): void;
-/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
 export declare function withIsolationBoundary<T>(fn: () => Promise<T> | T): Promise<T | undefined>;

package/dist/lib/isolation-boundary-report.js

@@ -1,12 +1,6 @@
 import chalk from 'chalk';
 import { IsolationBoundaryError } from './installations/shims.js';
 import { listInstalledVersions } from './installations/versions.js';
-/**
- * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
- * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
- * trace. The remedy is always the same shape, because the protection is derived from
- * the isolated copies themselves: drop them and the agent is ordinary again.
- */
 export function explainIsolationBoundary(err) {
     const versions = listInstalledVersions(err.agent);
     console.error(chalk.red(`\n${err.agent} is installed only as isolated copies.`));
@@ -19,7 +13,6 @@ export function explainIsolationBoundary(err) {
         console.error(chalk.gray(`    agents remove ${err.agent}@${v} --isolated`));
     }
 }
-/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
 export async function withIsolationBoundary(fn) {
     try {
         return await fn();

package/dist/lib/launch-identity.d.ts

@@ -1,10 +1,2 @@
-/**
- * Editor identity belongs to the first launch attached to that terminal. The
- * harness inherits it for its own tools, but another `agents run` is a new
- * launch, not another owner of the parent's editor tab. AGENTS_RUNTIME is set
- * by buildExecEnv, whereas an editor's initial launch sets AGENT_TERMINAL_ID
- * (and may already set AGENT_SESSION_ID) without that runtime marker.
- */
 export declare function launchIdentityEnv(env?: NodeJS.ProcessEnv): Record<string, string>;
-/** Identity absent from a new launch must not leak back in from a tmux server. */
 export declare const LAUNCH_IDENTITY_KEYS: readonly ["AGENT_TERMINAL_ID", "AGENT_SESSION_ID", "AGENTS_SESSION_ID", "AGENTS_MAILBOX_DIR", "AGENT_LAUNCH_ID", "AGENTS_PARENT_SESSION_ID", "AGENTS_PARENT_LAUNCH_ID", "AGENTS_ORIGIN_TERMINAL_ID"];

package/dist/lib/launch-identity.js

@@ -1,10 +1,3 @@
-/**
- * Editor identity belongs to the first launch attached to that terminal. The
- * harness inherits it for its own tools, but another `agents run` is a new
- * launch, not another owner of the parent's editor tab. AGENTS_RUNTIME is set
- * by buildExecEnv, whereas an editor's initial launch sets AGENT_TERMINAL_ID
- * (and may already set AGENT_SESSION_ID) without that runtime marker.
- */
 export function launchIdentityEnv(env = process.env) {
     const result = {};
     const terminal = env.AGENT_TERMINAL_ID?.trim();
@@ -24,7 +17,6 @@ export function launchIdentityEnv(env = process.env) {
         result.AGENTS_PARENT_SESSION_ID = parentSession;
     return result;
 }
-/** Identity absent from a new launch must not leak back in from a tmux server. */
 export const LAUNCH_IDENTITY_KEYS = [
     'AGENT_TERMINAL_ID', 'AGENT_SESSION_ID', 'AGENTS_SESSION_ID', 'AGENTS_MAILBOX_DIR',
     'AGENT_LAUNCH_ID', 'AGENTS_PARENT_SESSION_ID', 'AGENTS_PARENT_LAUNCH_ID', 'AGENTS_ORIGIN_TERMINAL_ID',

package/dist/lib/linear-autoclose.d.ts

@@ -1,30 +1,5 @@
-/**
- * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
- *
- * The pure decision function `shouldCloseIssue` is the only logic here —
- * it is unit-tested and shared with the command routine's equivalent
- * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
- * routine YAML's `command:` shell script so the routine stays self-contained
- * and independent of the CLI build.
- *
- * @see cli/routines/linear-autoclose.yml
- */
-/**
- * Subset of `gh pr view --json state,mergedAt` output that drives the
- * close decision.  State is one of: OPEN | CLOSED | MERGED (gh GraphQL).
- */
 export interface PrInfo {
-    /** gh GraphQL PR state: 'OPEN' | 'CLOSED' | 'MERGED' */
     state: string;
-    /** ISO-8601 merge timestamp, or null when the PR was not merged. */
     mergedAt: string | null;
 }
-/**
- * Pure decision: returns true when the PR has been merged and its linked
- * Linear issue should therefore be closed.
- *
- * A PR is considered merged only when both conditions hold:
- *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
- *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
- */
 export declare function shouldCloseIssue(pr: PrInfo): boolean;

package/dist/lib/linear-autoclose.js

@@ -1,22 +1,3 @@
-/**
- * Linear auto-close: close Linear issues whose linked GitHub PRs have merged.
- *
- * The pure decision function `shouldCloseIssue` is the only logic here —
- * it is unit-tested and shared with the command routine's equivalent
- * shell check.  The rest (Linear GraphQL, gh invocations) lives in the
- * routine YAML's `command:` shell script so the routine stays self-contained
- * and independent of the CLI build.
- *
- * @see cli/routines/linear-autoclose.yml
- */
-/**
- * Pure decision: returns true when the PR has been merged and its linked
- * Linear issue should therefore be closed.
- *
- * A PR is considered merged only when both conditions hold:
- *   1. `state === 'MERGED'`  — gh marks CLOSED (rejected) separately from MERGED
- *   2. `mergedAt !== null`   — defensive guard; a merged PR always carries a timestamp
- */
 export function shouldCloseIssue(pr) {
     return pr.state === 'MERGED' && pr.mergedAt !== null;
 }

package/dist/lib/linear-cache.d.ts

@@ -1,71 +1,14 @@
-/**
- * Disk TTL cache for the Linear answers behind the `agents projects` card.
- *
- * Linear meters two budgets independently, and only one of them binds. Observed
- * on this account's response headers:
- *
- *   x-ratelimit-requests-limit:   2500      remaining: 2
- *   x-ratelimit-complexity-limit: 3000000   remaining: 2999987
- *
- * Requests are scarce; complexity is 99.999% untouched. So the thing to
- * optimize is the NUMBER of calls, not their cost — and the way to spend 2500
- * of them is an agent (or a watch loop) running `projects status` repeatedly.
- * A human typing it is not the exhauster.
- *
- * The CLI is a short-lived process, so an in-memory memo would only help within
- * one invocation, which is the case that never needed help. This caches to disk.
- *
- * **One file per key, written by atomic rename.** A single JSON document holding
- * every entry has to be read, modified, and written back, and that sequence is
- * not atomic across processes — measured on this machine, two concurrent writers
- * of 40 distinct keys each left **8 of 80** surviving. This box routinely runs a
- * dozen agent sessions, so that is the normal case, not a corner. Per-key files
- * remove the shared mutable document entirely: two processes caching different
- * projects never touch the same path, and two caching the SAME project race only
- * to write identical data. `writeFileSync` to a temp path followed by `rename`
- * makes each file appear whole or not at all, so a reader never sees a partial
- * write.
- *
- * The load-bearing behavior is what happens on FAILURE: a stale entry keeps
- * being served, marked stale, instead of the line vanishing. That rule is
- * borrowed from `mergeAuthHealthEntries` — one 8s timeout must not flip a
- * populated chip to empty — and it is the fix for the card silently losing its
- * Linear line mid-session when the request budget ran out.
- */
-/** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
 export declare const LINEAR_CACHE_TTL_MS: number;
-/**
- * Resolve the Linear API key from the `LINEAR_API_KEY` env var, falling back to
- * the macOS keychain generic-password `linear-api-key` (how the rest of the
- * stack stores it). Null if none is resolvable. The shared resolver for every
- * Linear-touching surface (project counts, session discovery).
- */
 export declare function resolveLinearApiKey(): string | null;
-/** What a lookup found, and how much to trust it. */
 interface CacheHit<T> {
     value: T;
-    /** Age in ms. Past the TTL the value is still returned, flagged stale. */
     ageMs: number;
     stale: boolean;
 }
-/** Look up a project's cached answer. Returns stale entries too — the caller decides. */
 export declare function readCached<T>(projectId: string, nowMs: number): CacheHit<T> | undefined;
-/** Store a freshly fetched answer. */
 export declare function writeCached<T>(projectId: string, value: T, nowMs: number): void;
-/** Drop one project's entry — used when `projects link` re-points a definition. */
 export declare function invalidateCached(projectId: string): void;
-/** True when a prior 429 said the budget is exhausted and has not yet reset. */
 export declare function isRateLimited(nowMs: number): boolean;
-/**
- * Read a 429's `x-ratelimit-requests-reset` header into an epoch-ms instant.
- * Linear sends epoch milliseconds; anything absent, non-numeric, or already in
- * the past is not usable and the caller backs off a TTL instead. Pure, so the
- * parsing is testable without a live 429.
- */
 export declare function parseRateLimitReset(header: string | null, nowMs: number): number | undefined;
-/**
- * Record a 429 so the next runs don't spend a request learning the same thing.
- * `resetAtMs` comes from {@link parseRateLimitReset}; without it, back off one TTL.
- */
 export declare function noteRateLimited(resetAtMs: number | undefined, nowMs: number): void;
 export {};

package/dist/lib/linear-cache.js

@@ -1,49 +1,8 @@
-/**
- * Disk TTL cache for the Linear answers behind the `agents projects` card.
- *
- * Linear meters two budgets independently, and only one of them binds. Observed
- * on this account's response headers:
- *
- *   x-ratelimit-requests-limit:   2500      remaining: 2
- *   x-ratelimit-complexity-limit: 3000000   remaining: 2999987
- *
- * Requests are scarce; complexity is 99.999% untouched. So the thing to
- * optimize is the NUMBER of calls, not their cost — and the way to spend 2500
- * of them is an agent (or a watch loop) running `projects status` repeatedly.
- * A human typing it is not the exhauster.
- *
- * The CLI is a short-lived process, so an in-memory memo would only help within
- * one invocation, which is the case that never needed help. This caches to disk.
- *
- * **One file per key, written by atomic rename.** A single JSON document holding
- * every entry has to be read, modified, and written back, and that sequence is
- * not atomic across processes — measured on this machine, two concurrent writers
- * of 40 distinct keys each left **8 of 80** surviving. This box routinely runs a
- * dozen agent sessions, so that is the normal case, not a corner. Per-key files
- * remove the shared mutable document entirely: two processes caching different
- * projects never touch the same path, and two caching the SAME project race only
- * to write identical data. `writeFileSync` to a temp path followed by `rename`
- * makes each file appear whole or not at all, so a reader never sees a partial
- * write.
- *
- * The load-bearing behavior is what happens on FAILURE: a stale entry keeps
- * being served, marked stale, instead of the line vanishing. That rule is
- * borrowed from `mergeAuthHealthEntries` — one 8s timeout must not flip a
- * populated chip to empty — and it is the fix for the card silently losing its
- * Linear line mid-session when the request budget ran out.
- */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
-/** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
 export const LINEAR_CACHE_TTL_MS = 10 * 60_000;
-/**
- * Resolve the Linear API key from the `LINEAR_API_KEY` env var, falling back to
- * the macOS keychain generic-password `linear-api-key` (how the rest of the
- * stack stores it). Null if none is resolvable. The shared resolver for every
- * Linear-touching surface (project counts, session discovery).
- */
 export function resolveLinearApiKey() {
     const fromEnv = process.env.LINEAR_API_KEY?.trim();
     if (fromEnv)
@@ -59,46 +18,27 @@ export function resolveLinearApiKey() {
                 return key;
         }
         catch {
-            // not in keychain — fall through
         }
     }
     return null;
 }
 const CACHE_SUBDIR = 'linear-projects';
-/** Sits beside the per-project files; its own file, so it cannot be clobbered by them. */
 const RATE_LIMIT_FILE = 'rate-limit.json';
-/**
- * Where the snapshot lives. `AGENTS_LINEAR_CACHE_PATH` overrides the directory.
- * `getCacheDir()` resolves `HOME` once at module load, so a test that swaps
- * `process.env.HOME` afterwards would otherwise read and WRITE the developer's
- * real cache.
- */
 function cacheDir() {
     return process.env.AGENTS_LINEAR_CACHE_PATH ?? path.join(getCacheDir(), CACHE_SUBDIR);
 }
-/**
- * One file per project id. Linear ids are UUIDs, but this is a filename built
- * from external input, so anything outside the safe set is encoded rather than
- * trusted — a `/` or `..` must never escape the cache directory.
- */
 function entryPath(projectId) {
     return path.join(cacheDir(), `${projectId.replace(/[^a-zA-Z0-9._-]/g, '_')}.json`);
 }
-/** Parse a cache file, treating absent/corrupt/wrong-shaped as simply absent. */
 function readJson(file, valid) {
     try {
         const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
         return valid(raw) ? raw : undefined;
     }
     catch {
-        return undefined; // absent or corrupt — an empty cache is always a valid answer
+        return undefined;
     }
 }
-/**
- * Write whole-or-not-at-all: a temp file in the same directory (so `rename`
- * stays on one filesystem and is therefore atomic) swapped into place. A reader
- * concurrent with this never observes a half-written document.
- */
 function writeJson(file, value) {
     try {
         fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -107,7 +47,6 @@ function writeJson(file, value) {
         fs.renameSync(tmp, file);
     }
     catch {
-        /* best-effort: an unwritable cache degrades to no cache, never to an error */
     }
 }
 function isEntry(raw) {
@@ -116,7 +55,6 @@ function isEntry(raw) {
         typeof raw.at === 'number' &&
         'value' in raw);
 }
-/** Look up a project's cached answer. Returns stale entries too — the caller decides. */
 export function readCached(projectId, nowMs) {
     const entry = readJson(entryPath(projectId), isEntry);
     if (!entry)
@@ -124,33 +62,23 @@ export function readCached(projectId, nowMs) {
     const ageMs = nowMs - entry.at;
     return { value: entry.value, ageMs, stale: ageMs > LINEAR_CACHE_TTL_MS };
 }
-/** Store a freshly fetched answer. */
 export function writeCached(projectId, value, nowMs) {
     writeJson(entryPath(projectId), { at: nowMs, value });
 }
-/** Drop one project's entry — used when `projects link` re-points a definition. */
 export function invalidateCached(projectId) {
     try {
         fs.rmSync(entryPath(projectId), { force: true });
     }
     catch {
-        /* already gone is the desired state */
     }
 }
 function isRateLimitFile(raw) {
     return !!raw && typeof raw === 'object' && typeof raw.until === 'number';
 }
-/** True when a prior 429 said the budget is exhausted and has not yet reset. */
 export function isRateLimited(nowMs) {
     const f = readJson(path.join(cacheDir(), RATE_LIMIT_FILE), isRateLimitFile);
     return !!f && f.until > nowMs;
 }
-/**
- * Read a 429's `x-ratelimit-requests-reset` header into an epoch-ms instant.
- * Linear sends epoch milliseconds; anything absent, non-numeric, or already in
- * the past is not usable and the caller backs off a TTL instead. Pure, so the
- * parsing is testable without a live 429.
- */
 export function parseRateLimitReset(header, nowMs) {
     if (!header)
         return undefined;
@@ -159,15 +87,7 @@ export function parseRateLimitReset(header, nowMs) {
         return undefined;
     return n;
 }
-/**
- * Record a 429 so the next runs don't spend a request learning the same thing.
- * `resetAtMs` comes from {@link parseRateLimitReset}; without it, back off one TTL.
- */
 export function noteRateLimited(resetAtMs, nowMs) {
-    // The invariant this owns: `until` is always in the future. A reset already
-    // elapsed would record a window that is over before it is written, which
-    // reads as "not rate limited" and sends the next run straight back into the
-    // 429 it just took.
     const until = resetAtMs && resetAtMs > nowMs ? resetAtMs : nowMs + LINEAR_CACHE_TTL_MS;
     writeJson(path.join(cacheDir(), RATE_LIMIT_FILE), { until });
 }

package/dist/lib/linear-project-counts.d.ts

@@ -24,75 +24,28 @@
  * budget; a capped fetch reports `truncated: true` and the card renders the
  * total as a lower bound (`2500+ done`), never as the complete count.
  */
-/**
- * The next checkpoint the project is working toward: the earliest-dated
- * milestone that still has unfinished issues. A percentage says how far along
- * the project is; this says what it is due to hit next.
- */
 export interface LinearMilestone {
     name: string;
-    /** `YYYY-MM-DD` as Linear stores it. Absent when the milestone has no date. */
     targetDate?: string;
-    /** Issues in this milestone in a `completed`-type state. */
     done: number;
-    /**
-     * Issues assigned to this milestone. Legitimately `0` — a milestone can be
-     * declared with a date long before any issue is filed under it (that is the
-     * state of every milestone in this repo's own Linear project), and such a
-     * milestone is still the next checkpoint. The card omits the fraction rather
-     * than printing a meaningless `0/0`.
-     */
     total: number;
-    /** True when Linear itself flags this as the project's next milestone. */
     isNext?: boolean;
 }
-/** A milestone as the project declares it, independent of any issue. */
 export interface LinearMilestoneNode {
     id?: string;
     name?: string;
     targetDate?: string | null;
-    /**
-     * Linear's own marker. Observed values: `"next"` (it flags exactly one) and
-     * `"unstarted"`. Treated as an opaque string and only compared to `"next"` —
-     * the enum is not documented as closed, so switching exhaustively on it would
-     * break the day Linear adds a value.
-     */
     status?: string | null;
 }
-/** The counts the card renders. `total` counts every issue in the project. */
 export interface LinearProjectCounts {
-    /** Issues in a `completed`-type state. */
     done: number;
-    /** All issues in the project (any state type, including canceled). */
     total: number;
-    /** Issues in a `started`-type state. */
     inProgress: number;
-    /**
-     * True when the page cap cut the fetch short — `total` is then a LOWER
-     * bound (rendered `2500+`), never presented as the complete count.
-     */
     truncated?: boolean;
-    /**
-     * True when this answer came from the cache after a failed or skipped fetch.
-     * The card labels it rather than dropping the line — a populated Linear row
-     * that silently vanishes on one timeout is the defect this replaces.
-     */
     stale?: boolean;
-    /**
-     * Every milestone the project declares, in the order the card shows them:
-     * unfinished first by target date, then the finished ones. A project with
-     * three checkpoints has three; showing only the next one hides the shape of
-     * the plan, which is what `projects view` exists to show.
-     */
     milestones?: LinearMilestone[];
-    /**
-     * The one the project is working toward — `milestones[0]` when there is an
-     * unfinished one. Kept as its own field because the compact card shows only
-     * this, while `view` shows the whole list.
-     */
     nextMilestone?: LinearMilestone;
 }
-/** One issue node as the query selects it. */
 export interface LinearIssueNode {
     state?: {
         type?: string;
@@ -103,7 +56,6 @@ export interface LinearIssueNode {
         targetDate?: string | null;
     } | null;
 }
-/** The GraphQL response shape this module consumes (recorded for the tests). */
 export interface LinearIssuesResponse {
     issues?: {
         nodes?: LinearIssueNode[];
@@ -112,48 +64,13 @@ export interface LinearIssuesResponse {
             endCursor?: string | null;
         };
     };
-    /** Only the FIRST page asks for this — the milestone list does not paginate. */
     project?: {
         projectMilestones?: {
             nodes?: LinearMilestoneNode[];
         };
     } | null;
 }
-/**
- * Pure mapping: a Linear issues response → card counts, grouping by state
- * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
- * an issue with no state still counts toward `total`.
- */
 export declare function countsFromIssuesResponse(data: LinearIssuesResponse): LinearProjectCounts;
-/**
- * Pick the milestone the project is working toward next.
- *
- * The **declared** list is authoritative for which milestones exist, their
- * names, and their dates; issues only supply progress. Deriving the list from
- * issues instead looks tempting (it costs no extra request) and is wrong: a
- * milestone with nothing filed under it yet would be invisible, and that is the
- * common case — every milestone in this repo's own Linear project has zero
- * issues assigned, so an issue-derived list showed nothing at all.
- *
- * Next = the earliest-dated milestone that is not finished. A milestone with no
- * issues counts as unfinished (it is upcoming work, not completed work). Undated
- * milestones sort last, ties break by declaration order, so the answer is stable.
- */
 export declare function orderedMilestones(declared: LinearMilestoneNode[], nodes: LinearIssueNode[]): LinearMilestone[];
-/**
- * The milestone the project is working toward next.
- *
- * Linear flags one itself (`status: "next"`), and that is the answer the user
- * sees in Linear's own UI, so it wins when present. Only when nothing is
- * flagged does this fall back to "earliest-dated unfinished", which is a
- * reasonable guess but still a guess.
- */
 export declare function nextMilestone(declared: LinearMilestoneNode[], nodes: LinearIssueNode[]): LinearMilestone | undefined;
-/**
- * Fetch issue counts for one Linear project, paging `issues` filtered by
- * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
- * any failure (no key, network, API error, abort) returns undefined so the
- * card just omits the line. `fetchPage` is injectable for tests — the
- * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
- */
 export declare function fetchLinearProjectCounts(projectId: string, fetchPage?: (projectId: string, after: string | undefined, signal: AbortSignal) => Promise<LinearIssuesResponse | undefined>, nowMs?: number): Promise<LinearProjectCounts | undefined>;

package/dist/lib/linear-project-counts.js

@@ -30,16 +30,9 @@ import * as path from 'path';
 import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached, resolveLinearApiKey } from './linear-cache.js';
 import { reserveLinearRequest } from './linear-rate-limit.js';
 const LINEAR_API = 'https://api.linear.app/graphql';
-/** Overall budget across all pages — the card must never hang on Linear. */
 const TIMEOUT_MS = 8_000;
 const PAGE_SIZE = 250;
-/** Hard page cap so a pathological project can't page forever within the budget. */
 const MAX_PAGES = 10;
-/**
- * Pure mapping: a Linear issues response → card counts, grouping by state
- * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
- * an issue with no state still counts toward `total`.
- */
 export function countsFromIssuesResponse(data) {
     const nodes = data.issues?.nodes ?? [];
     let done = 0;
@@ -61,22 +54,7 @@ export function countsFromIssuesResponse(data) {
         counts.nextMilestone = next;
     return counts;
 }
-/**
- * Pick the milestone the project is working toward next.
- *
- * The **declared** list is authoritative for which milestones exist, their
- * names, and their dates; issues only supply progress. Deriving the list from
- * issues instead looks tempting (it costs no extra request) and is wrong: a
- * milestone with nothing filed under it yet would be invisible, and that is the
- * common case — every milestone in this repo's own Linear project has zero
- * issues assigned, so an issue-derived list showed nothing at all.
- *
- * Next = the earliest-dated milestone that is not finished. A milestone with no
- * issues counts as unfinished (it is upcoming work, not completed work). Undated
- * milestones sort last, ties break by declaration order, so the answer is stable.
- */
 export function orderedMilestones(declared, nodes) {
-    // Progress per milestone id, from whatever issues do carry one.
     const progress = new Map();
     for (const n of nodes) {
         const id = n?.projectMilestone?.id;
@@ -101,11 +79,8 @@ export function orderedMilestones(declared, nodes) {
         return m;
     })
         .filter((m) => m !== undefined);
-    // total 0 means "declared, nothing filed yet" — unfinished, not done.
     const open = (m) => m.total === 0 || m.done < m.total;
     all.sort((a, b) => {
-        // Unfinished before finished: what is still ahead is what a reader is
-        // scanning for.
         if (open(a) !== open(b))
             return open(a) ? -1 : 1;
         if (a.targetDate && b.targetDate)
@@ -118,20 +93,12 @@ export function orderedMilestones(declared, nodes) {
     });
     return all.map(({ order: _order, ...m }) => m);
 }
-/**
- * The milestone the project is working toward next.
- *
- * Linear flags one itself (`status: "next"`), and that is the answer the user
- * sees in Linear's own UI, so it wins when present. Only when nothing is
- * flagged does this fall back to "earliest-dated unfinished", which is a
- * reasonable guess but still a guess.
- */
 export function nextMilestone(declared, nodes) {
     const ordered = orderedMilestones(declared, nodes);
     const open = ordered.filter((m) => m.total === 0 || m.done < m.total);
+    // Linear's explicit next wins; otherwise choose the earliest unfinished milestone.
     return open.find((m) => m.isNext) ?? open[0];
 }
-/** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
 function resolveApiKey() {
     const fromChain = resolveLinearApiKey();
     if (fromChain)
@@ -144,38 +111,22 @@ function resolveApiKey() {
         return null;
     }
 }
-/**
- * Fetch issue counts for one Linear project, paging `issues` filtered by
- * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
- * any failure (no key, network, API error, abort) returns undefined so the
- * card just omits the line. `fetchPage` is injectable for tests — the
- * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
- */
 export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinearIssuesPage, nowMs = Date.now()) {
-    // Requests are the scarce budget (2500/hr; complexity is untouched), and this
-    // pages up to 10 of them per project per call. Serve a fresh snapshot without
-    // spending any.
     const cached = readCached(projectId, nowMs);
     if (cached && !cached.stale)
         return cached.value;
-    // A prior 429 said there is nothing left to spend — don't spend one finding
-    // that out again. Fall through to the stale snapshot rather than no line.
     if (isRateLimited(nowMs))
         return cached ? { ...cached.value, stale: true } : undefined;
+    // One abort budget covers all pages; milestones are fetched only on page zero.
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
     try {
         const all = [];
-        // Declared on the project, not on its issues — only page 0 asks for it.
         let declared = [];
         let after;
         let truncated = false;
         for (let page = 0;; page++) {
             const data = await fetchPage(projectId, after, ctrl.signal);
-            // A failed fetch keeps the last good answer on screen, marked stale,
-            // instead of the line vanishing. One 8s timeout must not blank a chip
-            // that was populated a minute ago — the rule `mergeAuthHealthEntries`
-            // already encodes for account health.
             if (!data)
                 return cached ? { ...cached.value, stale: true } : undefined;
             if (page === 0)
@@ -185,7 +136,6 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
             if (!pi?.hasNextPage || !pi.endCursor)
                 break;
             if (page + 1 >= MAX_PAGES) {
-                // The cap cut the fetch short — total is a lower bound, say so.
                 truncated = true;
                 break;
             }
@@ -208,21 +158,12 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
         clearTimeout(timer);
     }
 }
-/** One real GraphQL page; undefined on any HTTP/API-level failure. */
 async function fetchLinearIssuesPage(projectId, after, signal) {
     const apiKey = resolveApiKey();
     if (!apiKey)
         return undefined;
-    // Proactive shared budget (PHNX-2310): every agent on this key spends from one
-    // hourly pool, so N concurrent drains can't collectively blow Linear's 2500/hr
-    // limit. When the pool is spent, skip the request — the accumulator serves the
-    // last good (stale) snapshot instead, exactly as it does on any other failure.
-    // This is the proactive complement to the reactive 429 backoff below.
     if (!reserveLinearRequest(apiKey))
         return undefined;
-    // The declared-milestone list rides along on the FIRST page only — it does
-    // not paginate, and re-requesting it per page would spend up to MAX_PAGES
-    // copies of the same answer.
     const issuesSelection = 'issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
         PAGE_SIZE +
         ', after:$after){ nodes{ state{ type } projectMilestone{ id } } pageInfo{ hasNextPage endCursor } }';
@@ -242,9 +183,6 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
         signal,
     });
     if (res.status === 429) {
-        // Record when the budget refills so later runs skip the call entirely
-        // rather than spending one of the zero remaining requests to be told so.
-        // The header is epoch milliseconds; absent or unparseable, back off a TTL.
         const now = Date.now();
         noteRateLimited(parseRateLimitReset(res.headers.get('x-ratelimit-requests-reset'), now), now);
         return undefined;