@ouro.bot/cli 0.1.0-alpha.556 → 0.1.0-alpha.558

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.558",
+      "changes": [
+        "Rejected local vault unlock material is now cleared after Bitwarden proves it is wrong, so a stale Keychain/DPAPI/Secret Service/plaintext entry cannot keep retrying across fresh CLI processes and rate-limit the agent vault.",
+        "Legacy vault unlock entries are no longer copied to canonical coordinates during read. Ouro now canonicalizes them only after a successful vault login, preventing unvalidated local material from poisoning the primary unlock slot.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the invalid local unlock quarantine release."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.557",
+      "changes": [
+        "`ouro vault unlock` now validates the typed unlock secret against the agent vault before replacing this machine's saved local unlock material, so a failed unlock attempt cannot poison a previously working Keychain/DPAPI/Secret Service/plaintext entry.",
+        "The Bitwarden adapter now rebuilds stale per-agent local `bw` profiles when they point at the wrong vault account/server or reject a saved unlock during unlock, reducing restart-time false locked-vault failures while keeping wrong saved secrets explicit.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the vault unlock hardening release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.556",
       "changes": [

package/dist/heart/daemon/cli-exec.js

@@ -1453,15 +1453,13 @@ async function executeVaultUnlock(command, deps) {
     const progress = createHumanCommandProgress(deps, "vault unlock");
     let store;
     try {
+        await runCommandProgressPhase(progress, "checking vault access", () => (0, credential_access_1.probeCredentialVaultAccess)(command.agent, unlockSecret, { homeDir: deps.homeDir }), () => "ok");
         store = await runCommandProgressPhase(progress, "saving local unlock", () => (0, vault_unlock_1.storeVaultUnlockSecret)({
             agentName: command.agent,
             email: vault.email,
             serverUrl: vault.serverUrl,
         }, unlockSecret, { homeDir: deps.homeDir, store: command.store }), (saved) => saved.kind);
-        await runCommandProgressPhase(progress, "checking vault access", async () => {
-            (0, credential_access_1.resetCredentialStore)();
-            await (0, credential_access_1.getCredentialStore)(command.agent).get("__ouro_vault_probe__");
-        }, () => "ok");
+        (0, credential_access_1.resetCredentialStore)();
     }
     finally {
         progress.end();

package/dist/repertoire/bitwarden-store.js

@@ -88,7 +88,9 @@ function isBwSessionUnavailableMessage(message) {
         /local bitwarden session/i.test(message));
 }
 function isBwInvalidUnlockSecretMessage(message) {
-    return /invalid master password/i.test(message) || /saved vault unlock secret/i.test(message);
+    return (/invalid master password/i.test(message) ||
+        /saved vault unlock secret/i.test(message) ||
+        /username or password is incorrect/i.test(message));
 }
 function isBwTimeoutError(err) {
     const timeoutErr = err;
@@ -135,6 +137,13 @@ function isBwConfigLogoutRequired(err) {
 function isBwAlreadyLoggedInError(err) {
     return err.message.toLowerCase().includes("already logged in");
 }
+function isBwLoggedOutOrUnauthenticatedError(err) {
+    const message = err.message.toLowerCase();
+    return (message.includes("not logged in") ||
+        message.includes("not authenticated") ||
+        message.includes("unauthenticated") ||
+        message.includes("local bitwarden session because it is locked, missing, or expired"));
+}
 function shouldUseStructuredItemLookup(domain) {
     return domain.includes("/");
 }
@@ -392,7 +401,10 @@ class BitwardenCredentialStore {
     email;
     masterPassword;
     appDataDir;
+    onInvalidUnlockSecret;
+    onLoginSuccess;
     sessionToken = null;
+    terminalLoginError = null;
     bwBinaryPath = "bw";
     structuredItemCache = null;
     constructor(serverUrl, email, masterPassword, options = {}) {
@@ -400,6 +412,8 @@ class BitwardenCredentialStore {
         this.email = email;
         this.masterPassword = masterPassword;
         this.appDataDir = options.appDataDir;
+        this.onInvalidUnlockSecret = options.onInvalidUnlockSecret;
+        this.onLoginSuccess = options.onLoginSuccess;
     }
     isReady() {
         return true;
@@ -410,12 +424,36 @@ class BitwardenCredentialStore {
     execBwWithPasswordEnv(args) {
         return execBw([...args, "--passwordenv", BW_PASSWORD_ENV], undefined, this.appDataDir, undefined, this.bwBinaryPath, { [BW_PASSWORD_ENV]: this.masterPassword });
     }
+    async notifyInvalidUnlockSecret(error) {
+        if (!this.onInvalidUnlockSecret)
+            return;
+        try {
+            await this.onInvalidUnlockSecret(error);
+        }
+        catch (callbackError) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                event: "repertoire.bw_invalid_unlock_cleanup_failed",
+                component: "repertoire",
+                message: "failed to clean up rejected local vault unlock material",
+                meta: {
+                    email: this.email,
+                    serverUrl: this.serverUrl,
+                    error: callbackError instanceof Error ? callbackError.message : String(callbackError),
+                    originalError: error.message,
+                },
+            });
+        }
+    }
     /**
      * Ensure the bw CLI is authenticated and unlocked.
      * Handles three states: logged out → login, locked → unlock, already unlocked → no-op.
      * Retries transient failures (network/timeout) up to MAX_RETRIES with exponential backoff.
      */
     async login() {
+        if (this.terminalLoginError) {
+            throw this.terminalLoginError;
+        }
         // Ensure bw CLI is installed before any bw commands
         this.bwBinaryPath = await (0, bw_installer_1.ensureBwCli)();
         if (this.appDataDir) {
@@ -425,6 +463,7 @@ class BitwardenCredentialStore {
         for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
             try {
                 await this.loginAttempt();
+                await this.onLoginSuccess?.();
                 return;
             }
             catch (err) {
@@ -432,6 +471,10 @@ class BitwardenCredentialStore {
                 lastError = err instanceof Error ? err : new Error(String(err));
                 // Don't retry non-transient errors (auth failures, bw not installed)
                 if (!isTransientError(lastError)) {
+                    this.terminalLoginError = lastError;
+                    if (isBwInvalidUnlockSecretMessage(lastError.message)) {
+                        await this.notifyInvalidUnlockSecret(lastError);
+                    }
                     throw lastError;
                 }
                 // Don't retry after final attempt
@@ -447,22 +490,19 @@ class BitwardenCredentialStore {
                 await delay(backoffMs);
             }
         }
+        this.terminalLoginError = lastError;
+        /* v8 ignore next -- invalid unlock errors are non-transient and exit through the non-retry path above @preserve */
+        if (isBwInvalidUnlockSecretMessage(lastError.message)) {
+            await this.notifyInvalidUnlockSecret(lastError);
+        }
         throw lastError;
     }
     /** Single login attempt — called by login() retry loop. */
     async loginAttempt() {
-        // Check current status
-        let status = {};
-        try {
-            const raw = await this.execBw(["status"]);
-            status = JSON.parse(raw);
-        }
-        catch (err) {
-            // If bw CLI is not installed or a transient error, propagate it for retry
-            if (err instanceof Error && (isBwNotInstalled(err) || isTransientError(err))) {
-                throw err;
-            }
-            // CLI not configured or broken — proceed with full setup
+        let status = await this.readStatus();
+        if (this.shouldRebuildLocalProfile(status)) {
+            await this.rebuildLocalProfile("local bw profile did not match requested vault", status);
+            status = { status: "unlocked", serverUrl: this.serverUrl, userEmail: this.email };
         }
         // Configure server URL if needed (only works when logged out)
         if (status.status === "unauthenticated" || !status.serverUrl) {
@@ -471,43 +511,28 @@ class BitwardenCredentialStore {
             }
             catch (error) {
                 const err = error;
-                // "Logout required" means already logged in — that's fine, skip config.
-                if (!isBwConfigLogoutRequired(err)) {
+                if (!isBwConfigLogoutRequired(err))
                     throw err;
-                }
+                // "Logout required" means bw already has local auth state; keep the
+                // existing behavior and proceed to login/unlock below.
             }
         }
-        if (status.status === "locked") {
-            // Already logged in, just needs unlock
-            const unlockOutput = await this.execBwWithPasswordEnv(["unlock", "--raw"]);
-            this.sessionToken = unlockOutput.trim();
-        }
-        else if (status.status === "unauthenticated" || !status.status) {
-            // Not logged in — full login
-            let loginOutput;
-            try {
-                loginOutput = await this.execBwWithPasswordEnv(["login", this.email, "--raw"]);
-            }
-            catch (error) {
-                const err = error;
-                if (!isBwAlreadyLoggedInError(err)) {
-                    throw err;
-                }
-                loginOutput = await this.execBwWithPasswordEnv(["unlock", "--raw"]);
+        if (!this.sessionToken) {
+            if (status.status === "locked") {
+                // Already logged in, just needs unlock.
+                const unlockOutput = await this.execWithLocalProfileRebuild("unlock rejected saved local unlock material", status, () => this.execBwWithPasswordEnv(["unlock", "--raw"]));
+                this.sessionToken = unlockOutput.trim();
             }
-            try {
-                const parsed = JSON.parse(loginOutput);
-                this.sessionToken = parsed.access_token ?? loginOutput.trim();
+            else if (status.status === "unauthenticated" || !status.status) {
+                // Not logged in -- full login.
+                this.sessionToken = this.sessionTokenFromLoginOutput(await this.loginWithPassword());
             }
-            catch {
-                this.sessionToken = loginOutput.trim();
+            else {
+                // Status is "unlocked" -- already good, just need the session token.
+                const unlockOutput = await this.execWithLocalProfileRebuild("unlocked bw profile rejected saved local unlock material", status, () => this.execBwWithPasswordEnv(["unlock", "--raw"]));
+                this.sessionToken = unlockOutput.trim();
             }
         }
-        else {
-            // Status is "unlocked" — already good, just need the session token
-            const unlockOutput = await this.execBwWithPasswordEnv(["unlock", "--raw"]);
-            this.sessionToken = unlockOutput.trim();
-        }
         if (this.shouldSyncVaultAfterSession(status)) {
             /* v8 ignore next -- defensive: loginAttempt always sets sessionToken before sync @preserve */
             await this.execBw(["sync"], this.sessionToken ?? undefined);
@@ -521,6 +546,128 @@ class BitwardenCredentialStore {
                 meta: { email: this.email, serverUrl: this.serverUrl, freshnessWindowMs: BW_SYNC_FRESH_MS },
             });
         }
+        this.terminalLoginError = null;
+    }
+    async readStatus() {
+        try {
+            const raw = await this.execBw(["status"]);
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return {};
+            const record = parsed;
+            return {
+                ...(typeof record.status === "string" ? { status: record.status } : {}),
+                ...(typeof record.serverUrl === "string" ? { serverUrl: record.serverUrl } : {}),
+                ...(typeof record.userEmail === "string" ? { userEmail: record.userEmail } : {}),
+            };
+        }
+        catch (err) {
+            // If bw CLI is not installed or a transient error, propagate it for retry.
+            if (err instanceof Error && (isBwNotInstalled(err) || isTransientError(err))) {
+                throw err;
+            }
+            // CLI not configured or broken -- proceed with full setup.
+            return {};
+        }
+    }
+    normalizedServerUrl(value) {
+        return value.trim().replace(/\/+$/, "").toLowerCase();
+    }
+    shouldRebuildLocalProfile(status) {
+        if (status.status !== "locked" && status.status !== "unlocked")
+            return false;
+        if (status.serverUrl && this.normalizedServerUrl(status.serverUrl) !== this.normalizedServerUrl(this.serverUrl))
+            return true;
+        if (status.userEmail && status.userEmail.trim().toLowerCase() !== this.email.trim().toLowerCase())
+            return true;
+        return false;
+    }
+    sessionTokenFromLoginOutput(loginOutput) {
+        try {
+            const parsed = JSON.parse(loginOutput);
+            return typeof parsed.access_token === "string" && parsed.access_token.trim()
+                ? parsed.access_token.trim()
+                : loginOutput.trim();
+        }
+        catch {
+            return loginOutput.trim();
+        }
+    }
+    async loginWithPassword() {
+        try {
+            return await this.execBwWithPasswordEnv(["login", this.email, "--raw"]);
+        }
+        catch (error) {
+            const err = error;
+            if (!isBwAlreadyLoggedInError(err))
+                throw err;
+            return this.execBwWithPasswordEnv(["unlock", "--raw"]);
+        }
+    }
+    forgetLocalSyncMarker() {
+        if (!this.appDataDir)
+            return;
+        try {
+            fs.rmSync(path.join(this.appDataDir, BW_SYNC_MARKER_FILENAME), { force: true });
+        }
+        catch {
+            // A stale sync marker is only a cache hint; failure to remove it should not block auth repair.
+        }
+    }
+    async logoutLocalProfile(reason, status, cause) {
+        this.sessionToken = null;
+        this.structuredItemCache = null;
+        this.forgetLocalSyncMarker();
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            event: "repertoire.bw_local_profile_rebuild",
+            component: "repertoire",
+            message: "rebuilding local bw profile for agent vault",
+            meta: {
+                email: this.email,
+                serverUrl: this.serverUrl,
+                reason,
+                /* v8 ignore next -- defensive: every profile rebuild path starts from a locked/unlocked bw status @preserve */
+                previousStatus: status.status ?? "unknown",
+                previousServerUrl: status.serverUrl ?? null,
+                previousUserEmail: status.userEmail ?? null,
+                /* v8 ignore next -- defensive: internal rebuild callers pass Error or undefined causes @preserve */
+                error: cause instanceof Error ? cause.message : cause ? String(cause) : undefined,
+            },
+        });
+        try {
+            await this.execBw(["logout"]);
+        }
+        catch (error) {
+            const err = error;
+            if (isBwLoggedOutOrUnauthenticatedError(err))
+                return;
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                event: "repertoire.bw_local_profile_logout_failed",
+                component: "repertoire",
+                message: "failed to logout local bw profile before rebuild",
+                meta: { email: this.email, serverUrl: this.serverUrl, error: err.message },
+            });
+        }
+    }
+    async rebuildLocalProfile(reason, status, cause) {
+        await this.logoutLocalProfile(reason, status, cause);
+        await this.execBw(["config", "server", this.serverUrl]);
+        this.sessionToken = this.sessionTokenFromLoginOutput(await this.loginWithPassword());
+    }
+    async execWithLocalProfileRebuild(reason, status, operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const err = error;
+            if (!isBwInvalidUnlockSecretMessage(err.message))
+                throw err;
+            await this.rebuildLocalProfile(reason, status, err);
+            /* v8 ignore next -- defensive: rebuildLocalProfile always stores a string session token on success @preserve */
+            return this.sessionToken ?? "";
+        }
     }
     async ensureSession() {
         if (!this.sessionToken) {

package/dist/repertoire/credential-access.js

@@ -44,6 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCredentialStore = getCredentialStore;
+exports.probeCredentialVaultAccess = probeCredentialVaultAccess;
 exports.resetCredentialStore = resetCredentialStore;
 const crypto = __importStar(require("node:crypto"));
 const fs = __importStar(require("node:fs"));
@@ -64,13 +65,13 @@ function loadVaultSectionForAgent(agentName) {
         return { configPath };
     }
 }
-function bitwardenAppDataDir(agentName, vaultConfig) {
+function bitwardenAppDataDir(agentName, vaultConfig, homeDir = os.homedir()) {
     const digest = crypto
         .createHash("sha256")
         .update(`${agentName}:${vaultConfig.serverUrl}:${vaultConfig.email}`)
         .digest("hex")
         .slice(0, 24);
-    return path.join(os.homedir(), ".ouro-cli", "bitwarden", digest);
+    return path.join(homeDir, ".ouro-cli", "bitwarden", digest);
 }
 function getCredentialStore(agentNameInput) {
     const agentName = agentNameInput ?? identity.getAgentName();
@@ -91,7 +92,63 @@ function getCredentialStore(agentNameInput) {
         email: vaultConfig.email,
         serverUrl: vaultConfig.serverUrl,
     });
-    const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlock.secret, { appDataDir: bitwardenAppDataDir(agentName, vaultConfig) });
+    const unlockConfig = { agentName, email: vaultConfig.email, serverUrl: vaultConfig.serverUrl };
+    const unlockSource = unlock.source ?? unlockConfig;
+    let invalidUnlockCleared = false;
+    let canonicalUnlockStored = false;
+    const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlock.secret, {
+        appDataDir: bitwardenAppDataDir(agentName, vaultConfig),
+        onInvalidUnlockSecret: (error) => {
+            if (invalidUnlockCleared)
+                return;
+            invalidUnlockCleared = true;
+            (0, vault_unlock_1.clearVaultUnlockSecret)({
+                agentName,
+                email: unlockSource.email,
+                serverUrl: unlockSource.serverUrl,
+            });
+            stores.delete(cacheKey);
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                event: "repertoire.credential_store_invalid_unlock_cleared",
+                component: "repertoire",
+                message: "cleared rejected local vault unlock material",
+                meta: {
+                    agentName,
+                    serverUrl: vaultConfig.serverUrl,
+                    email: vaultConfig.email,
+                    sourceServerUrl: unlockSource.serverUrl,
+                    error: error.message,
+                },
+            });
+        },
+        onLoginSuccess: () => {
+            if (canonicalUnlockStored)
+                return;
+            if (unlockSource.serverUrl === vaultConfig.serverUrl && unlockSource.email === vaultConfig.email)
+                return;
+            canonicalUnlockStored = true;
+            try {
+                (0, vault_unlock_1.storeVaultUnlockSecret)(unlockConfig, unlock.secret);
+                (0, vault_unlock_1.noteVaultUnlockSelfHeal)(unlockConfig, unlock.store.kind, unlockSource.serverUrl);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    event: "repertoire.vault_unlock_self_heal_failed",
+                    component: "repertoire",
+                    message: "failed to rewrite local unlock material using canonical vault coordinates",
+                    meta: {
+                        store: unlock.store.kind,
+                        email: vaultConfig.email,
+                        sourceServerUrl: unlockSource.serverUrl,
+                        targetServerUrl: vaultConfig.serverUrl,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+        },
+    });
     stores.set(cacheKey, store);
     (0, runtime_1.emitNervesEvent)({
         event: "repertoire.credential_store_init",
@@ -106,6 +163,16 @@ function getCredentialStore(agentNameInput) {
     });
     return store;
 }
+async function probeCredentialVaultAccess(agentNameInput, unlockSecret, options = {}) {
+    const agentName = agentNameInput;
+    const { configPath, vault } = loadVaultSectionForAgent(agentName);
+    if (!vault || typeof vault.email !== "string" || vault.email.trim().length === 0) {
+        throw new Error((0, vault_unlock_1.credentialVaultNotConfiguredError)(agentName, configPath));
+    }
+    const vaultConfig = identity.resolveVaultConfig(agentName, vault);
+    const store = new bitwarden_store_1.BitwardenCredentialStore(vaultConfig.serverUrl, vaultConfig.email, unlockSecret, { appDataDir: bitwardenAppDataDir(agentName, vaultConfig, options.homeDir) });
+    await store.get("__ouro_vault_probe__");
+}
 function resetCredentialStore() {
     stores = new Map();
 }

package/dist/repertoire/vault-unlock.js

@@ -39,6 +39,8 @@ exports.isCredentialVaultNotConfiguredError = isCredentialVaultNotConfiguredErro
 exports.vaultCreateRecoverFix = vaultCreateRecoverFix;
 exports.promptConfirmedVaultUnlockSecret = promptConfirmedVaultUnlockSecret;
 exports.resolveVaultUnlockStore = resolveVaultUnlockStore;
+exports.noteVaultUnlockSelfHeal = noteVaultUnlockSelfHeal;
+exports.clearVaultUnlockSecret = clearVaultUnlockSecret;
 exports.readVaultUnlockSecret = readVaultUnlockSecret;
 exports.storeVaultUnlockSecret = storeVaultUnlockSecret;
 exports.getVaultUnlockStatus = getVaultUnlockStatus;
@@ -82,6 +84,12 @@ function vaultConfigCandidates(config) {
         serverUrl,
     }));
 }
+function exactVaultConfig(config) {
+    return {
+        ...config,
+        serverUrl: config.serverUrl.trim().replace(/\/+$/, ""),
+    };
+}
 function plaintextUnlockPath(config, deps) {
     const digest = crypto.createHash("sha256").update(vaultKey(config)).digest("hex").slice(0, 24);
     return path.join(homeDir(deps), PLAINTEXT_UNLOCK_DIR, `${digest}.secret`);
@@ -265,37 +273,13 @@ function noteVaultUnlockSelfHeal(config, storeKind, sourceServerUrl) {
         },
     });
 }
-function warnVaultUnlockSelfHealFailure(config, storeKind, sourceServerUrl, error) {
-    (0, runtime_1.emitNervesEvent)({
-        level: "warn",
-        component: "repertoire",
-        event: "repertoire.vault_unlock_self_heal_failed",
-        message: "failed to rewrite local unlock material using canonical vault coordinates",
-        meta: {
-            store: storeKind,
-            email: config.email,
-            sourceServerUrl,
-            targetServerUrl: config.serverUrl,
-            error: error instanceof Error ? error.message : String(error),
-        },
-    });
-}
 function readFromMacosKeychain(config, deps) {
     const candidates = vaultConfigCandidates(config);
-    for (const [index, candidate] of candidates.entries()) {
+    for (const candidate of candidates) {
         const secret = readFromMacosKeychainExact(vaultKey(candidate), deps);
-        if (!secret)
-            continue;
-        if (index > 0) {
-            try {
-                writeToMacosKeychain(config, secret, deps);
-                noteVaultUnlockSelfHeal(config, "macos-keychain", candidate.serverUrl);
-            }
-            catch (error) {
-                warnVaultUnlockSelfHealFailure(config, "macos-keychain", candidate.serverUrl, error);
-            }
+        if (secret) {
+            return { secret, source: exactVaultConfig(candidate) };
         }
-        return secret;
     }
     return null;
 }
@@ -337,20 +321,11 @@ function readFromLinuxSecretServiceExact(accountKey, deps) {
 }
 function readFromLinuxSecretService(config, deps) {
     const candidates = vaultConfigCandidates(config);
-    for (const [index, candidate] of candidates.entries()) {
+    for (const candidate of candidates) {
         const secret = readFromLinuxSecretServiceExact(vaultKey(candidate), deps);
-        if (!secret)
-            continue;
-        if (index > 0) {
-            try {
-                writeToLinuxSecretService(config, secret, deps);
-                noteVaultUnlockSelfHeal(config, "linux-secret-service", candidate.serverUrl);
-            }
-            catch (error) {
-                warnVaultUnlockSelfHealFailure(config, "linux-secret-service", candidate.serverUrl, error);
-            }
+        if (secret) {
+            return { secret, source: exactVaultConfig(candidate) };
         }
-        return secret;
     }
     return null;
 }
@@ -417,20 +392,11 @@ function readFromWindowsDpapiExact(config, deps) {
 }
 function readFromWindowsDpapi(config, deps) {
     const candidates = vaultConfigCandidates(config);
-    for (const [index, candidate] of candidates.entries()) {
+    for (const candidate of candidates) {
         const secret = readFromWindowsDpapiExact(candidate, deps);
-        if (!secret)
-            continue;
-        if (index > 0) {
-            try {
-                writeToWindowsDpapi(config, secret, deps);
-                noteVaultUnlockSelfHeal(config, "windows-dpapi", candidate.serverUrl);
-            }
-            catch (error) {
-                warnVaultUnlockSelfHealFailure(config, "windows-dpapi", candidate.serverUrl, error);
-            }
+        if (secret) {
+            return { secret, source: exactVaultConfig(candidate) };
         }
-        return secret;
     }
     return null;
 }
@@ -455,20 +421,11 @@ function readFromPlaintextFileExact(config, deps) {
 }
 function readFromPlaintextFile(config, deps) {
     const candidates = vaultConfigCandidates(config);
-    for (const [index, candidate] of candidates.entries()) {
+    for (const candidate of candidates) {
         const secret = readFromPlaintextFileExact(candidate, deps);
-        if (!secret)
-            continue;
-        if (index > 0) {
-            try {
-                writeToPlaintextFile(config, secret, deps);
-                noteVaultUnlockSelfHeal(config, "plaintext-file", candidate.serverUrl);
-            }
-            catch (error) {
-                warnVaultUnlockSelfHealFailure(config, "plaintext-file", candidate.serverUrl, error);
-            }
+        if (secret) {
+            return { secret, source: exactVaultConfig(candidate) };
         }
-        return secret;
     }
     return null;
 }
@@ -505,20 +462,96 @@ function writeToStore(config, store, secret, deps) {
     }
     writeToPlaintextFile(config, secret, deps);
 }
+function deleteFromMacosKeychainExact(config, deps) {
+    const result = spawnSync(deps)("security", [
+        "delete-generic-password",
+        "-s",
+        VAULT_UNLOCK_SERVICE,
+        "-a",
+        vaultKey(config),
+    ], { encoding: "utf8" });
+    if (result.status === 0)
+        return true;
+    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+    const error = result.error instanceof Error ? result.error.message : "";
+    const detail = stderr || error;
+    if (!detail || /could not be found in the keychain/i.test(detail))
+        return false;
+    throw new Error(`failed to clear vault unlock secret from macOS Keychain: ${detail}`);
+}
+function deleteFromLinuxSecretServiceExact(config, deps) {
+    const result = spawnSync(deps)("secret-tool", [
+        "clear",
+        "service",
+        VAULT_UNLOCK_SERVICE,
+        "account",
+        vaultKey(config),
+    ], { encoding: "utf8" });
+    if (result.status === 0)
+        return true;
+    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+    const error = result.error instanceof Error ? result.error.message : "";
+    const detail = stderr || error;
+    if (!detail || /not found/i.test(detail))
+        return false;
+    throw new Error(`failed to clear vault unlock secret from Linux Secret Service: ${detail}`);
+}
+function deleteFromWindowsDpapiExact(config, deps) {
+    const filePath = windowsDpapiUnlockPath(config, deps);
+    const existed = fs.existsSync(filePath);
+    fs.rmSync(filePath, { force: true });
+    return existed;
+}
+function deleteFromPlaintextFileExact(config, deps) {
+    const filePath = plaintextUnlockPath(config, deps);
+    const existed = fs.existsSync(filePath);
+    fs.rmSync(filePath, { force: true });
+    return existed;
+}
+function deleteFromStoreExact(config, store, deps) {
+    if (store.kind === "macos-keychain")
+        return deleteFromMacosKeychainExact(config, deps);
+    if (store.kind === "linux-secret-service")
+        return deleteFromLinuxSecretServiceExact(config, deps);
+    if (store.kind === "windows-dpapi")
+        return deleteFromWindowsDpapiExact(config, deps);
+    return deleteFromPlaintextFileExact(config, deps);
+}
+function clearVaultUnlockSecret(config, deps = {}) {
+    const canonicalConfig = canonicalizeVaultUnlockConfig(config);
+    const store = resolveVaultUnlockStore(canonicalConfig, deps);
+    const deletedAccounts = new Set();
+    let deleted = false;
+    for (const candidate of vaultConfigCandidates(config)) {
+        const exactCandidate = exactVaultConfig(candidate);
+        const key = vaultKey(exactCandidate);
+        if (deletedAccounts.has(key))
+            continue;
+        deletedAccounts.add(key);
+        deleted = deleteFromStoreExact(exactCandidate, store, deps) || deleted;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.vault_unlock_cleared",
+        message: "cleared local vault unlock material",
+        meta: { store: store.kind, secure: store.secure, hasAgentName: !!config.agentName, deleted },
+    });
+    return store;
+}
 function readVaultUnlockSecret(config, deps = {}) {
     const canonicalConfig = canonicalizeVaultUnlockConfig(config);
     const store = resolveVaultUnlockStore(canonicalConfig, deps);
-    const secret = readFromStore(canonicalConfig, store, deps);
-    if (!secret) {
+    const loaded = readFromStore(canonicalConfig, store, deps);
+    if (!loaded) {
         throw new Error(lockedMessage(canonicalConfig, store));
     }
     (0, runtime_1.emitNervesEvent)({
         component: "repertoire",
         event: "repertoire.vault_unlock_loaded",
         message: "loaded vault unlock material from local store",
-        meta: { store: store.kind, secure: store.secure, hasAgentName: !!config.agentName },
+        meta: { store: store.kind, secure: store.secure, hasAgentName: !!config.agentName, sourceServerUrl: loaded.source.serverUrl },
     });
-    return { secret, store };
+    return { secret: loaded.secret, store, source: loaded.source };
 }
 function storeVaultUnlockSecret(config, secret, deps = {}) {
     const canonicalConfig = canonicalizeVaultUnlockConfig(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.556",
+  "version": "0.1.0-alpha.558",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",