aquaman-proxy 0.12.1 → 0.13.1

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   │
@@ -18,7 +18,7 @@ Agent / OpenClaw / Coding Agent              Aquaman Proxy
 │  No credentials.     │  proxy.sock         │                      │
 │  No open ports.      │  (chmod 0o600)      │                      │
 │  Nothing to steal.   │                     │                      │
-└──────────────────────┘                     └───┬──────────┬───────┘
+└──────────────────────┘                     └──┬──────────┬────────┘
                                                 │          │
                                                 │          ▼
                                                 │  ~/.aquaman/audit/
@@ -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,13 @@ 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, wrapWithCache, resolveCacheTtl } from '../core/index.js';
 import { fileURLToPath } from 'node:url';
 import { createCredentialProxy } from '../daemon.js';
 import { createServiceRegistry, ServiceRegistry } from '../service-registry.js';
 import { createOpenClawIntegration, authProfilesAreSqliteOnly } from '../openclaw/integration.js';
+import { createHermesIntegration, detectHermes } from '../hermes/integration.js';
+import { managedScopeShadowedKeys, HERMES_MANAGED_ENV_PATH } from '../hermes/config-writer.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 +39,81 @@ function validateCredName(label, value) {
         process.exit(1);
     }
 }
+/**
+ * Soft hint for 1Password users running in biometric/desktop-app mode: every
+ * `op` spawn prompts, which makes unattended agents unusable. The daemon cache
+ * (v0.13.1+) bounds it to one prompt per TTL per credential; a service account
+ * removes prompts entirely. Printed by `aquaman doctor` and deep doctors.
+ */
+function printOnePasswordModeHint(config, indent = '    ') {
+    if (config.credentials.backend !== '1password')
+        return;
+    if (process.env['OP_SERVICE_ACCOUNT_TOKEN'] || process.env['OP_CONNECT_HOST'])
+        return;
+    const vault = config.credentials.onePasswordVault || 'aquaman';
+    const ttl = resolveCacheTtl(config);
+    const cacheNote = ttl > 0
+        ? `the daemon cache bounds this to one per ${Math.round(ttl / 60)} min per credential`
+        : 'and the credential cache is disabled (cacheTtlSeconds: 0)';
+    console.log(`${indent}• 1Password is in biometric/desktop-app mode — each vault read prompts (${cacheNote}).`);
+    console.log(`${indent}  For zero prompts, create a service account scoped to the "${vault}" vault (create the`);
+    console.log(`${indent}  vault + credentials as a human first, or grant write_items) and start the daemon with`);
+    console.log(`${indent}  OP_SERVICE_ACCOUNT_TOKEN. If OP_CONNECT_HOST/OP_CONNECT_TOKEN are set they take precedence.`);
+}
+/**
+ * Map config.credentials onto CredentialStoreOptions — the single source for
+ * every createCredentialStore() call in this CLI. Env fallbacks mirror
+ * applyEnvOverrides() (belt and braces for callers that build partial configs).
+ */
+function storeOptionsFromConfig(config) {
+    return {
+        backend: config.credentials.backend,
+        encryptionPassword: config.credentials.encryptionPassword || process.env['AQUAMAN_ENCRYPTION_PASSWORD'] || process.env['AQUAMAN_KEEPASS_PASSWORD'],
+        vaultAddress: config.credentials.vaultAddress || process.env['VAULT_ADDR'],
+        vaultToken: config.credentials.vaultToken || process.env['VAULT_TOKEN'],
+        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
+    };
+}
+/**
+ * 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 +185,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 +277,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) {
@@ -262,21 +354,10 @@ program
         // Vault \u2014 backend + creds
         try {
             const config = loadConfig();
-            const store = await createCredentialStore({
-                backend: config.credentials.backend,
-                encryptionPassword: config.credentials.encryptionPassword,
-                vaultAddress: config.credentials.vaultAddress,
-                vaultToken: config.credentials.vaultToken,
-                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
-            });
+            const store = await createCredentialStore(storeOptionsFromConfig(config));
             const creds = await store.list();
             console.log(`    \u2713 ${config.credentials.backend} backend (${creds.length} credential${creds.length !== 1 ? 's' : ''})`);
+            printOnePasswordModeHint(config);
         }
         catch (err) {
             console.log(`    \u2717 Backend not accessible: ${err.message}`);
@@ -349,6 +430,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.');
@@ -449,19 +561,7 @@ async function runVaultSetup(opts) {
     fs.mkdirSync(auditDir, { recursive: true, mode: 0o700 });
     let store;
     try {
-        store = await createCredentialStore({
-            backend: config.credentials.backend,
-            encryptionPassword: config.credentials.encryptionPassword || process.env['AQUAMAN_ENCRYPTION_PASSWORD'] || process.env['AQUAMAN_KEEPASS_PASSWORD'],
-            vaultAddress: config.credentials.vaultAddress || process.env['VAULT_ADDR'],
-            vaultToken: config.credentials.vaultToken || process.env['VAULT_TOKEN'],
-            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
-        });
+        store = await createCredentialStore(storeOptionsFromConfig(config));
     }
     catch (err) {
         console.error(`  Failed to initialize ${backend}: ${err instanceof Error ? err.message : err}`);
@@ -587,21 +687,7 @@ openclaw
     // Initialize credential store
     let credentialStore;
     try {
-        credentialStore = 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
-        });
+        credentialStore = wrapWithCache(await createCredentialStore(storeOptionsFromConfig(config)), resolveCacheTtl(config));
     }
     catch (err) {
         console.error(`Credential backend "${config.credentials.backend}" failed to initialize: ${err instanceof Error ? err.message : err}`);
@@ -619,6 +705,7 @@ openclaw
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -742,21 +829,7 @@ program
     // Initialize credential store
     let credentialStore;
     try {
-        credentialStore = 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
-        });
+        credentialStore = wrapWithCache(await createCredentialStore(storeOptionsFromConfig(config)), resolveCacheTtl(config));
     }
     catch (err) {
         console.error(`Credential backend "${config.credentials.backend}" failed to initialize: ${err instanceof Error ? err.message : err}`);
@@ -773,6 +846,7 @@ program
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig: policyConfig2,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -815,21 +889,7 @@ openclaw
     // Initialize credential store
     let credentialStore;
     try {
-        credentialStore = 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
-        });
+        credentialStore = wrapWithCache(await createCredentialStore(storeOptionsFromConfig(config)), resolveCacheTtl(config));
     }
     catch (err) {
         console.error(`Credential backend "${config.credentials.backend}" failed to initialize: ${err instanceof Error ? err.message : err}`);
@@ -852,6 +912,7 @@ openclaw
         allowedServices: config.credentials.proxiedServices,
         serviceRegistry,
         policyConfig: policyConfig3,
+        loopback: loadLoopbackOptions(config),
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
@@ -914,6 +975,248 @@ 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 shadowed = managedScopeShadowedKeys(integration.configureHermes());
+    if (shadowed.length > 0) {
+        console.log(`  Managed scope:     ⚠ ${HERMES_MANAGED_ENV_PATH} pins ${shadowed.join(', ')} — proxy bypassed for these keys`);
+    }
+    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}`);
+    }
+    // 3b. Hermes >=0.17 managed scope: /etc/hermes/.env overrides ~/.hermes/.env
+    {
+        const shadowed = managedScopeShadowedKeys(integration.configureHermes());
+        if (shadowed.length > 0) {
+            fail(`Hermes managed scope (${HERMES_MANAGED_ENV_PATH}) pins ${shadowed.join(', ')} — it overrides ~/.hermes/.env, so the proxy is BYPASSED for these keys. Remove them from the managed file or point them at the proxy.`);
+        }
+        else {
+            pass('No managed-scope override of aquaman env vars');
+        }
+    }
+    // 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(storeOptionsFromConfig(config));
+            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`);
+            }
+            printOnePasswordModeHint(config, '  ');
+        }
+        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')
@@ -1056,7 +1359,7 @@ openclaw
                     process.exit(1);
                 }
             }
-            catch (err) {
+            catch {
                 console.error(`  Cannot reach Vault at ${vaultAddr}.`);
                 process.exit(1);
             }
@@ -1136,19 +1439,7 @@ openclaw
     // 3. Prompt for API keys (or read from env in non-interactive mode)
     let store;
     try {
-        store = await createCredentialStore({
-            backend: config.credentials.backend,
-            encryptionPassword: config.credentials.encryptionPassword || process.env['AQUAMAN_ENCRYPTION_PASSWORD'] || process.env['AQUAMAN_KEEPASS_PASSWORD'],
-            vaultAddress: config.credentials.vaultAddress || process.env['VAULT_ADDR'],
-            vaultToken: config.credentials.vaultToken || process.env['VAULT_TOKEN'],
-            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
-        });
+        store = await createCredentialStore(storeOptionsFromConfig(config));
     }
     catch (err) {
         console.error(`  Failed to initialize ${backend} credential store: ${err instanceof Error ? err.message : err}`);