@ouro.bot/cli 0.1.0-alpha.446 → 0.1.0-alpha.448

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.448",
+      "changes": [
+        "`ouro status` and agent prompt provider visibility now distinguish \"the daemon has not loaded provider credentials in this process\" from \"the agent vault is missing credentials.\" A saved live check that passed stays ready instead of being downgraded to stale/missing just because status rendering is running in a fresh daemon process.",
+        "Provider visibility now carries a safe `not-loaded` credential state and renders it as `checked previously`, preserving the last live-check result without reading or printing secrets during ordinary status/prompt rendering.",
+        "Regression coverage locks the installed-product failure shape: an empty in-process provider cache plus ready provider state no longer produces misleading auth repair guidance."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.447",
+      "changes": [
+        "`ouro connect` now checks only the providers selected for the current agent lanes during preflight, and those live reads avoid mutating the older provider snapshot cache. That keeps the command focused on what this machine actually needs instead of paying whole-vault latency for unrelated provider records.",
+        "Structured vault reads for `providers/*` and `runtime/config` now reuse one short-lived Bitwarden item listing per store instance and skip redundant `bw sync` calls while the local Bitwarden cache is fresh, cutting repeated vault startup work without adding any disk credential cache.",
+        "The connections screen now lets the fresh live provider check outrank stale local credential visibility, so a provider that just passed appears ready and a provider that just failed shows the real live-check failure instead of falling back to misleading `credentials missing` guidance. `@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the connect preflight latency release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.446",
       "changes": [

package/dist/heart/daemon/agent-config-check.js

@@ -330,12 +330,20 @@ function selectedProviderPlan(agentName, state) {
         ...["outward", "inner"].map((lane) => `- ${laneAudienceLabel(lane)}: ${bindingLabel(state.lanes[lane])}`),
     ].join("\n");
 }
+function selectedProvidersForState(state) {
+    return [...new Set(["outward", "inner"].map((lane) => state.lanes[lane].provider))];
+}
 function mapVaultRefreshProgress(agentName, onProgress) {
     return (message) => {
         if (message.startsWith("reading vault items for ")) {
             onProgress(`${agentName}: opening saved provider credentials in the vault`);
             return;
         }
+        const providerRead = message.match(/^reading ([a-z0-9-]+) credentials\.\.\.$/i);
+        if (providerRead) {
+            onProgress(`${agentName}: reading saved ${providerRead[1]} credentials`);
+            return;
+        }
         if (message === "parsing provider credentials...") {
             onProgress(`${agentName}: organizing saved provider credentials`);
         }
@@ -381,7 +389,12 @@ async function checkAgentConfigWithProviderHealth(agentName, bundlesRoot, deps =
         return { ok: true };
     deps.onProgress?.(selectedProviderPlan(agentName, stateResult.state));
     const ping = deps.pingProvider ?? (await Promise.resolve().then(() => __importStar(require("../provider-ping")))).pingProvider;
-    const poolResult = await (0, provider_credentials_1.refreshProviderCredentialPool)(agentName, deps.onProgress ? { onProgress: mapVaultRefreshProgress(agentName, deps.onProgress) } : undefined);
+    const providers = selectedProvidersForState(stateResult.state);
+    const poolResult = await (0, provider_credentials_1.refreshProviderCredentialPool)(agentName, {
+        ...(deps.onProgress ? { onProgress: mapVaultRefreshProgress(agentName, deps.onProgress) } : {}),
+        providers,
+        skipCache: true,
+    });
     const pingGroups = new Map();
     const lanes = ["outward", "inner"];
     for (const lane of lanes) {

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

@@ -2060,11 +2060,33 @@ async function buildConnectMenu(agent, deps, onProgress) {
     onProgress?.("loading this machine's settings");
     const machineRuntime = await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(agent, currentMachineId(deps), { preserveCachedOnFailure: true });
     const { teamsEnabled, blueBubblesEnabled } = readConnectBaySenseFlags(agent, deps);
-    let perplexityStatus;
-    let perplexityDetailLines;
     const perplexityApiKey = runtimeConfig.ok
         ? readRuntimeConfigString(runtimeConfig.config, "integrations.perplexityApiKey")
         : null;
+    const embeddingsApiKey = runtimeConfig.ok
+        ? readRuntimeConfigString(runtimeConfig.config, "integrations.openaiEmbeddingsApiKey")
+        : null;
+    const shouldVerifyPerplexity = runtimeConfig.ok && !!perplexityApiKey;
+    const shouldVerifyEmbeddings = runtimeConfig.ok && !!embeddingsApiKey;
+    let perplexityVerification;
+    let embeddingsVerification;
+    if (shouldVerifyPerplexity && shouldVerifyEmbeddings) {
+        onProgress?.("verifying Perplexity search and memory embeddings");
+        [perplexityVerification, embeddingsVerification] = await Promise.all([
+            (0, runtime_capability_check_1.verifyPerplexityCapability)(perplexityApiKey),
+            (0, runtime_capability_check_1.verifyEmbeddingsCapability)(embeddingsApiKey),
+        ]);
+    }
+    else if (shouldVerifyPerplexity) {
+        onProgress?.("verifying Perplexity search");
+        perplexityVerification = await (0, runtime_capability_check_1.verifyPerplexityCapability)(perplexityApiKey);
+    }
+    else if (shouldVerifyEmbeddings) {
+        onProgress?.("verifying memory embeddings");
+        embeddingsVerification = await (0, runtime_capability_check_1.verifyEmbeddingsCapability)(embeddingsApiKey);
+    }
+    let perplexityStatus;
+    let perplexityDetailLines;
     if (!runtimeConfig.ok) {
         perplexityStatus = runtimeConfigReadStatus(runtimeConfig);
         perplexityDetailLines = [];
@@ -2074,16 +2096,15 @@ async function buildConnectMenu(agent, deps, onProgress) {
         perplexityDetailLines = ["no API key saved yet"];
     }
     else {
-        onProgress?.("verifying Perplexity search");
-        const verification = await (0, runtime_capability_check_1.verifyPerplexityCapability)(perplexityApiKey);
-        perplexityStatus = verification.ok ? "ready" : "needs attention";
-        perplexityDetailLines = [verification.ok ? "verified live just now" : `live check failed: ${verification.summary}`];
+        perplexityStatus = perplexityVerification?.ok ? "ready" : "needs attention";
+        perplexityDetailLines = [
+            perplexityVerification?.ok
+                ? "verified live just now"
+                : `live check failed: ${perplexityVerification.summary}`,
+        ];
     }
     let embeddingsStatus;
     let embeddingsDetailLines;
-    const embeddingsApiKey = runtimeConfig.ok
-        ? readRuntimeConfigString(runtimeConfig.config, "integrations.openaiEmbeddingsApiKey")
-        : null;
     if (!runtimeConfig.ok) {
         embeddingsStatus = runtimeConfigReadStatus(runtimeConfig);
         embeddingsDetailLines = [];
@@ -2093,10 +2114,12 @@ async function buildConnectMenu(agent, deps, onProgress) {
         embeddingsDetailLines = ["no API key saved yet"];
     }
     else {
-        onProgress?.("verifying memory embeddings");
-        const verification = await (0, runtime_capability_check_1.verifyEmbeddingsCapability)(embeddingsApiKey);
-        embeddingsStatus = verification.ok ? "ready" : "needs attention";
-        embeddingsDetailLines = [verification.ok ? "verified live just now" : `live check failed: ${verification.summary}`];
+        embeddingsStatus = embeddingsVerification?.ok ? "ready" : "needs attention";
+        embeddingsDetailLines = [
+            embeddingsVerification?.ok
+                ? "verified live just now"
+                : `live check failed: ${embeddingsVerification.summary}`,
+        ];
     }
     const teamsStatus = runtimeConfig.ok
         ? hasRuntimeConfigValue(runtimeConfig.config, "teams.clientId")
@@ -2943,7 +2966,7 @@ async function executeProviderCheck(command, deps) {
         throw error;
     }
 }
-function renderProviderCredentialLine(credential) {
+function renderProviderCredentialLine(agentName, credential) {
     if (credential.status === "present") {
         const credentialFields = credential.credentialFields.length > 0 ? ` credentials: ${credential.credentialFields.join(", ")}` : " credentials: none";
         const configFields = credential.configFields.length > 0 ? ` config: ${credential.configFields.join(", ")}` : " config: none";
@@ -2952,6 +2975,9 @@ function renderProviderCredentialLine(credential) {
     if (credential.status === "invalid-pool") {
         return `credentials: vault unavailable (${credential.error}); repair: ${credential.repair.command}`;
     }
+    if (credential.status === "not-loaded") {
+        return `credentials: not loaded in this process; run \`ouro provider refresh --agent ${agentName}\` to read the vault now`;
+    }
     return `credentials: missing; repair: ${credential.repair.command}`;
 }
 async function executeProviderStatus(command, deps) {
@@ -2987,7 +3013,7 @@ async function executeProviderStatus(command, deps) {
         const binding = resolved.binding;
         lines.push(`  ${lane}: ${binding.provider} / ${binding.model} (${binding.source})`);
         lines.push(`    readiness: ${binding.readiness.status}${binding.readiness.error ? ` (${binding.readiness.error})` : ""}`);
-        lines.push(`    ${renderProviderCredentialLine(binding.credential)}`);
+        lines.push(`    ${renderProviderCredentialLine(command.agent, binding.credential)}`);
         for (const warning of binding.warnings) {
             lines.push(`    warning: ${warning.message}`);
         }

package/dist/heart/daemon/connect-bay.js

@@ -84,6 +84,40 @@ function resolveProviderHealthCommand(providerHealth, status) {
     }
     return undefined;
 }
+function providerHealthTargetLane(providerHealth) {
+    const issue = providerHealth?.issue;
+    const actionLane = issue?.actions
+        .map((action) => "lane" in action && action.lane ? action.lane : undefined)
+        .find((lane) => lane === "outward" || lane === "inner");
+    if (actionLane)
+        return actionLane;
+    const text = [issue?.summary, issue?.detail, providerHealth?.error]
+        .filter(Boolean)
+        .join(" ")
+        .toLowerCase();
+    if (/\boutward provider\b/.test(text) || /\boutward lane\b/.test(text))
+        return "outward";
+    if (/\binner provider\b/.test(text) || /\binner lane\b/.test(text))
+        return "inner";
+    return undefined;
+}
+function providerHealthAppliesToLane(providerHealth, lane) {
+    const targetLane = providerHealthTargetLane(providerHealth);
+    return !targetLane || targetLane === lane.lane;
+}
+function providerHealthDetail(providerHealth, status) {
+    if (status === "locked")
+        return "vault locked on this machine";
+    if (status === "needs credentials")
+        return "credentials missing";
+    if (status === "needs setup") {
+        return providerHealth?.issue?.detail ?? providerHealth?.error ?? "needs setup";
+    }
+    const detail = providerHealth?.issue?.detail ?? providerHealth?.error;
+    if (!detail)
+        return "live check needs attention";
+    return /failed live check/i.test(detail) ? detail : `failed live check: ${detail}`;
+}
 function isProblemStatus(status) {
     return status !== "ready" && status !== "attached";
 }
@@ -160,6 +194,23 @@ function summarizeProviderLane(agent, lane, providerHealth) {
         };
     }
     const fallbackAction = providerHealthCommand ?? lane.credential.repairCommand;
+    if (providerHealth?.ok) {
+        return {
+            lane: lane.lane,
+            status: "ready",
+            title: `${lane.provider} / ${lane.model}`,
+            detail: "ready",
+        };
+    }
+    if (providerHealthStatus && providerHealthAppliesToLane(providerHealth, lane)) {
+        return {
+            lane: lane.lane,
+            status: providerHealthStatus,
+            title: `${lane.provider} / ${lane.model}`,
+            detail: providerHealthDetail(providerHealth, providerHealthStatus),
+            action: fallbackAction,
+        };
+    }
     if (lane.credential.status === "missing") {
         return {
             lane: lane.lane,
@@ -178,14 +229,6 @@ function summarizeProviderLane(agent, lane, providerHealth) {
             action: fallbackAction,
         };
     }
-    if (providerHealth?.ok) {
-        return {
-            lane: lane.lane,
-            status: "ready",
-            title: `${lane.provider} / ${lane.model}`,
-            detail: "ready",
-        };
-    }
     if (lane.readiness.status === "failed") {
         return {
             lane: lane.lane,

package/dist/heart/provider-binding-resolver.js

@@ -89,6 +89,16 @@ function resolveCredential(poolResult, provider, agentName) {
             warnings: [missingCredentialWarning(provider)],
         };
     }
+    if ((0, provider_credentials_1.isProviderCredentialPoolNotLoaded)(poolResult)) {
+        return {
+            credential: {
+                status: "not-loaded",
+                provider,
+                poolPath: poolResult.poolPath,
+            },
+            warnings: [],
+        };
+    }
     if (poolResult.reason === "invalid" || poolResult.reason === "unavailable") {
         return {
             credential: {
@@ -130,6 +140,9 @@ function staleReadiness(readiness, reason) {
 }
 function resolveReadiness(input) {
     if (!input.readiness) {
+        if (input.credential.status === "not-loaded") {
+            return { readiness: { status: "unknown" }, warnings: [] };
+        }
         if (input.credential.status === "missing") {
             return { readiness: { status: "unknown", reason: "credential-missing" }, warnings: [] };
         }
@@ -170,6 +183,9 @@ function resolveReadiness(input) {
             warnings: [],
         };
     }
+    if (input.credential.status === "not-loaded") {
+        return { readiness: readinessFromState(input.readiness), warnings: [] };
+    }
     return { readiness: readinessFromState(input.readiness), warnings: [] };
 }
 function resolveEffectiveProviderBinding(input) {

package/dist/heart/provider-credentials.js

@@ -33,10 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR = void 0;
 exports.splitProviderCredentialFields = splitProviderCredentialFields;
 exports.providerCredentialsVaultPath = providerCredentialsVaultPath;
 exports.providerCredentialItemName = providerCredentialItemName;
 exports.providerCredentialMachineHomeDir = providerCredentialMachineHomeDir;
+exports.isProviderCredentialPoolNotLoaded = isProviderCredentialPoolNotLoaded;
 exports.readProviderCredentialPool = readProviderCredentialPool;
 exports.refreshProviderCredentialPool = refreshProviderCredentialPool;
 exports.createProviderCredentialRecord = createProviderCredentialRecord;
@@ -54,6 +56,7 @@ const credential_access_1 = require("../repertoire/credential-access");
 const VALID_PROVIDERS = ["azure", "minimax", "anthropic", "openai-codex", "github-copilot"];
 const VALID_PROVENANCE_SOURCES = ["auth-flow", "manual"];
 const VAULT_ITEM_PREFIX = "providers/";
+exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR = "provider credentials have not been loaded from vault";
 const PROVIDER_FIELD_SPLITS = {
     anthropic: {
         credentials: ["setupToken", "refreshToken", "expiresAt"],
@@ -197,7 +200,7 @@ function recordFromPayload(payload) {
         provenance: { ...payload.provenance },
     };
 }
-function missingPool(agentName, error = "provider credentials have not been loaded from vault") {
+function missingPool(agentName, error = exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR) {
     return {
         ok: false,
         reason: "missing",
@@ -205,10 +208,20 @@ function missingPool(agentName, error = "provider credentials have not been load
         error,
     };
 }
+function isProviderCredentialPoolNotLoaded(result) {
+    return !result.ok
+        && result.reason === "missing"
+        && result.error === exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR;
+}
 function cacheResult(agentName, result) {
     cachedPools.set(agentName, result);
     return result;
 }
+function selectedProviders(providers) {
+    if (!providers || providers.length === 0)
+        return [...VALID_PROVIDERS];
+    return [...new Set(providers)];
+}
 function resultForProvider(poolResult, provider) {
     if (!poolResult.ok)
         return poolResult;
@@ -227,12 +240,13 @@ function readProviderCredentialPool(agentName) {
     return cachedPools.get(agentName) ?? missingPool(agentName);
 }
 async function refreshProviderCredentialPool(agentName, options = {}) {
+    const providersToRead = selectedProviders(options.providers);
     try {
         const store = (0, credential_access_1.getCredentialStore)(agentName);
         options.onProgress?.(`reading vault items for ${agentName}...`);
         const providers = {};
         let updatedAt = new Date(0).toISOString();
-        for (const provider of VALID_PROVIDERS) {
+        for (const provider of providersToRead) {
             const itemName = providerCredentialItemName(provider);
             options.onProgress?.(`reading ${provider} credentials...`);
             let raw;
@@ -261,9 +275,19 @@ async function refreshProviderCredentialPool(agentName, options = {}) {
             component: "config/identity",
             event: "config.provider_credentials_loaded",
             message: "loaded provider credentials from vault",
-            meta: { agentName, providerCount: Object.keys(providers).length },
+            meta: {
+                agentName,
+                providerCount: Object.keys(providers).length,
+                requestedProviderCount: providersToRead.length,
+                cacheSkipped: options.skipCache === true,
+            },
         });
-        return cacheResult(agentName, { ok: true, poolPath: providerCredentialsVaultPath(agentName), pool });
+        const result = {
+            ok: true,
+            poolPath: providerCredentialsVaultPath(agentName),
+            pool,
+        };
+        return options.skipCache ? result : cacheResult(agentName, result);
     }
     catch (error) {
         const cached = cachedPools.get(agentName);
@@ -282,7 +306,7 @@ async function refreshProviderCredentialPool(agentName, options = {}) {
         });
         if (options.preserveCachedOnFailure && cached?.ok)
             return cached;
-        return cacheResult(agentName, result);
+        return options.skipCache ? result : cacheResult(agentName, result);
     }
 }
 function createProviderCredentialRecord(input) {

package/dist/heart/provider-visibility.js

@@ -21,7 +21,7 @@ function credentialVisibility(binding) {
     }
     return {
         status: credential.status,
-        repairCommand: credential.repair.command,
+        ...("repair" in credential ? { repairCommand: credential.repair.command } : {}),
     };
 }
 function readinessVisibility(binding) {
@@ -87,6 +87,8 @@ function credentialLabel(credential) {
         return credential.source ?? "vault";
     if (credential.status === "invalid-pool")
         return "vault unavailable";
+    if (credential.status === "not-loaded")
+        return "checked previously";
     return "missing";
 }
 function readinessLabel(readiness) {
@@ -102,7 +104,7 @@ function readinessLabel(readiness) {
     return readiness.status;
 }
 function providerStatusDetail(lane) {
-    if (lane.credential.status !== "present")
+    if (lane.credential.status === "missing" || lane.credential.status === "invalid-pool")
         return undefined;
     return lane.readiness.error;
 }

package/dist/repertoire/bitwarden-store.js

@@ -134,15 +134,6 @@ function isBwConfigLogoutRequired(err) {
 function shouldPreferExactItemLookup(domain) {
     return domain.includes("/");
 }
-function isBwDirectLookupMissingError(err) {
-    const message = err.message.toLowerCase();
-    return message.includes("bw cli error: not found") || message.includes("bw cli error: item not found");
-}
-function isBwDirectLookupFallbackError(err) {
-    const message = err.message.toLowerCase();
-    return (message.includes("invalid json from bw get item") ||
-        message.includes("invalid item from bw get item"));
-}
 // ---------------------------------------------------------------------------
 // Cross-process bw CLI lock
 // ---------------------------------------------------------------------------
@@ -159,6 +150,9 @@ function isBwDirectLookupFallbackError(err) {
 const BW_LOCK_FILENAME = ".ouro-bw.lock";
 const BW_LOCK_TIMEOUT_MS = 30_000;
 const BW_LOCK_POLL_MS = 100;
+const BW_DATA_FILENAME = "data.json";
+const BW_SYNC_MARKER_FILENAME = ".ouro-last-sync";
+const BW_SYNC_FRESH_MS = 60_000;
 /** In-process async mutex keyed by appDataDir. */
 const inProcessLocks = new Map();
 function isPidAlive(pid) {
@@ -388,6 +382,7 @@ class BitwardenCredentialStore {
     appDataDir;
     sessionToken = null;
     bwBinaryPath = "bw";
+    structuredItemCache = null;
     constructor(serverUrl, email, masterPassword, options = {}) {
         this.serverUrl = serverUrl;
         this.email = email;
@@ -488,9 +483,19 @@ class BitwardenCredentialStore {
             const unlockOutput = await this.execBw(["unlock", this.masterPassword, "--raw"]);
             this.sessionToken = unlockOutput.trim();
         }
-        // Sync vault data after obtaining a fresh session token
-        /* v8 ignore next -- defensive: loginAttempt always sets sessionToken before sync @preserve */
-        await this.execBw(["sync"], this.sessionToken ?? undefined);
+        if (this.shouldSyncVaultAfterSession(status)) {
+            /* v8 ignore next -- defensive: loginAttempt always sets sessionToken before sync @preserve */
+            await this.execBw(["sync"], this.sessionToken ?? undefined);
+            this.writeSyncMarker();
+        }
+        else {
+            (0, runtime_1.emitNervesEvent)({
+                event: "repertoire.bw_sync_skipped",
+                component: "repertoire",
+                message: "skipping bw sync because local vault cache is still fresh",
+                meta: { email: this.email, serverUrl: this.serverUrl, freshnessWindowMs: BW_SYNC_FRESH_MS },
+            });
+        }
     }
     async ensureSession() {
         if (!this.sessionToken) {
@@ -512,6 +517,7 @@ class BitwardenCredentialStore {
                     throw err;
                 }
                 this.sessionToken = null;
+                this.structuredItemCache = null;
                 attemptedFreshSession = true;
             }
         }
@@ -614,6 +620,7 @@ class BitwardenCredentialStore {
                 notes: data.notes ?? null,
             };
             const encoded = Buffer.from(JSON.stringify(item)).toString("base64");
+            this.structuredItemCache = null;
             let savedItem;
             if (existing) {
                 const stdout = await this.execBw(["edit", "item", existing.id], session, encoded);
@@ -629,6 +636,7 @@ class BitwardenCredentialStore {
             }
             this.assertStoredCredentialMatches(domain, data, savedItem);
         });
+        this.structuredItemCache = null;
         (0, runtime_1.emitNervesEvent)({
             event: "repertoire.bw_credential_store_end",
             component: "repertoire",
@@ -677,6 +685,7 @@ class BitwardenCredentialStore {
             return false;
         }
         await this.withSessionRetry((session) => this.execBw(["delete", "item", item.id], session));
+        this.structuredItemCache = null;
         (0, runtime_1.emitNervesEvent)({
             event: "repertoire.bw_credential_delete_end",
             component: "repertoire",
@@ -688,25 +697,57 @@ class BitwardenCredentialStore {
     // --- Private ---
     async findItemByDomain(domain, session) {
         if (shouldPreferExactItemLookup(domain)) {
-            try {
-                const stdout = await this.execBw(["get", "item", domain], session);
-                const item = parseBwItem(stdout, "bw get item");
-                if (item.name === domain)
-                    return item;
-            }
-            catch (error) {
-                const err = error;
-                if (isBwDirectLookupMissingError(err))
-                    return null;
-                if (!isBwDirectLookupFallbackError(err))
-                    throw err;
-            }
+            const items = await this.readStructuredItemCache(session);
+            return items.get(domain) ?? null;
         }
         const stdout = await this.execBw(["list", "items", "--search", domain], session);
         const items = parseBwItems(stdout, "bw list items --search");
         // Find exact match by name
         return items.find((item) => item.name === domain) ?? null;
     }
+    shouldSyncVaultAfterSession(status) {
+        if (status.status === "unauthenticated" || !status.status)
+            return true;
+        if (!this.appDataDir)
+            return true;
+        const freshnessTimestamp = this.latestLocalSyncTimestamp();
+        if (freshnessTimestamp !== null) {
+            return Date.now() - freshnessTimestamp > BW_SYNC_FRESH_MS;
+        }
+        return true;
+    }
+    latestLocalSyncTimestamp() {
+        const files = [BW_SYNC_MARKER_FILENAME, BW_DATA_FILENAME];
+        let latest = null;
+        for (const name of files) {
+            try {
+                const mtimeMs = fs.statSync(path.join(this.appDataDir, name)).mtimeMs;
+                latest = latest === null ? mtimeMs : Math.max(latest, mtimeMs);
+            }
+            catch {
+                // Missing freshness file is fine; use any other available timestamp.
+            }
+        }
+        return latest;
+    }
+    writeSyncMarker() {
+        if (!this.appDataDir)
+            return;
+        try {
+            fs.writeFileSync(path.join(this.appDataDir, BW_SYNC_MARKER_FILENAME), `${Date.now()}\n`, { mode: 0o600 });
+        }
+        catch {
+            // If the marker cannot be written, fall back to syncing next time.
+        }
+    }
+    async readStructuredItemCache(session) {
+        if (this.structuredItemCache)
+            return this.structuredItemCache;
+        const stdout = await this.execBw(["list", "items"], session);
+        const items = parseBwItems(stdout, "bw list items");
+        this.structuredItemCache = new Map(items.map((item) => [item.name, item]));
+        return this.structuredItemCache;
+    }
     async findItemById(id, session) {
         const stdout = await this.execBw(["get", "item", id], session);
         return parseBwItem(stdout, "bw get item");

package/package.json

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