@phnx-labs/agents-cli 1.21.1 → 1.21.2

package/dist/lib/hooks.js

@@ -15,7 +15,7 @@ import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPerfDir } from './state.js';
 import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
@@ -256,12 +256,20 @@ export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
 /**
  * Resolve the command path to register for a hook.
  *
- * Returns either the raw script path (neither `cache:` nor `matches:` set,
- * legacy behavior) or the path to a generated wrapper shim. The shim is written
- * as a side effect when `cache:` and/or `matches:` is configured — it enforces
- * the `matches:` gate at fire time and layers the caching/timing machinery when
- * `cache:` is set. The agent-native settings file gets the same shape either
- * way — just a different command path.
+ * Returns either the raw script path (no `cache:`, `matches:`, or `matcher:`
+ * set — a bare lifecycle hook with nothing to gate or time) or the path to a
+ * generated wrapper shim. The shim is written as a side effect when `cache:`
+ * and/or `matches:` is configured — it enforces the `matches:` gate at fire
+ * time and layers the caching/timing machinery when `cache:` is set.
+ *
+ * A hook that declares only `matcher:` (e.g. git-guard/rm-guard scoped to the
+ * `Bash` tool, no `cache:`/`matches:`) also gets a shim now — a pass-through
+ * one with no gate and no cache, whose only job is the trailing timing sample
+ * (see PASSTHROUGH_TAIL in hooks/cache.ts). Before this, a matcher-only hook
+ * took the raw-path branch and fired completely uninstrumented: `agents perf
+ * hooks` showed zero samples for it no matter how often it ran. The agent-
+ * native settings file gets the same shape either way — just a different
+ * command path.
  */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
@@ -272,17 +280,20 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     const cache = parseCacheConfig(hookDef.cache);
     const matches = hookDef.matches;
     const hasMatches = matches != null && Object.keys(matches).length > 0;
-    if (!cache && !hasMatches) {
-        // No caching and no matches: gate opted in — make sure a previously
-        // generated shim from an earlier `cache:`/`matches:` config is gone so the
-        // JSONL doesn't keep claiming hits.
+    const hasMatcher = !!hookDef.matcher;
+    if (!cache && !hasMatches && !hasMatcher) {
+        // Nothing to gate, cache, or time: make sure a previously generated shim
+        // from an earlier cache:/matches:/matcher config is gone so the JSONL
+        // doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    // A shim is generated when the hook opts into caching and/or declares
-    // `matches:` predicates. The shim enforces the `matches:` gate at fire time
-    // (skipping the script when predicates don't hold) and, when `cache:` is set,
-    // layers the cache/timing machinery on top.
+    // A shim is generated when the hook opts into caching, declares `matches:`
+    // predicates, or declares a `matcher:` (even alone — see the doc comment
+    // above). The shim enforces the `matches:` gate at fire time (skipping the
+    // script when predicates don't hold) and, when `cache:` is set, layers the
+    // cache/timing machinery on top; with neither, it is a pure pass-through
+    // timing wrapper.
     return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
 }
 /**
@@ -645,7 +656,7 @@ export function checkVersionHookWiring(agent, version) {
             return null;
         const cache = parseCacheConfig(hookDef.cache);
         const hasMatches = hookDef.matches != null && Object.keys(hookDef.matches).length > 0;
-        if (!cache && !hasMatches)
+        if (!cache && !hasMatches && !hookDef.matcher)
             return toPortableCommand(scriptPath);
         return toPortableCommand(getHookShimPath(name));
     };
@@ -1264,7 +1275,17 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         return resolveHookScriptPath(script);
     };
     const managedPrefixes = overrideRoots
-        ? [path.join(overrideRoots[0], 'hooks') + path.sep]
+        ? [
+            path.join(overrideRoots[0], 'hooks') + path.sep,
+            // The shim dir is one global location regardless of which hooks
+            // source (agentsDirOverride vs the normal user/system dirs) resolved
+            // the underlying script, so it belongs in every managedPrefixes
+            // shape — omitting it here left a shim path unrecognized as managed
+            // under the override branch, so a hook's matcher/event change never
+            // GC'd its stale shim-path entry (only reachable via a caller that
+            // passes agentsDirOverride; no production call site does today).
+            getHookShimsDir() + path.sep,
+        ]
         : [
             ...getManagedHookPrefixes(),
             ...(localHooksDir ? [localHooksDir + path.sep] : []),
@@ -1373,9 +1394,42 @@ function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
     }
     const serializedDirect = JSON.stringify(Object.fromEntries(direct), null, 2);
     const serializedLifecycle = JSON.stringify(Object.fromEntries(lifecycle), null, 2);
+    // Same disposable perf spool the bash shims (hooks/cache.ts) append to — see
+    // the timedOut branch below for why OpenCode needs its own writer.
+    const perfSpoolPath = path.join(getPerfDir(), 'spool.jsonl');
     const pluginSource = `// Generated by agents-cli. Re-run agents sync to update.
+import fs from "node:fs"
+import os from "node:os"
+
 const directHooks = ${serializedDirect}
 const lifecycleHooks = ${serializedLifecycle}
+const PERF_SPOOL = ${JSON.stringify(perfSpoolPath)}
+
+function recordTimeoutSample(hook, payload) {
+  // hook.command already ran through a generated shim (hooks/cache.ts) that
+  // writes its own hook.fire sample on exit — but Bun.spawn's child.kill()
+  // below (SIGTERM) tears the shim down before it reaches that trailing
+  // printf, so a timed-out fire would otherwise leave ZERO trace in the
+  // warehouse. Write the sample ourselves from the side that knows it timed out.
+  try {
+    fs.mkdirSync(PERF_SPOOL.slice(0, PERF_SPOOL.lastIndexOf("/")), { recursive: true })
+    const line = JSON.stringify({
+      ts_ms: Date.now(),
+      kind: "hook.fire",
+      label: hook.name,
+      duration_ms: hook.timeout * 1000,
+      cache: "none",
+      exit_code: null,
+      status: "timeout",
+      cwd: payload && typeof payload.cwd === "string" ? payload.cwd : undefined,
+      session_id: payload && typeof payload.session_id === "string" ? payload.session_id : undefined,
+      hostname: (() => { try { return os.hostname() } catch { return "unknown" } })(),
+    }) + "\\n"
+    fs.appendFileSync(PERF_SPOOL, line)
+  } catch {
+    // best effort — never let sample recording break the timeout error path
+  }
+}
 
 function matches(hook, tool) {
   if (!hook.matcher) return true
@@ -1415,6 +1469,7 @@ async function runHooks(hooks, payload, $, matchTool = false) {
       const exitCode = await child.exited.finally(() => clearTimeout(timer))
       const stderr = await new Response(child.stderr).text()
       if (timedOut) {
+        recordTimeoutSample(hook, payload)
         throw new Error(\`\${hook.name} timed out after \${hook.timeout} seconds\`)
       }
       if (exitCode !== 0) {

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

@@ -0,0 +1,63 @@
+/**
+ * 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;
+/** What a lookup found, and how much to trust it. */
+export 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;

package/dist/lib/linear-cache.js

@@ -0,0 +1,146 @@
+/**
+ * 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 * 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;
+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,
+ * mirroring `AGENTS_FACTORY_PROJECTS_PATH` (`auto-dispatch.ts`) — `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
+    }
+}
+/**
+ * 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 });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(value), 'utf8');
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* best-effort: an unwritable cache degrades to no cache, never to an error */
+    }
+}
+function isEntry(raw) {
+    return (!!raw &&
+        typeof raw === 'object' &&
+        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)
+        return undefined;
+    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;
+    const n = Number(header);
+    if (!Number.isFinite(n) || n <= 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

@@ -43,12 +43,21 @@ export interface LinearMilestone {
      * 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 {
@@ -64,10 +73,22 @@ export interface LinearProjectCounts {
      */
     truncated?: boolean;
     /**
-     * The next unfinished milestone, when the project has one. Derived from the
-     * SAME paged issue fetch as the counts — a milestone is only ever a grouping
-     * of these issues, so asking Linear again would spend a second round trip to
-     * learn what the first already said.
+     * 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;
 }
@@ -118,6 +139,15 @@ export declare function countsFromIssuesResponse(data: LinearIssuesResponse): Li
  * 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
@@ -126,4 +156,4 @@ export declare function nextMilestone(declared: LinearMilestoneNode[], nodes: Li
  * 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>): Promise<LinearProjectCounts | undefined>;
+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

@@ -28,6 +28,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { resolveLinearApiKey } from './auto-dispatch-linear.js';
+import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached } from './linear-cache.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;
@@ -51,7 +52,11 @@ export function countsFromIssuesResponse(data) {
             inProgress++;
     }
     const counts = { done, total: nodes.length, inProgress };
-    const next = nextMilestone(data.project?.projectMilestones?.nodes ?? [], nodes);
+    const declared = data.project?.projectMilestones?.nodes ?? [];
+    const ordered = orderedMilestones(declared, nodes);
+    if (ordered.length)
+        counts.milestones = ordered;
+    const next = nextMilestone(declared, nodes);
     if (next)
         counts.nextMilestone = next;
     return counts;
@@ -70,7 +75,7 @@ export function countsFromIssuesResponse(data) {
  * 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 nextMilestone(declared, nodes) {
+export function orderedMilestones(declared, nodes) {
     // Progress per milestone id, from whatever issues do carry one.
     const progress = new Map();
     for (const n of nodes) {
@@ -83,7 +88,7 @@ export function nextMilestone(declared, nodes) {
             p.done++;
         progress.set(id, p);
     }
-    const candidates = declared
+    const all = declared
         .map((d, order) => {
         if (!d?.id || typeof d.name !== 'string' || !d.name)
             return undefined;
@@ -91,14 +96,18 @@ export function nextMilestone(declared, nodes) {
         const m = { name: d.name, done: p.done, total: p.total, order };
         if (d.targetDate)
             m.targetDate = d.targetDate;
+        if (d.status === 'next')
+            m.isNext = true;
         return m;
     })
-        .filter((m) => m !== undefined)
-        // total 0 means "declared, nothing filed yet" — unfinished, not done.
-        .filter((m) => m.total === 0 || m.done < m.total);
-    if (candidates.length === 0)
-        return undefined;
-    candidates.sort((a, b) => {
+        .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)
             return a.targetDate < b.targetDate ? -1 : a.targetDate > b.targetDate ? 1 : a.order - b.order;
         if (a.targetDate)
@@ -107,8 +116,20 @@ export function nextMilestone(declared, nodes) {
             return 1;
         return a.order - b.order;
     });
-    const { order: _order, ...m } = candidates[0];
-    return m;
+    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);
+    return open.find((m) => m.isNext) ?? open[0];
 }
 /** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
 function resolveApiKey() {
@@ -130,7 +151,17 @@ function resolveApiKey() {
  * 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) {
+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;
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
     try {
@@ -141,8 +172,12 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
         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 undefined;
+                return cached ? { ...cached.value, stale: true } : undefined;
             if (page === 0)
                 declared = data.project?.projectMilestones?.nodes ?? [];
             all.push(...(data.issues?.nodes ?? []));
@@ -156,16 +191,18 @@ export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinea
             }
             after = pi.endCursor;
         }
-        return {
+        const counts = {
             ...countsFromIssuesResponse({
                 issues: { nodes: all },
                 project: { projectMilestones: { nodes: declared } },
             }),
             ...(truncated ? { truncated } : {}),
         };
+        writeCached(projectId, counts, nowMs);
+        return counts;
     }
     catch {
-        return undefined;
+        return cached ? { ...cached.value, stale: true } : undefined;
     }
     finally {
         clearTimeout(timer);
@@ -182,7 +219,7 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
     const issuesSelection = 'issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
         PAGE_SIZE +
         ', after:$after){ nodes{ state{ type } projectMilestone{ id } } pageInfo{ hasNextPage endCursor } }';
-    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate } } }';
+    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate status } } }';
     const first = after === undefined;
     const res = await fetch(LINEAR_API, {
         method: 'POST',
@@ -197,6 +234,14 @@ 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;
+    }
     if (!res.ok)
         return undefined;
     const json = (await res.json());

package/dist/lib/menubar/MenubarHelper.app/Contents/Info.plist

@@ -7,7 +7,9 @@
     <key>CFBundleIdentifier</key>
     <string>com.phnx-labs.agents-menubar</string>
     <key>CFBundleName</key>
-    <string>Agents Menu Bar</string>
+    <string>AGI Menu</string>
+    <key>CFBundleDisplayName</key>
+    <string>AGI Menu</string>
     <key>CFBundleIconFile</key>
     <string>AppIcon</string>
     <key>CFBundlePackageType</key>

package/dist/lib/menubar/install-menubar.d.ts

@@ -40,10 +40,17 @@ export declare function codesignVerifies(appPath: string): boolean;
  * bootstrap a helper macOS would reject.
  */
 export declare function gatekeeperAssesses(appPath: string): boolean;
+/** True when the bundle carries a Developer ID TeamIdentifier (not ad-hoc). */
+export declare function hasDeveloperIdSignature(appPath: string): boolean;
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
  * with this install (e.g. Linux package, or a build without the helper).
+ *
+ * Also heals an older install that was ad-hoc re-signed over a Developer ID
+ * source: that unstable identity made Accessibility re-prompt on every upgrade.
+ * When the shipped source is Developer ID and the installed copy is only
+ * ad-hoc, replace it — even without forceReinstall.
  */
 export declare function ensureMenubarAppInstalled(opts?: {
     forceReinstall?: boolean;