@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/events.js

@@ -16,11 +16,9 @@ import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { gzipSync, gunzipSync } from 'node:zlib';
-import { parseSshConnection } from './session/provenance.js';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { getUserAgentsDir } from './state.js';
-import { resolveActor } from './actor.js';
-import { machineId } from './machine-id.js';
+import { stampProvenance, resetEventProvenanceForTest } from './event-provenance.js';
 /** Lazy perf warehouse write — avoids a hard cycle at module load. */
 function recordPerfTiming(payload) {
     try {
@@ -72,9 +70,50 @@ function isDisabled() {
 const DIR_MODE = 0o700;
 /** File permissions (owner read/write only). */
 const FILE_MODE = 0o600;
+/**
+ * Every {@link EventType}, as a runtime-checkable table.
+ *
+ * Typed `Record<EventType, true>` on purpose: the object literal is
+ * exhaustiveness-checked at COMPILE time, so adding a member to the union
+ * without adding it here fails `tsc`. That is what keeps the runtime validator
+ * (`isEventType`, used by `agents events emit` to reject an unknown kind from an
+ * out-of-process producer) from silently drifting behind the union.
+ */
+const EVENT_TYPE_TABLE = {
+    'agent.run.start': true, 'agent.run.end': true, 'agent.spawn.start': true, 'agent.spawn.end': true,
+    'version.install': true, 'version.switch': true, 'version.remove': true,
+    'skill.install': true, 'skill.remove': true,
+    'browser.launch': true, 'browser.close': true, 'browser.navigate': true, 'browser.screenshot': true,
+    'secrets.get': true, 'secrets.unlocked': true, 'secrets.create': true, 'secrets.import': true, 'secrets.export': true, 'secrets.view': true, 'secrets.set': true, 'secrets.delete': true, 'secrets.rename': true,
+    'cloud.dispatch': true, 'cloud.complete': true, 'cloud.cancel': true, 'cloud.message': true,
+    'teams.create': true, 'teams.add': true, 'teams.start': true, 'teams.complete': true, 'teams.disband': true,
+    'hook.fire': true, 'hook.complete': true, 'hook.error': true,
+    'mcp.add': true, 'mcp.remove': true, 'mcp.register': true,
+    'resource.sync': true,
+    'rotation.resolved': true,
+    'command.start': true, 'command.end': true,
+    'perf.timing': true,
+    'session.start': true, 'session.end': true,
+    'webhook.received': true, 'webhook.authorized': true, 'webhook.rejected': true, 'webhook.matched': true,
+    'webhook.fired': true, 'webhook.handler.start': true, 'webhook.handler.end': true,
+    'plan.created': true, 'pr.opened': true, 'pr.merged': true, 'worktree.created': true,
+    'worktree.removed': true, 'commit.created': true, 'pushed': true, 'subagent.spawned': true,
+    'artifact.created': true, 'task.completed': true, 'checklist.created': true, 'status.posted': true,
+    'file.edited': true,
+    'factory.command': true, 'factory.action': true, 'factory.uri': true, 'factory.launch': true,
+    'friction': true, 'error': true, 'warn': true, 'info': true, 'debug': true,
+};
+/** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
+export const EVENT_TYPES = Object.keys(EVENT_TYPE_TABLE);
+const EVENT_TYPE_SET = new Set(EVENT_TYPES);
+/** Runtime guard for an event kind arriving from outside this process. */
+export function isEventType(value) {
+    return EVENT_TYPE_SET.has(value);
+}
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
-    'secrets.get', 'secrets.unlocked', 'secrets.set', 'secrets.delete', 'secrets.rename',
+    'secrets.get', 'secrets.unlocked', 'secrets.create', 'secrets.import', 'secrets.export', 'secrets.view',
+    'secrets.set', 'secrets.delete', 'secrets.rename',
     'teams.create', 'teams.add', 'teams.start', 'teams.complete', 'teams.disband',
     'cloud.dispatch', 'cloud.complete', 'cloud.cancel', 'cloud.message',
     'version.install', 'version.switch', 'version.remove',
@@ -82,6 +121,11 @@ const AUDIT_EVENTS = new Set([
     'mcp.add', 'mcp.remove', 'mcp.register',
     'rotation.resolved',
     'session.start', 'session.end',
+    // An external process reaching into the user's editor (the CLI's
+    // vscodium-agent backend driving `/spawn` / `/inject` / `/focus`) is a
+    // "who reached in from outside" fact, which is what the audit lane answers.
+    // The other factory.* kinds are ordinary info — a palette press is not audit.
+    'factory.uri',
 ]);
 export function levelFor(event) {
     if (event === 'warn')
@@ -283,59 +327,21 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
     }
     return { kind: stdoutIsTTY ? 'terminal' : 'script' };
 }
-/**
- * Who is running this process and from where. Derived once per process from the
- * OS user and $SSH_CONNECTION (via the same parser the sessions layer uses), then
- * cached — provenance can't change mid-process, so every emit() pays for it once.
- */
-let _origin;
-function auditOrigin() {
-    if (_origin)
-        return _origin;
-    let osUser = 'unknown';
-    try {
-        osUser = os.userInfo().username;
-    }
-    catch {
-        // Container/edge cases where the uid has no passwd entry.
-    }
-    const ssh = process.env.SSH_CONNECTION ? parseSshConnection(process.env.SSH_CONNECTION) : undefined;
-    const actor = resolveActor();
-    _origin = {
-        osUser,
-        transport: ssh ? 'ssh' : 'local',
-        ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
-        actor: actor.id,
-        kind: actor.kind,
-    };
-    return _origin;
-}
-/** This machine's normalized device id, resolved once — it can't change mid-process. */
-let _machineId;
-function cachedMachineId() {
-    return (_machineId ??= machineId());
-}
-function resolveProvenance(env = process.env) {
-    const p = {};
-    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
-    if (sessionId)
-        p.sessionId = sessionId;
-    if (env.AGENTS_AGENT_NAME)
-        p.agent = env.AGENTS_AGENT_NAME;
-    if (env.AGENT_LAUNCH_ID)
-        p.launchId = env.AGENT_LAUNCH_ID;
-    if (env.AGENTS_PARENT_SESSION_ID)
-        p.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
-    return p;
-}
+// ─── Audit attribution ────────────────────────────────────────────────────────
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
  *
  * @param event - The event type
  * @param payload - Event-specific data (agent, version, cwd, etc.)
+ * @param overrides - Envelope fields the CALLER owns rather than the writer.
+ *   Only `ts` today: a batched out-of-process producer (`agents events emit`)
+ *   records when each event HAPPENED, but flushes them together later, so
+ *   stamping write-time would collapse a whole batch onto the flush instant and
+ *   corrupt every `--since` boundary. `ts` stays in RESERVED_META_KEYS so a
+ *   *payload* still cannot inject it — this explicit channel is the only way in.
  */
-export function emit(event, payload = {}) {
+export function emit(event, payload = {}, overrides = {}) {
     if (isDisabled())
         return;
     try {
@@ -344,13 +350,12 @@ export function emit(event, payload = {}) {
         const safePayload = sanitizePayload(payload);
         const record = {
             // Provenance floor first: env-sourced defaults an explicit payload overrides.
-            ...resolveProvenance(),
+            ...stampProvenance(),
             ...safePayload,
-            ts: new Date().toISOString(),
+            ts: overrides.ts ?? new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
             hostname: os.hostname(),
-            machineId: cachedMachineId(),
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
@@ -359,7 +364,6 @@ export function emit(event, payload = {}) {
             level: levelFor(event),
             caller: caller.kind,
             ...(caller.session ? { session: caller.session } : {}),
-            ...auditOrigin(),
         };
         const line = JSON.stringify(record) + '\n';
         const logPath = eventsPath();
@@ -867,8 +871,7 @@ export function getLogsPath() {
 }
 export function _resetForTest(overrideEventsPath) {
     _eventsPath = overrideEventsPath;
-    _origin = undefined;
-    _machineId = undefined;
+    resetEventProvenanceForTest();
     _chmoddedPath = undefined;
     lastRotationCheck = 0;
 }

package/dist/lib/feed.d.ts

@@ -12,7 +12,7 @@ export interface MessageReceipt {
     /** The message id this receipt describes. */
     msgId: string;
     /** Delivery lifecycle state. */
-    status: 'queued' | 'consumed' | 'continued';
+    status: 'queued' | 'consumed' | 'continued' | 'dropped' | 'expired';
     /** ISO-8601 timestamp of the state transition. */
     at: string;
     /** Optional sender label for the message. */

package/dist/lib/feed.js

@@ -153,6 +153,8 @@ const RECEIPT_STATUS_RANK = {
     queued: 0,
     consumed: 1,
     continued: 2,
+    dropped: 3,
+    expired: 3,
 };
 /**
  * Record a delivery-receipt transition for a message tied to a block.

package/dist/lib/git.d.ts

@@ -41,8 +41,12 @@ export declare function assertValidBranchName(branch: string): void;
  *
  * Prefer this over `git.push(remote, branch)` whenever the branch comes from
  * repo state rather than a hard-coded literal.
+ *
+ * Pass `targetBranch` to push the local `branch` to a differently-named remote
+ * branch (`git push origin <branch>:<targetBranch>`) — used when publishing the
+ * working tree to a branch other than the checked-out one.
  */
-export declare function pushOrigin(git: SimpleGit, branch: string): Promise<void>;
+export declare function pushOrigin(git: SimpleGit, branch: string, targetBranch?: string): Promise<void>;
 /** Parsed representation of a git source string (GitHub, generic URL, or local path). */
 export interface GitSource {
     type: 'github' | 'url' | 'local';
@@ -124,6 +128,8 @@ export declare function resolveGitHubUsername(): Promise<string | null>;
  * Get the remote URL for origin in a git repo.
  */
 export declare function getRemoteUrl(repoPath: string): Promise<string | null>;
+/** The repo's checked-out branch, or 'main' on a detached HEAD / read failure. */
+export declare function getCurrentBranch(repoPath: string): Promise<string>;
 /**
  * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
  * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
@@ -158,8 +164,13 @@ export type CommitAndPushResult = {
  * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
  * "nothing to push". Reports "already up to date" only when `ahead === 0` and
  * there is nothing to commit.
+ *
+ * `targetBranch` pushes the working tree to a differently-named remote branch
+ * (`<current>:<targetBranch>`) and is reported back as the result `branch`, so
+ * callers that print a branch-scoped URL reference where the commit actually
+ * landed — not the checked-out branch.
  */
-export declare function commitAndPush(repoPath: string, message: string): Promise<CommitAndPushResult>;
+export declare function commitAndPush(repoPath: string, message: string, targetBranch?: string): Promise<CommitAndPushResult>;
 /**
  * Check if repo has uncommitted changes.
  */

package/dist/lib/git.js

@@ -77,9 +77,18 @@ export function assertValidBranchName(branch) {
  *
  * Prefer this over `git.push(remote, branch)` whenever the branch comes from
  * repo state rather than a hard-coded literal.
+ *
+ * Pass `targetBranch` to push the local `branch` to a differently-named remote
+ * branch (`git push origin <branch>:<targetBranch>`) — used when publishing the
+ * working tree to a branch other than the checked-out one.
  */
-export async function pushOrigin(git, branch) {
+export async function pushOrigin(git, branch, targetBranch) {
     assertValidBranchName(branch);
+    if (targetBranch && targetBranch !== branch) {
+        assertValidBranchName(targetBranch);
+        await git.raw(['push', '--', 'origin', `${branch}:${targetBranch}`]);
+        return;
+    }
     await git.raw(['push', '--', 'origin', branch]);
 }
 /**
@@ -435,6 +444,16 @@ export async function getRemoteUrl(repoPath) {
         return null;
     }
 }
+/** The repo's checked-out branch, or 'main' on a detached HEAD / read failure. */
+export async function getCurrentBranch(repoPath) {
+    try {
+        const status = await simpleGit(repoPath).status();
+        return status.current || 'main';
+    }
+    catch {
+        return 'main';
+    }
+}
 /**
  * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
  * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
@@ -494,13 +513,23 @@ export async function checkGitHubRepoExists(owner, repo) {
  * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
  * "nothing to push". Reports "already up to date" only when `ahead === 0` and
  * there is nothing to commit.
+ *
+ * `targetBranch` pushes the working tree to a differently-named remote branch
+ * (`<current>:<targetBranch>`) and is reported back as the result `branch`, so
+ * callers that print a branch-scoped URL reference where the commit actually
+ * landed — not the checked-out branch.
  */
-export async function commitAndPush(repoPath, message) {
+export async function commitAndPush(repoPath, message, targetBranch) {
     try {
         const git = simpleGit(repoPath);
         let status = await git.status();
         const branch = status.current || 'main';
         assertValidBranchName(branch);
+        if (targetBranch)
+            assertValidBranchName(targetBranch);
+        // The branch the commit ends up on remotely — the checked-out branch unless
+        // an explicit target was requested.
+        const pushedBranch = targetBranch || branch;
         let committed = false;
         if (status.files.length > 0) {
             await git.add('-A');
@@ -509,7 +538,10 @@ export async function commitAndPush(repoPath, message) {
             status = await git.status();
         }
         const ahead = status.ahead ?? 0;
-        if (!committed && ahead === 0) {
+        // A same-branch push short-circuits when there is nothing new; a push to a
+        // different target branch must still run even from a clean, non-ahead tree,
+        // since the target may not carry these commits yet.
+        if (!committed && ahead === 0 && pushedBranch === branch) {
             return {
                 success: true,
                 detail: 'already up to date',
@@ -521,12 +553,12 @@ export async function commitAndPush(repoPath, message) {
         // Capture remote tip before push for a real ref range in the detail string.
         let before = '';
         try {
-            before = (await git.raw(['rev-parse', '--short=8', `origin/${branch}`])).trim();
+            before = (await git.raw(['rev-parse', '--short=8', `origin/${pushedBranch}`])).trim();
         }
         catch {
             /* origin/<branch> may not exist yet (first push) */
         }
-        await pushOrigin(git, branch);
+        await pushOrigin(git, branch, targetBranch);
         let after = '';
         try {
             after = (await git.raw(['rev-parse', '--short=8', 'HEAD'])).trim();
@@ -547,7 +579,7 @@ export async function commitAndPush(repoPath, message) {
         return {
             success: true,
             detail,
-            branch,
+            branch: pushedBranch,
             committed,
             pushed: true,
         };

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

@@ -0,0 +1,129 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * The same fetch also yields the **next milestone** — the earliest-dated
+ * milestone with unfinished issues — because each issue node carries its
+ * `projectMilestone`. A percentage tells you how far along a project is; the
+ * milestone tells you what it is due to hit next, which is the thing a person
+ * actually plans around. Deriving it here costs no extra request.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * 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;
+}
+/** A milestone as the project declares it, independent of any issue. */
+export interface LinearMilestoneNode {
+    id?: string;
+    name?: string;
+    targetDate?: 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;
+    /**
+     * 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.
+     */
+    nextMilestone?: LinearMilestone;
+}
+/** One issue node as the query selects it. */
+export interface LinearIssueNode {
+    state?: {
+        type?: string;
+    } | null;
+    projectMilestone?: {
+        id?: string;
+        name?: string;
+        targetDate?: string | null;
+    } | null;
+}
+/** The GraphQL response shape this module consumes (recorded for the tests). */
+export interface LinearIssuesResponse {
+    issues?: {
+        nodes?: LinearIssueNode[];
+        pageInfo?: {
+            hasNextPage?: boolean;
+            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 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>): Promise<LinearProjectCounts | undefined>;

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

@@ -0,0 +1,206 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * The same fetch also yields the **next milestone** — the earliest-dated
+ * milestone with unfinished issues — because each issue node carries its
+ * `projectMilestone`. A percentage tells you how far along a project is; the
+ * milestone tells you what it is due to hit next, which is the thing a person
+ * actually plans around. Deriving it here costs no extra request.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * budget; a capped fetch reports `truncated: true` and the card renders the
+ * total as a lower bound (`2500+ done`), never as the complete count.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { resolveLinearApiKey } from './auto-dispatch-linear.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;
+    let inProgress = 0;
+    for (const n of nodes) {
+        const type = n?.state?.type;
+        if (type === 'completed')
+            done++;
+        else if (type === 'started')
+            inProgress++;
+    }
+    const counts = { done, total: nodes.length, inProgress };
+    const next = nextMilestone(data.project?.projectMilestones?.nodes ?? [], nodes);
+    if (next)
+        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 nextMilestone(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;
+        if (!id)
+            continue;
+        const p = progress.get(id) ?? { done: 0, total: 0 };
+        p.total++;
+        if (n.state?.type === 'completed')
+            p.done++;
+        progress.set(id, p);
+    }
+    const candidates = declared
+        .map((d, order) => {
+        if (!d?.id || typeof d.name !== 'string' || !d.name)
+            return undefined;
+        const p = progress.get(d.id) ?? { done: 0, total: 0 };
+        const m = { name: d.name, done: p.done, total: p.total, order };
+        if (d.targetDate)
+            m.targetDate = d.targetDate;
+        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) => {
+        if (a.targetDate && b.targetDate)
+            return a.targetDate < b.targetDate ? -1 : a.targetDate > b.targetDate ? 1 : a.order - b.order;
+        if (a.targetDate)
+            return -1;
+        if (b.targetDate)
+            return 1;
+        return a.order - b.order;
+    });
+    const { order: _order, ...m } = candidates[0];
+    return m;
+}
+/** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
+function resolveApiKey() {
+    const fromChain = resolveLinearApiKey();
+    if (fromChain)
+        return fromChain;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.linear-cli', 'config.json'), 'utf8'));
+        return cfg.apiKey?.trim() || null;
+    }
+    catch {
+        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) {
+    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);
+            if (!data)
+                return undefined;
+            if (page === 0)
+                declared = data.project?.projectMilestones?.nodes ?? [];
+            all.push(...(data.issues?.nodes ?? []));
+            const pi = data.issues?.pageInfo;
+            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;
+            }
+            after = pi.endCursor;
+        }
+        return {
+            ...countsFromIssuesResponse({
+                issues: { nodes: all },
+                project: { projectMilestones: { nodes: declared } },
+            }),
+            ...(truncated ? { truncated } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        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;
+    // 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 } }';
+    const milestonesSelection = 'project(id:$pid){ projectMilestones(first:50){ nodes{ id name targetDate } } }';
+    const first = after === undefined;
+    const res = await fetch(LINEAR_API, {
+        method: 'POST',
+        headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            query: first
+                ? `query($p:ID!, $pid:String!, $after:String){ ${issuesSelection} ${milestonesSelection} }`
+                : `query($p:ID!, $after:String){ ${issuesSelection} }`,
+            variables: first
+                ? { p: projectId, pid: projectId, after: null }
+                : { p: projectId, after },
+        }),
+        signal,
+    });
+    if (!res.ok)
+        return undefined;
+    const json = (await res.json());
+    if (json.errors?.length || !json.data)
+        return undefined;
+    return json.data;
+}