@phnx-labs/agents-cli 1.22.75 → 1.22.77

package/dist/lib/hosts/ready.js

@@ -12,7 +12,8 @@ import { sshExec, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { remoteShellFor, buildWindowsAgentsCommand, encodePowershell, powershellQuote, POWERSHELL_PROGRESS_SILENCE } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
-import { isDeadVerdict } from '../auth-health.js';
+import { AUTH_PROBE_MAX_AGE_MS, isDeadVerdict } from '../auth-health.js';
+import { USAGE_STALE_REFUSAL_MAX_AGE_MS } from '../accounting/rotate.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
@@ -222,7 +223,7 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
  * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
  * pre-fix behavior, so a rolling fleet does not regress.
  */
-export function viewAgentAccountEligibility(view, agent) {
+export function viewAgentAccountEligibility(view, agent, now = Date.now()) {
     try {
         const rows = JSON.parse(view);
         const row = rows.find((candidate) => candidate.agent?.toLowerCase() === agent.toLowerCase());
@@ -234,11 +235,22 @@ export function viewAgentAccountEligibility(view, agent) {
             // Prefer the strict per-version launch signal; fall back to the display
             // `signedIn` for an older remote CLI that does not emit `launchable`.
             const launchable = typeof version.launchable === 'boolean' ? version.launchable : version.signedIn;
-            const throttled = version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits';
+            const usageCapturedAt = version.usageCapturedAt ? Date.parse(version.usageCapturedAt) : Number.NaN;
+            const usageFresh = Number.isFinite(usageCapturedAt)
+                ? now - usageCapturedAt <= USAGE_STALE_REFUSAL_MAX_AGE_MS
+                : version.usageCapturedAt === undefined;
+            const authFresh = typeof version.authCheckedAt === 'number'
+                ? now - version.authCheckedAt <= AUTH_PROBE_MAX_AGE_MS
+                : version.authCheckedAt === undefined;
+            const throttled = usageFresh
+                && (version.usageStatus === 'rate_limited' || version.usageStatus === 'out_of_credits');
             const authBlocked = version.authVerdict !== null
                 && version.authVerdict !== undefined
+                && authFresh
                 && isDeadVerdict(version.authVerdict);
-            const ready = launchable && !authBlocked && !throttled;
+            const freshnessKnown = version.usageCapturedAt !== undefined || version.authCheckedAt !== undefined;
+            const fresh = !freshnessKnown || (usageFresh && authFresh);
+            const ready = launchable && fresh && !authBlocked && !throttled;
             return [{ ready, pickerEligible: ready || !launchable || authBlocked }];
         });
         if (verdicts.length === 0)

package/dist/lib/hosts/reconnect.js

@@ -81,7 +81,9 @@ export function formatDuration(ms) {
 export function reconnectNotice(target, host, attempt, waitMs, remainingMs) {
     const secs = Math.round(waitMs / 1000);
     const when = secs <= 1 ? 'now' : `in ${secs}s`;
-    return `\nConnection to ${host} dropped — ${targetLabel(target)} is still running there.`
+    // A tmux-wrapped run is still live; a bare run was SIGHUPed and focus will
+    // resume it from disk. This wording is truthful for either peer configuration.
+    return `\nConnection to ${host} dropped — reconnecting to ${targetLabel(target)}.`
         + `\n  Reconnecting ${when} · ${formatDuration(remainingMs)} left · attempt ${attempt} · Ctrl-C to stop\n`;
 }
 /** Notice shown once the retry budget is spent on an unreachable host. */
@@ -99,7 +101,7 @@ export function remoteExitNotice(target, host) {
 }
 /** Notice shown when the user stops the wait with Ctrl-C. */
 export function interruptedNotice(target, host) {
-    return `\nStopped reconnecting. ${targetLabel(target)} is still running on ${host}:\n${recoveryHint(target, host)}`;
+    return `\nStopped reconnecting to ${targetLabel(target)} on ${host}. Recover it when the link is stable:\n${recoveryHint(target, host)}`;
 }
 /**
  * Wrap `cmd` in `bash -lc` with an exit-code remap: 255 becomes

package/dist/lib/identity/client.d.ts

@@ -30,6 +30,12 @@ export interface PhoenixSession {
     access_token: string;
     email?: string;
     userId?: string;
+    /**
+     * Hosted OAuth profile image (https URL), when Phoenix ID exposes one. Wins
+     * over the email-Gravatar fallback in share attribution. Optional forever —
+     * a missing value just means the Gravatar/initials fallback.
+     */
+    avatarUrl?: string;
     /** Unix ms; absent means the server did not scope the token's lifetime. */
     expires_at?: number;
 }

package/dist/lib/identity/index.d.ts

@@ -16,6 +16,8 @@ export interface WhoAmI {
     userId: string;
     email: string;
     valid: true;
+    /** Hosted OAuth profile image, when Phoenix ID stores one for this user. */
+    avatar_url?: string;
 }
 /**
  * RFC 8628 poll outcomes. `pending` and `slow_down` are normal states of a
@@ -28,6 +30,10 @@ export type DevicePoll = {
     user: {
         email: string;
         id: string;
+        /** Hosted OAuth profile image, when the provider exposed one to Phoenix ID. */
+        avatar_url?: string;
+        /** Google-style alias some providers use for the same field. */
+        picture?: string;
     };
 } | {
     status: 'pending';
@@ -41,6 +47,16 @@ export type DevicePoll = {
 export declare function startDeviceAuthorization(): Promise<DeviceAuthorization>;
 export declare function pollDeviceToken(deviceCode: string): Promise<DevicePoll>;
 export declare function fetchWhoAmI(token?: string): Promise<WhoAmI>;
+/**
+ * Best-effort fill of the session's hosted avatar (PHNX-3547): sessions written
+ * before the CLI tracked avatars have none, so ask `/api/v1/auth/me` and merge
+ * a hosted `avatar_url` into the persisted session — future publishes then
+ * stamp the OAuth profile image instead of only a Gravatar hash. A no-op when
+ * signed out, when an avatar is already stored, or when the server exposes
+ * none; network/server failures are swallowed (the share attribution falls
+ * back to Gravatar/initials either way).
+ */
+export declare function refreshSessionAvatar(): Promise<void>;
 export interface SpaceSummary {
     id: string;
     slug: string;

package/dist/lib/identity/index.js

@@ -2,7 +2,7 @@
  * Phoenix ID — the typed surface commands use. Every route the account backend
  * exposes is a function here; no command builds a URL or reads a token itself.
  */
-import { phoenixRequest, PhoenixApiError } from './client.js';
+import { phoenixRequest, PhoenixApiError, readSession, writeSession } from './client.js';
 export { PHOENIX_ID_BASE, PhoenixApiError, clearSession, readSession, sessionFilePath, writeSession, } from './client.js';
 export function startDeviceAuthorization() {
     return phoenixRequest('POST', '/api/v1/auth/device/authorization', {
@@ -38,6 +38,30 @@ export async function pollDeviceToken(deviceCode) {
 export function fetchWhoAmI(token) {
     return phoenixRequest('GET', '/api/v1/auth/me', { token });
 }
+/**
+ * Best-effort fill of the session's hosted avatar (PHNX-3547): sessions written
+ * before the CLI tracked avatars have none, so ask `/api/v1/auth/me` and merge
+ * a hosted `avatar_url` into the persisted session — future publishes then
+ * stamp the OAuth profile image instead of only a Gravatar hash. A no-op when
+ * signed out, when an avatar is already stored, or when the server exposes
+ * none; network/server failures are swallowed (the share attribution falls
+ * back to Gravatar/initials either way).
+ */
+export async function refreshSessionAvatar() {
+    const session = readSession();
+    if (!session || session.avatarUrl)
+        return;
+    try {
+        const me = await fetchWhoAmI();
+        const hosted = me.avatar_url?.trim();
+        if (hosted && /^https:\/\//i.test(hosted)) {
+            writeSession({ ...session, avatarUrl: hosted });
+        }
+    }
+    catch {
+        // Offline or server without the field — the Gravatar fallback covers it.
+    }
+}
 export const listSpaces = () => phoenixRequest('GET', '/api/v1/spaces');
 export const createSpace = (input) => phoenixRequest('POST', '/api/v1/spaces', { body: input });
 export const getSpace = (id) => phoenixRequest('GET', `/api/v1/spaces/${encodeURIComponent(id)}`);

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

@@ -2,6 +2,16 @@
 export { foldLegacySystemRepo } from '../migrate-fold.js';
 /** Migrate a legacy single-repo agents.yaml into ~/.agents/agents.yaml. Leaves the tracked system-mirror copy alone to avoid dirtying the npm-shipped defaults. */
 export declare function migrateAgentsYaml(systemDir?: string, userDir?: string): void;
+/**
+ * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
+ * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
+ * file that upstream never carries it can only ever show as `M`/`??`
+ * — dirtying the tree and, when a peer's publish commit arrives, tripping the
+ * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
+ * uncommitted; never `.gitignore`, which would re-introduce the same failure).
+ * Idempotent: a no-op once the path is untracked and excluded.
+ */
+export declare function detrackUserChangelog(userDir?: string): void;
 /** Fold the legacy global browser/sessions/<task>/ tree into the per-profile browser/<profile>/sessions/<task>/ layout. Unclaimed tasks move under `_legacy`. */
 export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): void;
 /** Repair node_modules/.bin/<cli> symlinks that resolve back into our own shims dir (infinite exec-loop fix). */

package/dist/lib/installations/migrate.js

@@ -16,6 +16,7 @@ import { setConfigValue } from '../device-config.js';
 import { enabledRoutineNames, replaceEnabledRoutines } from '../routine-activation.js';
 import { evaluateActivationReadiness } from '../routine-readiness.js';
 import { migrateDeviceConfigStores } from '../devices/config-migration.js';
+import { detrackViaGitExclude } from '../project-resources.js';
 // Two constants only, never the read/write API — migrations still operate on raw
 // YAML so they never take the meta lock or prime the meta cache mid-migration.
 import { LEGACY_DEFAULT_BROWSER_PROFILE_NAME } from '../browser/profiles.js';
@@ -70,6 +71,22 @@ function deleteSystemPromptsJson() {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Stop tracking the user repo's CHANGELOG.md. It duplicates the npm-shipped
+ * `.system/CHANGELOG.md` (read the canonical copy from there), and as a tracked
+ * file that upstream never carries it can only ever show as `M`/`??`
+ * — dirtying the tree and, when a peer's publish commit arrives, tripping the
+ * dirty-tree pull guard. De-track it into `.git/info/exclude` (per-clone,
+ * uncommitted; never `.gitignore`, which would re-introduce the same failure).
+ * Idempotent: a no-op once the path is untracked and excluded.
+ */
+export function detrackUserChangelog(userDir = USER_DIR) {
+    if (!fs.existsSync(path.join(userDir, '.git')))
+        return; // plain dir, not a clone
+    const untracked = detrackViaGitExclude(userDir, 'CHANGELOG.md');
+    if (untracked)
+        console.error('Stopped tracking ~/.agents/CHANGELOG.md (duplicates .system/CHANGELOG.md)');
+}
 /** Delete the legacy ~/.agents-system/config.json (dead teams agent registry). */
 function migrateSystemConfigJson() {
     const src = path.join(SYSTEM_DIR, 'config.json');
@@ -2242,6 +2259,7 @@ export async function runMigration() {
     migrateHumans();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
+    detrackUserChangelog();
     migratePromptcutsIntoHooks();
     migrateSystemVersionsToUser();
     mergeOverlappingVersionHomes();

package/dist/lib/profiles.d.ts

@@ -177,6 +177,8 @@ export interface HostModelOptions {
 export declare function profileFromHostModel(name: string, host: AgentId, model: string, opts?: HostModelOptions): Profile;
 /** Overrides applied on top of the source when forking a harness. */
 export interface ForkProfileOptions {
+    /** Translate the fork onto a different native harness host. */
+    host?: AgentId;
     /** Swap the pinned model. Written onto the source's model env key when it has
      *  one, else onto the host's canonical model var. */
     model?: string;

package/dist/lib/profiles.js

@@ -404,31 +404,50 @@ export function profileFromHostModel(name, host, model, opts = {}) {
  */
 export function forkProfile(source, name, opts = {}) {
     validateProfileName(name);
-    const host = source.host.agent;
+    const sourceHost = source.host.agent;
+    const host = opts.host ?? sourceHost;
     const env = { ...source.env };
-    if (opts.model) {
-        env[profileModelEnvKey(source) ?? modelEnvKeyForHost(host)] = opts.model;
+    const sourceModelKey = profileModelEnvKey(source) ?? modelEnvKeyForHost(sourceHost);
+    const targetModelKey = modelEnvKeyForHost(host);
+    const model = opts.model ?? env[sourceModelKey];
+    if (host !== sourceHost && sourceModelKey !== targetModelKey)
+        delete env[sourceModelKey];
+    if (model) {
+        env[targetModelKey] = model;
     }
-    if (opts.baseUrl) {
-        const key = baseUrlEnvKeyForHost(host);
+    const sourceBaseKey = baseUrlEnvKeyForHost(sourceHost);
+    const targetBaseKey = baseUrlEnvKeyForHost(host);
+    const baseUrl = opts.baseUrl ?? (sourceBaseKey ? env[sourceBaseKey] : undefined);
+    if (host !== sourceHost && sourceBaseKey && sourceBaseKey !== targetBaseKey)
+        delete env[sourceBaseKey];
+    if (baseUrl) {
+        const key = targetBaseKey;
         if (!key) {
             throw new Error(`Host '${host}' has no known base-URL env var; drop --base-url or fork onto a claude/codex host.`);
         }
-        env[key] = opts.baseUrl;
+        env[key] = baseUrl;
     }
     const forked = {
         ...source,
         name,
-        host: { agent: host, ...(opts.version ? { version: opts.version } : source.host.version ? { version: source.host.version } : {}) },
+        host: { agent: host, ...(opts.version ? { version: opts.version } : host === sourceHost && source.host.version ? { version: source.host.version } : {}) },
         env,
         // The source's description names the source's model, so inheriting it
         // across a model swap would describe the fork wrongly.
-        description: opts.description ?? (opts.model ? `Forked from ${source.name}: ${opts.model}` : source.description),
+        description: opts.description ?? (opts.model || host !== sourceHost
+            ? `Forked from ${source.name}: ${model ?? host}`
+            : source.description),
         forkedFrom: source.name,
     };
+    if (forked.auth && host !== sourceHost) {
+        const envVar = authEnvKeyForHost(host);
+        if (!envVar)
+            throw new Error(`Host '${host}' has no known auth env var; the source auth binding cannot be translated.`);
+        forked.auth = { ...forked.auth, envVar };
+    }
     // A fork that repoints the model or endpoint is no longer that preset — keep
     // the preset link only while the fork still matches what the preset defines.
-    if (opts.model || opts.baseUrl)
+    if (opts.model || opts.baseUrl || host !== sourceHost)
         delete forked.preset;
     if (opts.provider) {
         const envVar = opts.authEnvVar ?? source.auth?.envVar ?? authEnvKeyForHost(host);

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

@@ -21,6 +21,29 @@ export declare function syncProjectResourcesToAgent(agent: AgentId, version: str
  *     commits its own `.claude/CLAUDE.md` keeps it — it is not in the manifest).
  */
 export declare function managedGitignoreEntries(agentRoot: string, referenceRoot: string, managed: string[]): string[];
+/**
+ * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
+ * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
+ * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
+ * canonical copy ships in `.system/`).
+ *
+ * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
+ * `.gitignore` block would itself show as `M .gitignore` on every clone and
+ * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
+ * to kill. info/exclude is per-clone and never committed, so the working tree
+ * stays clean at rest.
+ *
+ * Idempotent and convergent: when the path is still tracked it is removed from
+ * the index (the working file is kept) AND that removal is committed — a bare
+ * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
+ * that re-arms the very pull trip this exists to prevent. The single removal
+ * commit also propagates the de-track fleet-wide: peers pull it and converge,
+ * their next run finding nothing to untrack. The exclude block is rewritten in
+ * place, unioning `relPath` with any entries already there, so a second run is a
+ * no-op. Fails open outside a git repo. Returns whether the path was untracked
+ * by this call (a signal for the caller's one-time log).
+ */
+export declare function detrackViaGitExclude(repoDir: string, relPath: string): boolean;
 /**
  * One human line for the files a project sync left alone because you already
  * wrote them. This is the normal steady state — every sync of a project whose

package/dist/lib/project-resources.js

@@ -284,6 +284,100 @@ function stripLegacyManagedGitignoreBlock(projectRoot, agent) {
     fs.writeFileSync(tmp, stripped);
     fs.renameSync(tmp, gitignorePath);
 }
+const DETRACK_BEGIN = '# BEGIN agents-cli detracked (managed)';
+const DETRACK_END = '# END agents-cli detracked (managed)';
+/**
+ * Stop git tracking `relPath` in the DotAgents clone at `repoDir` and keep it
+ * locally ignored — the PHNX-3718 pattern, applied to a shared config file the
+ * user repo should no longer carry (e.g. the duplicated CHANGELOG.md; the
+ * canonical copy ships in `.system/`).
+ *
+ * The ignore entry goes in `.git/info/exclude`, NOT `.gitignore`: a tracked
+ * `.gitignore` block would itself show as `M .gitignore` on every clone and
+ * reintroduce the exact dirty-tree-blocks-pull failure this whole effort exists
+ * to kill. info/exclude is per-clone and never committed, so the working tree
+ * stays clean at rest.
+ *
+ * Idempotent and convergent: when the path is still tracked it is removed from
+ * the index (the working file is kept) AND that removal is committed — a bare
+ * `git rm --cached` would leave a staged deletion, which is itself a dirty tree
+ * that re-arms the very pull trip this exists to prevent. The single removal
+ * commit also propagates the de-track fleet-wide: peers pull it and converge,
+ * their next run finding nothing to untrack. The exclude block is rewritten in
+ * place, unioning `relPath` with any entries already there, so a second run is a
+ * no-op. Fails open outside a git repo. Returns whether the path was untracked
+ * by this call (a signal for the caller's one-time log).
+ */
+export function detrackViaGitExclude(repoDir, relPath) {
+    const target = resolveGitExcludeTarget(repoDir);
+    if (!target)
+        return false; // not a git repo — nothing to de-track or ignore.
+    let untrackedNow = false;
+    const abs = path.join(repoDir, relPath);
+    if (isTrackedByGit(repoDir, abs)) {
+        try {
+            // Unstage anything else first so the removal commit records ONLY this
+            // path's deletion — a mixed reset (index only, worktree untouched). At
+            // migration time the index is already clean; this just makes the scope
+            // guaranteed rather than assumed.
+            execFileSync('git', ['-C', repoDir, 'reset', '-q'], { stdio: ['ignore', 'ignore', 'ignore'] });
+            // --cached keeps the working file; the commit records the removal so the
+            // tree is clean at rest and the de-track converges across the fleet. A
+            // pathspec commit would re-read the still-present worktree file and undo
+            // the removal, so the commit takes the staged index (just this deletion).
+            execFileSync('git', ['-C', repoDir, 'rm', '--cached', '--quiet', '--', relPath], {
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            execFileSync('git', ['-C', repoDir, '-c', 'commit.gpgsign=false', 'commit', '--no-verify',
+                '-m', `chore(config): stop tracking ${relPath}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+            untrackedNow = true;
+        }
+        catch {
+            // rm/commit can fail (e.g. mid-rebase, index.lock); the ignore entry below
+            // still lands and the next migration run retries the untrack. Fail open —
+            // but roll back a staged-but-uncommitted removal so we never LEAVE a dirty
+            // staged deletion behind (which would re-arm the pull trip).
+            try {
+                execFileSync('git', ['-C', repoDir, 'reset', '-q', '--', relPath], {
+                    stdio: ['ignore', 'ignore', 'ignore'],
+                });
+            }
+            catch { /* nothing staged to reset */ }
+            untrackedNow = false;
+        }
+    }
+    // Anchor to the worktree root so the pattern matches only the top-level file,
+    // exactly like git anchors a leading-slash info/exclude entry.
+    const entry = '/' + relPath.split(path.sep).join('/');
+    let original = '';
+    try {
+        original = fs.readFileSync(target.excludePath, 'utf-8');
+    }
+    catch {
+        original = '';
+    }
+    const existing = extractManagedEntries(original, DETRACK_BEGIN, DETRACK_END);
+    const entries = existing.includes(entry) ? existing : [...existing, entry].sort();
+    const next = applyManagedBlock(original, DETRACK_BEGIN, DETRACK_END, entries);
+    if (next !== null && next !== original) {
+        fs.mkdirSync(path.dirname(target.excludePath), { recursive: true });
+        const tmp = target.excludePath + '.tmp';
+        fs.writeFileSync(tmp, next);
+        fs.renameSync(tmp, target.excludePath);
+    }
+    return untrackedNow;
+}
+/** The entries currently inside a `begin`/`end` managed block, or `[]`. */
+function extractManagedEntries(content, begin, end) {
+    const lines = content.split('\n');
+    const bi = lines.indexOf(begin);
+    if (bi === -1)
+        return [];
+    const ei = lines.indexOf(end, bi + 1);
+    if (ei === -1)
+        return [];
+    return lines.slice(bi + 1, ei).map((l) => l.trim()).filter(Boolean);
+}
 function removeManagedPath(agentRoot, rel) {
     if (path.isAbsolute(rel) || rel.includes('..'))
         return;

package/dist/lib/reconcile-and-repair.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Post-reconcile repair — the shared "make it whole" pass `agents sync` runs
+ * after its prune+write, so sync is a true superset of the old `doctor --fix`.
+ *
+ * `syncResourcesToVersion` reconciles resource FILES (and, with a caller
+ * selection, prunes orphans). It does NOT: fill live-home gaps the staleness
+ * manifest can't see, generate/repair the managed hook runtime shims, or re-wire
+ * a present-but-unwired hook into settings.json. `doctor --fix` used to do all of
+ * that; now sync does, by calling this one routine at the tail of every reconcile.
+ * (The destructive stale-CLI purge `doctor --fix` also ran is NOT automatic here
+ * — it runs only via the explicit `agents sync --prune-clis`, see `pruneClis`.)
+ *
+ * Ordering matters: sync's own prune+write happens FIRST (unchanged), THEN this
+ * repair pass. Prune stays sync's job; heal only FILLS and FIXES (never deletes),
+ * so the two never fight. Pure of stdout — returns a structured report;
+ * `renderRepairAfterSync` prints it only when the caller is neither `--json` nor
+ * `--quiet`.
+ */
+import type { AgentId } from './types.js';
+import { type HealResult } from './heal.js';
+import { type HookRuntimeRepairReport } from './hooks/install.js';
+import { type RemediateStaleInstallsResult, type FindAgentsCliInstallsOptions } from './self-update.js';
+export interface HookRewireResult {
+    agent: AgentId;
+    version: string;
+    /** Hooks newly wired into settings.json by this pass. */
+    rewired: number;
+    /** Hooks still unwired after re-registering (source/home mismatch). */
+    remaining: number;
+    /** Stable failure class; never expose a generated temporary shim pathname. */
+    failure?: 'register-failed';
+}
+export interface RepairAfterSyncReport {
+    heal: HealResult;
+    hookRewire: HookRewireResult[];
+    hookRuntimeRepair: HookRuntimeRepairReport;
+    /** Only populated on the umbrella (no-agent) path; null otherwise. */
+    staleInstallPurge: RemediateStaleInstallsResult | null;
+}
+/**
+ * Test/override hook that scopes the destructive stale-CLI purge to injected
+ * paths so it NEVER touches real machine installs. `findAgentsCliInstalls`
+ * hard-codes `/usr/local/lib/node_modules` et al. when `globalNodeModulesDirs` is
+ * absent, so a purge is unsafe to run unscoped in a test — inject sandbox paths.
+ */
+export interface PurgeInjection {
+    runningRoot?: string;
+    runningVersion?: string;
+    pathEnv?: string;
+    findOpts?: FindAgentsCliInstallsOptions;
+    dryRun?: boolean;
+}
+export interface RepairAfterSyncOptions {
+    /** Scope the repair to one agent; omit for the umbrella sweep across all
+     *  installed agents. (The purge is NOT tied to this — see `pruneClis`.) */
+    agent?: AgentId;
+    /** The versions of `agent` the sync just reconciled. Passing them scopes
+     *  heal + rewire + runtime-repair to exactly those homes; omitting lets heal
+     *  apply its own non-isolated sweep. */
+    versions?: string[];
+    /** Resolution cwd for heal's diff. Defaults to heal's neutral home dir. */
+    cwd?: string;
+    /** Run the DESTRUCTIVE machine-wide stale-CLI purge (`fs.rmSync`s other
+     *  agents-cli installs). Default false — the purge is NEVER automatic; it runs
+     *  only on the umbrella (no-agent) path AND only when the caller passed
+     *  `agents sync --prune-clis`. */
+    pruneClis?: boolean;
+    /** Scope the purge scan+delete to injected paths (tests only). */
+    purgeInjection?: PurgeInjection;
+}
+/**
+ * Run the post-reconcile repair pass over the agents/versions a sync just
+ * touched: heal live-home gaps (mode 'full', matching the old `doctor --fix`),
+ * re-wire hooks the diff-driven heal leaves behind, run one bounded managed-hook
+ * runtime repair, and — ONLY when `pruneClis` is set on the umbrella (no-agent)
+ * path — purge stale/legacy agents-cli copies. The purge is never automatic.
+ * Returns a full account; never writes to stdout.
+ */
+export declare function repairAfterSync(opts: RepairAfterSyncOptions): Promise<RepairAfterSyncReport>;
+/** True when the repair pass changed (or attempted to change) anything. */
+export declare function repairChangedAnything(report: RepairAfterSyncReport): boolean;
+/**
+ * True when the RECONCILE repair left a per-version problem a human must fix — an
+ * unresolvable managed hook runtime shim, or a hook that could not be re-wired.
+ * These gate a sync's `ok`/exit code (the yosemite-s1 class the old
+ * `doctor --fix` surfaced).
+ *
+ * The machine-wide stale-CLI purge is deliberately EXCLUDED: a purge that could
+ * not delete a system-wide install (typically `EACCES` on `/usr/local/...`, which
+ * needs sudo) is a hygiene issue unrelated to whether the reconcile succeeded, so
+ * it must not flip a fleet peer's `agents sync --json` to `ok: false`. Purge
+ * failures stay fully visible — in the JSON `repair.staleInstallPurge.failed` and
+ * the rendered `hold`/`manual` lines.
+ */
+export declare function repairHadFailures(report: RepairAfterSyncReport): boolean;
+/**
+ * Serialize the repair pass for a `--json` sync payload — the machine surface the
+ * deleted `doctor --fix --json` used to carry (heal detail + hook rewire + hook
+ * runtime repair + the umbrella stale-CLI purge). Attached under the `repair` key
+ * so fleet fan-out sees what the reconcile fixed and whether anything still needs
+ * a human (mirror `repairHadFailures`).
+ */
+export declare function repairAfterSyncJson(report: RepairAfterSyncReport): Record<string, unknown>;
+/**
+ * Print the repair pass's human-readable detail. Sync calls this only on the
+ * interactive / non-json path; the header is emitted only when something actually
+ * changed, so a clean sync stays quiet.
+ */
+export declare function renderRepairAfterSync(report: RepairAfterSyncReport, log?: (s: string) => void): void;