@phnx-labs/agents-cli 1.22.74 → 1.22.76

package/dist/lib/fleet-shared-repo-sync.d.ts

@@ -21,6 +21,18 @@ export interface FleetSharedRepoSyncResult {
     timedOut: boolean;
     skipped: string | null;
     error: string | null;
+    /**
+     * Untracked working-tree files that collided with origin and were dropped
+     * (byte-identical to origin) before rebasing. See clearCollidingUntracked.
+     */
+    untrackedCleared?: number;
+    /**
+     * Untracked working-tree files that collided with origin, differed from it,
+     * and were moved to untrackedBackupDir before rebasing.
+     */
+    untrackedBackedUp?: string[];
+    /** Directory the differing untracked collisions were moved to, if any. */
+    untrackedBackupDir?: string;
 }
 /** Run one real process asynchronously with a hard wall-clock/process-tree bound. */
 export declare function runBoundedProcess(command: string, args: string[], options: {

package/dist/lib/fleet-shared-repo-sync.js

@@ -161,6 +161,72 @@ function retainedAutostash(stashList, objectId) {
         ref: null,
     };
 }
+/**
+ * `git rebase` checks out its base (origin/<branch>) and aborts when an
+ * untracked working-tree file would be overwritten by a file that origin
+ * tracks. `--autostash` only sets aside *tracked* changes, so these untracked
+ * collisions wedge the rebase on every sync and the device silently falls
+ * hundreds of commits behind — the fleet-wide drift root cause (PHNX-3923).
+ *
+ * In this shared-state repo an untracked file that also exists on origin is a
+ * stale local snapshot: the canonical copy is on origin and every device
+ * republishes its own state (this device's own owned file is already committed
+ * before we get here, so it is tracked and never appears below). Drop the ones
+ * byte-identical to origin (lossless) and move any that differ into a backup
+ * dir beside the repo root — outside the repo's tracked tree, so the move
+ * cannot create a fresh collision — so nothing is silently destroyed. Then let
+ * the rebase check out origin's version. A file we cannot clear is left in
+ * place; the rebase may still abort, no worse than today and never losing data.
+ */
+async function clearCollidingUntracked(git, root, branch) {
+    const others = await git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (others.code !== 0)
+        return { error: others };
+    const relPaths = others.stdout.split('\0').filter(Boolean);
+    let cleared = 0;
+    const backedUp = [];
+    let backupDir = null;
+    for (const rel of relPaths) {
+        // rev-parse doubles as the "does origin track this path" test (non-zero =
+        // absent) — only paths origin tracks are overwritten by the rebase checkout.
+        const originHash = await git(['rev-parse', `origin/${branch}:${rel}`]);
+        if (originHash.code !== 0 || !originHash.stdout.trim())
+            continue;
+        const abs = path.join(root, rel);
+        // Byte-exact identity via git blob SHAs. Comparing UTF-8-decoded strings
+        // would collapse distinct invalid bytes to U+FFFD and could delete
+        // non-identical content. `--no-filters` hashes the raw on-disk bytes (no
+        // clean/autocrlf normalization), so `identical` is true only when the local
+        // bytes exactly equal origin's stored blob — never a filter-normalized
+        // near-match. A hash-object failure (unreadable / vanished under a
+        // concurrent writer) means "leave it in place".
+        const localHash = await git(['hash-object', '--no-filters', '--', abs]);
+        if (localHash.code !== 0 || !localHash.stdout.trim())
+            continue;
+        const identical = originHash.stdout.trim() === localHash.stdout.trim();
+        try {
+            if (identical) {
+                fs.rmSync(abs, { force: true });
+                cleared++;
+            }
+            else {
+                if (!backupDir) {
+                    // A sibling of the repo root: outside the tracked tree (so the move
+                    // cannot create a fresh collision) yet colocated for easy recovery.
+                    backupDir = path.join(`${root}-fleet-sync-backups`, String(Date.now()));
+                }
+                const dest = path.join(backupDir, rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.renameSync(abs, dest);
+                backedUp.push(rel);
+            }
+        }
+        catch {
+            // Could not clear this collision; leave it in place.
+        }
+    }
+    return { cleared, backedUp, backupDir };
+}
 async function performFleetSharedRepoSync(root, device, timeoutMs) {
     if (!fs.existsSync(path.join(root, '.git'))) {
         return {
@@ -201,29 +267,57 @@ async function performFleetSharedRepoSync(root, device, timeoutMs) {
     }
     const ownedFile = fleetSharedStatePath(device, root);
     const relativeOwnedFile = path.relative(root, ownedFile).split(path.sep).join('/');
+    // The central `agents.yaml` is fleet-shared state too — `agents accounts label`
+    // writes version-scoped native account rows there (lib/state.ts writeMetaUnlocked),
+    // as a plain file write with no commit. Publishing only the per-device file and
+    // then `rebase --autostash`-ing over a dirty central file silently destroyed
+    // those labels: every box lost its account labels on its next daemon publish
+    // (PHNX-3887). Commit it alongside the device doc so the rebase carries the
+    // rows instead of stashing them, which is also what `accounts label --help`
+    // already promises ("labels live on the central account rows in agents.yaml,
+    // which repo push/pull already syncs fleet-wide").
+    const centralFile = path.join(root, 'agents.yaml');
+    const publishPaths = [relativeOwnedFile];
+    if (fs.existsSync(centralFile))
+        publishPaths.push('agents.yaml');
+    const existingPaths = publishPaths.filter(rel => fs.existsSync(path.join(root, rel)));
     let committed = false;
-    if (fs.existsSync(ownedFile)) {
-        const status = await git(['status', '--porcelain=v1', '--', relativeOwnedFile]);
+    if (existingPaths.length > 0) {
+        const status = await git(['status', '--porcelain=v1', '--', ...existingPaths]);
         if (status.code !== 0)
             return failure('git status', status);
         if (status.stdout.trim()) {
-            const add = await git(['add', '--', relativeOwnedFile]);
+            const add = await git(['add', '--', ...existingPaths]);
             if (add.code !== 0)
                 return failure('git add', add);
             const commit = await git([
                 '-c', 'commit.gpgsign=false',
                 'commit', '--no-verify', '-m', `chore(devices): publish ${device} daemon state`,
-                '--', relativeOwnedFile,
+                '--', ...existingPaths,
             ]);
             if (commit.code !== 0)
                 return failure('git commit', commit);
             committed = true;
         }
     }
+    let untrackedCleared = 0;
+    const untrackedBackedUp = [];
+    let untrackedBackupDir;
     for (let attempt = 1; attempt <= FLEET_SHARED_REPO_PUSH_ATTEMPTS; attempt++) {
         const fetch = await git(['fetch', 'origin']);
         if (fetch.code !== 0)
             return { ...failure('git fetch', fetch), committed };
+        // Untracked files that origin tracks would abort the rebase's checkout
+        // (autostash only covers tracked changes). Clear them first — this is the
+        // fleet-drift root cause (PHNX-3923).
+        const reconcile = await clearCollidingUntracked(git, root, branch);
+        if ('error' in reconcile) {
+            return { ...failure('git ls-files --others', reconcile.error), committed };
+        }
+        untrackedCleared += reconcile.cleared;
+        untrackedBackedUp.push(...reconcile.backedUp);
+        if (reconcile.backupDir)
+            untrackedBackupDir = reconcile.backupDir;
         // Keep enough of the same wall-clock bound available to remove a botched
         // autostash pop from the operator's live checkout before returning.
         const rebase = await git(['rebase', '--autostash', `origin/${branch}`], FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS);
@@ -283,6 +377,9 @@ async function performFleetSharedRepoSync(root, device, timeoutMs) {
                 timedOut: false,
                 skipped: null,
                 error: null,
+                untrackedCleared,
+                untrackedBackedUp,
+                untrackedBackupDir,
             };
         }
         if (attempt === FLEET_SHARED_REPO_PUSH_ATTEMPTS || !isPushRace(push)) {

package/dist/lib/fleet-shared-state.d.ts

@@ -26,6 +26,14 @@ export interface SessionMirrorRow {
     timestamp: string;
     ticketId?: string;
     prUrl?: string;
+    /** Daemon-computed goal (PHNX-3939) — carried so a peer renders it with no transcript. */
+    goal?: string;
+    /** Daemon-computed progress checkpoints, newest last (PHNX-3939). */
+    checkpoints?: import('./session/types.js').SessionCheckpoint[];
+    /** Daemon-computed detailed checklist (PHNX-3939). */
+    summaryChecklist?: import('./session/types.js').SessionChecklistItem[];
+    /** Lifecycle of the daemon-computed summary (PHNX-3939). */
+    summaryState?: import('./session/types.js').SummaryState;
     capturedAt: number;
 }
 export interface FleetSharedDeviceState {

package/dist/lib/heal.d.ts

@@ -3,9 +3,10 @@
  * what is actually present/valid in each installed agent home.
  *
  * Powers two callers:
- *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
- *     missing, overwrites drifted content, and refreshes stale plugins even when
- *     the baseline is unknown (the operator asked for it).
+ *   - `agents sync` — the one fixer, via the post-reconcile repair pass
+ *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
+ *     'full': fills missing, overwrites drifted content, and refreshes stale
+ *     plugins even when the baseline is unknown (the user asked to sync).
  *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
  *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
  *     provably-unmodified stale plugins). Drift and risky refreshes are reported,

package/dist/lib/heal.js

@@ -3,9 +3,10 @@
  * what is actually present/valid in each installed agent home.
  *
  * Powers two callers:
- *   - `agents doctor --fix`  — explicit, operator-driven. Mode 'full': fills
- *     missing, overwrites drifted content, and refreshes stale plugins even when
- *     the baseline is unknown (the operator asked for it).
+ *   - `agents sync` — the one fixer, via the post-reconcile repair pass
+ *     (`lib/reconcile-and-repair.ts`, run at the tail of every sync). Mode
+ *     'full': fills missing, overwrites drifted content, and refreshes stale
+ *     plugins even when the baseline is unknown (the user asked to sync).
  *   - the routines daemon's periodic safety check — Mode 'safe': fixes only the
  *     unambiguous gaps (missing resources, Claude-invalid plugin manifests, and
  *     provably-unmodified stale plugins). Drift and risky refreshes are reported,
@@ -86,7 +87,7 @@ export function notifyHeal(r) {
         ? `${needsAttention} plugin${needsAttention === 1 ? '' : 's'} need attention`
         : 'agents: auto-healed config gaps';
     const body = needsAttention > 0
-        ? `${summarizeHeal(r)}. Run: agents doctor --fix`
+        ? `${summarizeHeal(r)}. Run: agents sync`
         : summarizeHeal(r);
     notifyDesktop({ title, body, action: 'routines:list' });
 }

package/dist/lib/hosts/ready.d.ts

@@ -109,7 +109,7 @@ export interface ViewAgentAccountEligibility {
  * older remote CLI omits `launchable`, so it falls back to `signedIn` — the
  * pre-fix behavior, so a rolling fleet does not regress.
  */
-export declare function viewAgentAccountEligibility(view: string, agent: string): ViewAgentAccountEligibility;
+export declare function viewAgentAccountEligibility(view: string, agent: string, now?: number): ViewAgentAccountEligibility;
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;

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/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/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;