@phnx-labs/agents-cli 1.22.60 → 1.22.61

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/permissions.d.ts

@@ -347,3 +347,31 @@ export declare function saveDefaultPermissionSet(set: PermissionSet): {
     success: boolean;
     error?: string;
 };
+/**
+ * Harnesses whose native permission file carries a per-rule allow/deny list the
+ * writer emits verbatim, so `agents doctor` can verify a group's rules survived
+ * into the version home rule-for-rule. The compare is done in the harness's OWN
+ * native vocabulary (Cursor `Shell(...)`, Droid command arrays, …) — NOT
+ * canonical — because every target's canonical round-trip is lossy
+ * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
+ * would false-diff a correctly-synced home.
+ *
+ * Every other allowlist harness (codex/grok/kimi/kiro/antigravity/hermes/copilot)
+ * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
+ * approval, or a split/merged pattern — with no faithful per-group provenance, so
+ * doctor stays presence-only there and says so (`detail: 'format cannot verify
+ * content'`) rather than faking `ok`.
+ */
+export declare const PERMISSIONS_REPRESENTABLE: ReadonlySet<AgentId>;
+/**
+ * True when permission GROUP `groupName` is faithfully present in `agent`'s
+ * version home — every rule the group renders into that harness's native format
+ * is on disk. Only meaningful for {@link PERMISSIONS_REPRESENTABLE} agents (the
+ * caller keeps the lossy harnesses presence-only); returns true for a lossy
+ * harness or an empty/header group so the caller does not down-rank it.
+ *
+ * The expected rules are re-derived from the CURRENT source group every call
+ * (never a stored hash), so a rule edited/added in the source group surfaces as
+ * drift even though the group name is unchanged (PHNX-3504).
+ */
+export declare function permissionsGroupMatches(agent: AgentId, versionHome: string, groupName: string): boolean;

package/dist/lib/permissions.js

@@ -776,7 +776,16 @@ export function convertToGrokFormat(set) {
 }
 function canonicalToGrokRule(perm, action) {
     if (BLANKET_BASH_FORMS.has(perm)) {
-        return { action, tool: 'bash', pattern: '*' };
+        // Grok's `*` is a SINGLE-LEVEL wildcard, so a `pattern: '*'` bash rule does
+        // NOT auto-approve a multi-token command like `ssh host cmd` or `scp a b`
+        // (PHNX-3294 — verified: two boxes carrying the identical `pattern="*"` rule
+        // differed only by `[ui].permission_mode`, and only the always-approve box
+        // ran ssh without prompting). Grok's documented "bare prefix matches all
+        // invocations" idiom is a rule with NO `pattern` key — the true allow-all
+        // shell form, matching how kimi (bare `Bash`), droid (`*`) and claude
+        // express a blanket Bash grant. This reads back as `Bash(*)` via the
+        // registry's pattern-less path, so the round-trip is unchanged.
+        return { action, tool: 'bash' };
     }
     const parsed = parseCanonicalPattern(perm);
     if (!parsed)
@@ -1885,3 +1894,149 @@ export function saveDefaultPermissionSet(set) {
     set.name = DEFAULT_PERMISSION_SET_NAME;
     return savePermissionSet(set);
 }
+// ============================================================================
+// Content-drift check (agents doctor, PHNX-3504)
+// ============================================================================
+/**
+ * Harnesses whose native permission file carries a per-rule allow/deny list the
+ * writer emits verbatim, so `agents doctor` can verify a group's rules survived
+ * into the version home rule-for-rule. The compare is done in the harness's OWN
+ * native vocabulary (Cursor `Shell(...)`, Droid command arrays, …) — NOT
+ * canonical — because every target's canonical round-trip is lossy
+ * (`lossyBecause` in `permissions-registry.ts`), so a canonical subset check
+ * would false-diff a correctly-synced home.
+ *
+ * Every other allowlist harness (codex/grok/kimi/kiro/antigravity/hermes/copilot)
+ * stores a lossy projection — a sandbox flag, whole-tool gate, per-directory
+ * approval, or a split/merged pattern — with no faithful per-group provenance, so
+ * doctor stays presence-only there and says so (`detail: 'format cannot verify
+ * content'`) rather than faking `ok`.
+ */
+export const PERMISSIONS_REPRESENTABLE = new Set([
+    'claude',
+    'opencode',
+    'cursor',
+    'droid',
+    'openclaw',
+]);
+function toStringSet(v) {
+    return new Set(Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+}
+function readJsonFileSafe(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** allow/deny rule strings in `agent`'s NATIVE vocabulary from its version home. */
+function homeNativePermissionRules(agent, versionHome) {
+    const target = PERMISSION_TARGETS[agent];
+    if (!target)
+        return null;
+    const configPath = target.home(versionHome);
+    if (!fs.existsSync(configPath))
+        return null;
+    switch (agent) {
+        case 'claude':
+        case 'cursor': {
+            const c = readJsonFileSafe(configPath);
+            const perms = (c?.permissions ?? {});
+            return { allow: toStringSet(perms.allow), deny: toStringSet(perms.deny) };
+        }
+        case 'droid': {
+            const c = readJsonFileSafe(configPath);
+            return { allow: toStringSet(c?.commandAllowlist), deny: toStringSet(c?.commandDenylist) };
+        }
+        case 'openclaw': {
+            const c = readJsonFileSafe(configPath);
+            const tools = (c?.tools ?? {});
+            return { allow: toStringSet(tools.alsoAllow), deny: toStringSet(tools.deny) };
+        }
+        case 'opencode': {
+            let c = null;
+            try {
+                c = JSON.parse(stripJsonComments(fs.readFileSync(configPath, 'utf-8')));
+            }
+            catch {
+                return null;
+            }
+            const bash = (c?.permission?.bash ?? {});
+            const allow = new Set();
+            const deny = new Set();
+            for (const [pattern, action] of Object.entries(bash)) {
+                if (action === 'allow')
+                    allow.add(pattern);
+                else if (action === 'deny')
+                    deny.add(pattern);
+            }
+            return { allow, deny };
+        }
+        default:
+            return null;
+    }
+}
+/** allow/deny rule strings in `agent`'s NATIVE vocabulary the writer WOULD emit. */
+function expectedNativePermissionRules(agent, set) {
+    switch (agent) {
+        case 'claude': {
+            const c = convertToClaudeFormat(set);
+            return { allow: new Set(c.permissions.allow), deny: new Set(c.permissions.deny) };
+        }
+        case 'cursor': {
+            const c = convertToCursorFormat(set);
+            return { allow: new Set(c.permissions.allow), deny: new Set(c.permissions.deny ?? []) };
+        }
+        case 'droid': {
+            const c = convertToDroidFormat(set);
+            return { allow: new Set(c.commandAllowlist), deny: new Set(c.commandDenylist) };
+        }
+        case 'openclaw': {
+            const c = convertToOpenClawFormat(set);
+            return { allow: new Set(c.alsoAllow), deny: new Set(c.deny) };
+        }
+        case 'opencode': {
+            const c = convertToOpenCodeFormat(set);
+            const allow = new Set();
+            const deny = new Set();
+            for (const [pattern, action] of Object.entries(c.permission.bash)) {
+                if (action === 'allow')
+                    allow.add(pattern);
+                else if (action === 'deny')
+                    deny.add(pattern);
+            }
+            return { allow, deny };
+        }
+        default:
+            return { allow: new Set(), deny: new Set() };
+    }
+}
+/**
+ * True when permission GROUP `groupName` is faithfully present in `agent`'s
+ * version home — every rule the group renders into that harness's native format
+ * is on disk. Only meaningful for {@link PERMISSIONS_REPRESENTABLE} agents (the
+ * caller keeps the lossy harnesses presence-only); returns true for a lossy
+ * harness or an empty/header group so the caller does not down-rank it.
+ *
+ * The expected rules are re-derived from the CURRENT source group every call
+ * (never a stored hash), so a rule edited/added in the source group surfaces as
+ * drift even though the group name is unchanged (PHNX-3504).
+ */
+export function permissionsGroupMatches(agent, versionHome, groupName) {
+    if (!PERMISSIONS_REPRESENTABLE.has(agent))
+        return true;
+    const expected = expectedNativePermissionRules(agent, buildPermissionsFromGroups([groupName]));
+    if (expected.allow.size === 0 && expected.deny.size === 0)
+        return true; // header / empty group
+    const home = homeNativePermissionRules(agent, versionHome);
+    if (!home)
+        return false;
+    for (const r of expected.allow)
+        if (!home.allow.has(r))
+            return false;
+    for (const r of expected.deny)
+        if (!home.deny.has(r))
+            return false;
+    return true;
+}

package/dist/lib/refresh.js

@@ -20,7 +20,7 @@ import { readManifest, MANIFEST_FILENAME } from './manifest.js';
 import { getUserAgentsDir } from './state.js';
 import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './installations/versions.js';
 import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
-import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './installations/shims.js';
+import { ensureShimCurrent, ensureGhOverloadShim, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './installations/shims.js';
 import { parseHookManifest, registerHooksToSettings } from './hooks/install.js';
 import { isPromptCancelled } from './format.js';
 /**
@@ -240,6 +240,14 @@ export async function refresh(options = {}) {
         }
     }
     // 5. Auto-add shims to PATH
+    // Refresh the gh overload shim so `gh pr checks` escapes the GraphQL rate limit
+    // for every user, transparently (PHNX-3501). Idempotent; POSIX-only in v1.
+    try {
+        ensureGhOverloadShim();
+    }
+    catch {
+        // Never let a shim-write hiccup break sync — real gh stays fine without it.
+    }
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {