@phnx-labs/agents-cli 1.21.2 → 1.22.0

package/dist/lib/plugins.js

@@ -14,7 +14,7 @@ import * as yaml from 'yaml';
 import { execFileSync } from 'child_process';
 import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir, getSystemPluginsDir } from './state.js';
 import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
-import { assertSafeGitTransport } from './git.js';
+import { assertSafeGitTransport, resolveSnapshotSha } from './git.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
@@ -90,6 +90,13 @@ export function discoverPlugins(opts = {}) {
     return out;
 }
 export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user' }) {
+    // Every marketplace kind lays plugins out as `<repo>/plugins/<name>`, so the
+    // repo root is always the grandparent of pluginRoot — true for user
+    // (~/.agents), system (~/.agents/.system), each extra repo, and the project
+    // repo (<cwd>/.agents) alike. Deriving it here means every caller of
+    // buildDiscoveredPlugin (discoverPluginsInDir, inspectPluginCapabilities, …)
+    // gets provenance for free with no signature change.
+    const repoRoot = path.dirname(path.dirname(pluginRoot));
     return {
         name: manifest.name,
         root: pluginRoot,
@@ -107,6 +114,10 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         monitors: discoverPluginMonitors(pluginRoot),
         hasMcp: fs.existsSync(path.join(pluginRoot, '.mcp.json')),
         hasSettings: pluginHasNonPermissionSettings(pluginRoot),
+        repoRoot,
+        get snapshotSha() {
+            return resolveSnapshotSha(repoRoot);
+        },
     };
 }
 /**

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;
+    }
+}

package/dist/lib/redact.d.ts

@@ -1,6 +1,8 @@
 /**
  * Shared redaction helpers for text that may be exported or logged.
  */
+/** Remove terminal control sequences from untrusted text before storage or display. */
+export declare function sanitizeForTerminal(text: string): string;
 /**
  * Scrub secrets from `text`. Two passes: format-based patterns (above), then a
  * value-aware pass that masks any `knownValues` verbatim — a credential we

package/dist/lib/redact.js

@@ -20,9 +20,31 @@ const SECRET_PATTERNS = [
     [/\bxapp-[A-Za-z0-9-]{10,}\b/g, '[REDACTED_SLACK_TOKEN]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    // Headers frequently appear inside shell arguments. Consume a quoted header
+    // as one unit so cookie attributes after a space do not survive redaction.
+    [/(^|\s)(["'])(Cookie|Set-Cookie|Authorization|Proxy-Authorization)\s*:\s*.*?\2/gi, '$1$2$3: [REDACTED]$2'],
+    [/(^|\s)(["'])(Cookie|Set-Cookie|Authorization|Proxy-Authorization)\s*:\s*(?:(?!\2).)*$/gi, '$1$2$3: [REDACTED]'],
     [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
+    [/\b((?:Cookie|Set-Cookie)\s*:\s*)\S+/gi, '$1[REDACTED]'],
+    [/\b(Authorization\s*:\s*)(?!Bearer\s+\[REDACTED\])\S+(?:\s+\S+)?/gi, '$1[REDACTED]'],
+    // Structured secret fields can arrive as raw JSON output rather than an
+    // argument object, so the object walker alone is not sufficient.
+    [/(^[,{\s]|["'])([A-Z0-9_-]*(?:TOKEN|KEY|SECRET|PASSWORD|AUTHORIZATION|COOKIE)[A-Z0-9_-]*["']?\s*:\s*)(["'][^"']*["']|[^,}\]\s]+)/gim, '$1$2"[REDACTED]"'],
+    [/(\s--?(?:password|token|secret|api[_-]?key)(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s--user(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s-u\s+)(["']?)[^\s"']+\2/g, '$1[REDACTED]'],
+    [/(\s--proxy-user(?:=|\s+))(["']?)[^\s"']+\2/gi, '$1[REDACTED]'],
+    [/(\s-U\s+)(["']?)[^\s"']+\2/g, '$1[REDACTED]'],
+    [/(https?:\/\/)[^/\s:@]+:[^@\s/]+@/gi, '$1[REDACTED]@'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
+const TERMINAL_ESCAPE_REGEX = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x9d[^\x07\x9c]*(?:\x07|\x9c)|\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b[@-_]|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/** Remove terminal control sequences from untrusted text before storage or display. */
+export function sanitizeForTerminal(text) {
+    if (!text)
+        return text;
+    return text.replace(TERMINAL_ESCAPE_REGEX, '');
+}
 /** Env vars whose NAME marks their VALUE as a credential worth masking literally. */
 const SECRET_ENV_NAME = /(?:TOKEN|KEY|SECRET|PASSWORD)/i;
 /** Don't literal-mask trivially short values — they collide with ordinary text. */

package/dist/lib/remote-agents-json.d.ts

@@ -10,6 +10,8 @@ export interface RemoteAgentsJsonOptions<T> {
      * printing a line per offline box above its output. Never a silent drop.
      */
     quiet?: boolean;
+    /** Per-peer deadline. Long-running maintenance commands override 12 seconds. */
+    timeoutMs?: number;
 }
 export interface RemoteAgentsJsonParseResult<T> {
     items: T[];

package/dist/lib/remote-agents-json.js

@@ -32,7 +32,7 @@ export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     const inner = `${noFanoutEnv}=1 agents ${args.map(shellQuote).join(' ')}`;
     return `bash -lc ${shellQuote(inner)}`;
 }
-function sshCapture(target, remoteCmd) {
+function sshCapture(target, remoteCmd, timeoutMs) {
     assertValidSshTarget(target);
     return new Promise((resolve) => {
         const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
@@ -49,7 +49,7 @@ function sshCapture(target, remoteCmd) {
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
             done(null);
-        }, REMOTE_TIMEOUT_MS);
+        }, timeoutMs);
         child.stdout.on('data', (data) => { stdout += data.toString(); });
         child.on('error', () => done(null));
         child.on('close', (code) => done(code));
@@ -102,7 +102,7 @@ export async function gatherRemoteAgentsJson(options) {
     const parseFailed = [];
     const results = await Promise.all(targets.map(async (target) => {
         const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
-        const result = await sshCapture(target.target, command);
+        const result = await sshCapture(target.target, command, options.timeoutMs ?? REMOTE_TIMEOUT_MS);
         if (result.code !== 0) {
             skipped.push(target.name);
             if (!options.quiet) {

package/dist/lib/resources.d.ts

@@ -16,6 +16,22 @@ export interface ResolvedResource {
      * or the alias name (e.g. 'rush') for extra repos registered in agents.yaml.
      */
     source: string;
+    /**
+     * Absolute path to the DotAgents repo root this resource resolved from (the
+     * project/user/system/extra-repo dir — one level above the `kind`
+     * subdirectory). DotAgents repos are git-tracked (plugins.ts), so this pairs
+     * with {@link snapshotSha} to answer "which commit of which repo".
+     */
+    repoRoot: string;
+    /**
+     * Short HEAD sha of `repoRoot`'s git checkout, lazily resolved (a getter,
+     * not computed at construction) and memoized per repoRoot
+     * (`git.ts` `resolveSnapshotSha`) — a caller that never inspects provenance
+     * never pays for the git shell-out, and resolving many resources from the
+     * same repo pays for exactly one. `undefined` when `repoRoot` isn't a git
+     * repo (or has no commits).
+     */
+    readonly snapshotSha: string | undefined;
 }
 /**
  * True when `rawName` (a filename with its extension already stripped) names a

package/dist/lib/resources.js

@@ -15,6 +15,16 @@ import { WorkflowsHandler } from './resources/workflows.js';
 import { isCapable } from './capabilities.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
 import { isNameActiveInResourceProfile } from './resource-profiles.js';
+import { resolveSnapshotSha } from './git.js';
+/** Build a ResolvedResource with a lazy, memoized `snapshotSha` getter. */
+function withProvenance(base) {
+    return {
+        ...base,
+        get snapshotSha() {
+            return resolveSnapshotSha(base.repoRoot);
+        },
+    };
+}
 function profiledKind(kind) {
     switch (kind) {
         case 'commands':
@@ -70,19 +80,19 @@ export function resolveResource(kind, name, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const candidates = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of candidates) {
+    for (const [dir, source, repoRoot] of candidates) {
         if (!fs.existsSync(dir))
             continue;
         // Try exact name (for directories like skills/subagents)
         const exactPath = path.join(dir, name);
         if (fs.existsSync(exactPath)) {
             if (resourceIsActive(kind, name, source)) {
-                return { name, path: exactPath, source };
+                return withProvenance({ name, path: exactPath, source, repoRoot });
             }
             continue;
         }
@@ -94,7 +104,7 @@ export function resolveResource(kind, name, cwd) {
             const withExt = exactPath + ext;
             if (fs.existsSync(withExt)) {
                 if (resourceIsActive(kind, name, source)) {
-                    return { name, path: withExt, source };
+                    return withProvenance({ name, path: withExt, source, repoRoot });
                 }
                 continue;
             }
@@ -113,12 +123,12 @@ export function listResources(kind, cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
     const roots = [
-        ...(projectDir ? [[path.join(projectDir, kind), 'project']] : []),
-        [path.join(getUserAgentsDir(), kind), 'user'],
-        [path.join(getSystemAgentsDir(), kind), 'system'],
-        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias]),
+        ...(projectDir ? [[path.join(projectDir, kind), 'project', projectDir]] : []),
+        [path.join(getUserAgentsDir(), kind), 'user', getUserAgentsDir()],
+        [path.join(getSystemAgentsDir(), kind), 'system', getSystemAgentsDir()],
+        ...extraRepos.map((e) => [path.join(e.dir, kind), e.alias, e.dir]),
     ];
-    for (const [dir, source] of roots) {
+    for (const [dir, source, repoRoot] of roots) {
         if (!fs.existsSync(dir))
             continue;
         let entries;
@@ -143,11 +153,12 @@ export function listResources(kind, cwd) {
             if (!resourceIsActive(kind, rawName, source))
                 continue;
             seen.add(rawName);
-            results.push({
+            results.push(withProvenance({
                 name: rawName,
                 path: path.join(dir, entry.name),
                 source,
-            });
+                repoRoot,
+            }));
         }
     }
     return results;

package/dist/lib/rotate.d.ts

@@ -174,7 +174,81 @@ export declare function capacityWeight(usedPercent: number | null, minutesToLimi
  * usage headroom.
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number): RotateResult | null;
+/**
+ * Per-harness routing summary for `agents run auto` — the cross-harness layer
+ * that sits above `pickBalancedCandidate` (which is strictly per-harness).
+ */
+export interface HarnessSummary {
+    agent: AgentId;
+    /** Every installed account slot probed for this harness. */
+    candidates: RotateCandidate[];
+    /** Healthy accounts after identity dedupe, sorted by headroom. */
+    healthy: RotateCandidate[];
+    /** The account this harness would route to (best verified headroom). Null when the harness is excluded. */
+    best: RotateCandidate | null;
+    /** Routing used% of `best` (max across non-session windows); null when unknown. */
+    bestUsedPercent: number | null;
+    /** Why the harness was excluded, e.g. ['2 rate_limited', '1 signed_out']. Empty when healthy. */
+    exclusionReasons: string[];
+}
+export interface HarnessPickResult {
+    /** The harness picked for this run. */
+    picked: HarnessSummary;
+    /** Harnesses with ≥1 healthy account (including the picked one). */
+    healthy: HarnessSummary[];
+    /** Harnesses with zero healthy accounts — excluded, not down-weighted. */
+    excluded: HarnessSummary[];
+}
+/**
+ * Classify every harness's candidates into healthy (with a representative
+ * best account) vs excluded (with per-reason counts). Pure — the pick and the
+ * zero-healthy error message both read this, so they can never disagree.
+ *
+ * Health uses the exact account-layer gate (`isRotationEligible`: signed in
+ * AND not maxed on ANY blocking window, weekly included). The representative
+ * best account honors `preferVerified`: confirmed headroom beats apparent
+ * headroom, the same freshness rule the account layer routes on.
+ */
+export declare function classifyHarnessCandidates(byHarness: ReadonlyMap<AgentId, RotateCandidate[]>, nowMs?: number): HarnessSummary[];
+/**
+ * Pick a harness for `agents run auto` using weighted random by best-account
+ * headroom (RUSH-2132).
+ *
+ * A harness's capacity is `100 − min(routingUsed% across its healthy accounts)`
+ * — its best account's headroom. The pick reuses `weightedRandomByCapacity` on
+ * the representative best accounts, so host/harness/account layers all share
+ * one sampling behavior. Harnesses with zero healthy accounts are EXCLUDED,
+ * not down-weighted. Returns null when no harness has any healthy account;
+ * call `classifyHarnessCandidates` for the exclusion detail to message with.
+ */
+export declare function pickHarnessWeighted(byHarness: ReadonlyMap<AgentId, RotateCandidate[]>, nowMs?: number): HarnessPickResult | null;
+/** One-line banner naming the auto-picked harness and why (headroom). */
+export declare function formatHarnessPickBanner(result: HarnessPickResult): string;
+/**
+ * The earliest FUTURE window reset across these candidates' usage snapshots —
+ * when the first exhausted account becomes usable again. Null when no snapshot
+ * carries a reset timestamp.
+ */
+export declare function earliestResetAcross(candidates: RotateCandidate[], nowMs?: number): Date | null;
+/**
+ * The zero-healthy-account error (RUSH-2132). EXACT contract — the Factory
+ * watchdog tail-detects this text: it must contain the literal `no healthy`
+ * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
+ */
+export declare function formatNoHealthyAccountError(agent: AgentId, strategy: RunStrategy, excluded: RotateCandidate[], nowMs?: number): string;
+/**
+ * The zero-healthy-harness error for `agents run auto` — names each harness's
+ * exclusion reason plus the earliest reset across all snapshots.
+ */
+export declare function formatNoHealthyHarnessError(summaries: HarnessSummary[], nowMs?: number): string;
 export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
+/**
+ * Collect run candidates for every harness with ≥1 installed version — the
+ * probe `agents run auto` routes on (the same per-harness account probe
+ * `agents view` aggregates). Harnesses with nothing installed are absent from
+ * the map: not a candidate at all, rather than an excluded one.
+ */
+export declare function collectHarnessCandidates(agentIds?: AgentId[]): Promise<Map<AgentId, RotateCandidate[]>>;
 /**
  * Resolve an account identity to the installed version slot that holds it, over
  * an already-collected candidate list. Pure — no I/O — so it is unit-tested
@@ -207,9 +281,18 @@ export declare function resolveAccountVersion(agent: AgentId, account: string):
 export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
-export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{
+export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string, collect?: (agent: AgentId) => Promise<RotateCandidate[]>): Promise<{
     version: string | null;
     rotation: RotateResult | null;
+    /**
+     * Set when a non-pinned strategy found ZERO healthy candidates among the
+     * installed versions: the full excluded set, so callers fail loud with
+     * per-account reasons instead of launching the exhausted pinned default
+     * (RUSH-2132). Undefined for pinned, for successful picks, and when no
+     * version is installed at all (the pre-existing not-installed path — there
+     * is no account to be "unhealthy").
+     */
+    exhausted?: RotateCandidate[];
 }>;
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through