@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/agents.js

@@ -15,6 +15,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
+import { needsWindowsShell } from './platform/index.js';
 import { latestFileMtimeMs } from './fs-walk.js';
 import { damerauLevenshtein } from './fuzzy.js';
 import { getCacheDir, getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
@@ -296,6 +297,7 @@ export const AGENTS = {
         commandsDir: '', // OpenClaw uses Gateway-based slash commands, not file-based
         commandsSubdir: '',
         skillsDir: path.join(HOME, '.openclaw', 'skills'),
+        nativeCommandRuntime: true, // Gateway resolves slash commands — don't convert commands to skills
         hooksDir: 'hooks',
         instructionsFile: 'workspace/AGENTS.md', // Primary memory file (also has SOUL.md, IDENTITY.md, etc.)
         format: 'markdown',
@@ -781,6 +783,7 @@ export async function getAccountInfo(agentId, home) {
         usageStatus: null,
         overageCredits: null,
         lastActive: null,
+        signedIn: false,
     };
     const configFiles = {
         claude: path.join(base, '.claude.json'),
@@ -852,6 +855,7 @@ export async function getAccountInfo(agentId, home) {
                     usageStatus,
                     overageCredits,
                     lastActive,
+                    signedIn: !!email,
                 };
             }
             case 'codex': {
@@ -893,11 +897,13 @@ export async function getAccountInfo(agentId, home) {
                     usageStatus,
                     overageCredits: null,
                     lastActive,
+                    signedIn: !!email,
                 };
             }
             case 'gemini': {
                 const data = JSON.parse(await fs.promises.readFile(path.join(base, '.gemini', 'google_accounts.json'), 'utf-8'));
-                return { ...empty, email: data.active || null, lastActive };
+                const email = data.active || null;
+                return { ...empty, email, signedIn: !!email, lastActive };
             }
             case 'grok': {
                 // Grok stores auth in ~/.grok/auth.json
@@ -906,12 +912,44 @@ export async function getAccountInfo(agentId, home) {
                     if (fs.existsSync(authPath)) {
                         const data = JSON.parse(await fs.promises.readFile(authPath, 'utf-8'));
                         const email = data.email || data.user?.email || data.account?.email || null;
-                        return { ...empty, email, lastActive };
+                        return { ...empty, email, signedIn: !!email, lastActive };
                     }
                 }
                 catch { }
                 return { ...empty, lastActive };
             }
+            case 'antigravity': {
+                // Antigravity (`agy`) stores a Google OAuth token at
+                // ~/.gemini/antigravity-cli/antigravity-oauth-token. It's a consumer
+                // OAuth grant (access + refresh token, no id_token), so there's no email
+                // claim to read locally — presence of a refresh token is the only
+                // signed-in signal we can derive without a network call.
+                const tokenPath = path.join(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
+                if (!fs.existsSync(tokenPath))
+                    return { ...empty, lastActive };
+                const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));
+                const hasToken = typeof data?.token?.refresh_token === 'string' && !!data.token.refresh_token;
+                if (!hasToken)
+                    return { ...empty, lastActive };
+                return { ...empty, signedIn: true, lastActive };
+            }
+            case 'kimi': {
+                // Kimi Code stores OAuth credentials at
+                // ~/.kimi-code/credentials/kimi-code.json. The access token is a JWT
+                // whose payload carries an opaque user_id (no email), so we report
+                // signed-in state plus a stable account key for usage dedup.
+                const credPath = path.join(base, '.kimi-code', 'credentials', 'kimi-code.json');
+                if (!fs.existsSync(credPath))
+                    return { ...empty, lastActive };
+                const data = JSON.parse(await fs.promises.readFile(credPath, 'utf-8'));
+                const accessToken = data?.access_token;
+                if (typeof accessToken !== 'string' || !accessToken)
+                    return { ...empty, lastActive };
+                const decoded = decodeJwtPayload(accessToken);
+                const userId = normalizeIdentityPart(decoded?.user_id ?? decoded?.sub);
+                const accountKey = buildIdentityKey(agentId, [['user', userId]]);
+                return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
+            }
             default:
                 return { ...empty, lastActive };
         }
@@ -1150,7 +1188,10 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         }
         // When home is specified, override HOME so MCP config writes to the version's config dir
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execFileAsync(bin, args, env ? { env } : undefined);
+        // On Windows a bare command name / `.cmd` wrapper (the npm-installed agent
+        // CLI) can't be exec'd directly — it needs shell:true for PATHEXT/cmd. Off
+        // Windows this is always false, so the no-shell argv path is unchanged.
+        await execFileAsync(bin, args, { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {
@@ -1169,7 +1210,7 @@ export async function unregisterMcp(agentId, name, options) {
     try {
         const bin = options?.binary || agent.cliCommand;
         const env = options?.home ? { ...process.env, HOME: options.home } : undefined;
-        await execFileAsync(bin, ['mcp', 'remove', name], env ? { env } : undefined);
+        await execFileAsync(bin, ['mcp', 'remove', name], { ...(env ? { env } : {}), shell: needsWindowsShell(bin) });
         return { success: true };
     }
     catch (err) {

package/dist/lib/browser/drivers/ssh.d.ts

@@ -1,11 +1,56 @@
 import { CDPClient } from '../cdp.js';
 import type { BrowserProfile } from '../types.js';
+import { shellQuote } from '../../ssh-exec.js';
+export { shellQuote };
 export interface SSHConnection {
     cdp: CDPClient;
     port: number;
     pid: number;
     cleanup: () => void;
 }
-export declare function shellQuote(s: string): string;
+/**
+ * Which shell dialect the *remote* host speaks. Selected per-endpoint via the
+ * `&os=windows` query param on an `ssh://` target. POSIX is the default — the
+ * historical behavior for macOS/Linux remotes. Windows remotes run OpenSSH
+ * Server with cmd.exe as the default shell, so the launch/teardown command
+ * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
+ */
+export type RemoteOs = 'windows' | 'posix';
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
-export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;
+/**
+ * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
+ * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn
+ * → Windows sshd → cmd.exe with zero escaping hazards (hand-quoted
+ * `powershell -Command "…"` is fragile the moment a path or URL is involved).
+ */
+export declare function encodePowerShell(script: string): string;
+/**
+ * The PowerShell that launches the browser on a Windows remote. Two hard
+ * requirements shaped this:
+ *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
+ *      the session's job tree on disconnect, which reaps both `start /B` and
+ *      `Start-Process` children (verified against a real box). WMI
+ *      `Win32_Process.Create` spawns under the WMI provider service instead,
+ *      so the process survives after we drop the ssh connection and reconnect
+ *      over the CDP tunnel.
+ *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      port comes up even when the user already has Edge open.
+ * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
+ * registry at runtime rather than relying on a bare `msedge` name.
+ */
+export declare function buildWindowsLaunchScript(browserType: string, port: number, customBinary?: string): string;
+/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+export declare function buildWindowsKillScript(port: number): string;
+/**
+ * Build the remote command that launches the browser detached with a CDP port.
+ * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
+ * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ */
+export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string, port: number, customBinary?: string): string;
+/**
+ * Build the remote command that kills whatever holds the CDP port.
+ * POSIX uses `lsof`+`kill`; Windows uses encoded PowerShell
+ * (Get-NetTCPConnection → Stop-Process).
+ */
+export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
+export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;

package/dist/lib/browser/drivers/ssh.js

@@ -4,11 +4,10 @@ import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.j
 import { getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } from '../profiles.js';
 import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
-export function shellQuote(s) {
-    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
-        return s;
-    return "'" + s.replace(/'/g, "'\\''") + "'";
-}
+// shellQuote lives in the shared ssh-exec helper (single choke point); re-export
+// so existing importers of `shellQuote` from this module keep working.
+import { shellQuote } from '../../ssh-exec.js';
+export { shellQuote };
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -24,6 +23,11 @@ export async function connectSSH(endpoint, profile) {
     }
     const host = parsed.host;
     const remotePort = parsed.port;
+    // `&os=windows` switches the remote-command dialect (cmd.exe launch via
+    // `start`, taskkill teardown). Anything else — including absent — is posix.
+    // The query param is the single source of truth so the driver never has to
+    // be threaded a separate per-profile field.
+    const remoteOs = (url.searchParams.get('os') || '').toLowerCase() === 'windows' ? 'windows' : 'posix';
     // Bind the tunnel to the SAME local port the user configured. Using an
     // allocated port instead made `status` print confusing rows like
     // `port 9200 (configured 10005)` and made it impossible to predict which
@@ -40,7 +44,7 @@ export async function connectSSH(endpoint, profile) {
             `Either kill that process (\`kill ${occupant.pid}\`) or change the profile's port.`);
     }
     try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
     }
     catch {
         // Browser may already be running, continue
@@ -156,28 +160,100 @@ function tryConnect(port) {
         socket.on('error', reject);
     });
 }
-async function ensureRemoteBrowser(user, host, browserType, port, customBinary) {
-    const browserPaths = {
-        chrome: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-        comet: '/Applications/Comet.app/Contents/MacOS/Comet',
-        chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
-        brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
-        edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-    };
-    let browserPath;
+// macOS .app launchers — the historical POSIX table.
+const POSIX_BROWSER_PATHS = {
+    chrome: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    comet: '/Applications/Comet.app/Contents/MacOS/Comet',
+    chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+};
+// Windows App Paths registry keys per browser. CreateProcess (used by WMI
+// Win32_Process.Create) does not honor App Paths the way ShellExecute/`start`
+// does, so the launch script resolves the real `.exe` path from this registry
+// key at runtime — covering both Program Files and Program Files (x86)
+// installs without hardcoding (or guessing) the location.
+const WIN_BROWSER_APPPATH = {
+    chrome: 'chrome.exe',
+    chromium: 'chrome.exe',
+    brave: 'brave.exe',
+    edge: 'msedge.exe',
+};
+/** Single-quote a string for embedding inside a PowerShell literal. */
+function psSingleQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
+ * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn
+ * → Windows sshd → cmd.exe with zero escaping hazards (hand-quoted
+ * `powershell -Command "…"` is fragile the moment a path or URL is involved).
+ */
+export function encodePowerShell(script) {
+    const b64 = Buffer.from(script, 'utf16le').toString('base64');
+    return `powershell -NoProfile -EncodedCommand ${b64}`;
+}
+/**
+ * The PowerShell that launches the browser on a Windows remote. Two hard
+ * requirements shaped this:
+ *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
+ *      the session's job tree on disconnect, which reaps both `start /B` and
+ *      `Start-Process` children (verified against a real box). WMI
+ *      `Win32_Process.Create` spawns under the WMI provider service instead,
+ *      so the process survives after we drop the ssh connection and reconnect
+ *      over the CDP tunnel.
+ *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      port comes up even when the user already has Edge open.
+ * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
+ * registry at runtime rather than relying on a bare `msedge` name.
+ */
+export function buildWindowsLaunchScript(browserType, port, customBinary) {
+    let exeExpr;
     if (customBinary) {
-        browserPath = customBinary;
+        exeExpr = psSingleQuote(customBinary);
     }
     else if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
     }
     else {
-        browserPath = browserPaths[browserType];
-        if (!browserPath) {
-            throw new Error(`Unknown browser type: ${browserType}`);
+        const exeKey = WIN_BROWSER_APPPATH[browserType];
+        if (!exeKey)
+            throw new Error(`Unknown browser type for windows remote: ${browserType}`);
+        exeExpr =
+            `(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}').'(default)'`;
+    }
+    // Keep the `--remote-allow-origins=http://127.0.0.1:${port}` literal in
+    // source — a test asserts CDP is never opened to `*`.
+    return [
+        `$exe = ${exeExpr}`,
+        `$cl = '"' + $exe + '" --remote-debugging-port=${port}` +
+            ` --remote-allow-origins=http://127.0.0.1:${port}` +
+            ` --disable-background-timer-throttling --user-data-dir="' + $env:TEMP + '\\agents-browser-${port}"'`,
+        `Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cl } | Out-Null`,
+    ].join('; ');
+}
+/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+export function buildWindowsKillScript(port) {
+    return (`Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue ` +
+        `| ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }`);
+}
+/**
+ * Build the remote command that launches the browser detached with a CDP port.
+ * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
+ * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ */
+export function buildLaunchCmd(remoteOs, browserType, port, customBinary) {
+    if (remoteOs === 'windows') {
+        return encodePowerShell(buildWindowsLaunchScript(browserType, port, customBinary));
+    }
+    const browserPath = customBinary ?? POSIX_BROWSER_PATHS[browserType];
+    if (!browserPath) {
+        if (browserType === 'custom') {
+            throw new Error('browser: custom requires a binary path in the profile');
         }
+        throw new Error(`Unknown browser type for posix remote: ${browserType}`);
     }
-    const remoteCmd = [
+    return [
         shellQuote(browserPath),
         `--remote-debugging-port=${port}`,
         shellQuote(`--remote-allow-origins=http://127.0.0.1:${port}`),
@@ -185,6 +261,20 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         `--user-data-dir=/tmp/agents-browser-${port}`,
         '</dev/null >/dev/null 2>&1 &',
     ].join(' ');
+}
+/**
+ * Build the remote command that kills whatever holds the CDP port.
+ * POSIX uses `lsof`+`kill`; Windows uses encoded PowerShell
+ * (Get-NetTCPConnection → Stop-Process).
+ */
+export function buildKillCmd(remoteOs, port) {
+    if (remoteOs === 'windows') {
+        return encodePowerShell(buildWindowsKillScript(port));
+    }
+    return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
+}
+async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+    const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
         const child = spawn('ssh', [
             `${user}@${host}`,
@@ -200,12 +290,11 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         }, 2000);
     });
 }
-export async function restartRemoteBrowser(user, host, browserType, port, customBinary) {
+export async function restartRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
     // Kill any process using the remote debugging port
-    const killCmd = `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
-    await runSSHCommand(user, host, killCmd);
+    await runSSHCommand(user, host, buildKillCmd(remoteOs, port));
     await sleep(500);
-    await ensureRemoteBrowser(user, host, browserType, port, customBinary);
+    await ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary);
     await sleep(1500);
 }
 function runSSHCommand(user, host, cmd) {

package/dist/lib/browser/profiles.js

@@ -194,6 +194,27 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
+/**
+ * True when any endpoint is an `ssh://…?os=windows` target — i.e. the browser
+ * lives on a remote Windows host. Such a profile's binary (`msedge.exe`) will
+ * never exist on this Mac, so create-time local-binary validation must be
+ * skipped; the binary is resolved on the remote at connect time instead.
+ */
+function hasRemoteWindowsEndpoint(endpoints) {
+    const targets = Array.isArray(endpoints)
+        ? endpoints
+        : Object.values(endpoints).map((preset) => preset.target);
+    return targets.some((target) => {
+        try {
+            const url = new URL(target);
+            return (url.protocol === 'ssh:' &&
+                (url.searchParams.get('os') || '').toLowerCase() === 'windows');
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export async function createProfile(profile) {
     const meta = readMeta();
     if (meta.browser?.[profile.name]) {
@@ -220,7 +241,13 @@ export async function createProfile(profile) {
     // error ("Comet not installed at /Applications/Comet.app") rather than
     // deferring the failure to the first task. `findBrowserPath` short-circuits
     // for browser=custom without a binary by throwing — same outcome.
-    findBrowserPath(profile.browser, profile.binary);
+    //
+    // Skip for remote-Windows profiles: the browser is `msedge.exe` on the
+    // remote box, never on this Mac, so a local lookup would always (wrongly)
+    // fail. The remote launcher resolves it at connect time via App Paths.
+    if (!hasRemoteWindowsEndpoint(profile.endpoints)) {
+        findBrowserPath(profile.browser, profile.binary);
+    }
     meta.browser = meta.browser ?? {};
     meta.browser[profile.name] = profileToConfig(profile);
     writeMeta(meta);

package/dist/lib/browser/runtime-state.js

@@ -248,20 +248,40 @@ export function reapOrphanedProcesses() {
     return { reaped, details };
 }
 function matchesCommand(pid, expectedCommand) {
+    const out = liveProcessCommand(pid);
+    if (!out)
+        return false;
+    // Match on the basename only — `/Applications/Comet.app/Contents/MacOS/Comet`
+    // vs the recorded `Comet`, vs `Google\ Chrome`, vs Windows `chrome.exe`.
+    // Case-insensitive.
+    const live = path.basename(out).toLowerCase();
+    const want = path.basename(expectedCommand).toLowerCase();
+    return live === want || live.startsWith(want) || want.startsWith(live);
+}
+/**
+ * The executable/image name the live `pid` is running, or null if it can't be
+ * determined. The process-listing API differs per OS: Windows has no `ps`, so
+ * we query `tasklist` (CSV image name in column 1); POSIX uses `ps -o comm=`.
+ */
+function liveProcessCommand(pid) {
     try {
+        if (process.platform === 'win32') {
+            const out = execFileSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            // Rows look like: "node.exe","1234","Console","1","12,345 K"
+            // A no-match prints an "INFO: No tasks..." line that won't match the regex.
+            const m = out.match(/^"([^"]+)"/);
+            return m ? m[1] : null;
+        }
         const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();
-        if (!out)
-            return false;
-        // Match on the basename only — `/Applications/Comet.app/Contents/MacOS/Comet`
-        // vs the recorded `Comet`, vs `Google\ Chrome`. Case-insensitive.
-        const live = path.basename(out).toLowerCase();
-        const want = path.basename(expectedCommand).toLowerCase();
-        return live === want || live.startsWith(want) || want.startsWith(live);
+        return out || null;
     }
     catch {
-        return false;
+        return null;
     }
 }

package/dist/lib/browser/types.d.ts

@@ -7,7 +7,16 @@ export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge' | '
  * Per-endpoint overrides take precedence over profile-level fields.
  */
 export interface EndpointPreset {
-    /** CDP URL — `cdp://host:port` or `ssh://host?port=N` */
+    /**
+     * CDP URL — `cdp://host:port` or `ssh://host?port=N`.
+     *
+     * For an SSH target whose remote is Windows, append `&os=windows` (e.g.
+     * `ssh://user@host?port=9222&os=windows`). The driver then speaks the
+     * Windows dialect (launch via WMI Win32_Process.Create so the browser
+     * survives the ssh session, teardown via Get-NetTCPConnection/Stop-Process)
+     * instead of the POSIX default. The query param is the single source of
+     * truth for remote-OS selection.
+     */
     target: string;
     /** Override the profile-level binary (e.g. a remote host has no local binary). */
     binary?: string;

package/dist/lib/cli-resources.js

@@ -116,7 +116,16 @@ export function parseCheckSpec(raw, defaultName) {
  * decide whether to surface or swallow the error per file.
  */
 export function parseCliManifest(contents, opts) {
-    const raw = yaml.parse(contents);
+    // Tolerant parse. A manifest may legitimately carry OS-specific strings — a
+    // Windows path like `C:\Users\...` embedded in a double-quoted YAML scalar
+    // trips YAML's escape rules (`\U` is an invalid escape) and makes the strict
+    // `yaml.parse` throw a parser error. That throw must NOT pre-empt the
+    // security validation below: the per-field allowlist checks (unsafe tokens,
+    // non-https URLs, path traversal) are the authoritative gate on a hostile
+    // manifest. parseDocument collects those escape errors instead of throwing
+    // and still recovers the scalar values, so the dangerous content reaches
+    // assertSafeCheckToken / assertNpmPackage and is rejected on its merits.
+    const raw = yaml.parseDocument(contents, { strict: false }).toJS();
     if (!raw || typeof raw !== 'object') {
         throw new Error('manifest must be a YAML object');
     }

package/dist/lib/daemon.js

@@ -260,6 +260,36 @@ export async function runDaemon() {
     };
     const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
     void runSessionSync(); // kick once at startup
+    // Resource safety check: heal gaps between what DotAgents repos define and
+    // what's actually installed in each agent home — the slow rot that nothing
+    // else catches (a non-default version left stale, a Claude-invalid plugin
+    // manifest silently rejecting a whole plugin). Conservative 'safe' mode: it
+    // fills missing resources, repairs invalid manifests, and fast-forwards
+    // provably-unmodified stale plugins, but never overwrites hand-edited content
+    // or a plugin it can't prove is pristine — those it reports for `doctor --fix`.
+    // Runs ~every 6h plus once ~30s after startup (staggered so launch isn't busy).
+    let healing = false;
+    const runHealCheck = async () => {
+        if (healing)
+            return;
+        healing = true;
+        try {
+            const { heal, summarizeHeal, notifyHeal, healChangedAnything } = await import('./heal.js');
+            const result = await heal({ mode: 'safe' });
+            if (healChangedAnything(result) || result.skippedPlugins.length > 0) {
+                log('INFO', `heal: ${summarizeHeal(result)}`);
+                notifyHeal(result);
+            }
+        }
+        catch (err) {
+            log('ERROR', `heal check failed: ${err.message}`);
+        }
+        finally {
+            healing = false;
+        }
+    };
+    const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
+    const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -275,6 +305,8 @@ export async function runDaemon() {
         await browserIPC.stop();
         clearInterval(monitorInterval);
         clearInterval(syncInterval);
+        clearInterval(healInterval);
+        clearTimeout(healKickoff);
         removeDaemonPid();
         process.exit(0);
     };

package/dist/lib/doctor-diff.d.ts

@@ -20,6 +20,7 @@
  *     against the compiled artifact, not the raw source file.
  */
 import type { AgentId } from './types.js';
+import type { DiscoveredPlugin } from './types.js';
 export type DoctorKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'promptcuts';
 export type DiffStatus = 'ok' | 'diff' | 'missing' | 'extra';
 export type SourceLayer = 'project' | 'user' | 'system' | 'extra';
@@ -32,6 +33,9 @@ export interface ResourceDiff {
     sourcePath?: string;
     /** Absolute path to the file/dir inside the version home (when present). */
     homePath?: string;
+    /** Human-readable specifics for a divergent row — e.g. for a stale plugin:
+     *  "0.6.1→0.7.0, missing skills: ship, learn". Currently set for plugins. */
+    detail?: string;
 }
 export interface VersionResourceReport {
     agent: AgentId;
@@ -55,10 +59,25 @@ export interface VersionResourceReport {
         extra: number;
     };
 }
+/**
+ * Describe how a version's marketplace MIRROR of a plugin diverges from its
+ * central source — the detail presence-only checks miss. Surfaces a stale mirror
+ * version, a Claude-invalid manifest, and (the part users care about) the
+ * plugin's own skills/commands that never made it into the mirror. Returns null
+ * when the mirror faithfully matches source.
+ */
+export declare function describePluginDrift(central: DiscoveredPlugin, mirrorDir: string): string | null;
 export interface DiffOptions {
     cwd?: string;
     /** Restrict to specific kinds; undefined = all. */
     kinds?: DoctorKind[];
+    /**
+     * Drop the project (`<cwd>/.agents/`) layer from resolution. Used by the heal
+     * path: the GLOBAL version home is only ever reconciled against user/system/
+     * extra sources — project resources are layered at launch, never synced into
+     * the global home, so counting them as "missing" there is a false gap.
+     */
+    excludeProject?: boolean;
 }
 export declare function diffVersionResources(agent: AgentId, version: string, options?: DiffOptions): VersionResourceReport;
 export declare const DOCTOR_ALL_KINDS: DoctorKind[];