@phnx-labs/agents-cli 1.21.3 → 1.22.1

package/dist/lib/model-tiers.js

@@ -0,0 +1,229 @@
+import { getModelCatalog } from './models.js';
+import { getModelPricing } from './pricing/index.js';
+/** The four cross-harness cost tiers, cheapest -> most capable. */
+export const MODEL_TIERS = ['cheap', 'default', 'best', 'ultra'];
+/** True if `s` is one of the four tier tokens (not a concrete model id). */
+export function isTierToken(s) {
+    return !!s && MODEL_TIERS.includes(s);
+}
+// --- single-model harnesses: the tier is reasoning effort, not a model ---------
+const TIER_EFFORT = {
+    cheap: 'low',
+    default: 'medium',
+    best: 'high',
+    ultra: 'xhigh',
+};
+// --- Droid: no live catalog; prices in credit multipliers. Curated map, capped
+//     at 2x (no 4x models like Fable 5 / Fast modes). Ids are Factory -m values.
+const DROID_TIERS = {
+    cheap: 'glm-5.2', // 0.55x (Droid Core)
+    default: 'kimi-k3', // 0.6x (Droid Core)
+    best: 'claude-opus-5', // 2x
+    ultra: 'claude-opus-5', // clamp to best; avoid 4x
+};
+/** Router / pseudo models that are not a concrete choice and never a tier target. */
+const PSEUDO = /(^|[-/])(auto|auto-review|router|dynamic)([-/]|$)/i;
+/** Effort / speed suffixes aggregator harnesses (Cursor) bake into ids. */
+const AGGREGATOR_SUFFIX = /-(low|medium|high|xhigh|thinking|fast|reasoning)\b/gi;
+/** Anthropic capability family -> rank (cheapest 0 -> dearest 3). */
+function anthropicFamilyRank(id) {
+    if (/(^|[-/])claude-haiku|(^|[-/])haiku/.test(id))
+        return 0;
+    if (/claude-sonnet|(^|[-/])sonnet/.test(id))
+        return 1;
+    if (/claude-opus|(^|[-/])opus/.test(id))
+        return 2;
+    if (/claude-(fable|mythos)|(^|[-/])(fable|mythos)/.test(id))
+        return 3;
+    return null;
+}
+/** Rank from the provider's own description keywords (e.g. Codex Sol/Terra/Luna). */
+function descriptionRank(desc) {
+    if (!desc)
+        return null;
+    const d = desc.toLowerCase();
+    if (/(fast|affordable|cost-efficient|small|cheap|mini|nano|lightweight|spark)/.test(d))
+        return 0;
+    if (/(balanced|everyday|strong|general)/.test(d))
+        return 1;
+    if (/(frontier|latest|flagship|most capable|complex|advanced|professional)/.test(d))
+        return 2;
+    return null;
+}
+/** Last-resort ordering from size tokens embedded in the id. */
+function sizeTokenRank(id) {
+    if (/(nano|mini|lite|flash|highspeed|small|air|spark)/.test(id))
+        return 0;
+    if (/(pro|max|ultra|opus|sol|large|frontier|heavy|thinking)/.test(id))
+        return 2;
+    return 1;
+}
+const blended = (id) => {
+    const p = getModelPricing(id);
+    return p ? p.inputPerToken + p.outputPerToken : null;
+};
+/** Strip an aggregator's effort/speed suffixes down to a base provider id. */
+function normalizeAggregatorId(id) {
+    return id.replace(AGGREGATOR_SUFFIX, '').replace(/-+$/, '');
+}
+/**
+ * Compare two concrete ids so the newest wins within a family. Strips a trailing
+ * date stamp (`-20251101`), rebuild marker (`-v1`), and `-fast` first, so a dated
+ * `opus-4-5-20251101` doesn't out-rank the genuinely newer `opus-4-8` (a bare
+ * `compareVersions` reads the date as a huge version component).
+ */
+function cleanForCompare(id) {
+    return id
+        .replace(/-\d{8}(?=($|-))/, '')
+        .replace(/-v\d+$/, '')
+        .replace(/-fast$/, '');
+}
+/** Numeric segments of a (cleaned) id, splitting on BOTH dashes and dots. */
+function versionSegments(id) {
+    const m = cleanForCompare(id).match(/\d+/g);
+    return m ? m.map((n) => parseInt(n, 10)) : [];
+}
+/**
+ * Newest concrete id within a family wins. `compareVersions` only splits on `.`,
+ * so it degenerates to a single `[0]` segment for a dash-separated model id and
+ * mis-ranks e.g. `claude-sonnet-5` below `claude-sonnet-4-6`. Compare the numeric
+ * segments directly instead.
+ */
+function newer(a, b) {
+    const A = versionSegments(a);
+    const B = versionSegments(b);
+    for (let i = 0; i < Math.max(A.length, B.length); i++) {
+        const d = (A[i] ?? 0) - (B[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/**
+ * Rank a harness's catalog models cheapest -> dearest and collapse variants of
+ * one model to a single rung (keeping the newest concrete id). Strategy depends
+ * on the harness class: aggregator (Cursor) ranks by price of the normalized
+ * base id; single-provider harnesses rank by the provider lineup with price and
+ * size tokens as fallbacks.
+ */
+function rankCatalog(agent, models) {
+    const usable = models.filter((m) => !PSEUDO.test(m.id));
+    const aggregator = agent === 'cursor';
+    const scored = usable.map((m) => {
+        const rawId = m.id;
+        const baseId = aggregator ? normalizeAggregatorId(rawId) : rawId;
+        const lc = baseId.toLowerCase();
+        const price = blended(baseId) ?? blended(rawId);
+        let rank;
+        let family;
+        if (aggregator) {
+            // cross-provider: price is the unifying signal; family = base id
+            rank = price != null ? price * 1e6 : 100 + sizeTokenRank(lc);
+            family = baseId;
+        }
+        else {
+            const fam = anthropicFamilyRank(lc);
+            const desc = descriptionRank(m.description);
+            if (fam != null) {
+                rank = fam;
+                family = `anthropic-${fam}`;
+            }
+            else if (desc != null) {
+                rank = desc;
+                family = `desc-${desc}-${baseId.replace(/[0-9].*$/, '')}`;
+            }
+            else if (price != null) {
+                rank = 10 + price * 1e6;
+                // Collapse only true re-releases of ONE model (same base id, differing
+                // date/rebuild suffix). Keying on price would merge two DIFFERENT models
+                // that happen to cost the same (e.g. gpt-5.5 and gpt-5.6-sol), dropping
+                // one from every tier.
+                family = cleanForCompare(baseId);
+            }
+            else {
+                rank = 20 + sizeTokenRank(lc);
+                family = cleanForCompare(baseId);
+            }
+        }
+        return { id: rawId, baseId, rank, family, price };
+    });
+    // collapse by family: keep the newest concrete id, lowest (cheapest) rank
+    const byFamily = new Map();
+    for (const s of scored) {
+        const prev = byFamily.get(s.family);
+        if (!prev) {
+            byFamily.set(s.family, s);
+            continue;
+        }
+        // keep the newer id; keep the cheaper rank
+        if (newer(s.id, prev.id) > 0)
+            prev.id = s.id;
+        if (s.rank < prev.rank)
+            prev.rank = s.rank;
+        if (prev.price == null && s.price != null)
+            prev.price = s.price;
+    }
+    return [...byFamily.values()].sort((a, b) => a.rank - b.rank || newer(b.id, a.id));
+}
+/** Which ranked rung each tier index maps to, collapsing when there are < 4 rungs. */
+function rungIndexFor(tierIndex, n) {
+    return n >= 4 ? Math.round((tierIndex / 3) * (n - 1)) : Math.min(tierIndex, n - 1);
+}
+/**
+ * Resolve all four tiers for an (agent, version). The map is what `agents models`
+ * prints and what `resolveTier` indexes into.
+ */
+export function resolveTierMap(agent, version) {
+    // Droid: curated credit-multiplier map (no live catalog).
+    if (agent === 'droid') {
+        return {
+            cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x' },
+            default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x' },
+            best: { tier: 'best', model: DROID_TIERS.best, note: '2x' },
+            ultra: { tier: 'ultra', model: DROID_TIERS.ultra, clampedFrom: 'best', note: 'capped at 2x (4x models excluded)' },
+        };
+    }
+    const catalog = getModelCatalog(agent, version);
+    return tierizeModels(agent, catalog?.models ?? []);
+}
+/**
+ * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup)
+ * so it is directly testable with synthetic inputs. Ranks the models, collapses
+ * variants, buckets onto cheap/default/best/ultra, and clamps absent tiers down
+ * to the nearest lower one. A single-model harness maps the tiers to reasoning
+ * effort instead of models.
+ */
+export function tierizeModels(agent, models) {
+    const rungs = rankCatalog(agent, models);
+    // Single-model harness (e.g. Grok): the tier is reasoning effort, not a model.
+    if (rungs.length === 1) {
+        const only = rungs[0].id;
+        const map = {};
+        for (const t of MODEL_TIERS)
+            map[t] = { tier: t, model: only, effort: TIER_EFFORT[t], note: 'single model — tier maps to reasoning effort' };
+        return map;
+    }
+    const n = rungs.length;
+    const map = {};
+    if (n === 0) {
+        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
+        for (const t of MODEL_TIERS)
+            map[t] = { tier: t, model: null };
+        return map;
+    }
+    // Map each tier onto a rung; a tier that shares the rung of the tier below it
+    // has no distinct rung of its own, so mark it clamped for an honest display.
+    for (let i = 0; i < MODEL_TIERS.length; i++) {
+        const t = MODEL_TIERS[i];
+        const idx = rungIndexFor(i, n);
+        const shared = i > 0 && rungIndexFor(i - 1, n) === idx;
+        map[t] = shared
+            ? { tier: t, model: rungs[idx].id, clampedFrom: MODEL_TIERS[i - 1], note: `no distinct ${t} rung; using ${MODEL_TIERS[i - 1]}` }
+            : { tier: t, model: rungs[idx].id };
+    }
+    return map;
+}
+/** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
+export function resolveTier(agent, version, tier) {
+    return resolveTierMap(agent, version)[tier];
+}

package/dist/lib/models.d.ts

@@ -1,4 +1,5 @@
 import type { AgentId } from './types.js';
+import { type ModelPricing } from './pricing/index.js';
 /** Model identifiers per cloud provider (used by Claude's multi-cloud routing). */
 export interface ModelPerCloud {
     firstParty: string;
@@ -28,6 +29,8 @@ export interface ModelInfo {
     reasoningLevels?: ReasoningLevel[];
     /** Default reasoning level if applicable */
     defaultReasoningLevel?: string;
+    /** Per-token USD pricing when known (from prices.json); absent for subscription/unpriced models. */
+    pricing?: ModelPricing;
 }
 /** The complete model catalog for a specific (agent, version) pair. */
 export interface ModelCatalog {

package/dist/lib/models.js

@@ -15,6 +15,7 @@ import { getVersionDir, getVersionHomePath, getBinaryPath } from './versions.js'
 import { getModelsCachePath } from './state.js';
 import { agentConfigDirName } from './agents.js';
 import { resolveRunDefaults } from './run-defaults.js';
+import { getModelPricing } from './pricing/index.js';
 const CACHE_PATH = getModelsCachePath();
 /**
  * Bump when the extractor logic changes shape in an incompatible way so cached
@@ -342,17 +343,12 @@ function extractClaudeCatalog(text) {
             mantle: m[6] ?? null,
         };
     }
-    const allIds = new Set([
-        ...Object.values(aliases),
-        ...Object.keys(displayNames),
-        ...Object.keys(perCloud),
-    ]);
     const aliasReverse = {};
     for (const [a, id] of Object.entries(aliases))
         aliasReverse[id] = a;
     const defaults = new Set(Object.values(aliases));
-    const models = Array.from(allIds)
-        .filter((id) => /^claude-(opus|sonnet|haiku)-/.test(id))
+    const build = (ids) => Array.from(new Set(ids))
+        .filter((id) => /^claude-(opus|sonnet|haiku|fable|mythos)-/.test(id))
         .sort()
         .map((id) => ({
         id,
@@ -361,6 +357,32 @@ function extractClaudeCatalog(text) {
         isDefault: defaults.has(id),
         perCloud: perCloud[id],
     }));
+    // The structured maps (alias/perCloud/const) are the curated, accurate
+    // supported set. Prefer them.
+    let models = build([
+        ...Object.values(aliases),
+        ...Object.keys(displayNames),
+        ...Object.keys(perCloud),
+    ]);
+    // Fallback id scan. The structured maps fail on the newest native-binary
+    // format (verified: claude@2.1.219 leaks only a stray id, so the curated set
+    // is effectively empty). Only when the curated catalog is that thin do we scan
+    // the raw strings for canonical ids -- so an older version keeps its precise
+    // catalog while a newer one still gets a real catalog (incl. fable/mythos and
+    // the opus-5/sonnet-5 line) rather than an empty or single-model one.
+    if (models.length < 2) {
+        const scanned = new Set();
+        // Dash-separated segments only. Real ids are `claude-sonnet-4-6`; the dotted
+        // form `claude-sonnet-4.6` appears only inside the binary's own "Typo in
+        // model ID" troubleshooting text, so a `.`-permitting pattern would scrape a
+        // non-model string as if it were real.
+        const idRe = /claude-(?:opus|sonnet|haiku|fable|mythos)-\d+(?:-\d+)*(?:-(?:fast|v\d+))?/g;
+        let sm;
+        while ((sm = idRe.exec(text)) !== null)
+            scanned.add(sm[0]);
+        if (scanned.size >= 2)
+            models = build(scanned);
+    }
     return { models, aliases };
 }
 /**
@@ -929,6 +951,14 @@ export function getModelCatalog(agent, version) {
         else if (agent === 'grok')
             ({ models, aliases } = extractGrokCatalog(src.path));
     }
+    // Attach per-token pricing where the offline table knows the model, so the
+    // catalog carries $/token for the tier display and budgeting. Subscription /
+    // unknown models keep `pricing` undefined (surfaced as "--", never faked).
+    for (const m of models) {
+        const p = getModelPricing(m.id);
+        if (p)
+            m.pricing = p;
+    }
     const catalog = {
         agent,
         version,
@@ -1123,5 +1153,12 @@ export function buildReasoningFlags(agent, level) {
         const droidLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
         return ['-r', droidLevel];
     }
+    if (agent === 'grok') {
+        // Grok: `--reasoning-effort <low|medium|high>` (alias --effort). xhigh/max
+        // clamp to high. This is the effort dial cost tiers steer for Grok, whose
+        // catalog exposes a single model.
+        const grokLevel = (normalized === 'xhigh' || normalized === 'max') ? 'high' : normalized;
+        return ['--reasoning-effort', grokLevel];
+    }
     return [];
 }

package/dist/lib/pricing/prices.json

@@ -1,5 +1,5 @@
 {
-    "version": "2026-06-24",
+    "version": "2026-08-03",
     "models": {
         "claude-opus-4": {
             "inputPerToken": 0.000005,
@@ -49,6 +49,21 @@
             "cacheReadPerToken": 0.0000015,
             "cacheWritePerToken": 0.00001875
         },
+        "gpt-5.6-sol": {
+            "inputPerToken": 0.000005,
+            "outputPerToken": 0.00003,
+            "cacheReadPerToken": 0.0000005
+        },
+        "gpt-5.6-terra": {
+            "inputPerToken": 0.0000025,
+            "outputPerToken": 0.000015,
+            "cacheReadPerToken": 0.00000025
+        },
+        "gpt-5.6-luna": {
+            "inputPerToken": 0.000001,
+            "outputPerToken": 0.000006,
+            "cacheReadPerToken": 0.0000001
+        },
         "gpt-5.5": {
             "inputPerToken": 0.000005,
             "outputPerToken": 0.00003,

package/dist/lib/project-focus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a project's work actually went, from the local git history.
+ *
+ * The card can say how many agents are running and how many PRs merged, but not
+ * *what was worked on*. That answer is already sitting in the checkout — every
+ * merged commit names the files it touched — so it costs no API call, no
+ * credential, and no rate-limit budget. Measured at 0.23s on this repo's own
+ * 7-day window (897 commits), which is why it runs unconditionally rather than
+ * behind a flag.
+ *
+ * Deliberately NOT from `gh`: the GitHub API would spend a request per PR to
+ * learn what `git log --name-only` already knows locally, and it would be wrong
+ * on a monorepo whose interesting unit is a subdirectory rather than a repo.
+ */
+/** One directory and how many file-touches landed in it during the window. */
+export interface FocusArea {
+    path: string;
+    touches: number;
+}
+/** Areas shown on the card before the tail is dropped. */
+export declare const FOCUS_LIMIT = 4;
+/**
+ * Bucket a file path to its area. Files shallower than {@link DEPTH} bucket to
+ * their own directory, so a repo-root `README.md` does not vanish.
+ */
+export declare function focusBucket(file: string): string | undefined;
+/**
+ * Rank areas by file-touches, descending, ties broken by path so the order is
+ * stable across runs. Pure — the caller supplies the file list, so this is
+ * testable without a git repo.
+ */
+export declare function rankFocusAreas(files: string[], limit?: number): FocusArea[];
+/**
+ * Read the window's changed files from a checkout. Best-effort in the same shape
+ * as the rest of the card's enrichment: a missing checkout, a shallow clone, or
+ * a repo with no commits in the window yields an empty list, never a throw.
+ *
+ * Reads the LOCAL default branch ref rather than fetching — a status command
+ * must not mutate the repo it is describing, so the answer is only as fresh as
+ * the user's last fetch, which is the correct trade for a read-only card.
+ */
+export declare function readFocusAreas(root: string, windowDays: number): Promise<FocusArea[]>;

package/dist/lib/project-focus.js

@@ -0,0 +1,80 @@
+/**
+ * Where a project's work actually went, from the local git history.
+ *
+ * The card can say how many agents are running and how many PRs merged, but not
+ * *what was worked on*. That answer is already sitting in the checkout — every
+ * merged commit names the files it touched — so it costs no API call, no
+ * credential, and no rate-limit budget. Measured at 0.23s on this repo's own
+ * 7-day window (897 commits), which is why it runs unconditionally rather than
+ * behind a flag.
+ *
+ * Deliberately NOT from `gh`: the GitHub API would spend a request per PR to
+ * learn what `git log --name-only` already knows locally, and it would be wrong
+ * on a monorepo whose interesting unit is a subdirectory rather than a repo.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+/** How deep a bucket goes: `apps/cli/src`, not `apps` and not every leaf file. */
+const DEPTH = 3;
+/** Areas shown on the card before the tail is dropped. */
+export const FOCUS_LIMIT = 4;
+/**
+ * Paths whose churn is process, not engineering.
+ *
+ * This repo files one changelog fragment per PR, so `.changelog` ranks second by
+ * raw file-touches — presenting it as an "area of focus" would read as a signal
+ * while measuring nothing but the number of PRs. Same for the generated
+ * CHANGELOG and lockfiles.
+ */
+const NOISE = /(^|\/)(\.changelog|CHANGELOG\.md|bun\.lock|package-lock\.json|yarn\.lock)(\/|$)/;
+/**
+ * Bucket a file path to its area. Files shallower than {@link DEPTH} bucket to
+ * their own directory, so a repo-root `README.md` does not vanish.
+ */
+export function focusBucket(file) {
+    if (NOISE.test(file))
+        return undefined;
+    const parts = file.split('/').filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return parts.slice(0, Math.min(DEPTH, parts.length - 1)).join('/');
+}
+/**
+ * Rank areas by file-touches, descending, ties broken by path so the order is
+ * stable across runs. Pure — the caller supplies the file list, so this is
+ * testable without a git repo.
+ */
+export function rankFocusAreas(files, limit = FOCUS_LIMIT) {
+    const counts = new Map();
+    for (const f of files) {
+        const bucket = focusBucket(f.trim());
+        if (!bucket)
+            continue;
+        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([path, touches]) => ({ path, touches }))
+        .sort((a, b) => b.touches - a.touches || a.path.localeCompare(b.path))
+        .slice(0, Math.max(1, limit));
+}
+/**
+ * Read the window's changed files from a checkout. Best-effort in the same shape
+ * as the rest of the card's enrichment: a missing checkout, a shallow clone, or
+ * a repo with no commits in the window yields an empty list, never a throw.
+ *
+ * Reads the LOCAL default branch ref rather than fetching — a status command
+ * must not mutate the repo it is describing, so the answer is only as fresh as
+ * the user's last fetch, which is the correct trade for a read-only card.
+ */
+export async function readFocusAreas(root, windowDays) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', root, 'log', `--since=${windowDays} days ago`, '--name-only', '--pretty=format:'], { timeout: 5000, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+        return rankFocusAreas(stdout.split('\n').filter((l) => l.trim().length > 0));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/project-schedule.d.ts

@@ -0,0 +1,75 @@
+/**
+ * What a project's milestone dates prove about its schedule — and nothing more.
+ *
+ * The tempting version of this file computes "on track / at risk". It cannot be
+ * written honestly against this data. Probed live against a real workspace:
+ *
+ *   health: null            projectUpdates: []
+ *   startDate: null         targetDate: null
+ *   scopeHistory: []        completedScopeHistory: []
+ *
+ * "Behind schedule" needs either start+target dates to interpolate an expected
+ * progress line, or a history series to extrapolate a finish date. Both are
+ * absent, so any on-track/at-risk chip would be invented — and a confident wrong
+ * answer on a status card is worse than a blank one, because it is unfalsifiable
+ * from the card itself.
+ *
+ * So every verdict here is arithmetic on a stored date or a count:
+ *
+ *   overdue        a milestone's targetDate has passed and it is unfinished
+ *   due-soon       the next one lands within DUE_SOON_DAYS
+ *   untracked      milestones exist but nothing is filed against any of them,
+ *                  so their progress is not measurable
+ *   scheduled      dated milestones ahead, none due soon, work is filed
+ *   no-dates       milestones exist, none carries a date
+ *   none           the project declares no milestones
+ *
+ * `declared` relays Linear's OWN health when a human has posted one. It is
+ * passed through and attributed, never synthesized — if the user starts posting
+ * project updates, their answer wins over anything derived here.
+ */
+import type { LinearMilestone } from './linear-project-counts.js';
+/** How far ahead counts as "due soon" — one sprint's notice. */
+export declare const DUE_SOON_DAYS = 14;
+/** A verdict about the schedule, as a tagged union so `--json` stays stable. */
+export type ProjectVerdict = {
+    kind: 'declared';
+    health: string;
+} | {
+    kind: 'overdue';
+    milestone: string;
+    days: number;
+} | {
+    kind: 'due-soon';
+    milestone: string;
+    days: number;
+} | {
+    kind: 'untracked';
+    milestones: number;
+} | {
+    kind: 'scheduled';
+    milestone: string;
+    days: number;
+} | {
+    kind: 'no-dates';
+    milestones: number;
+} | {
+    kind: 'none';
+};
+/** Whole days from `nowMs` to a `YYYY-MM-DD` date, compared at LOCAL midnight. */
+export declare function daysUntil(targetDate: string, nowMs: number): number | undefined;
+/**
+ * Decide what the dates prove. Precedence is time-sensitivity first:
+ *
+ *   declared > overdue > due-soon > untracked > no-dates > scheduled
+ *
+ * An overdue milestone outranks an approaching one, and both outrank the
+ * observation that nothing is filed — a deadline moves, that observation does
+ * not. `declared` overrides everything, because a human said it.
+ */
+export declare function scheduleVerdict(milestones: LinearMilestone[], nowMs: number, declaredHealth?: string | null): ProjectVerdict;
+/** One line for the card. Returns undefined for `none` — an empty row says nothing. */
+export declare function formatVerdict(v: ProjectVerdict): {
+    text: string;
+    warn: boolean;
+} | undefined;

package/dist/lib/project-schedule.js

@@ -0,0 +1,110 @@
+/**
+ * What a project's milestone dates prove about its schedule — and nothing more.
+ *
+ * The tempting version of this file computes "on track / at risk". It cannot be
+ * written honestly against this data. Probed live against a real workspace:
+ *
+ *   health: null            projectUpdates: []
+ *   startDate: null         targetDate: null
+ *   scopeHistory: []        completedScopeHistory: []
+ *
+ * "Behind schedule" needs either start+target dates to interpolate an expected
+ * progress line, or a history series to extrapolate a finish date. Both are
+ * absent, so any on-track/at-risk chip would be invented — and a confident wrong
+ * answer on a status card is worse than a blank one, because it is unfalsifiable
+ * from the card itself.
+ *
+ * So every verdict here is arithmetic on a stored date or a count:
+ *
+ *   overdue        a milestone's targetDate has passed and it is unfinished
+ *   due-soon       the next one lands within DUE_SOON_DAYS
+ *   untracked      milestones exist but nothing is filed against any of them,
+ *                  so their progress is not measurable
+ *   scheduled      dated milestones ahead, none due soon, work is filed
+ *   no-dates       milestones exist, none carries a date
+ *   none           the project declares no milestones
+ *
+ * `declared` relays Linear's OWN health when a human has posted one. It is
+ * passed through and attributed, never synthesized — if the user starts posting
+ * project updates, their answer wins over anything derived here.
+ */
+/** How far ahead counts as "due soon" — one sprint's notice. */
+export const DUE_SOON_DAYS = 14;
+/** Whole days from `nowMs` to a `YYYY-MM-DD` date, compared at LOCAL midnight. */
+export function daysUntil(targetDate, nowMs) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(targetDate.trim());
+    if (!m)
+        return undefined;
+    const due = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    if (Number.isNaN(due.getTime()))
+        return undefined;
+    const now = new Date(nowMs);
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    return Math.round((due.getTime() - today.getTime()) / 86_400_000);
+}
+const unfinished = (m) => m.total === 0 || m.done < m.total;
+/**
+ * Decide what the dates prove. Precedence is time-sensitivity first:
+ *
+ *   declared > overdue > due-soon > untracked > no-dates > scheduled
+ *
+ * An overdue milestone outranks an approaching one, and both outrank the
+ * observation that nothing is filed — a deadline moves, that observation does
+ * not. `declared` overrides everything, because a human said it.
+ */
+export function scheduleVerdict(milestones, nowMs, declaredHealth) {
+    if (declaredHealth)
+        return { kind: 'declared', health: declaredHealth };
+    if (milestones.length === 0)
+        return { kind: 'none' };
+    const open = milestones.filter(unfinished);
+    const dated = open
+        .map((m) => ({ m, days: m.targetDate ? daysUntil(m.targetDate, nowMs) : undefined }))
+        .filter((x) => x.days !== undefined)
+        .sort((a, b) => a.days - b.days);
+    const worst = dated[0];
+    if (worst && worst.days < 0)
+        return { kind: 'overdue', milestone: worst.m.name, days: -worst.days };
+    // A date bearing down is time-sensitive; "nothing is filed" is a standing
+    // condition that will still be true tomorrow. So an approaching deadline is
+    // reported even when the milestone has no issues against it — reversing these
+    // hid a milestone due in two days behind "3 milestones, no issues filed".
+    if (worst && worst.days <= DUE_SOON_DAYS)
+        return { kind: 'due-soon', milestone: worst.m.name, days: worst.days };
+    // Nothing is filed against ANY milestone, so no progress can be computed for
+    // them — the useful thing to say, and the actual state of a project whose
+    // milestones were created before its issues. Checked against the full list,
+    // not just the open ones: a COMPLETED milestone necessarily has issues, so a
+    // project with one cannot honestly be called untracked.
+    if (milestones.every((m) => m.total === 0))
+        return { kind: 'untracked', milestones: milestones.length };
+    if (!worst)
+        return { kind: 'no-dates', milestones: open.length };
+    return { kind: 'scheduled', milestone: worst.m.name, days: worst.days };
+}
+/** One line for the card. Returns undefined for `none` — an empty row says nothing. */
+export function formatVerdict(v) {
+    switch (v.kind) {
+        case 'declared':
+            // Attributed, so nobody mistakes a human's call for a derived one.
+            return { text: `per Linear: ${v.health}`, warn: v.health.toLowerCase() !== 'ontrack' };
+        case 'overdue':
+            return { text: `${v.milestone} overdue by ${v.days} day${v.days === 1 ? '' : 's'}`, warn: true };
+        case 'due-soon':
+            return {
+                text: `${v.milestone} due ${v.days === 0 ? 'today' : v.days === 1 ? 'tomorrow' : `in ${v.days} days`}`,
+                warn: false,
+            };
+        case 'untracked':
+            return {
+                text: `${v.milestones} milestone${v.milestones === 1 ? '' : 's'}, no issues filed against any — progress is not measurable`,
+                warn: true,
+            };
+        case 'scheduled':
+            return { text: `${v.milestone} in ${v.days} days`, warn: false };
+        case 'no-dates':
+            return { text: `${v.milestones} open milestone${v.milestones === 1 ? '' : 's'}, none dated`, warn: false };
+        case 'none':
+            return undefined;
+    }
+}