aquaman-proxy 0.14.1 → 0.16.0

package/dist/cli/index.js

@@ -12,15 +12,17 @@ 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, generateLoopbackToken, DEFAULT_LOOPBACK_PORT, wrapWithCache, resolveCacheTtl } from '../core/index.js';
+import { loadConfig, getConfigDir, getConfigPath, 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 { createOpenClawIntegration, authProfilesAreSqliteOnly, legacyAuthProfilesBlockProviders, pluginInstallNeedsCapabilityConsent } from '../openclaw/integration.js';
 import { supportsSecretRefIntegrations, wireSecretRefProviders, secretRefWiringStatus } from '../openclaw/secretref.js';
+import { CHANNEL_ROUTING_SUPPORTED, wireChannelRouting, channelRoutingStatus } from '../openclaw/channel-routing.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 { managedScopeShadowedKeys, hermesManagedEnvPath, HERMES_SUPPORTED_SERVICES, hermesSecretSourceRefs } from '../hermes/config-writer.js';
+import { createBrokerScope, parseAquamanRef, defaultProjectsPath } from '../broker-scope.js';
+import { loadPolicyFromConfig, validatePolicyConfig, lintPolicyConfig, getDefaultPolicyPresets, matchPolicy } from '../request-policy.js';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 // Read version from package.json (single source of truth)
 const __cliFilename = fileURLToPath(import.meta.url);
@@ -80,7 +82,9 @@ function storeOptionsFromConfig(config) {
         keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
         bitwardenFolder: config.credentials.bitwardenFolder,
         bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-        bitwardenCollectionId: config.credentials.bitwardenCollectionId
+        bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+        keeperFolderUid: config.credentials.keeperFolderUid,
+        keeperConfigPath: config.credentials.keeperConfigPath
     };
 }
 /**
@@ -101,6 +105,112 @@ function loadLoopbackOptions(config) {
     }
     return { port: lb.port || DEFAULT_LOOPBACK_PORT, token: lb.token, host: lb.host || '127.0.0.1' };
 }
+/** Broker scope for `aquaman daemon`, or undefined when `broker.enabled: false`. */
+function daemonBrokerScope(config) {
+    if (config.broker?.enabled === false)
+        return undefined;
+    return createBrokerScope({
+        configPath: getConfigPath(),
+        loopbackDeniedServices: HERMES_SUPPORTED_SERVICES,
+    });
+}
+/**
+ * Add or remove refs in config.yaml `broker.allowedRefs`. Edits the raw file
+ * (not loadConfig + saveConfig) so env overrides such as the loopback token
+ * are never persisted as a side effect. The daemon re-reads the list on change.
+ */
+function updateBrokerAllowedRefs(refs, mode) {
+    const invalid = refs.filter(r => !parseAquamanRef(r));
+    if (invalid.length > 0) {
+        console.error(`Invalid ref${invalid.length > 1 ? 's' : ''}: ${invalid.join(', ')}`);
+        console.error('Refs look like aquaman://<service>/<key>, e.g. aquaman://github/token');
+        process.exit(1);
+    }
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        const parsed = yamlParse(fs.readFileSync(configPath, 'utf-8'));
+        if (parsed && typeof parsed === 'object')
+            raw = parsed;
+    }
+    const current = new Set(Array.isArray(raw.broker?.allowedRefs) ? raw.broker.allowedRefs : []);
+    for (const ref of refs) {
+        if (mode === 'allow')
+            current.add(ref);
+        else
+            current.delete(ref);
+    }
+    raw.broker = { ...(raw.broker && typeof raw.broker === 'object' ? raw.broker : {}), allowedRefs: [...current].sort() };
+    fs.writeFileSync(configPath, yamlStringify(raw), { encoding: 'utf-8', mode: 0o600 });
+    const verb = mode === 'allow' ? 'Allowed' : 'Revoked';
+    for (const ref of refs)
+        console.log(`${verb}: ${ref}`);
+    if (mode === 'allow') {
+        console.log('\nAny process running as you can now fetch these values from `aquaman daemon`. Only allow refs you intend to materialize.');
+    }
+    if (raw.broker.enabled === false) {
+        console.log('Note: broker.enabled is false in config.yaml, so the broker is off regardless.');
+    }
+}
+/**
+ * `POST /broker/resolve` against the running daemon over UDS. Always goes
+ * through the daemon (never the vault directly), so `aquaman get` is
+ * scope-checked and audited exactly like a coding-agent or Hermes resolve.
+ */
+function brokerResolve(socketPath, service, key, timeoutMs) {
+    const body = JSON.stringify({ service, key });
+    return new Promise((resolve) => {
+        const req = http.request({
+            socketPath,
+            path: '/broker/resolve',
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+            timeout: timeoutMs,
+        }, (res) => {
+            let payload = '';
+            res.on('data', (chunk) => { payload += chunk; });
+            res.on('end', () => {
+                let json;
+                try {
+                    json = JSON.parse(payload);
+                }
+                catch {
+                    resolve({ error: `Proxy returned a non-JSON response (HTTP ${res.statusCode})` });
+                    return;
+                }
+                if (res.statusCode === 200 && typeof json.value === 'string') {
+                    resolve({ value: json.value });
+                }
+                else {
+                    resolve({ error: json.error || `Broker error (HTTP ${res.statusCode})`, fix: json.fix, code: json.code });
+                }
+            });
+        });
+        req.on('error', (err) => {
+            if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+                resolve({ error: `Cannot reach the aquaman proxy at ${socketPath}`, fix: 'Start it with: aquaman daemon', code: 'proxy_unreachable' });
+            }
+            else if (err.code === 'EPERM' || err.code === 'EACCES') {
+                resolve({ error: `Connecting to ${socketPath} was denied (${err.code})`, fix: 'If this runs inside a sandbox, allowlist the socket; otherwise check its owner and 0600 mode', code: 'socket_blocked' });
+            }
+            else {
+                resolve({ error: err.message });
+            }
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve({ error: `Broker request timed out after ${timeoutMs}ms`, fix: 'A vault that prompts (e.g. 1Password biometrics) may need longer: pass --timeout <ms>' });
+        });
+        req.end(body);
+    });
+}
+function describeBroker(scope) {
+    if (!scope)
+        return 'disabled (broker.enabled: false)';
+    const n = scope.declared().length;
+    return `${n} declared ref${n === 1 ? '' : 's'} (see: aquaman broker list)`;
+}
 /**
  * Probe the loopback listener's /_health endpoint (no token required). Returns
  * true if it responds 200 within a short timeout, false otherwise.
@@ -183,6 +293,23 @@ async function promptSecretInput(prompt) {
         });
     });
 }
+/** One-line explanation of why `openclaw setup` left a channel alone. */
+function describeChannelSkip(reason, channel) {
+    switch (reason) {
+        case 'no-vault-credential':
+            return `no credential in the vault (add it: aquaman credentials add ${channel} bot_token)`;
+        case 'user-endpoint':
+            return 'it already points at your own endpoint (self-hosted Bot API or regional proxy)';
+        case 'token-file':
+            return 'its token comes from tokenFile, whose precedence over a config token we will not guess at';
+        case 'multi-account':
+            return 'multi-account channels need one vault entry per account, which the service model has no room for yet';
+        case 'not-wired':
+            return 'routable but not wired yet (re-run: aquaman openclaw setup)';
+        case 'unroutable':
+            return 'this OpenClaw exposes no endpoint override for it, so its traffic cannot be routed';
+    }
+}
 const program = new Command();
 program
     .name('aquaman')
@@ -239,7 +366,7 @@ program
         }
         lines.push('');
         lines.push(aqua('Vault management'));
-        for (const name of ['credentials', 'audit', 'services', 'policy']) {
+        for (const name of ['credentials', 'get', 'broker', 'audit', 'services', 'policy']) {
             const c = byName.get(name);
             if (c)
                 lines.push(renderCmd(c));
@@ -263,13 +390,12 @@ program
         }
         // --- Coder namespace (shim \u2014 list documented subcommands) ---
         if (byName.has('coder')) {
-            lines.push(aqua('AI coding-agent integration (Claude Code today)'));
+            lines.push(aqua('AI coding-agent integration (Claude Code, Codex)'));
             const coderSubs = [
-                ['coder setup <agent>', 'Install hooks for an agent (claude-code today)'],
+                ['coder setup <agent>', 'Install hooks for an agent (claude-code, codex)'],
                 ['coder doctor', 'Deep diagnostic \u2014 projects, broker, per-project vault'],
                 ['coder status', 'Configured projects + hook wiring + broker activity'],
                 ['coder project list/add/remove', 'Manage ~/.aquaman/projects.yaml'],
-                ['coder get <ref>', 'Resolve an aquaman://service/key reference'],
                 ['coder exec <cmd>', 'Run command with project env injected + output redacted'],
             ];
             for (const [term, desc] of coderSubs) {
@@ -316,7 +442,7 @@ program
 program
     .command('setup')
     .description('Vault-only setup wizard \u2014 backend + credentials (use `aquaman openclaw setup` or `aquaman coder setup` for full bundles)')
-    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--no-policy', 'Skip request policy preset configuration')
     .option('--non-interactive', 'Use environment variables instead of prompts (for CI)')
     .action(async (options) => {
@@ -541,7 +667,7 @@ async function runVaultSetup(opts) {
             }
         }
     }
-    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden'];
+    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden', 'keeper'];
     if (!validBackends.includes(backend)) {
         console.error(`  Invalid backend: ${backend}. Valid: ${validBackends.join(', ')}`);
         process.exit(1);
@@ -557,6 +683,9 @@ async function runVaultSetup(opts) {
         config = loadConfig();
     }
     config.credentials.backend = backend;
+    if (backend === 'keeper' && process.env['AQUAMAN_KEEPER_FOLDER_UID']) {
+        config.credentials.keeperFolderUid = process.env['AQUAMAN_KEEPER_FOLDER_UID'];
+    }
     fs.writeFileSync(configPath, yamlStringify(config), { encoding: 'utf-8', mode: 0o600 });
     const auditDir = path.join(configDir, 'audit');
     fs.mkdirSync(auditDir, { recursive: true, mode: 0o700 });
@@ -700,6 +829,8 @@ openclaw
     // Start credential proxy
     const socketPath = path.join(getConfigDir(), 'proxy.sock');
     const policyConfig = loadPolicyFromConfig(config);
+    // No `broker`: this proxy fronts OpenClaw, and the OpenClaw path never
+    // hands credential values out (v0.15.0; see broker-scope.ts).
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
@@ -710,7 +841,8 @@ openclaw
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -841,6 +973,10 @@ program
     const serviceRegistry = createServiceRegistry({ configPath: config.services.configPath });
     // Start credential proxy
     const policyConfig2 = loadPolicyFromConfig(config);
+    // The daemon is the only proxy that serves the credential broker, and only
+    // for declared refs (projects.yaml + broker.allowedRefs). Over loopback the
+    // Hermes LLM-provider keys are never materialized.
+    const brokerScope = daemonBrokerScope(config);
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
@@ -848,10 +984,12 @@ program
         serviceRegistry,
         policyConfig: policyConfig2,
         loopback: loadLoopbackOptions(config),
+        broker: brokerScope,
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -861,6 +999,10 @@ program
     // Write PID file
     writePidFile();
     console.log(`Credential proxy: ${socketPath}`);
+    console.log(`Credential broker: ${describeBroker(brokerScope)}`);
+    if (brokerScope?.declarationError()) {
+        console.error(`  ⚠ ${brokerScope.declarationError()} — refs declared there are refused until it parses`);
+    }
     console.log(`Audit logging: ${config.audit.enabled ? 'enabled' : 'disabled'}`);
     console.log(`Credential backend: ${config.credentials.backend}`);
     console.log(`PID file: ${getPidFile()}`);
@@ -907,6 +1049,9 @@ openclaw
     const serviceRegistry = createServiceRegistry({ configPath: config.services.configPath });
     // Start credential proxy
     const policyConfig3 = loadPolicyFromConfig(config);
+    // No `broker`: this proxy runs inside the OpenClaw plugin's lifecycle and
+    // must never hand credential values to the gateway or its agents — that
+    // was the ClawScan finding against 0.14.x (v0.15.0; see broker-scope.ts).
     const credentialProxy = createCredentialProxy({
         socketPath,
         store: credentialStore,
@@ -917,7 +1062,8 @@ openclaw
         onRequest: (info) => {
             auditLogger.logCredentialAccess('system', 'system', {
                 service: info.service,
-                operation: 'use',
+                // A broker resolve hands the value out; everything else injects it.
+                operation: info.method === 'BROKER' ? 'read' : 'use',
                 success: !info.error,
                 error: info.error
             });
@@ -1086,7 +1232,7 @@ hermes
     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`);
+        console.log(`  Managed scope:     ⚠ ${hermesManagedEnvPath()} 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'}`);
@@ -1150,7 +1296,7 @@ hermes
     {
         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.`);
+            fail(`Hermes managed scope (${hermesManagedEnvPath()}) 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');
@@ -1177,7 +1323,38 @@ hermes
             fail(`Vault backend "${config.credentials.backend}" failed: ${err instanceof Error ? err.message : err}`);
         }
     }
-    // 5. Hermes installed
+    // 5. Secret-source bindings are declared to the broker (v0.15.0+). The
+    // daemon only materializes declared refs, so a binding in Hermes'
+    // config.yaml alone now resolves to a "not declared" warning at startup.
+    {
+        const bound = hermesSecretSourceRefs();
+        if (bound.error) {
+            fail(`Hermes config unreadable (${bound.error}) — can't check secret-source bindings`);
+        }
+        else if (bound.refs.length === 0) {
+            console.log(`  • No aquaman secret-source bindings in ${bound.path} (optional)`);
+        }
+        else {
+            const scope = daemonBrokerScope(config);
+            if (!scope) {
+                fail(`${bound.refs.length} secret-source binding(s) in ${bound.path}, but broker.enabled is false — none will resolve`);
+            }
+            else {
+                const undeclared = bound.refs.filter((ref) => {
+                    const r = parseAquamanRef(ref);
+                    return !scope.check(r.service, r.key, 'loopback').allowed;
+                });
+                if (undeclared.length === 0) {
+                    pass(`All ${bound.refs.length} secret-source binding(s) are declared to the broker`);
+                }
+                else {
+                    fail(`Secret-source binding(s) not declared to the broker, so the daemon refuses them: ${undeclared.join(', ')}`);
+                    console.log(`    → aquaman broker allow ${undeclared.join(' ')}`);
+                }
+            }
+        }
+    }
+    // 6. Hermes installed
     const info = await detectHermes(config.hermes?.binaryPath || 'hermes');
     if (info.installed)
         pass(`Hermes CLI installed (v${info.version})`);
@@ -1264,7 +1441,7 @@ program
 openclaw
     .command('setup')
     .description('Full setup for OpenClaw — vault + plugin + auth profiles + (optional) auto-migrate')
-    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Credential backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--no-openclaw', 'Skip OpenClaw plugin installation step (run vault setup only)')
     .option('--no-policy', 'Skip request policy preset configuration')
     .option('--non-interactive', 'Use environment variables instead of prompts (for CI)')
@@ -1311,7 +1488,7 @@ openclaw
         }
     }
     // Validate backend
-    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden'];
+    const validBackends = ['keychain', 'encrypted-file', 'keepassxc', '1password', 'vault', 'systemd-creds', 'bitwarden', 'keeper'];
     if (!validBackends.includes(backend)) {
         console.error(`  Invalid backend: ${backend}`);
         console.error(`  Valid options: ${validBackends.join(', ')}`);
@@ -1429,10 +1606,30 @@ openclaw
             process.exit(1);
         }
     }
+    else if (backend === 'keeper') {
+        const { KeeperStore } = await import('../core/credentials/backends/keeper.js');
+        if (!KeeperStore.isAvailable()) {
+            console.error('  Keeper Commander (keeper) not found.');
+            console.error('  Install: pip install keepercommander');
+            console.error('  Then, once: keeper shell -> login -> this-device register -> this-device persistent-login on');
+            process.exit(1);
+        }
+        if (!process.env['AQUAMAN_KEEPER_FOLDER_UID']) {
+            console.error('  Keeper backend needs the folder that will hold aquaman records.');
+            console.error('  Create one in Keeper, then: export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>');
+            console.error('  (find the UID with: keeper get "<folder name>" --format json)');
+            process.exit(1);
+        }
+    }
     // 2. Run init internally (create dirs, config)
     ensureConfigDir();
     const config = getDefaultConfig();
     config.credentials.backend = backend;
+    if (backend === 'keeper') {
+        config.credentials.keeperFolderUid = process.env['AQUAMAN_KEEPER_FOLDER_UID'];
+        if (process.env['AQUAMAN_KEEPER_CONFIG'])
+            config.credentials.keeperConfigPath = process.env['AQUAMAN_KEEPER_CONFIG'];
+    }
     fs.writeFileSync(configPath, yamlStringify(config), { encoding: 'utf-8', mode: 0o600 });
     // Create audit directory
     const auditDir = path.join(configDir, 'audit');
@@ -1587,6 +1784,19 @@ openclaw
                 shouldInstall = answer.toLowerCase() !== 'n';
             }
             if (shouldInstall) {
+                // Detect the gateway version once — it gates the install command
+                // (capability consent on 2026.8.1+) and the credential surface:
+                // SecretRef wiring (canonical, >= 2026.6.5) vs the legacy
+                // auth-profiles.json placeholder. AQUAMAN_OPENCLAW_VERSION overrides
+                // detection (tests + operators pinning behavior explicitly).
+                let ocVersion = process.env.AQUAMAN_OPENCLAW_VERSION || null;
+                if (!ocVersion) {
+                    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 */ }
+                }
                 // a. Copy plugin files
                 const currentDir = path.dirname(fileURLToPath(import.meta.url));
                 const pluginSrc = path.resolve(currentDir, '../../../plugin');
@@ -1597,14 +1807,26 @@ openclaw
                     console.log('  \u2713 Plugin installed to ' + pluginDest);
                 }
                 else if (cliDetected) {
-                    // npm install — plugin source not bundled, use openclaw's plugin installer
+                    // npm install — plugin source not bundled, use openclaw's plugin
+                    // installer. OpenClaw 2026.8.1+ requires capability consent for
+                    // third-party plugins: interactively we let OpenClaw show its own
+                    // consent screen to the human; --non-interactive means the operator
+                    // pre-approved, so we pass --accept-capabilities and say so. The
+                    // clawhub: source avoids the extra --force an npm spec needs.
+                    const consent = pluginInstallNeedsCapabilityConsent(ocVersion);
+                    const args = consent
+                        ? ['plugins', 'install', 'clawhub:aquaman-plugin', ...(isNonInteractive ? ['--accept-capabilities'] : [])]
+                        : ['plugins', 'install', 'aquaman-plugin'];
                     try {
-                        const { execSync: execSyncFallback } = await import('node:child_process');
-                        execSyncFallback('openclaw plugins install aquaman-plugin', { stdio: 'pipe' });
+                        const { execFileSync: execFileSyncFallback } = await import('node:child_process');
+                        execFileSyncFallback('openclaw', args, { stdio: consent && !isNonInteractive ? 'inherit' : 'pipe' });
                         console.log('  \u2713 Plugin installed via openclaw');
+                        if (consent && isNonInteractive) {
+                            console.log('  \u2192 Accepted the plugin\u2019s OpenClaw capabilities on your behalf (--non-interactive)');
+                        }
                     }
                     catch {
-                        console.log('  \u2717 Could not install plugin. Run: openclaw plugins install aquaman-plugin');
+                        console.log(`  \u2717 Could not install plugin. Run: openclaw ${args.join(' ')}${consent && isNonInteractive ? '' : consent ? '  (then approve its capabilities)' : ''}`);
                     }
                 }
                 // b. Write/merge openclaw.json
@@ -1620,11 +1842,20 @@ openclaw
                     openclawConfig.plugins = {};
                 if (!openclawConfig.plugins.entries)
                     openclawConfig.plugins.entries = {};
-                // Set plugins.allow so OpenClaw trusts the plugin (avoids extensions_no_allowlist audit warning)
-                if (!openclawConfig.plugins.allow)
-                    openclawConfig.plugins.allow = [];
-                if (!openclawConfig.plugins.allow.includes('aquaman-plugin')) {
-                    openclawConfig.plugins.allow.push('aquaman-plugin');
+                // plugins.allow is an allowlist for EVERY plugin, OpenClaw's own
+                // included: on current gateways the anthropic/openai model providers
+                // are stock plugins. Creating a list that holds only aquaman-plugin
+                // (what setup did through v0.14.x) blocked them, so every
+                // anthropic/* model became "Unknown model" (verified 2026-09-18 on
+                // 2026.7.33 and 2026.9.1). Append to an existing list; never create
+                // a restrictive one on the user's behalf.
+                if (Array.isArray(openclawConfig.plugins.allow)) {
+                    if (!openclawConfig.plugins.allow.includes('aquaman-plugin')) {
+                        openclawConfig.plugins.allow.push('aquaman-plugin');
+                    }
+                }
+                else {
+                    console.log('  \u2192 No plugins.allow list in openclaw.json; left it unset (a list with only aquaman-plugin would block OpenClaw\u2019s own provider plugins)');
                 }
                 const configuredServices = storedServices.length > 0 ? storedServices : ['anthropic', 'openai'];
                 openclawConfig.plugins.entries['aquaman-plugin'] = {
@@ -1634,33 +1865,91 @@ openclaw
                         services: configuredServices,
                     }
                 };
-                // Detect the gateway version once \u2014 it gates the credential surface:
-                // SecretRef wiring (canonical, >= 2026.6.5) vs the legacy
-                // auth-profiles.json placeholder. AQUAMAN_OPENCLAW_VERSION overrides
-                // detection (tests + operators pinning behavior explicitly).
-                let ocVersion = process.env.AQUAMAN_OPENCLAW_VERSION || null;
-                if (!ocVersion) {
-                    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 */ }
-                }
                 // b2. SecretRef provider wiring (v0.14.0+, OpenClaw >= 2026.6.5).
                 // Config-level refs in openclaw.json are runtime-read on every
                 // version and survive OpenClaw's plaintext scrubs \u2014 no SQLite
                 // import step needed, unlike the legacy placeholder.
                 const secretRefSupported = supportsSecretRefIntegrations(ocVersion);
-                if (secretRefSupported) {
-                    const wiring = wireSecretRefProviders(openclawConfig, configuredServices);
+                // Which configured channels aquaman can actually take over: the host
+                // must expose an endpoint override and the vault must already hold
+                // the real token. Resolved up front because the wiring is sync, and
+                // only for channels the user actually configured -- a vault probe
+                // can be slow (keepassxc opens and derives a key per call).
+                const channelsConfigured = CHANNEL_ROUTING_SUPPORTED.filter(c => openclawConfig.channels?.[c] && typeof openclawConfig.channels[c] === 'object');
+                const channelsWithVaultCredential = new Set();
+                if (channelsConfigured.length > 0) {
+                    const channelRegistry = createServiceRegistry();
+                    for (const channel of channelsConfigured) {
+                        const def = channelRegistry.get(channel);
+                        if (!def)
+                            continue;
+                        if (await store.exists(channel, def.credentialKey)) {
+                            channelsWithVaultCredential.add(channel);
+                        }
+                    }
+                }
+                // Both routes need the loopback listener: model traffic (provider
+                // baseUrl) and channel egress (apiRoot). Decide once.
+                let loopbackOrigin;
+                let loopbackToken;
+                if (secretRefSupported || channelsConfigured.length > 0) {
+                    // OpenClaw's model transport builds its own undici dispatcher: it
+                    // ignores the aquaman.local sentinel (its own DNS fails) and never
+                    // calls globalThis.fetch, so the plugin's interceptor can't see
+                    // provider traffic. Route it at the loopback listener instead —
+                    // OpenClaw's documented local-provider pattern (v0.15.0).
+                    const lbHost = config.loopback?.host || '127.0.0.1';
+                    const lbPort = config.loopback?.port || DEFAULT_LOOPBACK_PORT;
+                    const lbToken = config.loopback?.token || generateLoopbackToken();
+                    config.loopback = { enabled: true, host: lbHost, port: lbPort, token: lbToken };
+                    saveConfig(config);
+                    loopbackOrigin = `http://${lbHost}:${lbPort}`;
+                    loopbackToken = lbToken;
+                    console.log(`  \u2713 Loopback listener enabled on ${loopbackOrigin} (token-gated, loopback-bound)`);
+                }
+                if (secretRefSupported && loopbackOrigin) {
+                    const wiring = wireSecretRefProviders(openclawConfig, configuredServices, { loopbackOrigin });
                     if (wiring.wiredProviders.length > 0) {
                         console.log(`  \u2713 SecretRef wiring for ${wiring.wiredProviders.join(', ')} (canonical credential surface)`);
                     }
+                    if (wiring.baseUrlProviders.length > 0) {
+                        console.log(`  \u2713 Model traffic routed through the proxy for ${wiring.baseUrlProviders.join(', ')}`);
+                    }
+                    if (wiring.keptUserBaseUrl.length > 0) {
+                        console.log(`  \u2192 Left existing user-set baseUrl untouched for: ${wiring.keptUserBaseUrl.join(', ')} (proxy NOT in the path for those)`);
+                    }
                     const userKept = wiring.skippedProviders.filter(s => s === 'anthropic' || s === 'openai');
                     if (userKept.length > 0) {
                         console.log(`  \u2192 Left existing user-set apiKey untouched for: ${userKept.join(', ')}`);
                     }
                 }
+                // b3. Channel egress routing (v0.15.0+). Channels each build their
+                // own undici dispatcher, so the plugin's fetch interceptor never
+                // sees them. Telegram is the one bundled channel with an endpoint
+                // override, and the Bot API carries its token in the path, so the
+                // placeholder written here is the loopback token itself.
+                if (loopbackOrigin && loopbackToken) {
+                    const routing = wireChannelRouting(openclawConfig, {
+                        loopbackOrigin,
+                        loopbackToken,
+                        hasVaultCredential: (svc) => channelsWithVaultCredential.has(svc)
+                    });
+                    if (routing.routedChannels.length > 0) {
+                        // A routed channel that isn't in proxiedServices gets a 404 from
+                        // our own proxy, which is exactly the dead bot the all-or-nothing
+                        // wiring exists to avoid. Open the route we just pointed at us.
+                        const proxied = config.credentials.proxiedServices;
+                        const added = routing.routedChannels.filter(c => !proxied.includes(c));
+                        if (added.length > 0) {
+                            config.credentials.proxiedServices = [...proxied, ...added];
+                            saveConfig(config);
+                        }
+                        console.log(`  \u2713 Channel traffic routed through the proxy for ${routing.routedChannels.join(', ')}`);
+                    }
+                    for (const skip of routing.skipped) {
+                        console.log(`  \u2192 ${skip.channel} left as-is: ${describeChannelSkip(skip.reason, skip.channel)}`);
+                    }
+                }
                 fs.writeFileSync(openclawJsonPath, JSON.stringify(openclawConfig, null, 2), 'utf-8');
                 console.log('  \u2713 Plugin config written to ' + openclawJsonPath);
                 // c. Generate auth-profiles.json (only if missing). With SecretRef
@@ -1669,6 +1958,12 @@ openclaw
                 const profilesPath = path.join(openclawStateDir, 'agents', 'main', 'agent', 'auth-profiles.json');
                 if (secretRefSupported) {
                     console.log('  \u2192 Legacy auth-profiles.json placeholder skipped (SecretRef wiring replaces it)');
+                    if (legacyAuthProfilesBlockProviders(ocVersion) && fs.existsSync(profilesPath)) {
+                        // Left behind by aquaman-plugin <= 0.14.x. On 2026.8.1+ it locks
+                        // anthropic/openai out until OpenClaw archives it.
+                        console.log('  \u2717 A legacy auth-profiles.json from an older aquaman-plugin blocks providers on this OpenClaw');
+                        console.log('      Run once: openclaw doctor --fix   (archives it; aquaman-plugin 0.15.0+ never recreates it)');
+                    }
                 }
                 else if (!fs.existsSync(profilesPath)) {
                     const profiles = {};
@@ -1780,6 +2075,9 @@ openclaw
     // 2. Backend accessible
     let config;
     let store = null;
+    // Services the vault holds anything for. Used by the channel-routing
+    // check below, which runs outside the store's try block.
+    const vaultServices = new Set();
     try {
         config = loadConfig();
         if (config.credentials.backend === 'systemd-creds') {
@@ -1788,6 +2086,12 @@ openclaw
                 throw new Error('systemd-creds backend requires systemd >= 256 with --user support');
             }
         }
+        if (config.credentials.backend === 'keeper') {
+            const { KeeperStore } = await import('../core/credentials/backends/keeper.js');
+            if (!KeeperStore.isAvailable()) {
+                throw new Error('Keeper Commander (keeper) not found. Install: pip install keepercommander');
+            }
+        }
         if (config.credentials.backend === 'bitwarden') {
             const { BitwardenStore } = await import('../core/credentials/backends/bitwarden.js');
             if (!BitwardenStore.isAvailable()) {
@@ -1808,10 +2112,14 @@ openclaw
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
         // 3. Count credentials
         const creds = await store.list();
+        for (const c of creds)
+            vaultServices.add(c.service);
         if (creds.length > 0) {
             const names = creds.map(c => `${c.service}/${c.key}`).join(', ');
             console.log(`  \u2713 ${aqua('Backend:')} ${config.credentials.backend} (accessible)`);
@@ -1916,6 +2224,12 @@ openclaw
                     console.log(`      ${svc}: ${summary}`);
                 }
             }
+            // Deny rules that can never fire (pre-0.15.0 preset shapes) — a
+            // security issue, since the operator believes the endpoint is blocked.
+            for (const warning of lintPolicyConfig(policyConfigDoc)) {
+                console.log(`  \u2717 ${aqua('Policy')} ${warning}`);
+                issues++;
+            }
             // Warn about policies for non-proxied services
             if (config.credentials.proxiedServices) {
                 for (const svc of Object.keys(policyConfigDoc)) {
@@ -2020,9 +2334,21 @@ openclaw
         if (fs.existsSync(openclawJsonPath)) {
             try {
                 const openclawConfig = JSON.parse(fs.readFileSync(openclawJsonPath, 'utf-8'));
-                const allowList = openclawConfig.plugins?.allow || [];
-                if (allowList.includes('aquaman-plugin')) {
+                const allowList = Array.isArray(openclawConfig.plugins?.allow) ? openclawConfig.plugins.allow : undefined;
+                if (!allowList) {
+                    console.log(`  \u2713 ${aqua('Plugin')} allowed (no plugins.allow trust list; \`openclaw security audit\` notes extensions_no_allowlist)`);
+                }
+                else if (allowList.includes('aquaman-plugin')) {
                     console.log(`  \u2713 ${aqua('Plugin')} in plugins.allow trust list`);
+                    // A list that excludes OpenClaw's own provider plugins blocks
+                    // them (aquaman setup <= 0.14.x wrote exactly such a list).
+                    const svcs = openclawConfig.plugins?.entries?.['aquaman-plugin']?.config?.services ?? ['anthropic', 'openai'];
+                    const blocked = ['anthropic', 'openai'].filter(p => svcs.includes(p) && !allowList.includes(p));
+                    if (blocked.length > 0 && supportsSecretRefIntegrations(openclawVersion)) {
+                        console.log(`  \u2717 ${aqua('Plugin')} plugins.allow blocks OpenClaw\u2019s own provider plugin(s): ${blocked.join(', ')} (their models report "Unknown model")`);
+                        console.log(`    \u2192 Add ${blocked.map(b => `"${b}"`).join(', ')} to plugins.allow in openclaw.json (aquaman setup <= 0.14.x created a list without them)`);
+                        issues++;
+                    }
                 }
                 else {
                     console.log(`  \u2717 ${aqua('Plugin')} not in plugins.allow trust list`);
@@ -2048,6 +2374,17 @@ openclaw
                 if (status.providerConfigured && status.missingProviders.length === 0) {
                     secretRefFullyWired = true;
                     console.log(`  ✓ ${aqua('SecretRef')} wiring active (${status.wiredProviders.join(', ') || 'no providers'})`);
+                    // The apiKey ref alone doesn't put the proxy in the path: without
+                    // a loopback baseUrl OpenClaw's transport calls the upstream
+                    // directly and the placeholder fails there (v0.15.0).
+                    if (status.missingBaseUrl.length > 0) {
+                        console.log(`  ✗ ${aqua('Model routing')} ${status.missingBaseUrl.join(', ')} still call the provider directly — the proxy is bypassed`);
+                        console.log('    → Run: aquaman openclaw setup   (points models.providers.<svc>.baseUrl at the loopback listener)');
+                        issues++;
+                    }
+                    else if (status.baseUrlProviders.length > 0) {
+                        console.log(`  ✓ ${aqua('Model routing')} through the proxy for ${status.baseUrlProviders.join(', ')}`);
+                    }
                 }
                 else if (status.providerConfigured) {
                     // Half-migrated: the provider block exists but some providers still
@@ -2068,6 +2405,42 @@ openclaw
                 // openclaw.json invalid — already reported above
             }
         }
+        // 8.6. Channel egress routing (v0.15.0+). Channels build their own
+        //      undici dispatcher, so the plugin's fetch interceptor never sees
+        //      them. Only channels whose endpoint OpenClaw lets us override can
+        //      be routed; the rest are at-rest storage only and say so.
+        if (fs.existsSync(openclawJsonPath)) {
+            try {
+                const openclawConfig = JSON.parse(fs.readFileSync(openclawJsonPath, 'utf-8'));
+                const routing = channelRoutingStatus(openclawConfig, {
+                    hasVaultCredential: (svc) => vaultServices.has(svc)
+                });
+                if (routing.routed.length > 0) {
+                    console.log(`  \u2713 ${aqua('Channel routing')} through the proxy for ${routing.routed.join(', ')}`);
+                    // Routed but not proxied means our own proxy 404s the channel.
+                    const notProxied = routing.routed.filter(c => !(config?.credentials?.proxiedServices ?? []).includes(c));
+                    if (notProxied.length > 0) {
+                        console.log(`  \u2717 ${aqua('Channel routing')} ${notProxied.join(', ')} routed here but missing from proxiedServices, so the proxy returns 404`);
+                        console.log(`    \u2192 Add ${notProxied.join(', ')} to credentials.proxiedServices in ~/.aquaman/config.yaml (or re-run: aquaman openclaw setup)`);
+                        issues++;
+                    }
+                }
+                for (const skip of routing.notRouted) {
+                    console.log(`  \u2717 ${aqua('Channel routing')} ${skip.channel} sends its token straight to the vendor`);
+                    console.log(`    \u2192 ${describeChannelSkip(skip.reason, skip.channel)}`);
+                    issues++;
+                }
+                if (routing.unroutable.length > 0) {
+                    // Not a failure: nothing the user can do, and the credentials can
+                    // still live in the vault. Stated so nobody assumes coverage.
+                    console.log(`  \u2192 ${aqua('Channel routing')} not available for ${routing.unroutable.join(', ')} on this OpenClaw (no endpoint override)`);
+                    console.log('    (their tokens can live in the vault, but the proxy is not in their egress path)');
+                }
+            }
+            catch {
+                // openclaw.json invalid \u2014 already reported above
+            }
+        }
         // 9. Auth profiles. With SecretRef wiring active this surface is
         //    legacy/inert. Otherwise: OpenClaw >= 2026.6.5 reads provider auth
         //    profiles from each agent's openclaw-agent.sqlite and no longer reads
@@ -2077,7 +2450,18 @@ openclaw
         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 (secretRefFullyWired) {
+        if (legacyAuthProfilesBlockProviders(openclawVersion) && fs.existsSync(profilesPath)) {
+            // OpenClaw 2.0 line: the legacy JSON is not inert any more — it blocks
+            // providers with AUTH_PROFILE_MIGRATION_REQUIRED (#114033). Older
+            // aquaman-plugin versions rewrote it on every load; 0.15.0+ doesn't.
+            console.log(`  \u2717 ${aqua('Auth profiles')} legacy auth-profiles.json blocks anthropic/openai on ${openclawVersion} (AUTH_PROFILE_MIGRATION_REQUIRED)`);
+            if (!secretRefFullyWired) {
+                console.log('    \u2192 First: aquaman openclaw setup   (wires the SecretRef provider that replaces it)');
+            }
+            console.log('    \u2192 Then run once: openclaw doctor --fix   (archives the file; aquaman-plugin 0.15.0+ never recreates it)');
+            issues++;
+        }
+        else if (secretRefFullyWired) {
             console.log(`  ✓ ${aqua('Auth profiles')} not needed (SecretRef wiring replaces the placeholder flow)`);
             if (fs.existsSync(profilesPath)) {
                 console.log('    → Optional: the legacy auth-profiles.json placeholder is inert and may be deleted');
@@ -2095,8 +2479,8 @@ openclaw
                 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');
+                console.log(`  \u2717 ${aqua('Auth profiles')} missing: no credential wiring for OpenClaw ${openclawVersion}`);
+                console.log('    \u2192 Run: aquaman openclaw setup   (wires the SecretRef provider; the plugin no longer writes auth-profiles.json here)');
                 issues++;
             }
         }
@@ -2285,7 +2669,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch (error) {
@@ -2368,7 +2754,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch {
@@ -2405,7 +2793,9 @@ credentials
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
     }
     catch {
@@ -2423,7 +2813,7 @@ credentials
 credentials
     .command('guide')
     .description('Show setup commands for seeding credentials based on your backend')
-    .option('--backend <backend>', 'Override backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden)')
+    .option('--backend <backend>', 'Override backend (keychain, encrypted-file, keepassxc, 1password, vault, systemd-creds, bitwarden, keeper)')
     .option('--service <name>', 'Show commands for a single service only')
     .action(async (options) => {
     const config = loadConfig();
@@ -2584,6 +2974,105 @@ policy
         console.log(`  \u2717 DENIED by rule: ${rule.method} ${rule.path} \u2192 ${rule.action}`);
     }
 });
+// Credential broker scope (v0.15.0+)
+const broker = program
+    .command('broker')
+    .description('Credential broker scope: which refs `aquaman daemon` may hand out');
+broker
+    .command('list')
+    .description('List the refs the daemon broker will materialize, and where each is declared')
+    .action(() => {
+    const config = loadConfig();
+    console.log('Credential broker: served by `aquaman daemon` only. OpenClaw-hosted proxies never hand out credential values.\n');
+    if (config.broker?.enabled === false) {
+        console.log('  Disabled (broker.enabled: false in config.yaml) — every broker request is refused.');
+        return;
+    }
+    const scope = daemonBrokerScope(config);
+    const declared = scope.declared();
+    if (declared.length === 0) {
+        console.log('  No declared refs — every broker request is refused.');
+    }
+    for (const d of declared)
+        console.log(`  ${d.ref}  (${d.source})`);
+    const err = scope.declarationError();
+    if (err)
+        console.log(`\n  ⚠ ${err} — refs declared there are refused until it parses`);
+    console.log(`\n  Never over the loopback listener: ${HERMES_SUPPORTED_SERVICES.join(', ')} (process-isolated on the proxy path)`);
+    console.log(`  Coding-agent refs: ${defaultProjectsPath()}  (aquaman coder project add ...)`);
+    console.log(`  Other refs:        broker.allowedRefs in ${getConfigPath()}  (aquaman broker allow ...)`);
+});
+broker
+    .command('allow')
+    .description('Allow aquaman://service/key refs to be materialized (e.g. Hermes secret-source bindings)')
+    .argument('<refs...>', 'one or more aquaman://service/key refs')
+    .action((refs) => {
+    updateBrokerAllowedRefs(refs, 'allow');
+});
+broker
+    .command('revoke')
+    .description('Stop materializing refs added with `aquaman broker allow`')
+    .argument('<refs...>', 'one or more aquaman://service/key refs')
+    .action((refs) => {
+    updateBrokerAllowedRefs(refs, 'revoke');
+});
+// v0.16.0: fills the "run a command, read the secret from stdout" slot every
+// host now has (sbx secret set --command, Codex model_providers.*.auth.command,
+// Claude Code apiKeyHelper, OpenClaw exec providers, Hermes command sources).
+// This materializes the value into the CALLING process, so it is not process
+// isolation; it is scope-checked and audited because it goes through the daemon.
+program
+    .command('get')
+    .description('Print a declared credential to stdout, via the running daemon (for host credential-helper commands)')
+    .argument('<ref>', 'aquaman://service/key, declared with `aquaman broker allow` or in projects.yaml')
+    .option('--show', 'Allow printing to an interactive terminal')
+    .option('--timeout <ms>', 'How long to wait for the daemon (vaults that prompt may need longer)', '15000')
+    .addHelpText('after', `
+Examples:
+  sbx secret set github --command "$(command -v node) $(command -v aquaman) get aquaman://github/token"
+  Codex config.toml:  [model_providers.openai.auth]  command = "aquaman"  args = ["get", "aquaman://openai/api_key"]
+  Claude Code:        "apiKeyHelper": "aquaman get aquaman://anthropic/api_key"
+
+The value lands in whichever process runs this command. Every read is checked
+against the broker scope and written to the audit log.`)
+    .action(async (ref, opts) => {
+    const parsed = parseAquamanRef(ref);
+    if (!parsed) {
+        console.error(`Invalid ref: ${ref}`);
+        console.error('Refs look like aquaman://<service>/<key>, e.g. aquaman://github/token');
+        process.exit(1);
+    }
+    const timeoutMs = Number(opts.timeout);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+        console.error(`Invalid --timeout: ${opts.timeout} (milliseconds, a positive integer)`);
+        process.exit(1);
+    }
+    // Refuse before resolving, so an accidental run at a prompt neither
+    // prints the secret into scrollback nor spends an audited read.
+    if (process.stdout.isTTY && !opts.show) {
+        console.error('Refusing to print a credential to a terminal.');
+        console.error('This command is meant to be run by another program. To print it anyway, pass --show.');
+        process.exit(1);
+    }
+    const result = await brokerResolve(path.join(getConfigDir(), 'proxy.sock'), parsed.service, parsed.key, timeoutMs);
+    if ('value' in result) {
+        // No trailing newline when piped: credential-helper consumers differ on
+        // whether they trim, and a stray "\n" in an auth header breaks requests.
+        process.stdout.write(process.stdout.isTTY ? `${result.value}\n` : result.value);
+        return;
+    }
+    console.error(`Error: ${result.error}`);
+    if (result.code === 'broker_ref_not_declared') {
+        console.error(`Fix: aquaman broker allow ${ref}`);
+    }
+    else if (result.code === 'broker_disabled') {
+        console.error('Fix: the proxy on this socket does not serve the broker. If the OpenClaw plugin started it, run `aquaman daemon` instead (the last proxy started owns the socket).');
+    }
+    else if (result.fix) {
+        console.error(`Fix: ${result.fix}`);
+    }
+    process.exit(1);
+});
 // Migration commands
 openclaw
     .command('migrate')
@@ -3017,7 +3506,9 @@ openclaw
             keepassxcKeyFilePath: config.credentials.keepassxcKeyFilePath,
             bitwardenFolder: config.credentials.bitwardenFolder,
             bitwardenOrganizationId: config.credentials.bitwardenOrganizationId,
-            bitwardenCollectionId: config.credentials.bitwardenCollectionId
+            bitwardenCollectionId: config.credentials.bitwardenCollectionId,
+            keeperFolderUid: config.credentials.keeperFolderUid,
+            keeperConfigPath: config.credentials.keeperConfigPath
         });
         const creds = await store.list();
         console.log(`\nStored credentials: ${creds.length}`);