aquaman-proxy 0.12.0 → 0.13.0

package/README.md

@@ -1,6 +1,6 @@
 # aquaman-proxy
 
-The vault + daemon + audit core of [aquaman](https://github.com/tech4242/aquaman). API key protection for AI agents — credentials stay in your vault, never in the agent's memory.
+The vault + daemon + audit core of [aquaman](https://github.com/tech4242/aquaman). API key protection for AI agents. Bring your own vault. Credentials stay where you already keep them, never in the agent's memory.
 
 This is the **always-on piece**: every other aquaman package (`aquaman-plugin` for OpenClaw, `aquaman-coder` for AI coding agents) talks to it. If you only install one aquaman package, install this one.
 
@@ -8,7 +8,7 @@ This is the **always-on piece**: every other aquaman package (`aquaman-plugin` f
 Agent / OpenClaw / Coding Agent              Aquaman Proxy
 ┌──────────────────────┐                     ┌──────────────────────┐
 │                      │                     │                      │
-│  ANTHROPIC_BASE_URL  │═══════ UDS ════════>│  Keychain / 1Pass /  │
+│  ANTHROPIC_BASE_URL  │════ UDS / HTTP ════>│  Keychain / 1Pass /  │
 │  = aquaman.local     │                     │  Vault / Encrypted   │
 │                      │<══════════════════  │                      │
 │  fetch() interceptor │═══ broker:resolve ═>│  + Policy enforced   │
@@ -57,16 +57,16 @@ aquaman daemon &        # start the proxy on ~/.aquaman/proxy.sock
 
 Four layers of protection:
 
-- **Process isolation** — credentials in a separate address space, connected via UDS (`chmod 0o600`)
-- **Service allowlisting** — `proxiedServices` controls which APIs the agent can reach
-- **Request policies** — method + path rules per service, checked *before* credential injection ([details in the root README](https://github.com/tech4242/aquaman#request-policies))
-- **Audit trail** — SHA-256 hash-chained logs of every credential use
+- **Process isolation**: credentials in a separate address space, connected via UDS (`chmod 0o600`)
+- **Service allowlisting**: `proxiedServices` controls which APIs the agent can reach
+- **Request policies**: method + path rules per service, checked *before* credential injection ([details in the root README](https://github.com/tech4242/aquaman#request-policies))
+- **Audit trail**: SHA-256 hash-chained logs of every credential use
 
-7 credential backends: Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file.
+**Bring your own vault.** Aquaman has no house vault. It injects credentials from the secret store you already run: Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, or encrypted-file. No new store to adopt, no migration.
 
 ## Broker endpoint (v0.12.0+)
 
-`POST /broker/resolve` over the UDS — used by `aquaman-coder` to materialize credentials per tool call. Body:
+`POST /broker/resolve` over the UDS - used by `aquaman-coder` to materialize credentials per tool call. Body:
 
 ```json
 {"service":"anthropic","key":"api_key","ttl_seconds":60}
@@ -76,10 +76,10 @@ Response: `{"value":"...","expires_at":"2026-05-20T12:34:56Z"}`. Validates servi
 
 ## Documentation
 
-- **[Root README](https://github.com/tech4242/aquaman#readme)** — value prop, three-path Quick Start, security model
-- **[`docs/PACKAGES.md`](../../docs/PACKAGES.md)** — package boundary policy
-- **[`docs/compliance/`](../../docs/compliance/)** — MITRE ATLAS + NIST SP 800-53 mappings
-- **[`CLAUDE.md`](../../CLAUDE.md)** — architecture notes
+- **[Root README](https://github.com/tech4242/aquaman#readme)**: value prop, three-path Quick Start, security model
+- **[`docs/PACKAGES.md`](../../docs/PACKAGES.md)**: package boundary policy
+- **[`docs/compliance/`](../../docs/compliance/)**: MITRE ATLAS + NIST SP 800-53 mappings
+- **[`CLAUDE.md`](../../CLAUDE.md)**: architecture notes
 
 ## License
 

package/dist/cli/index.js

@@ -12,11 +12,12 @@ import { Command, Help } from 'commander';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
-import { loadConfig, getConfigDir, ensureConfigDir, getDefaultConfig, expandPath, createAuditLogger, createCredentialStore, saveConfig } from '../core/index.js';
+import { loadConfig, getConfigDir, ensureConfigDir, getDefaultConfig, expandPath, createAuditLogger, createCredentialStore, saveConfig, generateLoopbackToken, DEFAULT_LOOPBACK_PORT } from '../core/index.js';
 import { fileURLToPath } from 'node:url';
 import { createCredentialProxy } from '../daemon.js';
 import { createServiceRegistry, ServiceRegistry } from '../service-registry.js';
-import { createOpenClawIntegration } from '../openclaw/integration.js';
+import { createOpenClawIntegration, authProfilesAreSqliteOnly } from '../openclaw/integration.js';
+import { createHermesIntegration, detectHermes } from '../hermes/integration.js';
 import { loadPolicyFromConfig, validatePolicyConfig, getDefaultPolicyPresets, matchPolicy } from '../request-policy.js';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 // Read version from package.json (single source of truth)
@@ -37,6 +38,38 @@ function validateCredName(label, value) {
         process.exit(1);
     }
 }
+/**
+ * Build loopback listener options from config for the daemon. Returns undefined
+ * unless the loopback listener is explicitly enabled. If it's enabled but no
+ * token is configured we refuse to start the listener (an unauthenticated
+ * loopback proxy would be an open credential gateway for any local process) and
+ * print how to fix it — the UDS proxy still starts normally.
+ */
+function loadLoopbackOptions(config) {
+    const lb = config.loopback;
+    if (!lb?.enabled)
+        return undefined;
+    if (!lb.token) {
+        console.error('Loopback listener is enabled but no token is set — refusing to start it (would be unauthenticated).');
+        console.error('Fix: run `aquaman hermes setup` to generate one, or set AQUAMAN_LOOPBACK_TOKEN.');
+        return undefined;
+    }
+    return { port: lb.port || DEFAULT_LOOPBACK_PORT, token: lb.token, host: lb.host || '127.0.0.1' };
+}
+/**
+ * Probe the loopback listener's /_health endpoint (no token required). Returns
+ * true if it responds 200 within a short timeout, false otherwise.
+ */
+function probeLoopbackHealth(host, port, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const req = http.get({ host, port, path: '/_health', timeout: timeoutMs }, (res) => {
+            res.resume();
+            resolve(res.statusCode === 200);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
 // PID file management
 const getPidFile = () => path.join(getConfigDir(), 'daemon.pid');
 const writePidFile = () => {
@@ -108,7 +141,7 @@ async function promptSecretInput(prompt) {
 const program = new Command();
 program
     .name('aquaman')
-    .description('Credential isolation for AI agents \u2014 vault for the proxy core, OpenClaw plugin path, coding-agent adapter path')
+    .description('Credential isolation for AI agents \u2014 vault for the proxy core, OpenClaw plugin path, coding-agent adapter path, Hermes loopback path')
     .version(VERSION)
     .configureHelp({
     subcommandTerm(cmd) {
@@ -200,6 +233,21 @@ program
             lines.push(`  ${'(delegates to the aquaman-coder binary; install: npm install -g aquaman-coder)'}`);
             lines.push('');
         }
+        // --- Hermes namespace (nested) ---
+        const hm = byName.get('hermes');
+        if (hm) {
+            lines.push(aqua('Hermes integration'));
+            const hmOrder = ['setup', 'doctor', 'status', 'configure'];
+            const hmSubs = helper.visibleCommands(hm).filter((s) => s.name() !== 'help');
+            const hmSorted = [
+                ...hmOrder.map((n) => hmSubs.find((s) => s.name() === n)).filter(Boolean),
+                ...hmSubs.filter((s) => !hmOrder.includes(s.name())),
+            ];
+            for (const sub of hmSorted) {
+                lines.push(renderRow(`hermes ${sub.name()}`, sub.description() || ''));
+            }
+            lines.push('');
+        }
         // --- Other ---
         const helpCmd = byName.get('help');
         if (helpCmd) {
@@ -349,6 +397,37 @@ program
         console.log(`      Your coding agents (Claude Code, Codex, \u2026) could use the same`);
         console.log(`      vault protection. Install: ${aqua('npm install -g aquaman-coder')}`);
     }
+    // Hermes integration
+    const hermesStateDir = process.env['HERMES_HOME'] || path.join(os.homedir(), '.hermes');
+    let hermesDetected = false;
+    try {
+        const { execSync } = await import('node:child_process');
+        execSync('which hermes', { stdio: 'pipe' });
+        hermesDetected = true;
+    }
+    catch { /* */ }
+    if (!hermesDetected)
+        hermesDetected = fs.existsSync(hermesStateDir);
+    console.log('');
+    console.log(`  ${aqua('Hermes integration')}`);
+    if (!hermesDetected) {
+        console.log(`    \u2022 not detected (skipping \u2014 only relevant if you run the Hermes agent host)`);
+    }
+    else {
+        let loopbackEnabled = false;
+        try {
+            loopbackEnabled = loadConfig().loopback?.enabled === true;
+        }
+        catch { /* */ }
+        if (loopbackEnabled) {
+            console.log(`    \u2713 loopback listener enabled   (deep: ${aqua('aquaman hermes doctor')})`);
+        }
+        else {
+            console.log(`    \u2022 not configured`);
+            console.log(`      Isolate Hermes' provider keys via an opt-in loopback listener.`);
+            console.log(`      Run: ${aqua('aquaman hermes setup')}`);
+        }
+    }
     console.log('');
     if (issues === 0) {
         console.log('  All baseline checks passed.');
@@ -619,6 +698,7 @@ openclaw
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -773,6 +853,7 @@ program
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig: policyConfig2,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -852,6 +933,7 @@ openclaw
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig: policyConfig3,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -914,6 +996,247 @@ openclaw
         console.log(`Configuration written to: ${result}`);
     }
 });
+// ── aquaman hermes … — Hermes integration via loopback listener ──
+const hermes = program
+    .command('hermes')
+    .description('Hermes integration via opt-in loopback listener');
+/** Mask a loopback token for display: keep the prefix + last 4 chars. */
+function maskToken(token) {
+    if (token.length <= 12)
+        return '****';
+    return `${token.slice(0, 7)}…${token.slice(-4)}`;
+}
+// hermes setup — enable loopback listener, generate token, wire ~/.hermes/.env
+hermes
+    .command('setup')
+    .description('Enable the loopback listener, generate a token, and wire ~/.hermes/.env for Hermes')
+    .option('--port <port>', 'Loopback listener port')
+    .option('--dry-run', 'Show what would change without writing')
+    .option('--no-write', 'Configure the proxy but do not write ~/.hermes/.env')
+    .action(async (options) => {
+    const config = loadConfig();
+    // Resolve port: flag > existing config > default.
+    let port = config.loopback?.port || DEFAULT_LOOPBACK_PORT;
+    if (options.port) {
+        const p = Number(options.port);
+        if (!Number.isInteger(p) || p <= 0 || p >= 65536) {
+            console.error(`Invalid --port: ${options.port}`);
+            process.exit(1);
+        }
+        port = p;
+    }
+    const host = config.loopback?.host || '127.0.0.1';
+    const token = config.loopback?.token || generateLoopbackToken();
+    // Which services get wired (anthropic/openai today).
+    const integration = createHermesIntegration({
+        port, token, host,
+        services: config.credentials.proxiedServices,
+        config: config.hermes,
+    });
+    const wired = integration.wiredServices();
+    const env = integration.configureHermes();
+    if (wired.length === 0) {
+        console.log('No Hermes-supported services (anthropic, openai) are in your proxiedServices list.');
+        console.log('Add one with: aquaman credentials add anthropic api_key');
+    }
+    if (options.dryRun) {
+        console.log('Dry run — would apply this configuration:\n');
+        console.log(`  Loopback listener: http://${host}:${port}  (enabled)`);
+        console.log(`  Token:             ${maskToken(token)}`);
+        console.log(`  Wired services:    ${wired.join(', ') || '(none)'}`);
+        console.log(`  ~/.hermes/.env:    ${integration.envPath()}`);
+        console.log('\nEnv vars:');
+        console.log(integration.getEnvForDisplay());
+        return;
+    }
+    // Persist loopback config (enabled + port + token + host).
+    config.loopback = { enabled: true, port, host, token };
+    saveConfig(config);
+    console.log(`✓ Loopback listener enabled on http://${host}:${port} (saved to ${path.join(getConfigDir(), 'config.yaml')})`);
+    if (options.write !== false) {
+        const dest = integration.writeConfiguration(env);
+        console.log(`✓ Wrote Hermes env block to ${dest}`);
+    }
+    else {
+        console.log('Skipped writing ~/.hermes/.env (--no-write). Env vars:');
+        console.log(integration.getEnvForDisplay());
+    }
+    const info = await detectHermes(config.hermes?.binaryPath || 'hermes');
+    console.log('');
+    if (info.installed) {
+        console.log(`✓ Hermes detected (v${info.version})`);
+    }
+    else {
+        console.log('• Hermes CLI not found on PATH. Install: uv tool install hermes-agent');
+    }
+    console.log('\nNext steps:');
+    console.log(`  1. Add credentials:  ${aqua('aquaman credentials add anthropic api_key')}`);
+    console.log(`  2. Start the daemon: ${aqua('aquaman daemon')}`);
+    console.log(`  3. Verify:           ${aqua('aquaman hermes doctor')}`);
+});
+// hermes status — loopback config + env file + Hermes detection (overview)
+hermes
+    .command('status')
+    .description('Show loopback listener config, ~/.hermes/.env wiring, and Hermes detection')
+    .action(async () => {
+    const config = loadConfig();
+    const lb = config.loopback;
+    console.log('Hermes integration status\n');
+    if (lb?.enabled) {
+        console.log(`  Loopback listener: ${aqua('enabled')}  http://${lb.host || '127.0.0.1'}:${lb.port || DEFAULT_LOOPBACK_PORT}`);
+        console.log(`  Token:             ${lb.token ? maskToken(lb.token) : aqua('MISSING — run: aquaman hermes setup')}`);
+    }
+    else {
+        console.log(`  Loopback listener: disabled  (enable with: ${aqua('aquaman hermes setup')})`);
+    }
+    const integration = createHermesIntegration({
+        port: lb?.port || DEFAULT_LOOPBACK_PORT,
+        token: lb?.token || '',
+        host: lb?.host || '127.0.0.1',
+        services: config.credentials.proxiedServices,
+        config: config.hermes,
+    });
+    console.log(`  Wired services:    ${integration.wiredServices().join(', ') || '(none)'}`);
+    const envPath = integration.envPath();
+    let envWired = false;
+    try {
+        envWired = fs.existsSync(envPath) && fs.readFileSync(envPath, 'utf-8').includes('aquaman managed');
+    }
+    catch { /* unreadable */ }
+    console.log(`  ~/.hermes/.env:    ${envWired ? aqua('wired') : 'not wired'}  (${envPath})`);
+    const info = await detectHermes(config.hermes?.binaryPath || 'hermes');
+    console.log(`  Hermes CLI:        ${info.installed ? aqua(`v${info.version}`) : 'not found'}`);
+    // Live liveness probe of the loopback listener (no token needed for _health).
+    if (lb?.enabled) {
+        const alive = await probeLoopbackHealth(lb.host || '127.0.0.1', lb.port || DEFAULT_LOOPBACK_PORT);
+        console.log(`  Listener:          ${alive ? aqua('responding') : 'not responding (is the daemon running?)'}`);
+    }
+});
+// hermes doctor — deep diagnostic; exit 1 on any failure
+hermes
+    .command('doctor')
+    .description('Deep diagnostic — loopback config, listener reachability, env wiring, per-service vault credentials')
+    .action(async () => {
+    const config = loadConfig();
+    const lb = config.loopback;
+    let ok = true;
+    const fail = (msg) => { ok = false; console.log(`  ✗ ${msg}`); };
+    const pass = (msg) => console.log(`  ✓ ${msg}`);
+    console.log('Hermes integration diagnostic\n');
+    // 1. Loopback enabled + token present
+    if (!lb?.enabled) {
+        fail('Loopback listener is disabled — run: aquaman hermes setup');
+    }
+    else {
+        pass(`Loopback listener enabled (http://${lb.host || '127.0.0.1'}:${lb.port || DEFAULT_LOOPBACK_PORT})`);
+        if (!lb.token)
+            fail('Loopback token missing — run: aquaman hermes setup');
+        else
+            pass('Loopback token configured');
+    }
+    // 2. Listener reachable
+    if (lb?.enabled) {
+        const alive = await probeLoopbackHealth(lb.host || '127.0.0.1', lb.port || DEFAULT_LOOPBACK_PORT);
+        if (alive)
+            pass('Loopback listener responding to /_health');
+        else
+            fail('Loopback listener not responding — start the daemon: aquaman daemon');
+    }
+    // 3. ~/.hermes/.env wired
+    const integration = createHermesIntegration({
+        port: lb?.port || DEFAULT_LOOPBACK_PORT,
+        token: lb?.token || '',
+        host: lb?.host || '127.0.0.1',
+        services: config.credentials.proxiedServices,
+        config: config.hermes,
+    });
+    const envPath = integration.envPath();
+    try {
+        if (fs.existsSync(envPath) && fs.readFileSync(envPath, 'utf-8').includes('aquaman managed')) {
+            pass(`~/.hermes/.env has the aquaman block (${envPath})`);
+        }
+        else {
+            fail(`~/.hermes/.env not wired — run: aquaman hermes setup`);
+        }
+    }
+    catch {
+        fail(`Could not read ${envPath}`);
+    }
+    // 4. Per-service vault credentials resolve
+    const wired = integration.wiredServices();
+    if (wired.length === 0) {
+        fail('No Hermes-supported services configured (anthropic, openai)');
+    }
+    else {
+        try {
+            const store = await createCredentialStore({
+                backend: config.credentials.backend,
+                encryptionPassword: config.credentials.encryptionPassword,
+                vaultAddress: config.credentials.vaultAddress,
+                vaultToken: config.credentials.vaultToken,
+                vaultNamespace: config.credentials.vaultNamespace,
+                vaultMountPath: config.credentials.vaultMountPath,
+                onePasswordVault: config.credentials.onePasswordVault,
+                onePasswordAccount: config.credentials.onePasswordAccount,
+                keepassxcDatabasePath: config.credentials.keepassxcDatabasePath,
+                keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
+                bitwardenFolder: config.credentials.bitwardenFolder,
+                bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
+                bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            });
+            for (const svc of wired) {
+                const val = await store.get(svc, 'api_key');
+                if (val)
+                    pass(`Vault credential ${svc}/api_key resolves`);
+                else
+                    fail(`No credential for ${svc}/api_key — run: aquaman credentials add ${svc} api_key`);
+            }
+        }
+        catch (err) {
+            fail(`Vault backend "${config.credentials.backend}" failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // 5. Hermes installed
+    const info = await detectHermes(config.hermes?.binaryPath || 'hermes');
+    if (info.installed)
+        pass(`Hermes CLI installed (v${info.version})`);
+    else
+        console.log('  • Hermes CLI not found on PATH (install: uv tool install hermes-agent)');
+    console.log('');
+    console.log(ok ? aqua('All checks passed.') : 'Some checks failed — see above.');
+    process.exit(ok ? 0 : 1);
+});
+// hermes configure — emit/write the Hermes env vars without touching daemon config
+hermes
+    .command('configure')
+    .description('Generate the Hermes env vars (base URLs + placeholder key) for ~/.hermes/.env')
+    .option('--method <method>', 'Output method: env (display) or dotenv (write ~/.hermes/.env)', 'env')
+    .option('--dry-run', 'Show configuration without writing')
+    .action(async (options) => {
+    const config = loadConfig();
+    const lb = config.loopback;
+    if (!lb?.token) {
+        console.error('No loopback token configured. Run `aquaman hermes setup` first.');
+        process.exit(1);
+    }
+    const integration = createHermesIntegration({
+        port: lb.port || DEFAULT_LOOPBACK_PORT,
+        token: lb.token,
+        host: lb.host || '127.0.0.1',
+        services: config.credentials.proxiedServices,
+        config: { configMethod: options.method === 'dotenv' ? 'dotenv' : 'env', binaryPath: config.hermes?.binaryPath },
+    });
+    const env = integration.configureHermes();
+    if (options.dryRun || options.method !== 'dotenv') {
+        console.log('Hermes env vars (add to ~/.hermes/.env):\n');
+        for (const [k, v] of Object.entries(env))
+            console.log(`${k}=${v}`);
+    }
+    else {
+        const dest = integration.writeConfiguration(env);
+        console.log(`Configuration written to: ${dest}`);
+    }
+});
 // Init command
 program
     .command('init')
@@ -1363,6 +1686,26 @@ openclaw
                     fs.mkdirSync(profilesDir, { recursive: true, mode: 0o700 });
                     fs.writeFileSync(profilesPath, JSON.stringify({ version: 1, profiles, order }, null, 2), { mode: 0o600 });
                     console.log('  \u2713 Auth profiles generated at ' + profilesPath);
+                    // OpenClaw >= 2026.6.5 reads provider auth profiles from each agent's
+                    // openclaw-agent.sqlite, not auth-profiles.json (openclaw/openclaw#89102).
+                    // The placeholder above must be imported into SQLite once with
+                    // `openclaw doctor --fix`. We deliberately do NOT auto-run that here:
+                    // it is OpenClaw's broad config-healing command \u2014 verified to take
+                    // ~19s (gateway probes) and to rewrite openclaw.json (it reset our
+                    // plugin entry to bundled defaults in testing). `aquaman openclaw
+                    // doctor` detects the SQLite-only case and prints the import step so
+                    // the operator runs it intentionally. Holistic fix (SecretRef
+                    // provider manifest) is tracked for the next plugin touch.
+                    let ocVersion = null;
+                    try {
+                        const { execSync } = await import('node:child_process');
+                        ocVersion = execSync('openclaw --version', { stdio: 'pipe', encoding: 'utf-8', timeout: 5000 }).trim();
+                    }
+                    catch { /* CLI not on PATH */ }
+                    if (authProfilesAreSqliteOnly(ocVersion)) {
+                        console.log('  \u2192 OpenClaw \u2265 2026.6.5 reads auth profiles from SQLite; import the placeholder once:');
+                        console.log('      openclaw doctor --fix    (backs up openclaw.json first; see aquaman openclaw doctor)');
+                    }
                 }
             }
         }
@@ -1602,6 +1945,7 @@ openclaw
     }
     // 6. OpenClaw detection
     let openclawDetected = false;
+    let openclawVersion = null;
     let cliFound = false;
     try {
         const { execSync } = await import('node:child_process');
@@ -1613,6 +1957,7 @@ openclaw
         try {
             const { execSync } = await import('node:child_process');
             const ver = execSync('openclaw --version', { stdio: 'pipe', encoding: 'utf-8', timeout: 5000 }).trim();
+            openclawVersion = ver;
             console.log(`  \u2713 ${aqua('OpenClaw')} installed (${ver})`);
         }
         catch {
@@ -1695,9 +2040,31 @@ openclaw
                 // openclaw.json invalid — already reported above
             }
         }
-        // 9. Auth profiles exist
-        const profilesPath = path.join(openclawStateDir, 'agents', 'main', 'agent', 'auth-profiles.json');
-        if (fs.existsSync(profilesPath)) {
+        // 9. Auth profiles. OpenClaw >= 2026.6.5 reads provider auth profiles from
+        //    each agent's openclaw-agent.sqlite and no longer reads
+        //    auth-profiles.json at runtime (openclaw/openclaw#89102). On those
+        //    versions the placeholder the plugin writes to the JSON file must be
+        //    imported into SQLite once via `openclaw doctor --fix`.
+        const agentDir = path.join(openclawStateDir, 'agents', 'main', 'agent');
+        const profilesPath = path.join(agentDir, 'auth-profiles.json');
+        const sqlitePath = path.join(agentDir, 'openclaw-agent.sqlite');
+        if (authProfilesAreSqliteOnly(openclawVersion)) {
+            if (fs.existsSync(profilesPath)) {
+                console.log(`  \u2717 ${aqua('Auth profiles')} JSON present but ${openclawVersion} reads from SQLite`);
+                console.log('    \u2192 Import the placeholder once: openclaw doctor --fix  (backs up openclaw.json first)');
+                console.log('      (OpenClaw \u2265 2026.6.5 dropped the runtime auth-profiles.json read path \u2014 openclaw/openclaw#89102)');
+                issues++;
+            }
+            else if (fs.existsSync(sqlitePath)) {
+                console.log(`  \u2713 ${aqua('Auth profiles')} (SQLite store present; OpenClaw \u2265 2026.6.5)`);
+            }
+            else {
+                console.log(`  \u2717 ${aqua('Auth profiles')} missing (no SQLite store found)`);
+                console.log('    \u2192 Run: aquaman setup, then: openclaw doctor --fix');
+                issues++;
+            }
+        }
+        else if (fs.existsSync(profilesPath)) {
             console.log(`  \u2713 ${aqua('Auth profiles')} exist`);
         }
         else {