@phnx-labs/agents-cli 1.20.45 → 1.20.47

package/dist/lib/secrets/linux.js

@@ -19,6 +19,7 @@
 import { spawnSync } from 'child_process';
 import * as os from 'os';
 import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+import { noteNativeShadow, _resetFallbackNoticeForTest, } from './fallback.js';
 // Re-exported so existing importers (and tests) can keep reaching these via
 // './linux.js'. The implementations live in ./filestore.ts.
 export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
@@ -35,13 +36,16 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
+// Set once the keyring is observed locked/unreachable in this process, so the
+// read-through in get/has stops re-probing it (and stops re-emitting notices).
+let nativeUnreachable = false;
 function activateFileFallback() {
     if (useFileFallback)
         return;
     useFileFallback = true;
     if (!warnedFallback) {
         warnedFallback = true;
-        process.stderr.write(`[agents] secret-service collection locked, using file-based store at ${fileDir()}\n`);
+        process.stderr.write(`[agents] using the encrypted file store at ${fileDir()}\n`);
     }
 }
 function isLockedCollectionError(stderr) {
@@ -111,8 +115,21 @@ export function usesFileFallback() {
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export function hasSecretToolToken(item) {
-    if (preflight() === 'file')
-        return fileStore.has(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return true;
+        // The file store is primary under the fallback, but an item can still live
+        // only in an (unlocked) keyring that predates it — read through so it isn't
+        // silently shadowed.
+        const probe = readNativeItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return true;
+        }
+        if (probe.locked)
+            noteNativeShadow('locked', fileDir());
+        return false;
+    }
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -125,14 +142,25 @@ export function hasSecretToolToken(item) {
     }
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.has(item);
     }
     return false;
 }
 export function getSecretToolToken(item) {
-    if (preflight() === 'file')
-        return fileStore.get(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return fileStore.get(item);
+        const probe = readNativeItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return probe.value;
+        }
+        if (probe.locked)
+            noteNativeShadow('locked', fileDir());
+        throw new Error(`Secret '${item}' not found in the file store or keyring.`);
+    }
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -148,6 +176,7 @@ export function getSecretToolToken(item) {
     }
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.get(item);
     }
@@ -171,6 +200,7 @@ export function setSecretToolToken(item, value) {
         return;
     const stderr = result.stderr?.toString().trim() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         fileStore.set(item, value);
         return;
@@ -193,6 +223,7 @@ export function deleteSecretToolToken(item) {
         return true;
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.delete(item);
     }
@@ -252,6 +283,81 @@ export function listSecretToolItems(prefix) {
     const output = `${result.stdout?.toString() || ''}\n${result.stderr?.toString() || ''}`;
     return parseSecretToolItems(output, prefix);
 }
+// ---------- native-direct helpers (bypass preflight routing) ----------
+//
+// These always talk to secret-tool regardless of whether the process has fallen
+// back to the file store. They power (a) the read-through that keeps the file
+// store from silently shadowing keyring items, and (b) `import-keyring`.
+/**
+ * Read one item straight from the keyring. Returns `{value}` on a hit,
+ * `{locked:true}` when the collection is locked/unreachable, and `{}` on a plain
+ * miss. Never throws and never emits — the caller decides whether to notice.
+ */
+function readNativeItemRaw(item) {
+    if (nativeUnreachable)
+        return { locked: true };
+    if (!secretToolAvailable())
+        return {};
+    const user = os.userInfo().username;
+    const r = spawnSync('secret-tool', [
+        'lookup', 'service', SERVICE, 'account', user, 'item', item,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status === 0) {
+        const v = r.stdout?.toString().trim();
+        return v && v.length ? { value: v } : {};
+    }
+    if (isLockedCollectionError(r.stderr?.toString() ?? '')) {
+        nativeUnreachable = true;
+        return { locked: true };
+    }
+    return {};
+}
+/**
+ * Enumerate agents-cli items in the keyring whose name starts with `prefix`.
+ * `available` is false when secret-tool isn't installed; `locked` is true when
+ * the collection is locked.
+ */
+function listNativeItemsRaw(prefix) {
+    if (!secretToolAvailable())
+        return { items: [], locked: false, available: false };
+    const r = spawnSync('secret-tool', [
+        'search', '--all', 'service', SERVICE,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) {
+        const locked = isLockedCollectionError(r.stderr?.toString() ?? '');
+        if (locked)
+            nativeUnreachable = true;
+        return { items: [], locked, available: true };
+    }
+    const output = `${r.stdout?.toString() || ''}\n${r.stderr?.toString() || ''}`;
+    return { items: parseSecretToolItems(output, prefix), locked: false, available: true };
+}
+/**
+ * Copy agents-cli items from the keyring into the file store (the `import-keyring`
+ * backend for Linux). Requires an unlocked keyring; items already in the file
+ * store are left untouched. With `commit=false` it reports what it *would* do.
+ */
+export function importNativeSecretToolItems(prefix, commit) {
+    const { items, locked, available } = listNativeItemsRaw(prefix);
+    if (!available || locked)
+        return { available, locked, results: [] };
+    const results = [];
+    for (const item of items) {
+        if (fileStore.has(item)) {
+            results.push({ item, status: 'exists' });
+            continue;
+        }
+        const probe = readNativeItemRaw(item);
+        if (probe.value === undefined) {
+            results.push({ item, status: 'failed', detail: probe.locked ? 'keyring locked' : 'unreadable' });
+            continue;
+        }
+        if (commit)
+            fileStore.set(item, probe.value);
+        results.push({ item, status: commit ? 'imported' : 'would-import' });
+    }
+    return { available, locked, results };
+}
 /** KeychainBackend implementation for Linux. Routes through secret-tool
  *  with a transparent encrypted-file fallback when the default Secret
  *  Service collection is locked (or libsecret-tools is not installed but
@@ -280,6 +386,8 @@ export function _resetForTest(opts = {}) {
     _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
+    nativeUnreachable = false;
     checkedAvailability = false;
     isAvailable = false;
+    _resetFallbackNoticeForTest();
 }

package/dist/lib/secrets/windows.d.ts

@@ -27,6 +27,7 @@
  * names directly.
  */
 import type { KeychainBackend } from './index.js';
+import { type NativeImportReport } from './fallback.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
 /**
  * CRED_MAX_CREDENTIAL_BLOB_SIZE — Credential Manager rejects a generic
@@ -53,6 +54,12 @@ export declare function listCredManItems(prefix: string): string[];
  * parseSecretToolItems (linux.ts). Exported for tests.
  */
 export declare function parseWindowsCredList(output: string, prefix: string): string[];
+/**
+ * Copy agents-cli credentials from Credential Manager into the file store (the
+ * `import-keyring` backend for Windows). Requires a reachable store; items
+ * already in the file store are left untouched.
+ */
+export declare function importNativeCredManItems(prefix: string, commit: boolean): NativeImportReport;
 /**
  * KeychainBackend implementation for Windows. Routes through Windows Credential
  * Manager (via PowerShell P/Invoke) with a transparent encrypted-file fallback

package/dist/lib/secrets/windows.js

@@ -29,6 +29,7 @@
 import { spawnSync } from 'child_process';
 import { encodePwshBase64 } from '../pwsh.js';
 import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+import { noteNativeShadow, _resetFallbackNoticeForTest, } from './fallback.js';
 // Re-exported so importers (and tests) can keep reaching these via './windows.js'.
 export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
 const POWERSHELL = 'powershell.exe';
@@ -250,13 +251,16 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
+// Set once Credential Manager is observed unreachable in this process, so the
+// read-through in get/has stops re-probing it (and re-emitting notices).
+let nativeUnreachable = false;
 function activateFileFallback() {
     if (useFileFallback)
         return;
     useFileFallback = true;
     if (!warnedFallback) {
         warnedFallback = true;
-        process.stderr.write(`[agents] Windows Credential Manager unavailable, using file-based store at ${fileDir()}\n`);
+        process.stderr.write(`[agents] using the encrypted file store at ${fileDir()}\n`);
     }
 }
 /**
@@ -316,22 +320,45 @@ export function usesFileFallback() {
 }
 // ---------- Credential Manager ops with fallback ----------
 export function hasCredManToken(item) {
-    if (preflight() === 'file')
-        return fileStore.has(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return true;
+        // Read through to Credential Manager so an item that predates the fallback
+        // isn't silently shadowed by the file store.
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return true;
+        }
+        if (probe.unavailable)
+            noteNativeShadow('locked', fileDir());
+        return false;
+    }
     const r = runCred('has', { target: item });
     if (r.status === 0)
         return true;
     if (r.status === 3)
         return false;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.has(item);
     }
     return false;
 }
 export function getCredManToken(item) {
-    if (preflight() === 'file')
-        return fileStore.get(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return fileStore.get(item);
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return probe.value;
+        }
+        if (probe.unavailable)
+            noteNativeShadow('locked', fileDir());
+        throw new Error(`Secret '${item}' not found in the file store or Credential Manager.`);
+    }
     const r = runCred('get', { target: item });
     if (r.status === 0) {
         // stdout is base64 of the raw UTF-8 blob (dodges PowerShell encoding corruption).
@@ -340,6 +367,7 @@ export function getCredManToken(item) {
     if (r.status === 3)
         throw new Error(`Secret '${item}' not found in Credential Manager.`);
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.get(item);
     }
@@ -362,6 +390,7 @@ export function setCredManToken(item, value) {
     if (r.status === 0)
         return;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         fileStore.set(item, value);
         return;
@@ -377,6 +406,7 @@ export function deleteCredManToken(item) {
     if (r.status === 3)
         return false;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.delete(item);
     }
@@ -389,6 +419,7 @@ export function listCredManItems(prefix) {
     if (r.status === 0)
         return parseWindowsCredList(r.stdout, prefix);
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.list(prefix);
     }
@@ -407,6 +438,78 @@ export function parseWindowsCredList(output, prefix) {
         .filter((s) => s.startsWith(prefix));
     return [...new Set(items)]; // dedupe
 }
+// ---------- native-direct helpers (bypass preflight routing) ----------
+//
+// Always talk to Credential Manager regardless of the file fallback. They power
+// (a) the read-through that keeps the file store from shadowing credman items,
+// and (b) `import-keyring`.
+/**
+ * Read one item straight from Credential Manager. `{value}` on hit,
+ * `{unavailable:true}` when the store is unreachable, `{}` on a plain miss.
+ * Never throws, never emits.
+ */
+function readNativeCredItemRaw(item) {
+    if (nativeUnreachable)
+        return { unavailable: true };
+    if (!powershellAvailable())
+        return {};
+    const r = runCred('get', { target: item });
+    if (r.status === 0)
+        return { value: Buffer.from(r.stdout.trim(), 'base64').toString('utf8') };
+    if (r.status === 3)
+        return {};
+    if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
+        return { unavailable: true };
+    }
+    return {};
+}
+/**
+ * Enumerate agents-cli credentials under `prefix`. Windows credentials have no
+ * service scoping — the target IS the identifier — so we NEVER enumerate with an
+ * empty filter (that returns unrelated machine credentials). The filter is
+ * floored to the `agents-cli.` namespace; bare items (unprefixed targets) are
+ * therefore out of scope for auto-discovery on Windows.
+ */
+function listNativeCredItemsRaw(prefix) {
+    if (!powershellAvailable())
+        return { items: [], locked: false, available: false };
+    const floor = prefix && prefix.startsWith('agents-cli.') ? prefix : 'agents-cli.';
+    const r = runCred('list', { prefix: floor });
+    if (r.status === 0)
+        return { items: parseWindowsCredList(r.stdout, floor), locked: false, available: true };
+    if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
+        return { items: [], locked: true, available: true };
+    }
+    return { items: [], locked: false, available: true };
+}
+/**
+ * Copy agents-cli credentials from Credential Manager into the file store (the
+ * `import-keyring` backend for Windows). Requires a reachable store; items
+ * already in the file store are left untouched.
+ */
+export function importNativeCredManItems(prefix, commit) {
+    const { items, locked, available } = listNativeCredItemsRaw(prefix);
+    if (!available || locked)
+        return { available, locked, results: [] };
+    const results = [];
+    for (const item of items) {
+        if (fileStore.has(item)) {
+            results.push({ item, status: 'exists' });
+            continue;
+        }
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value === undefined) {
+            results.push({ item, status: 'failed', detail: probe.unavailable ? 'credential manager unavailable' : 'unreadable' });
+            continue;
+        }
+        if (commit)
+            fileStore.set(item, probe.value);
+        results.push({ item, status: commit ? 'imported' : 'would-import' });
+    }
+    return { available, locked, results };
+}
 /**
  * KeychainBackend implementation for Windows. Routes through Windows Credential
  * Manager (via PowerShell P/Invoke) with a transparent encrypted-file fallback
@@ -440,6 +543,8 @@ export function _resetForTest(opts = {}) {
     _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
+    nativeUnreachable = false;
+    _resetFallbackNoticeForTest();
     if (opts.forceAvailable === undefined || opts.forceAvailable === null) {
         checkedAvailability = false;
         isAvailable = false;

package/dist/lib/self-heal/checks/path.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const pathCheck: HealCheck;

package/dist/lib/self-heal/checks/path.js

@@ -0,0 +1,30 @@
+// path check — ensures the shims dir is on PATH. On POSIX it appends to the shell
+// rc file; on Windows it registers on the user PATH (registry). addShimsToPath is a
+// no-op when already present, so this is idempotent. Formerly an interactive prompt
+// in index.ts fired on every new shell; here the daemon does it once, silently.
+//
+// Caveat: an already-open shell won't pick up the new rc/PATH entry until it reloads
+// — but new shells will, so the recurring prompt stops.
+import { resultOf } from '../types.js';
+import { isShimsInPath, addShimsToPath } from '../../shims.js';
+export const pathCheck = {
+    id: 'path',
+    title: 'Shims directory on PATH',
+    cadence: 'startup',
+    async run(ctx) {
+        if (isShimsInPath())
+            return resultOf([], []);
+        if (ctx.dryRun)
+            return resultOf(['add shims dir to PATH'], []);
+        const r = addShimsToPath();
+        if (r.success && !r.alreadyPresent) {
+            return resultOf([`added shims to PATH (${r.location ?? r.rcFile ?? 'PATH'})`], []);
+        }
+        if (r.success && r.alreadyPresent) {
+            // Present in the rc file but not in THIS process's PATH — a reload issue,
+            // not something to fix again. Report quietly.
+            return resultOf([], [`shims dir in ${r.rcFile ?? 'rc file'} but not loaded — open a new terminal`]);
+        }
+        return resultOf([], [`could not add shims to PATH: ${r.error ?? 'unknown'}`]);
+    },
+};

package/dist/lib/self-heal/checks/resources.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const resourcesCheck: HealCheck;

package/dist/lib/self-heal/checks/resources.js

@@ -0,0 +1,36 @@
+// resources check — reconciles each installed version's home against the DotAgents
+// definitions (commands, skills, hooks, rules, mcp, plugins). This is a thin adapter
+// over the existing, battle-tested heal() engine (lib/heal.ts) — no behavior change;
+// it just re-expresses heal()'s result in the unified CheckResult shape.
+import { resultOf } from '../types.js';
+export const resourcesCheck = {
+    id: 'resources',
+    title: 'Resource sync (commands, skills, hooks, rules, plugins)',
+    cadence: 'periodic',
+    async run(ctx) {
+        // Lazy import so the (heavy) heal graph only loads when this check actually runs.
+        const { heal } = await import('../../heal.js');
+        const result = await heal({ mode: ctx.mode, dryRun: ctx.dryRun });
+        const fixed = [];
+        const needsAttention = [];
+        let healed = 0;
+        for (const v of result.versions) {
+            healed += v.healed.length;
+            for (const s of v.skipped) {
+                needsAttention.push(`${v.agent}@${v.version}: ${s.kind}/${s.name} (${s.reason})`);
+            }
+        }
+        if (healed > 0)
+            fixed.push(`${healed} resource(s) reconciled`);
+        for (const m of result.repairedManifests) {
+            fixed.push(`plugin ${m.plugin}: dropped ${m.droppedFields.join(', ')}`);
+        }
+        for (const p of result.refreshedPlugins) {
+            fixed.push(`plugin ${p.plugin}: ${p.from} -> ${p.to}`);
+        }
+        for (const s of result.skippedPlugins) {
+            needsAttention.push(`plugin ${s.plugin}: ${s.reason} (${s.from} vs ${s.upstream})`);
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

package/dist/lib/self-heal/checks/shadowing.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const shadowingCheck: HealCheck;

package/dist/lib/self-heal/checks/shadowing.js

@@ -0,0 +1,48 @@
+// shadowing check — when a harness's own launcher shadows our shim on PATH, adopt
+// it (symlink-only, reversible) so version management wins regardless of PATH order.
+// A REAL native binary is never moved — it's surfaced as needsAttention so the
+// interactive layer can inform the user once. POSIX-only (the launcher convention
+// and PATH-order problem are POSIX; Windows resolves via the registry PATH).
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { getPathShadowingExecutable, adoptShadowingLauncher, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { getGlobalDefault } from '../../versions.js';
+export const shadowingCheck = {
+    id: 'shadowing',
+    title: 'Launcher shadowing the version-managed shim',
+    platforms: ['darwin', 'linux'],
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        const needsAttention = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            if (!getGlobalDefault(agent))
+                continue; // only default agents, like the interactive flow
+            const cmd = AGENTS[agent].cliCommand;
+            const shadowedBy = getPathShadowingExecutable(agent);
+            if (!shadowedBy)
+                continue;
+            if (ctx.dryRun) {
+                // Classify without mutating: adoption only ever touches a symlink.
+                let isSymlink = false;
+                try {
+                    const fs = await import('node:fs');
+                    isSymlink = fs.lstatSync(shadowedBy).isSymbolicLink();
+                }
+                catch { /* treat as real binary */ }
+                if (isSymlink)
+                    fixed.push(`${cmd} launcher (${shadowedBy})`);
+                else
+                    needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+                continue;
+            }
+            const res = adoptShadowingLauncher(agent);
+            if (res.adopted)
+                fixed.push(`adopted ${cmd} launcher (${res.launcher})`);
+            else if (res.reason === 'not-a-symlink') {
+                needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+            }
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

package/dist/lib/self-heal/checks/shims.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const shimsCheck: HealCheck;

package/dist/lib/self-heal/checks/shims.js

@@ -0,0 +1,35 @@
+// shims check — keeps the dispatch shims and versioned aliases current, and clears
+// pre-split legacy shim files. Formerly done in the interactive index.ts startup
+// (which PRINTED "Updated <cli> shim" on every run); here it runs silently in the
+// background so the shim schema settles without user-facing churn.
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { ensureShimCurrent, ensureVersionedAliasCurrent, isShimCurrent, isVersionedAliasCurrent, removeLegacyUserShim, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { listInstalledVersions } from '../../versions.js';
+export const shimsCheck = {
+    id: 'shims',
+    title: 'Dispatch shims + versioned aliases',
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            const cmd = AGENTS[agent].cliCommand;
+            if (!isShimCurrent(agent)) {
+                if (!ctx.dryRun)
+                    ensureShimCurrent(agent);
+                fixed.push(`${cmd} shim`);
+            }
+            for (const version of listInstalledVersions(agent)) {
+                if (!isVersionedAliasCurrent(agent, version)) {
+                    if (!ctx.dryRun)
+                        ensureVersionedAliasCurrent(agent, version);
+                    fixed.push(`${cmd}@${version} alias`);
+                }
+            }
+            // Pre-split ~/.agents/shims/<cli> files cause false-positive shadow hits.
+            if (!ctx.dryRun && removeLegacyUserShim(agent))
+                fixed.push(`removed legacy ${cmd} shim`);
+        }
+        return resultOf(fixed, []);
+    },
+};

package/dist/lib/self-heal/registry.d.ts

@@ -0,0 +1,22 @@
+import type { HealCheck, HealCheckId, HealCadence, SelfHealReport } from './types.js';
+export declare const HEAL_CHECKS: HealCheck[];
+export interface SelfHealOptions {
+    /** Restrict to these check ids; omit to run every registered check. */
+    checks?: HealCheckId[];
+    /** Only run checks whose cadence is in this set (daemon scheduling). */
+    cadences?: HealCadence[];
+    /** 'safe' (daemon default) or 'full' (doctor --fix). Default 'safe'. */
+    mode?: 'safe' | 'full';
+    /** Detect only — never write. Default false. */
+    dryRun?: boolean;
+    /** Override the platform gate (tests). Default process.platform. */
+    platform?: NodeJS.Platform;
+}
+/** Run the selected checks, isolating per-check failures. */
+export declare function runSelfHeal(opts?: SelfHealOptions): Promise<SelfHealReport>;
+/** True if any check repaired something (for daemon logging / notification). */
+export declare function selfHealChangedAnything(report: SelfHealReport): boolean;
+/** True if any check surfaced something a human should look at. */
+export declare function selfHealNeedsAttention(report: SelfHealReport): boolean;
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export declare function summarizeSelfHeal(report: SelfHealReport): string;

package/dist/lib/self-heal/registry.js

@@ -0,0 +1,66 @@
+// The self-heal registry + runner.
+//
+// One ordered list of HealChecks; one runner that executes the requested subset,
+// isolating failures (one check throwing never aborts the rest) and aggregating a
+// SelfHealReport. Both front doors — the daemon (by cadence) and `agents doctor`
+// (all, or by id) — call runSelfHeal.
+import { resourcesCheck } from './checks/resources.js';
+import { shimsCheck } from './checks/shims.js';
+import { shadowingCheck } from './checks/shadowing.js';
+import { pathCheck } from './checks/path.js';
+// Order matters: cheap structural fixes (shims, shadow adoption, PATH) before the
+// heavier resource reconciliation, so a freshly-repaired shim is in place first.
+export const HEAL_CHECKS = [
+    shimsCheck,
+    shadowingCheck,
+    pathCheck,
+    resourcesCheck,
+];
+/** Run the selected checks, isolating per-check failures. */
+export async function runSelfHeal(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const ctx = { mode: opts.mode ?? 'safe', dryRun: opts.dryRun ?? false };
+    const selected = HEAL_CHECKS.filter((c) => {
+        if (opts.checks && !opts.checks.includes(c.id))
+            return false;
+        if (opts.cadences && !opts.cadences.includes(c.cadence))
+            return false;
+        if (c.platforms && !c.platforms.includes(platform))
+            return false;
+        return true;
+    });
+    const reports = [];
+    for (const check of selected) {
+        try {
+            const result = await check.run(ctx);
+            reports.push({ id: check.id, title: check.title, result });
+        }
+        catch (err) {
+            reports.push({ id: check.id, title: check.title, result: null, error: err.message });
+        }
+    }
+    return { checks: reports };
+}
+/** True if any check repaired something (for daemon logging / notification). */
+export function selfHealChangedAnything(report) {
+    return report.checks.some((c) => (c.result?.fixed.length ?? 0) > 0);
+}
+/** True if any check surfaced something a human should look at. */
+export function selfHealNeedsAttention(report) {
+    return report.checks.some((c) => (c.result?.needsAttention.length ?? 0) > 0 || Boolean(c.error));
+}
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export function summarizeSelfHeal(report) {
+    const parts = [];
+    for (const c of report.checks) {
+        if (c.error) {
+            parts.push(`${c.id}: error (${c.error})`);
+            continue;
+        }
+        const n = c.result?.fixed.length ?? 0;
+        const a = c.result?.needsAttention.length ?? 0;
+        if (n > 0 || a > 0)
+            parts.push(`${c.id}: ${n} fixed${a > 0 ? `, ${a} to review` : ''}`);
+    }
+    return parts.join('; ') || 'nothing to heal';
+}