@phnx-labs/agents-cli 1.22.59 → 1.22.61

package/dist/lib/harness-connection-test.js

@@ -0,0 +1,80 @@
+/**
+ * Pre-save connection test for a custom harness (PHNX-2221).
+ *
+ * A harness binds a (host CLI + model + endpoint + auth) — but none of that is
+ * exercised until the first real run, so a typo in the base URL, a wrong account,
+ * or a model id the endpoint doesn't serve only surfaces later. This module runs
+ * a genuine minimal request through the SAME resolution path a real run takes —
+ * `agents run <name> "say alive in one word" --headless --timeout 60s`, which
+ * flows `resolveProfileForRun` → `resolveProfileEnv` (keychain/account read) →
+ * `buildExecEnv` → spawn — and classifies the result so the user learns it works
+ * (or exactly why it doesn't) before committing the harness.
+ *
+ * There is no mock or dry-run: the profile must already be on disk (the caller
+ * writes it first) because the test drives the real `agents run` argv. The
+ * classifier is a pure function over the child's exit code + combined output, so
+ * it is unit-tested against real stderr samples with no spawn.
+ */
+import { spawnSync } from 'node:child_process';
+import { getCliLaunch } from './cli-entry.js';
+/** The prompt the smoke test sends — cheap, deterministic, one token of output. */
+export const CONNECTION_TEST_PROMPT = 'say alive in one word';
+/**
+ * Classify a finished `agents run` smoke test from its exit code and combined
+ * stdout+stderr. Pure — no spawn — so the mapping (pass / auth / endpoint /
+ * model / unknown) is unit-tested against real provider error strings.
+ *
+ * Exit 0 is a pass. Otherwise the output is matched against provider-error
+ * shapes in priority order: an auth rejection (401 / invalid key) is the most
+ * specific, then a model-not-served error, then a transport/DNS failure; a
+ * failure that matches none is `unknown` (the run failed but not in a way we can
+ * name — surfaced verbatim, never swallowed).
+ */
+export function classifyConnectionOutput(exitCode, output) {
+    if (exitCode === 0)
+        return { ok: true, message: 'Connection test passed.' };
+    const text = output || '';
+    const firstLine = text.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    const detail = firstLine ? ` (${firstLine})` : '';
+    if (/\b401\b|unauthor|invalid[\s_-]?(x-)?api[\s_-]?key|authentication|invalid x-api-key|missing[\s_-]?api[\s_-]?key/i.test(text)) {
+        return { ok: false, reason: 'auth', message: `Authentication rejected — check the harness's account/key.${detail}` };
+    }
+    if (/model[^\n]{0,48}(not\s+found|not\s+exist|does\s+not\s+exist|unknown|invalid|unsupported|unavailable)|no\s+such\s+model|unknown\s+model|invalid\s+model|unrecognized\s+model/i.test(text)) {
+        return { ok: false, reason: 'model', message: `The endpoint did not accept that model id.${detail}` };
+    }
+    if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|EHOSTUNREACH|getaddrinfo|connection\s+refused|could\s+not\s+connect|unreachable|fetch\s+failed|socket\s+hang\s+up|network\s+error|dns|certificate|self[\s-]?signed/i.test(text)) {
+        return { ok: false, reason: 'endpoint', message: `The endpoint was unreachable — check the base URL.${detail}` };
+    }
+    return { ok: false, reason: 'unknown', message: `Run failed (exit ${exitCode ?? 'null'}).${detail}` };
+}
+/**
+ * Run the real connection test against an already-saved harness. Spawns the CLI
+ * itself (`getCliLaunch`, the one self-invocation primitive) with the same argv a
+ * user would type, and classifies the result. Never throws on a failed run — a
+ * failure is returned as a classified {@link ConnectionTestResult}; only a spawn
+ * that never produced an exit (killed by the wall-clock cap) reads as `endpoint`
+ * (the request hung).
+ */
+export async function runHarnessConnectionTest(name, opts = {}) {
+    const { command, args } = getCliLaunch([
+        'run',
+        name,
+        CONNECTION_TEST_PROMPT,
+        '--headless',
+        '--timeout',
+        opts.timeout ?? '60s',
+    ]);
+    const result = spawnSync(command, args, {
+        encoding: 'utf-8',
+        timeout: opts.killAfterMs ?? 90_000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.error && result.error.code === 'ETIMEDOUT') {
+        return { ok: false, reason: 'endpoint', message: 'The request hung past the timeout — the endpoint may be unreachable or wrong.' };
+    }
+    if (result.error) {
+        return { ok: false, reason: 'unknown', message: `Could not launch the test: ${result.error.message}` };
+    }
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+    return classifyConnectionOutput(result.status, output);
+}

package/dist/lib/heal.js

@@ -43,6 +43,7 @@ const KIND_TO_SELECTION = {
     permissions: 'permissions',
     subagents: 'subagents',
     plugins: 'plugins',
+    workflows: 'workflows',
 };
 function totalHealed(r) {
     return r.versions.reduce((n, v) => n + v.healed.length, 0);
@@ -173,9 +174,13 @@ function healVersion(agent, version, opts) {
                 result.skipped.push({ kind: row.kind, name: row.name, reason: 'drift' });
                 continue;
             }
-            if (row.kind === 'promptcuts')
-                continue; // not version-synced
-            if (row.kind === 'rules') {
+            // Rules (the composed instruction file) and knowledge memory (~/.agents/
+            // memory/ facts) are both repaired by a sync of this version: rules via the
+            // preset re-composition `selection.memory` drives, knowledge facts via the
+            // unconditional `syncMemoryToVersionHome` fan-out every sync runs. Setting
+            // the rules selection guarantees a sync executes, so a memory-fact drift is
+            // reconciled the same pass (PHNX-3504).
+            if (row.kind === 'rules' || row.kind === 'memory') {
                 selection.memory = 'all';
                 attempted.push({ kind: row.kind, name: row.name, was: row.status });
                 continue;

package/dist/lib/installations/shims.d.ts

@@ -88,6 +88,28 @@ export declare function createBrandShim(name: string): string;
 export declare function isBrandShim(filePath: string): boolean;
 /** Remove a brand's shim companions. Returns true if anything was removed. */
 export declare function removeBrandShim(name: string): boolean;
+/**
+ * The POSIX gh overload shim. Self-healing by construction: it resolves the real
+ * gh (first `gh` on PATH that is not this shims dir) and execs it directly whenever
+ * agents-cli is gone, the sentinel is already set (recursion), or the verb is
+ * anything but `pr checks` — so a leftover/orphaned shim can never break `gh`.
+ */
+export declare function generateGhOverloadShim(): string;
+/** True when the file is our gh overload shim (not a user's real gh). */
+export declare function isGhOverloadShim(filePath: string): boolean;
+/**
+ * Create/refresh the gh overload shim so a user's `gh pr checks` transparently
+ * escapes the GraphQL rate limit. POSIX only in v1 (Windows keeps native gh —
+ * resolving the real gh without recursion needs a separate `.cmd` design).
+ *
+ * Skips (returns null) when there is no real `gh` to overload — shadowing a
+ * non-existent binary would only turn a clean "command not found" into shim
+ * output. Never clobbers a non-shim `gh` a user placed in the shims dir. If a real
+ * gh later disappears, the shim itself fails loud with 127 rather than looping.
+ */
+export declare function ensureGhOverloadShim(): string | null;
+/** Remove the gh overload shim — real gh returns immediately. Called on uninstall. */
+export declare function removeGhOverloadShim(): boolean;
 /** Remove the shim(s) for an agent. */
 export declare function removeShim(agent: AgentId): boolean;
 /**

package/dist/lib/installations/shims.js

@@ -806,6 +806,110 @@ export function removeBrandShim(name) {
     }
     return removed;
 }
+// ── gh overload shim ────────────────────────────────────────────────────────
+// A transparent interceptor for the ONE thing that keeps rate-limiting the fleet:
+// agents' trained `gh pr checks`. It routes that (and only that) to REST via
+// `agents __gh`, and execs the real gh for everything else. Agents keep their
+// habit; we decide what it runs. See cli/src/lib/github/gh-overload.ts + PHNX-3501.
+const GH_OVERLOAD_MARKER = '# gh overload shim:';
+/**
+ * The POSIX gh overload shim. Self-healing by construction: it resolves the real
+ * gh (first `gh` on PATH that is not this shims dir) and execs it directly whenever
+ * agents-cli is gone, the sentinel is already set (recursion), or the verb is
+ * anything but `pr checks` — so a leftover/orphaned shim can never break `gh`.
+ */
+export function generateGhOverloadShim() {
+    const agentsBin = shellQuote(getAgentsBinForGeneratedShim());
+    const shimsDir = shellQuote(getShimsDir());
+    return `#!/bin/sh
+# Auto-generated by agents-cli - do not edit
+${GH_OVERLOAD_MARKER} routes 'gh pr checks' to REST via 'agents __gh' (GraphQL rate-limit escape)
+AGENTS_BIN=${agentsBin}
+SHIMS_DIR=${shimsDir}
+find_real_gh() {
+  _oldifs=$IFS; IFS=:
+  for _d in $PATH; do
+    [ "$_d" = "$SHIMS_DIR" ] && continue
+    if [ -x "$_d/gh" ]; then IFS=$_oldifs; printf '%s\\n' "$_d/gh"; return 0; fi
+  done
+  IFS=$_oldifs; return 1
+}
+REAL_GH=$(find_real_gh)
+# No real gh on PATH: fail loud like "command not found" (127). NEVER fall back to
+# the bare string 'gh' — on a gh-less box that resolves to THIS shim and loops.
+if [ -z "$REAL_GH" ]; then
+  echo "gh: not found (agents-cli gh overload: no real gh on PATH)" >&2
+  exit 127
+fi
+# Self-heal + recursion guard: agents-cli missing, or already inside the overload,
+# or any verb other than 'pr checks' -> just be plain gh. REAL_GH is always an
+# absolute path here, so this can never re-enter the shim.
+if [ -n "$AGENTS_GH_SHIM" ] || [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
+  exec "$REAL_GH" "$@"
+fi
+if [ "$1" = "pr" ] && [ "$2" = "checks" ]; then
+  AGENTS_GH_SHIM=1 exec "$AGENTS_BIN" __gh --real-gh "$REAL_GH" -- "$@"
+fi
+exec "$REAL_GH" "$@"
+`;
+}
+/** True when the file is our gh overload shim (not a user's real gh). */
+export function isGhOverloadShim(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8').slice(0, 300).includes(GH_OVERLOAD_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a REAL `gh` binary exists on PATH outside our shims dir. */
+function hasRealGhOnPath() {
+    const shimsDir = path.resolve(getShimsDir());
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+        if (!dir || path.resolve(dir) === shimsDir)
+            continue;
+        const candidate = path.join(dir, 'gh');
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            // not here / not executable — keep scanning
+        }
+    }
+    return false;
+}
+/**
+ * Create/refresh the gh overload shim so a user's `gh pr checks` transparently
+ * escapes the GraphQL rate limit. POSIX only in v1 (Windows keeps native gh —
+ * resolving the real gh without recursion needs a separate `.cmd` design).
+ *
+ * Skips (returns null) when there is no real `gh` to overload — shadowing a
+ * non-existent binary would only turn a clean "command not found" into shim
+ * output. Never clobbers a non-shim `gh` a user placed in the shims dir. If a real
+ * gh later disappears, the shim itself fails loud with 127 rather than looping.
+ */
+export function ensureGhOverloadShim() {
+    if (!shimTargetsFor(process.platform).bash)
+        return null;
+    if (!hasRealGhOnPath())
+        return null;
+    ensureAgentsDir();
+    const shimPath = path.join(getShimsDir(), 'gh');
+    if (fs.existsSync(shimPath) && !isGhOverloadShim(shimPath))
+        return null;
+    fs.writeFileSync(shimPath, generateGhOverloadShim(), { mode: 0o755 });
+    return shimPath;
+}
+/** Remove the gh overload shim — real gh returns immediately. Called on uninstall. */
+export function removeGhOverloadShim() {
+    const shimPath = path.join(getShimsDir(), 'gh');
+    if (fs.existsSync(shimPath) && isGhOverloadShim(shimPath)) {
+        fs.unlinkSync(shimPath);
+        return true;
+    }
+    return false;
+}
 /**
  * Generate a Windows `.cmd` launcher that delegates to `agents __shim <spec>`.
  * `spec` is the agent's cliCommand for the default-version shim, or

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

@@ -28,6 +28,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached, resolveLinearApiKey } from './linear-cache.js';
+import { reserveLinearRequest } from './linear-rate-limit.js';
 const LINEAR_API = 'https://api.linear.app/graphql';
 /** Overall budget across all pages — the card must never hang on Linear. */
 const TIMEOUT_MS = 8_000;
@@ -212,6 +213,13 @@ async function fetchLinearIssuesPage(projectId, after, signal) {
     const apiKey = resolveApiKey();
     if (!apiKey)
         return undefined;
+    // Proactive shared budget (PHNX-2310): every agent on this key spends from one
+    // hourly pool, so N concurrent drains can't collectively blow Linear's 2500/hr
+    // limit. When the pool is spent, skip the request — the accumulator serves the
+    // last good (stale) snapshot instead, exactly as it does on any other failure.
+    // This is the proactive complement to the reactive 429 backoff below.
+    if (!reserveLinearRequest(apiKey))
+        return undefined;
     // The declared-milestone list rides along on the FIRST page only — it does
     // not paginate, and re-requesting it per page would spend up to MAX_PAGES
     // copies of the same answer.

package/dist/lib/linear-rate-limit.d.ts

@@ -0,0 +1,26 @@
+/** One hour, the window Linear's request quota is measured over. */
+export declare const LINEAR_RATE_WINDOW_MS: number;
+/**
+ * The shared proactive budget, one key's requests per rolling hour. Deliberately
+ * under Linear's hard 2500/hr so it leaves headroom for a human using the key and
+ * absorbs the concurrent check-then-create overshoot (at most N-1 for N racing
+ * agents) without ever reaching a real 429.
+ */
+export declare const LINEAR_HOURLY_REQUEST_BUDGET = 2400;
+export declare function setLinearRateLimitDirForTest(dir: string | null): string | null;
+/**
+ * Count this key's requests inside the rolling window, sweeping elapsed stamp
+ * files as it goes (they can only accumulate at the rate requests are issued, and
+ * this is the one place that already lists them). Pure read otherwise.
+ */
+export declare function linearRequestsInWindow(apiKey: string, nowMs?: number): number;
+/**
+ * Try to reserve one Linear request against the shared hourly budget.
+ *
+ * Returns `true` and records the reservation when there is room, `false` when the
+ * budget is exhausted — the caller then serves the cache instead of spending a
+ * request that would 429. The write is a single empty file whose NAME carries the
+ * whole record, so a concurrent reserver can neither clobber it nor be clobbered
+ * by it.
+ */
+export declare function reserveLinearRequest(apiKey: string, nowMs?: number): boolean;

package/dist/lib/linear-rate-limit.js

@@ -0,0 +1,163 @@
+/**
+ * A shared, cross-process request budget for the Linear API — the proactive half
+ * of the frugality story `linear-cache.ts` started.
+ *
+ * Linear meters requests per API KEY at 2500/hr (complexity is 99.999% untouched,
+ * so requests are the only budget that binds — see `linear-cache.ts`). The
+ * failure this exists to stop: this box routinely runs ~13 agent sessions on ONE
+ * key, each a separate short-lived process, and nothing coordinated their
+ * spending. `linear-cache.ts` already caches reads and backs off AFTER a 429
+ * lands (`isRateLimited`/`noteRateLimited`), but that is reactive — by the time
+ * the 429 arrives the budget is already gone and every agent's status update is
+ * throttled fleet-wide (PHNX-2310). This adds the missing PROACTIVE gate: before
+ * a request goes out, it must fit inside a shared hourly budget, so the N agents
+ * degrade to serving the (stale) cache instead of collectively blowing the limit.
+ *
+ * ## The budget lives in the FILENAMES, and that is the whole design
+ *
+ * State is on disk, not in memory, because the spenders are separate processes.
+ * The obvious shape — one JSON document holding a counter — is read-modify-write,
+ * and without a lock two agents reserving at once both read the old count and let
+ * the lower write land last, silently under-counting. That is not theoretical
+ * here: the triggering condition is a burst of concurrent agents, which is
+ * exactly what a fleet drain issues. This is the same race `usage-backoff.ts`
+ * documents, and the answer is the same: no shared mutable document.
+ *
+ * Each reserved request is its own empty file, `<createdMs>.<pid>.<seq>`, and the
+ * count is `readdir().length` after elapsed files (older than the window) are
+ * swept. Two concurrent writers create two DIFFERENT files and neither can erase
+ * the other, so the count can only be under-read by an in-flight peer that has
+ * not yet created its file — never corrupted, and never over-counted. A sliding
+ * one-hour window of stamp files is a token bucket whose tokens refill as the
+ * oldest requests age out, with no lock on a path every reservation touches.
+ *
+ * The budget is set BELOW Linear's hard 2500/hr ({@link LINEAR_HOURLY_REQUEST_BUDGET}).
+ * Two reasons: it leaves headroom for a human running `projects status` by hand
+ * (the CLI is not the only caller of the key), and it absorbs the small
+ * check-then-create race — N agents reserving in the same instant can each read
+ * `count < budget` and all create, overshooting by at most (N-1). Bounding the
+ * budget under the real ceiling keeps that overshoot from ever reaching a real 429.
+ *
+ * State is per KEY (hashed, so the raw key never lands on disk), because the
+ * 2500/hr quota is per key: two different keys spend independently.
+ *
+ * Scope is per MACHINE. The state lives under `getCacheDir()`
+ * (`~/.agents/.cache/`), which is machine-local and NOT fleet-synced — so this
+ * budgets the many concurrent agent processes on one box against each other, the
+ * case that actually exhausted the key (~13 sessions on one machine). Two
+ * different boxes sharing the same key each keep their own budget, so their
+ * aggregate can still exceed 2500/hr; coordinating the budget across devices
+ * (a synced or served counter) is a known limitation, not yet built.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from './state.js';
+/** One hour, the window Linear's request quota is measured over. */
+export const LINEAR_RATE_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * The shared proactive budget, one key's requests per rolling hour. Deliberately
+ * under Linear's hard 2500/hr so it leaves headroom for a human using the key and
+ * absorbs the concurrent check-then-create overshoot (at most N-1 for N racing
+ * agents) without ever reaching a real 429.
+ */
+export const LINEAR_HOURLY_REQUEST_BUDGET = 2400;
+/**
+ * Test seam, mirroring `setUsageBackoffDirForTest`. The cache dir resolves `HOME`
+ * once at import time, so a test that swaps `process.env.HOME` afterwards would
+ * otherwise read and WRITE the developer's real cache and throttle their own
+ * Linear reads. Returns the previous value so a test can restore it.
+ */
+let rateLimitDirOverride = null;
+export function setLinearRateLimitDirForTest(dir) {
+    const prev = rateLimitDirOverride;
+    rateLimitDirOverride = dir;
+    return prev;
+}
+function rateLimitRoot() {
+    return rateLimitDirOverride ?? path.join(getCacheDir(), 'linear-rate-limit');
+}
+/**
+ * Per-key directory. The key is hashed so the raw credential never touches disk;
+ * a short hex prefix is collision-safe enough for the handful of keys one fleet
+ * uses and keeps the path short.
+ */
+function keyDir(apiKey) {
+    const hash = crypto.createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
+    return path.join(rateLimitRoot(), hash);
+}
+/** Parse `<createdMs>.<pid>.<seq>` back to its creation instant, or null if it is not one of ours. */
+function createdMsOf(name) {
+    const first = name.indexOf('.');
+    if (first <= 0)
+        return null;
+    const head = name.slice(0, first);
+    if (!/^\d+$/.test(head))
+        return null;
+    const n = Number(head);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Count this key's requests inside the rolling window, sweeping elapsed stamp
+ * files as it goes (they can only accumulate at the rate requests are issued, and
+ * this is the one place that already lists them). Pure read otherwise.
+ */
+export function linearRequestsInWindow(apiKey, nowMs = Date.now()) {
+    const dir = keyDir(apiKey);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return 0; // no directory yet — nothing spent
+    }
+    const cutoff = nowMs - LINEAR_RATE_WINDOW_MS;
+    let live = 0;
+    for (const name of names) {
+        const created = createdMsOf(name);
+        if (created === null)
+            continue;
+        if (created <= cutoff) {
+            try {
+                fs.rmSync(path.join(dir, name), { force: true });
+            }
+            catch {
+                /* another process may have swept it already */
+            }
+        }
+        else {
+            live++;
+        }
+    }
+    return live;
+}
+let reserveSeq = 0;
+/**
+ * Try to reserve one Linear request against the shared hourly budget.
+ *
+ * Returns `true` and records the reservation when there is room, `false` when the
+ * budget is exhausted — the caller then serves the cache instead of spending a
+ * request that would 429. The write is a single empty file whose NAME carries the
+ * whole record, so a concurrent reserver can neither clobber it nor be clobbered
+ * by it.
+ */
+export function reserveLinearRequest(apiKey, nowMs = Date.now()) {
+    if (linearRequestsInWindow(apiKey, nowMs) >= LINEAR_HOURLY_REQUEST_BUDGET)
+        return false;
+    const dir = keyDir(apiKey);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        // `<createdMs>.<pid>.<seq>`: pid separates processes, the in-process counter
+        // separates two reservations in the same millisecond, so the name is unique
+        // without a lock or a random token. Empty contents — the name is the record.
+        fs.writeFileSync(path.join(dir, `${nowMs}.${process.pid}.${reserveSeq++}`), '');
+        return true;
+    }
+    catch {
+        // An unwritable cache dir costs the cross-process budget, not correctness: if
+        // we cannot record the reservation we still let the request through rather
+        // than blocking a caller on a broken cache dir. The reactive 429 backoff in
+        // linear-cache.ts remains the backstop.
+        return true;
+    }
+}

package/dist/lib/mcp.d.ts

@@ -160,6 +160,15 @@ export declare function installMcpServers(agentId: AgentId, version: string, ver
  * Write an MCP server config to ~/.agents/mcp/.
  */
 export declare function writeMcpServerConfig(config: McpYamlConfig): string;
+/**
+ * True when MCP server `name` materialized in `agent`'s version home byte-matches
+ * the resolved SOURCE definition `source` — the content-drift predicate `agents
+ * doctor` uses. Parses the home's canonical MCP config for the harness (no
+ * `claude mcp add` shell-out — the on-disk file is parseable) and structurally
+ * compares command/args/env/url. Returns false when the server is absent from
+ * the home (surfaced as `missing`/`extra` at the name level, not here).
+ */
+export declare function mcpServerMatches(agent: AgentId, versionHome: string, name: string, source: McpYamlConfig): boolean;
 /**
  * Remove an MCP server config from ~/.agents/mcp/.
  */

package/dist/lib/mcp.js

@@ -16,7 +16,7 @@ import * as os from 'os';
 import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir, getUserAgentsDir } from './state.js';
 import { getBinaryPath, getVersionHomePath } from './installations/versions.js';
 import { IS_WINDOWS, execFileShellSpec } from './platform/index.js';
-import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath, stripJsonComments } from './agents.js';
+import { AGENTS, getMcpConfigPathForHome, getProjectMcpConfigPath, parseMcpConfig, stripJsonComments } from './agents.js';
 import { MCP_TARGETS, mcpWriteUnsupportedReason } from './mcp-registry.js';
 import { isCapable } from './capabilities.js';
 /**
@@ -814,6 +814,42 @@ export function writeMcpServerConfig(config) {
     fs.writeFileSync(filePath, content, 'utf-8');
     return filePath;
 }
+/**
+ * Canonical string form of an MCP server for a structural, format-agnostic
+ * compare: http servers by url; stdio servers by command + args (order
+ * significant) + env (key-sorted, so serialization order is not drift). Undefined
+ * / empty fields are dropped so `{args: []}` and `{}` compare equal.
+ */
+function mcpCanonical(entry) {
+    if (entry.url)
+        return JSON.stringify({ url: entry.url });
+    const env = entry.env && Object.keys(entry.env).length > 0
+        ? Object.fromEntries(Object.entries(entry.env).sort(([a], [b]) => a.localeCompare(b)))
+        : undefined;
+    return JSON.stringify({
+        command: entry.command,
+        args: entry.args && entry.args.length > 0 ? entry.args : undefined,
+        env,
+    });
+}
+/**
+ * True when MCP server `name` materialized in `agent`'s version home byte-matches
+ * the resolved SOURCE definition `source` — the content-drift predicate `agents
+ * doctor` uses. Parses the home's canonical MCP config for the harness (no
+ * `claude mcp add` shell-out — the on-disk file is parseable) and structurally
+ * compares command/args/env/url. Returns false when the server is absent from
+ * the home (surfaced as `missing`/`extra` at the name level, not here).
+ */
+export function mcpServerMatches(agent, versionHome, name, source) {
+    const homePath = getMcpConfigPathForHome(agent, versionHome);
+    const home = parseMcpConfig(agent, homePath)[name];
+    if (!home)
+        return false;
+    const sourceComparable = source.transport === 'http'
+        ? { url: source.url }
+        : { command: source.command, args: source.args, env: source.env };
+    return mcpCanonical(sourceComparable) === mcpCanonical(home);
+}
 /**
  * Remove an MCP server config from ~/.agents/mcp/.
  */

package/dist/lib/open-url.js

@@ -128,9 +128,11 @@ export async function resolveViewer(opts = {}) {
         return 'os';
     }
     if (profile.browser === 'arc') {
-        // Arc exposes no CDP page targets and crashes on tab creation, so it can be
-        // a configured profile but never a drivable viewer.
-        console.error(`[viewer] "${resolved}" is Arc, which cannot be driven — using the OS browser.`);
+        // agents browser can drive an attached Arc's existing tabs, but showing the
+        // user a page needs its OWN fresh tab, and Arc crashes on tab creation over
+        // CDP (Target.createTarget). So Arc is a fine automation profile but never a
+        // viewer — fall back to the OS browser for anything a human is meant to read.
+        console.error(`[viewer] "${resolved}" is Arc, which cannot open a new viewer tab — using the OS browser.`);
         return 'os';
     }
     if (!isProfileLaunchableHere(profile)) {

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

@@ -6,7 +6,7 @@
  */
 import Database from '../sqlite.js';
 import type { AggregateOptions, PerfAggregateRow } from './types.js';
-export type { AggregateOptions, PerfAggregateRow, PerfSample } from './types.js';
+export type { AggregateOptions, PerfAggregateRow, PerfPhaseStat, PerfSample } from './types.js';
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export declare const PERF_SCHEMA_VERSION = 1;

package/dist/lib/perf/db.js

@@ -12,6 +12,31 @@ import { localMachineId } from '../origin-machine.js';
 import { resolveProjectKey } from '../project-key.js';
 import { percentile } from '../percentile.js';
 import { resolveSpoolPath, shortSessionId, _resetPerfSpoolForTest } from './spool.js';
+/**
+ * Parse the `phases` map from a sample's meta_json. Fail-soft: a row with no
+ * meta_json, malformed JSON, or a non-numeric phase value contributes nothing
+ * rather than throwing (the warehouse must survive any writer's shape).
+ */
+function parsePhases(metaJson) {
+    if (!metaJson)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(metaJson);
+    }
+    catch {
+        return undefined;
+    }
+    const phases = parsed?.phases;
+    if (!phases || typeof phases !== 'object')
+        return undefined;
+    const out = {};
+    for (const [name, val] of Object.entries(phases)) {
+        if (typeof val === 'number' && Number.isFinite(val))
+            out[name] = val;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 export { recordSample, shortSessionId, resolveSpoolPath } from './spool.js';
 export { percentile } from '../percentile.js';
 export const PERF_SCHEMA_VERSION = 1;
@@ -222,7 +247,7 @@ export function aggregateSamples(opts = {}) {
         clauses.push('agent = ?');
         params.push(opts.agent);
     }
-    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd
+    const rows = db.prepare(`SELECT kind, label, duration_ms, cache, exit_code, status, cwd, meta_json
      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.
@@ -244,10 +269,21 @@ export function aggregateSamples(opts = {}) {
         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, blocks: 0, timeouts: 0 };
+            b = { kind: r.kind, label: r.label, durations: [], hits: 0, stale: 0, misses: 0, errors: 0, blocks: 0, timeouts: 0, phases: new Map() };
             map.set(key, b);
         }
         b.durations.push(Number(r.duration_ms));
+        const phases = parsePhases(r.meta_json);
+        if (phases) {
+            for (const [name, ms] of Object.entries(phases)) {
+                let arr = b.phases.get(name);
+                if (!arr) {
+                    arr = [];
+                    b.phases.set(name, arr);
+                }
+                arr.push(ms);
+            }
+        }
         if (r.cache === 'hit')
             b.hits++;
         else if (r.cache === 'stale-prefetch')
@@ -301,6 +337,21 @@ export function aggregateSamples(opts = {}) {
         }
         if (b.timeouts > 0)
             row.timeoutRate = Math.round((b.timeouts / n) * 1000) / 1000;
+        if (b.phases.size > 0) {
+            const phases = {};
+            for (const [name, durs] of b.phases) {
+                if (durs.length === 0)
+                    continue;
+                const ps = durs.slice().sort((a, c) => a - c);
+                phases[name] = {
+                    n: ps.length,
+                    p50Ms: Math.round(percentile(ps, 50)),
+                    p90Ms: Math.round(percentile(ps, 90)),
+                };
+            }
+            if (Object.keys(phases).length > 0)
+                row.phases = phases;
+        }
         if (opts.project)
             row.project = opts.project;
         out.push(row);