@phnx-labs/agents-cli 1.21.0 → 1.21.2

package/dist/lib/notify.js

@@ -1,14 +1,6 @@
-/**
- * Urgent-block phone notifier.
- *
- * Reuses the OpenClaw Telegram gateway on the local mac-mini (Jeff/`default` bot)
- * instead of raw bot tokens. Notifies once per block (tracked by `notifiedAt`).
- * Best-effort: any openclaw failure is surfaced as a warning, not a hard error,
- * so a notification hiccup never blocks the agent.
- */
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-const execFileAsync = promisify(execFile);
+import { readMeta } from './state.js';
+import { registerBuiltinProviders } from './channels/providers/index.js';
+import { lookupTransport } from './channels/resolve.js';
 export function formatUrgentBlockMessage(block) {
     const q = block.questions[0];
     const header = q?.header ? `[${q.header}] ` : '';
@@ -18,11 +10,14 @@ export function formatUrgentBlockMessage(block) {
     const cost = block.costOfDelay ?? 'low';
     return `URGENT ${cls.toUpperCase()}${host}: ${header}${text} (cost: ${cost}, id: ${block.blockId})`;
 }
-/** Build openclaw argv for urgent notify (exported for tests). */
-export function buildOpenClawNotifyArgs(text, options = {}) {
-    const channel = options.channel ?? 'telegram';
-    const account = options.account ?? 'default';
-    const target = options.target ?? '6078999250';
+/**
+ * Build openclaw argv for a Telegram send (used by the openclaw-telegram
+ * provider and its tests). `target` is required — the recipient is always
+ * resolved by the caller, never defaulted to a hardcoded number here.
+ */
+export function buildOpenClawNotifyArgs(text, opts) {
+    const channel = opts.channel ?? 'telegram';
+    const account = opts.account ?? 'default';
     return [
         'message',
         'send',
@@ -31,11 +26,38 @@ export function buildOpenClawNotifyArgs(text, options = {}) {
         '--account',
         account,
         '--target',
-        target,
+        opts.target,
         '--message',
         text,
     ];
 }
+/**
+ * Deliver a message to the configured owner through the one channel seam.
+ * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * selects the provider per host. A missing owner config or a delivery failure
+ * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
+ * ENOENT — so callers surface a consistent, best-effort failure.
+ */
+export async function sendToOwner(text, options = {}) {
+    const meta = options.meta ?? readMeta();
+    const owner = meta.notify?.owner;
+    const channel = options.channel ?? owner?.channel;
+    const target = options.target ?? owner?.to;
+    if (!channel || !target) {
+        return {
+            ok: false,
+            channel: channel ?? 'unknown',
+            id: target ?? '',
+            error: 'notify.owner.{channel,to} not set in agents.yaml',
+        };
+    }
+    registerBuiltinProviders();
+    const { provider, error } = lookupTransport(channel, meta);
+    if (!provider) {
+        return { ok: false, channel, id: target, error };
+    }
+    return provider.send(text, { target, dryRun: options.dryRun });
+}
 export async function notifyUrgentBlock(block, options = {}) {
     if (block.notifiedAt) {
         return { ok: true, skipped: true };
@@ -43,19 +65,6 @@ export async function notifyUrgentBlock(block, options = {}) {
     if (options.dryRun) {
         return { ok: true, skipped: true };
     }
-    // Check that openclaw is installed.
-    try {
-        await execFileAsync('which', ['openclaw']);
-    }
-    catch {
-        return { ok: false, error: 'openclaw CLI not found on PATH' };
-    }
-    const text = formatUrgentBlockMessage(block);
-    try {
-        await execFileAsync('openclaw', buildOpenClawNotifyArgs(text, options));
-        return { ok: true };
-    }
-    catch (err) {
-        return { ok: false, error: err.message };
-    }
+    const result = await sendToOwner(formatUrgentBlockMessage(block), options);
+    return result.ok ? { ok: true } : { ok: false, error: result.error };
 }

package/dist/lib/perf/db.d.ts

@@ -17,7 +17,12 @@ export declare function drainSpool(db?: Database.Database): number;
 /** Percentile of a sorted-ascending array. p in [0,100]. */
 export declare function percentile(sorted: number[], p: number): number;
 /**
- * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
+ *
+ * `opts.project` scopes the query to samples whose recorded `cwd` resolves to
+ * that project key (see project-key.ts) — resolution runs per unique cwd
+ * (memoized) rather than per row, since `resolveProjectKey` does a filesystem
+ * walk and a warehouse query can carry many rows sharing the same cwd.
  */
 export declare function aggregateSamples(opts?: AggregateOptions): PerfAggregateRow[];
 export declare function perfDbPath(): string;

package/dist/lib/perf/db.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import Database from '../sqlite.js';
 import { getPerfDbPath, getPerfDir } from '../state.js';
 import { localMachineId } from '../session/origin-machine.js';
+import { resolveProjectKey } from '../project-key.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export const PERF_SCHEMA_VERSION = 1;
@@ -200,7 +201,12 @@ export function percentile(sorted, p) {
     return sorted[lo] * (1 - frac) + sorted[hi] * frac;
 }
 /**
- * Aggregate samples by (kind, label) with p50/p99. Drains the spool first.
+ * Aggregate samples by (kind, label) with p50/p95/p99. Drains the spool first.
+ *
+ * `opts.project` scopes the query to samples whose recorded `cwd` resolves to
+ * that project key (see project-key.ts) — resolution runs per unique cwd
+ * (memoized) rather than per row, since `resolveProjectKey` does a filesystem
+ * walk and a warehouse query can carry many rows sharing the same cwd.
  */
 export function aggregateSamples(opts = {}) {
     const db = openDb();
@@ -228,14 +234,29 @@ export function aggregateSamples(opts = {}) {
         clauses.push('agent = ?');
         params.push(opts.agent);
     }
-    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd
      FROM samples WHERE ${clauses.join(' AND ')}`).all(...params);
+    // Memoize cwd -> project key: resolveProjectKey walks the filesystem for
+    // a repo root, and many rows in one warehouse query share the same cwd.
+    const projectCache = new Map();
+    const projectForCwd = (cwd) => {
+        if (!cwd)
+            return undefined;
+        let key = projectCache.get(cwd);
+        if (key === undefined && !projectCache.has(cwd)) {
+            key = resolveProjectKey(cwd);
+            projectCache.set(cwd, key);
+        }
+        return key;
+    };
     const map = new Map();
     for (const r of rows) {
+        if (opts.project && projectForCwd(r.cwd) !== opts.project)
+            continue;
         const key = `${r.kind}\0${r.label}`;
         let b = map.get(key);
         if (!b) {
-            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0 };
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, timeouts: 0 };
             map.set(key, b);
         }
         b.durations.push(Number(r.duration_ms));
@@ -245,7 +266,9 @@ export function aggregateSamples(opts = {}) {
             b.stale++;
         else if (r.cache === 'miss' || r.cache === 'none')
             b.misses++;
-        if (typeof r.exit_code === 'number' && r.exit_code !== 0)
+        if (r.status === 'timeout')
+            b.timeouts++;
+        else if (typeof r.exit_code === 'number' && r.exit_code !== 0)
             b.errors++;
     }
     const out = [];
@@ -260,6 +283,7 @@ export function aggregateSamples(opts = {}) {
             label: b.label,
             n,
             p50Ms: Math.round(percentile(sorted, 50)),
+            p95Ms: Math.round(percentile(sorted, 95)),
             p99Ms: Math.round(percentile(sorted, 99)),
             meanMs: Math.round(sum / n),
             maxMs: sorted[n - 1],
@@ -270,8 +294,14 @@ export function aggregateSamples(opts = {}) {
             row.cacheStalePct = Math.round((b.stale / n) * 100);
             row.cacheMissPct = Math.round((b.misses / n) * 100);
         }
-        if (b.errors > 0)
+        if (b.errors > 0) {
             row.errorCount = b.errors;
+            row.errorRate = Math.round((b.errors / n) * 1000) / 1000;
+        }
+        if (b.timeouts > 0)
+            row.timeoutRate = Math.round((b.timeouts / n) * 1000) / 1000;
+        if (opts.project)
+            row.project = opts.project;
         out.push(row);
     }
     out.sort((a, b) => b.p99Ms - a.p99Ms);

package/dist/lib/perf/types.d.ts

@@ -26,6 +26,7 @@ export interface PerfAggregateRow {
     label: string;
     n: number;
     p50Ms: number;
+    p95Ms: number;
     p99Ms: number;
     meanMs: number;
     maxMs: number;
@@ -34,6 +35,13 @@ export interface PerfAggregateRow {
     cacheStalePct?: number;
     cacheMissPct?: number;
     errorCount?: number;
+    /** Fraction (0-1) of samples with a nonzero exit code. */
+    errorRate?: number;
+    /** Fraction (0-1) of samples with status:'timeout'. */
+    timeoutRate?: number;
+    /** Project key (see project-key.ts) the row is scoped to — set only when
+     *  the `project` filter narrowed the query to one project. */
+    project?: string;
 }
 export interface AggregateOptions {
     days?: number;
@@ -42,4 +50,6 @@ export interface AggregateOptions {
     machine?: string;
     agent?: string;
     minN?: number;
+    /** Scope results to samples whose cwd resolves to this project key. */
+    project?: string;
 }

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

@@ -0,0 +1,36 @@
+/**
+ * Definition-vs-reality checks for `agents projects`.
+ *
+ * A project definition is hand-editable YAML that nothing validates against the
+ * world it describes, so it can drift into being confidently wrong. The one that
+ * bit for real: `repo:` said `<user>/agents-cli` while the checkout's `origin`
+ * was `phnx-labs/agents-cli`. Both are real repositories, so nothing errored —
+ * the card's merged-PR and release lines simply reported a stranger's repo (0
+ * merges in 7 days instead of 100). A wrong answer that looks like a right one
+ * is worse than a missing one, so the mismatch gets said out loud wherever the
+ * def is shown.
+ *
+ * Findings carry their own fix, mirroring `DoctorFinding.remediation`
+ * (`lib/devices/doctor-findings.ts`) — a warning the reader has to go work out
+ * how to act on is half a warning. Pure: the caller supplies the observed
+ * remote, so this is unit-testable with no git and no fixture repo.
+ */
+import type { ProjectDef } from './projects.js';
+/** A definition that disagrees with the machine it describes. */
+export interface ProjectFinding {
+    project: string;
+    /** One line naming the disagreement, both sides quoted. */
+    message: string;
+    /** The exact command that fixes it. */
+    remediation: string;
+}
+/**
+ * Compare a def's `repo` slug against the checkout's real `origin` remote.
+ *
+ * - remote unreadable (no checkout on this machine, not a git repo) → no
+ *   finding. The def may be perfectly right; this machine just can't say.
+ * - def has no `repo` → a finding only when a remote exists to adopt, so the
+ *   fix is a real one-liner rather than a nag.
+ * - they disagree → a finding. This is the case that silently lies.
+ */
+export declare function checkRepoSlug(def: ProjectDef, actualRemote: string | undefined): ProjectFinding | undefined;

package/dist/lib/project-doctor.js

@@ -0,0 +1,45 @@
+/**
+ * Definition-vs-reality checks for `agents projects`.
+ *
+ * A project definition is hand-editable YAML that nothing validates against the
+ * world it describes, so it can drift into being confidently wrong. The one that
+ * bit for real: `repo:` said `<user>/agents-cli` while the checkout's `origin`
+ * was `phnx-labs/agents-cli`. Both are real repositories, so nothing errored —
+ * the card's merged-PR and release lines simply reported a stranger's repo (0
+ * merges in 7 days instead of 100). A wrong answer that looks like a right one
+ * is worse than a missing one, so the mismatch gets said out loud wherever the
+ * def is shown.
+ *
+ * Findings carry their own fix, mirroring `DoctorFinding.remediation`
+ * (`lib/devices/doctor-findings.ts`) — a warning the reader has to go work out
+ * how to act on is half a warning. Pure: the caller supplies the observed
+ * remote, so this is unit-testable with no git and no fixture repo.
+ */
+/**
+ * Compare a def's `repo` slug against the checkout's real `origin` remote.
+ *
+ * - remote unreadable (no checkout on this machine, not a git repo) → no
+ *   finding. The def may be perfectly right; this machine just can't say.
+ * - def has no `repo` → a finding only when a remote exists to adopt, so the
+ *   fix is a real one-liner rather than a nag.
+ * - they disagree → a finding. This is the case that silently lies.
+ */
+export function checkRepoSlug(def, actualRemote) {
+    if (!actualRemote)
+        return undefined;
+    if (def.repo === actualRemote)
+        return undefined;
+    const fix = `agents projects set ${def.name} --repo ${actualRemote}`;
+    if (!def.repo) {
+        return {
+            project: def.name,
+            message: `no repo set; origin is ${actualRemote}`,
+            remediation: fix,
+        };
+    }
+    return {
+        project: def.name,
+        message: `repo is ${def.repo} but origin is ${actualRemote} — PR and release counts are being read from the wrong repository`,
+        remediation: fix,
+    };
+}

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

@@ -63,8 +63,18 @@ export declare function validateImportOpts(flags: RawImportFlags): ImportOptions
  * `repoSlug`→`repo`, `linearProjectId`→`linear.projectId`), now gated on the
  * row's `confidence`. A row with no confidence field is a guess with no stated
  * strength, so it ranks below every floor and only `--all` takes it.
+ *
+ * `resolveRemote` reads the checkout's actual `origin` and OVERRIDES the row's
+ * `repoSlug`. Factory derives that slug from the checkout path's last two
+ * segments (`apps/factory/src/core/projectIndex.ts:19-26`), which is only right
+ * when the directory tree happens to mirror the GitHub org. It commonly does
+ * not: a checkout at `~/src/github.com/<you>/agents-cli` whose remote is
+ * `phnx-labs/agents-cli` imported as `<you>/agents-cli` — a real, different
+ * repo — so the card's merged-PR and release lines silently reported a
+ * stranger's repository instead of failing. The remote is the only authority on
+ * which repo a checkout is; the path is a guess about it.
  */
-export declare function buildFactoryImportCandidates(rows: unknown[], existing: Map<string, ProjectDef>, opts: Pick<ImportOptions, 'minConfidence' | 'force'>): ImportPlan;
+export declare function buildFactoryImportCandidates(rows: unknown[], existing: Map<string, ProjectDef>, opts: Pick<ImportOptions, 'minConfidence' | 'force'>, resolveRemote?: (root: string) => string | undefined): ImportPlan;
 /**
  * Turn a Linear project name into a definition slug: lowercase, every run of
  * unusable characters collapsed to one `-`, trimmed of leading/trailing

package/dist/lib/project-import.js

@@ -60,8 +60,18 @@ export function validateImportOpts(flags) {
  * `repoSlug`→`repo`, `linearProjectId`→`linear.projectId`), now gated on the
  * row's `confidence`. A row with no confidence field is a guess with no stated
  * strength, so it ranks below every floor and only `--all` takes it.
+ *
+ * `resolveRemote` reads the checkout's actual `origin` and OVERRIDES the row's
+ * `repoSlug`. Factory derives that slug from the checkout path's last two
+ * segments (`apps/factory/src/core/projectIndex.ts:19-26`), which is only right
+ * when the directory tree happens to mirror the GitHub org. It commonly does
+ * not: a checkout at `~/src/github.com/<you>/agents-cli` whose remote is
+ * `phnx-labs/agents-cli` imported as `<you>/agents-cli` — a real, different
+ * repo — so the card's merged-PR and release lines silently reported a
+ * stranger's repository instead of failing. The remote is the only authority on
+ * which repo a checkout is; the path is a guess about it.
  */
-export function buildFactoryImportCandidates(rows, existing, opts) {
+export function buildFactoryImportCandidates(rows, existing, opts, resolveRemote = () => undefined) {
     const floor = CONFIDENCE_RANK[opts.minConfidence];
     const defs = [];
     const skipped = [];
@@ -97,8 +107,12 @@ export function buildFactoryImportCandidates(rows, existing, opts) {
         const def = { name };
         if (typeof o.path === 'string')
             def.root = toHomeRelative(o.path);
-        if (typeof o.repoSlug === 'string')
-            def.repo = o.repoSlug;
+        // The checkout's own remote wins over the registry's path-derived guess;
+        // the guess is the fallback for a path with no git remote to ask.
+        const fromRemote = typeof o.path === 'string' ? resolveRemote(o.path) : undefined;
+        const repo = fromRemote ?? (typeof o.repoSlug === 'string' ? o.repoSlug : undefined);
+        if (repo)
+            def.repo = repo;
         if (typeof o.linearProjectId === 'string')
             def.linear = { projectId: o.linearProjectId };
         defs.push(def);

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

@@ -54,11 +54,25 @@ export interface ProjectSessionRollup {
  * with the full definition list to show zero-agent projects.
  */
 export declare function rollupSessionsByProject(defs: ProjectDef[], sessions: ActiveSession[]): Map<string, ProjectSessionRollup>;
-/** Plan completion percentage (0–100), or undefined when nothing is tracked. */
-export declare function planPct(plan: {
-    done: number;
-    total: number;
-}): number | undefined;
+/** Live vs finished sessions on a project. */
+export interface LiveDeadSplit {
+    live: number;
+    dead: number;
+    /** Dead broken out by status, for the card's parenthetical. */
+    deadByStatus: Array<{
+        status: string;
+        n: number;
+    }>;
+}
+/**
+ * Split a rollup's sessions into what is working and what is wreckage.
+ *
+ * The headline used to be the raw session count, which on a real project read
+ * `39 agents` when 19 of those had crashed. A count that is half corpses is not
+ * a throughput signal — but the corpses are worth their own number, because 19
+ * crashed sessions is itself a thing to go fix.
+ */
+export declare function liveDeadSplit(byStatus: Partial<Record<ActiveStatus, number>>): LiveDeadSplit;
 /** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
 export declare function sortProjectMembers(members: ProjectMember[]): ProjectMember[];
 /** Cap for the members line before it collapses to `+N more`. */
@@ -77,6 +91,12 @@ export interface ProjectRemoteSignals {
     windowDays: number;
     /** PRs merged into the primary repo within the window (via `gh`). */
     mergedPrs: number;
+    /**
+     * True when the `gh` fetch cap cut the count short — `mergedPrs` is then a
+     * LOWER bound (rendered `100+`), never presented as the complete count. Same
+     * contract `LinearProjectCounts.truncated` keeps for the Linear line.
+     */
+    mergedPrsTruncated?: boolean;
     /** Artifacts agents produced within the window (activity.created milestones). */
     artifacts: number;
     /** Basename of the most recent artifact, when any. */

package/dist/lib/project-status.js

@@ -17,6 +17,13 @@ import chalk from 'chalk';
 import { projectNameForCwd } from './projects.js';
 import { readRecentActivity } from './activity.js';
 const execFileAsync = promisify(execFile);
+/**
+ * How many recent merges `gh` is asked for. A repo busy enough that all of them
+ * land inside the window has more than this — agents-cli itself merged 100 of
+ * its 100 most recent PRs within 7 days — so the count is reported as a lower
+ * bound rather than as a total.
+ */
+const MERGED_PR_LIMIT = 100;
 function blank(name) {
     return {
         name,
@@ -77,11 +84,40 @@ export function rollupSessionsByProject(defs, sessions) {
     }
     return map;
 }
-/** Plan completion percentage (0–100), or undefined when nothing is tracked. */
-export function planPct(plan) {
-    if (plan.total <= 0)
-        return undefined;
-    return Math.round((plan.done / plan.total) * 100);
+/**
+ * Statuses that mean the session is over. Taken from the repo's own rule
+ * (`commands/sessions.ts`): "`closed` and `crashed` are unconditionally dead".
+ * `orphaned` is NOT among them — `session/active.ts` defines it as "Alive, but
+ * no client is attached", i.e. the agent outlived its window and is still
+ * working. Counting it as dead understates the project by exactly the sessions
+ * that are running unattended.
+ */
+const DEAD_STATUSES = new Set(['closed', 'crashed']);
+/**
+ * Split a rollup's sessions into what is working and what is wreckage.
+ *
+ * The headline used to be the raw session count, which on a real project read
+ * `39 agents` when 19 of those had crashed. A count that is half corpses is not
+ * a throughput signal — but the corpses are worth their own number, because 19
+ * crashed sessions is itself a thing to go fix.
+ */
+export function liveDeadSplit(byStatus) {
+    let live = 0;
+    let dead = 0;
+    const deadByStatus = [];
+    for (const [status, n] of Object.entries(byStatus)) {
+        if (!n)
+            continue;
+        if (DEAD_STATUSES.has(status)) {
+            dead += n;
+            deadByStatus.push({ status, n });
+        }
+        else {
+            live += n;
+        }
+    }
+    deadByStatus.sort((a, b) => b.n - a.n || a.status.localeCompare(b.status));
+    return { live, dead, deadByStatus };
 }
 /**
  * Display order for the members line: the states a human scans for first
@@ -158,9 +194,15 @@ export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
     }
     if (def.repo && !opts.skipRemote) {
         try {
-            const { stdout } = await execFileAsync('gh', ['pr', 'list', '--repo', def.repo, '--state', 'merged', '--json', 'number,mergedAt', '--limit', '100'], { timeout: 8000, encoding: 'utf8' });
+            const { stdout } = await execFileAsync('gh', ['pr', 'list', '--repo', def.repo, '--state', 'merged', '--json', 'number,mergedAt', '--limit', String(MERGED_PR_LIMIT)], { timeout: 8000, encoding: 'utf8' });
             const rows = JSON.parse(stdout);
             out.mergedPrs = rows.filter((r) => r.mergedAt && Date.parse(r.mergedAt) >= sinceMs).length;
+            // `--limit 100` caps the fetch, so a busy repo where every one of the 100
+            // most recent merges falls inside the window has MORE than 100 — this repo
+            // really does. Say so (`100+`) rather than presenting a cap as a count,
+            // the same contract `LinearProjectCounts.truncated` already keeps.
+            if (rows.length >= MERGED_PR_LIMIT && out.mergedPrs >= MERGED_PR_LIMIT)
+                out.mergedPrsTruncated = true;
         }
         catch {
             /* gh missing / unauthenticated / repo not found — skip this signal */

package/dist/lib/rotate.d.ts

@@ -24,6 +24,15 @@ export interface RotateCandidate {
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
     usageError: string | null;
+    /**
+     * Projected minutes until this account's 5-hour session window caps, as
+     * computed by the daemon's burn-rate refresher and read from the headroom
+     * cache. `null` when unknown (cold cache, idle, or not burning up). Balanced
+     * routing deprioritizes an account projected to cap soon — see
+     * {@link capacityWeight} — so a launch avoids an account racing toward its
+     * limit, not just one already 100%-maxed.
+     */
+    usageMinutesToLimit: number | null;
     plan: string | null;
     signedIn: boolean;
     lastActive: Date | null;
@@ -141,6 +150,24 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  * version so behavior stays predictable.
  */
 export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export declare const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export declare function capacityWeight(usedPercent: number | null, minutesToLimit: number | null): number;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most

package/dist/lib/rotate.js

@@ -12,6 +12,7 @@ import { listInstalledVersions, getVersionHomePath, resolveVersion } from './ver
 import { getProjectRunConfigs } from './run-config.js';
 import { emit } from './events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
+import { readAccountHeadroom } from './fleet-cache.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -264,20 +265,37 @@ function preferVerified(pool, nowMs, choose) {
         usageUnverified: verified.length === 0,
     };
 }
+/**
+ * How far from its projected cap an account must be to keep its FULL headroom
+ * weight. Inside this horizon the weight is scaled down linearly toward the
+ * floor, so an account racing toward its 5h cap loses priority before it maxes.
+ */
+export const PROJECTION_HORIZON_MIN = 30;
+/**
+ * Weight one candidate by remaining routing capacity, deprioritized by how soon
+ * it is projected to cap. The base is weekly headroom (`max(1, 100 - used)`);
+ * an account with no live snapshot is treated as full-capacity (100) since there
+ * is no signal to deprioritize it. `minutesToLimit` (the daemon's burn-rate
+ * projection on the 5h session window) then scales that base: >= horizon (or
+ * unknown) keeps full weight, and closer-to-cap scales toward the floor of 1 —
+ * so a launch avoids an account projected to cap soon, not just a 100%-maxed
+ * one. Pure + exported so the deprioritization is unit-tested directly (a
+ * weighted-random draw is not).
+ */
+export function capacityWeight(usedPercent, minutesToLimit) {
+    const base = usedPercent === null ? 100 : Math.max(1, 100 - usedPercent);
+    if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
+        return base;
+    const factor = Math.max(0, Math.min(1, minutesToLimit / PROJECTION_HORIZON_MIN));
+    return Math.max(1, base * factor);
+}
 /**
  * Pick one candidate from `sorted` using weights proportional to remaining
- * routing capacity. Floor each weight at 1 so a near-exhausted-but-still-
- * eligible candidate can still be picked occasionally. When usage is unknown
- * (no live snapshot), treat the candidate as full-capacity (weight 100) — we
- * have no signal to deprioritize it.
+ * routing capacity (see {@link capacityWeight}). Floor each weight at 1 so a
+ * near-exhausted-but-still-eligible candidate can still be picked occasionally.
  */
 function weightedRandomByCapacity(sorted) {
-    const weights = sorted.map((c) => {
-        const used = getRoutingUsedPercent(c.usageSnapshot);
-        if (used === null)
-            return 100;
-        return Math.max(1, 100 - used);
-    });
+    const weights = sorted.map((c) => capacityWeight(getRoutingUsedPercent(c.usageSnapshot), c.usageMinutesToLimit));
     const total = weights.reduce((sum, w) => sum + w, 0);
     if (total <= 0)
         return sorted[0];
@@ -350,26 +368,35 @@ export async function collectRunCandidates(agent) {
             lastActive: info.lastActive,
         };
     }));
-    // These candidates feed a routing decision, so cap how stale their usage may
-    // be (see USAGE_DECISION_MAX_AGE_MS). Past that the fetch blocks on a live
-    // read instead of serving the cache — one bounded, parallel round trip per
-    // account, and none at all inside the 2-minute fresh window that back-to-back
-    // launches hit. A failed read still falls back to the cache; the pick then
-    // routes around it via isUsageVerified rather than trusting the old number.
+    // These candidates feed a routing decision on the `agents run` hot path, so
+    // this read is CACHE-ONLY (`readOnly`): it never blocks on a live provider
+    // fetch. A snapshot older than USAGE_DECISION_MAX_AGE_MS is not trusted for
+    // the pick — but the guard that enforces that is `isUsageVerified` below, not
+    // a blocking refresh here. Keeping the cache fresh is the daemon's job
+    // (`runUsageRefresh`, adaptive + rate-capped, sole-writer per local account),
+    // so a cold `agents run` reads the last daemon-written snapshot instead of
+    // stalling on N parallel HTTP round trips (the measured cold-start stall this
+    // removes). A stale-or-absent snapshot routes as unverified, exactly as a
+    // failed live read did before.
     const { usageByKey } = await getUsageInfoByIdentity(rows.map(({ home, info, version }) => ({
         agentId: agent,
         home,
         cliVersion: version,
         info,
-    })), { maxAgeMs: USAGE_DECISION_MAX_AGE_MS });
+    })), { readOnly: true });
     return rows.map(({ home: _home, info, ...candidate }) => {
         const usageKey = getUsageLookupKey(info);
         const usage = usageKey ? usageByKey.get(usageKey) : undefined;
+        // Projected headroom is a separate cache-only read (also off the network) —
+        // the daemon publishes minutesToLimit; a cold cache yields null and routing
+        // falls back to snapshot-only weighting.
+        const headroom = usageKey ? readAccountHeadroom(usageKey) : null;
         return {
             ...candidate,
             usageKey,
             usageSnapshot: usage?.snapshot ?? null,
             usageError: usage?.error ?? null,
+            usageMinutesToLimit: headroom?.minutesToLimit ?? null,
         };
     });
 }

package/dist/lib/routines.d.ts

@@ -504,6 +504,22 @@ export declare function getLatestRun(jobName: string): RunMeta | null;
  * run's prompt.
  */
 export declare function getLatestCompletedRun(jobName: string): RunMeta | null;
+/** Duration + outcome rollup for a job's run history. */
+export interface RoutineStats {
+    /** Total run records (any status, including `missed`). */
+    count: number;
+    failed: number;
+    missed: number;
+    avgMs: number;
+    p50: number;
+    p95: number;
+}
+/**
+ * Fold a job's run history (`listRuns`) into a duration + outcome summary.
+ * `missed` fires (no process ever ran) carry no `duration` and are excluded
+ * from the latency percentiles but still counted in `count`/`missed`.
+ */
+export declare function routineStats(jobName: string): RoutineStats;
 /** Persist run metadata to its run directory as meta.json. */
 export declare function writeRunMeta(meta: RunMeta): void;
 /** Read run metadata from disk. Returns null if missing or corrupt. */