@lore-co/cli 0.2.20 → 0.2.21

package/dist/cli.js

@@ -24,6 +24,8 @@ import { CLAUDE_RELIABILITY_INTEGRATION, CODEX_RELIABILITY_INTEGRATION, COPILOT_
 import { runHook, } from "./runtime.js";
 import { readInvocationHealthWriteInput, runInvocationHealthWrite, } from "./invocation-health-writer.js";
 import { runAskCommand } from "./ask.js";
+import { runLearningsCommand } from "./learnings.js";
+import { runEmbeddingsCommand } from "./embeddings.js";
 import { runRememberCommand } from "./remember.js";
 import { installLoreSkill, removeLoreSkill } from "./skills.js";
 import { runApproachCommand } from "./approach.js";
@@ -48,6 +50,8 @@ export const LORE_OPENCODE_PLUGIN = "@lore-co/opencode";
 export const DEFAULT_HOSTED_API_URL = "https://api.uselore.co";
 export const DEFAULT_HOSTED_DASHBOARD_URL = "https://uselore.co";
 const CONFIGURED_AGENT_NAMES = NATIVE_CODING_AGENT_NAMES;
+/** Agents that only need the saved credential: no hooks or agent config are written. */
+const CREDENTIAL_ONLY_AGENTS = ["cowork", "devin"];
 const HOOK_EVENTS = [
     "UserPromptSubmit",
     "PreToolUse",
@@ -111,7 +115,7 @@ Options:
   --login               Approve access securely in the Lore dashboard
   --no-open             Print the approval URL without opening a browser
   --token <token>       Workspace bearer token (or LORE_WORKSPACE_TOKEN/LORE_TOKEN)
-  --agent <name>        claude, codex, copilot, copilot-cli, copilot-vscode, cowork, cursor, opencode, polytoken, or t3code
+  --agent <name>        claude, codex, copilot, copilot-cli, copilot-vscode, cowork, cursor, devin, opencode, polytoken, or t3code
   --timeout-ms <ms>     Hook request timeout, 250-10000 (default: 2500)
   --fallback <agent>   claude, codex, opencode, devin, cursor, copilot-cli, polytoken
   --no-recovery        Disable automatic handoff setup (otherwise enabled with two installed clients)
@@ -125,6 +129,7 @@ Folder choices control capture; learning scope controls where knowledge applies.
 Examples:
   lore connect --login --agent claude --folder .
   lore connect --login --agent cowork
+  lore connect --login --agent devin --folder .
   lore connect --token "$LORE_WORKSPACE_TOKEN" --agent claude
   lore connect --url http://localhost:3004 --token dev-token --agent codex
   lore connect --token "$LORE_WORKSPACE_TOKEN" --agent cursor
@@ -216,9 +221,12 @@ function isConfiguredAgent(value) {
 function isConnectAgent(value) {
     return (isConfiguredAgent(value) ||
         value === "copilot" ||
-        value === "cowork" ||
+        isCredentialOnlyAgent(value) ||
         value === "t3code");
 }
+function isCredentialOnlyAgent(value) {
+    return CREDENTIAL_ONLY_AGENTS.includes(value);
+}
 function hookCommand(agent, paths, event) {
     if (isWindows()) {
         const invocation = IS_STANDALONE_BINARY ? [process.execPath, "hook"] : [process.execPath, paths.runtime];
@@ -1392,7 +1400,7 @@ async function readT3CodeProviderInstallations(paths) {
 }
 async function expandConnectInstallations(requested, paths) {
     const direct = requested.flatMap((agent) => {
-        if (agent === "cowork" || agent === "t3code") {
+        if (isCredentialOnlyAgent(agent) || agent === "t3code") {
             return [];
         }
         return [
@@ -1438,6 +1446,7 @@ async function installRuntime(paths) {
             rm(resolve(dirname(paths.runtime), "retrieval-task.js"), { force: true }),
             rm(resolve(dirname(paths.runtime), "runtime-redaction.js"), { force: true }),
             rm(resolve(dirname(paths.runtime), "user-message.js"), { force: true }),
+            rm(resolve(dirname(paths.runtime), "host-envelopes.js"), { force: true }),
             rm(resolve(dirname(paths.runtime), "approach-guidance.js"), { force: true }),
             rm(resolve(dirname(paths.runtime), "skill-guidance.js"), { force: true }),
             rm(paths.runtimeContextFallback, { force: true }),
@@ -1476,6 +1485,8 @@ async function installRuntime(paths) {
         "retrieval-task.js": (await readFile(resolve(sourceDirectory, "retrieval-task.js"), "utf8")).replaceAll("@lore-co/core/user-message", "./user-message.js"),
         "runtime-redaction.js": await readFile(resolve(sourceDirectory, "runtime-redaction.js"), "utf8"),
         "user-message.js": await readFile(fileURLToPath(import.meta.resolve("@lore-co/core/user-message")), "utf8"),
+        // user-message.js imports the host-envelope registry it derives from.
+        "host-envelopes.js": await readFile(fileURLToPath(import.meta.resolve("@lore-co/core/host-envelopes")), "utf8"),
         "approach-guidance.js": await readFile(resolve(sourceDirectory, "approach-guidance.js"), "utf8"),
         "skill-guidance.js": await readFile(resolve(sourceDirectory, "skill-guidance.js"), "utf8"),
         "repository.js": repository,
@@ -1508,6 +1519,7 @@ async function installRuntime(paths) {
         atomicWrite(resolve(dirname(paths.runtime), "retrieval-task.js"), runtimeFiles["retrieval-task.js"], 0o600),
         atomicWrite(resolve(dirname(paths.runtime), "runtime-redaction.js"), runtimeFiles["runtime-redaction.js"], 0o600),
         atomicWrite(resolve(dirname(paths.runtime), "user-message.js"), runtimeFiles["user-message.js"], 0o600),
+        atomicWrite(resolve(dirname(paths.runtime), "host-envelopes.js"), runtimeFiles["host-envelopes.js"], 0o600),
         atomicWrite(resolve(dirname(paths.runtime), "approach-guidance.js"), runtimeFiles["approach-guidance.js"], 0o600),
         atomicWrite(resolve(dirname(paths.runtime), "skill-guidance.js"), runtimeFiles["skill-guidance.js"], 0o600),
         atomicWrite(paths.runtimeRepository, repository, 0o600),
@@ -1642,7 +1654,7 @@ function parseConnectArguments(args) {
             parsed.agents.push(value);
         }
         else {
-            throw new Error("--agent must be claude, codex, copilot, copilot-cli, copilot-vscode, cowork, cursor, opencode, polytoken, or t3code");
+            throw new Error("--agent must be claude, codex, copilot, copilot-cli, copilot-vscode, cowork, cursor, devin, opencode, polytoken, or t3code");
         }
     }
     validateConnectProjectOptions(parsed);
@@ -1739,9 +1751,26 @@ async function connectWithCredentialLocked(options, identity) {
     const agents = [
         ...new Set(installations.map((installation) => installation.agent)),
     ].sort();
-    const credentialOnlyCowork = options.agents.includes("cowork");
-    if (agents.length === 0 && !credentialOnlyCowork) {
-        throw new Error("No Claude, Codex, Copilot CLI, Cursor, OpenCode, or Polytoken installation detected. Use --agent <name>; T3 Code users can use --agent t3code.");
+    const installedAgents = [
+        ...new Set([
+            ...requestedExpansion.installations.map((installation) => installation.agent),
+            ...detectedAgents,
+            ...options.agents.filter((agent) => isCredentialOnlyAgent(agent) || agent === "t3code"),
+        ]),
+    ].sort();
+    const keptAgents = [
+        ...new Set(configuredInstallations(existing, paths).map((installation) => installation.agent)),
+    ]
+        .filter((agent) => !installedAgents.includes(agent))
+        .sort();
+    const knownDashboardUrl = dashboardUrl ??
+        (existing?.apiUrl === apiUrl ? existing.dashboardUrl : undefined) ??
+        (apiUrl === DEFAULT_HOSTED_API_URL ? DEFAULT_HOSTED_DASHBOARD_URL : undefined);
+    // Cowork and the Devin CLI read the saved credential from ~/.lore/config.json
+    // and need no hooks, so they connect without a native agent installation.
+    const credentialOnlyAgents = CREDENTIAL_ONLY_AGENTS.filter((agent) => options.agents.includes(agent));
+    if (agents.length === 0 && credentialOnlyAgents.length === 0) {
+        throw new Error("No Claude, Codex, Copilot CLI, Cursor, OpenCode, or Polytoken installation detected. Use --agent <name>; T3 Code users can use --agent t3code, and Devin CLI users --agent devin.");
     }
     const now = new Date();
     const documents = new Map();
@@ -1830,17 +1859,39 @@ async function connectWithCredentialLocked(options, identity) {
     if (options.recovery === false)
         await disableRecovery(paths.home);
     const skills = await installLoreSkill(paths, installations);
+    // An unchanged reconnect: same server, credential, and workspace, every
+    // configured agent was already configured, and no agent file was rewritten.
+    const alreadyConnected = existing !== null &&
+        existing.apiUrl === apiUrl &&
+        existing.token === token &&
+        existing.workspaceId === identity.workspaceId &&
+        existing.connectionId === config.connectionId &&
+        agents.every((agent) => existing.agents.includes(agent)) &&
+        changedHookFiles.length === 0 &&
+        JSON.stringify(existing.directories ?? null) === JSON.stringify(config.directories ?? null);
+    // A Codex set up in this run gets the approval step in its next-step line;
+    // the warning covers a kept Codex whose hooks file was rewritten anyway.
+    const codexHookPaths = installations
+        .filter((installation) => installation.agent === "codex")
+        .map((installation) => installation.configPath);
+    const codexNeedsApproval = !installedAgents.includes("codex") &&
+        changedHookFiles.some((path) => codexHookPaths.includes(path));
     return {
         capture: { folders: config.directories?.include ?? null, excludedFolders: config.directories?.exclude ?? [] },
         skillFiles: skills.files,
         connected: true,
         apiUrl: config.apiUrl,
         identity,
-        agents: credentialOnlyCowork ? [...agents, "cowork"] : agents,
+        agents: [...agents, ...credentialOnlyAgents],
+        installedAgents,
+        keptAgents,
+        alreadyConnected,
+        ...(knownDashboardUrl === undefined ? {} : { dashboardUrl: knownDashboardUrl }),
+        folder: options.cwd ?? process.cwd(),
         config: paths.config,
         changedHookFiles,
         backups,
-        warnings: [...skills.warnings, ...(connection.needsFolders ? [`Lore is off for ${config.connectionName} until you choose where to record. Reconnect with --folder <path> or --all-projects, or run lore config open --connection ${config.connectionName}.`] : []), ...requestedExpansion.warnings, ...hostRecoveryWarnings, ...(agents.includes("codex")
+        warnings: [...skills.warnings, ...(connection.needsFolders ? [`Lore is off for ${config.connectionName} until you choose where to record. Reconnect with --folder <path> or --all-projects, or run lore config open --connection ${config.connectionName}.`] : []), ...requestedExpansion.warnings, ...hostRecoveryWarnings, ...(codexNeedsApproval
                 ? ["Codex requires hook approval. Open /hooks in Codex and review any new or changed Lore hooks, then start a fresh session. Run lore doctor to verify approval and the first invocation."]
                 : [])],
         ...(recoveryNotice ? { recoveryNotice } : {}),
@@ -1969,6 +2020,53 @@ async function acknowledgeDeviceAuthorization(apiUrl, authorization) {
         }
     }
 }
+/** The exact step each agent needs before Lore records its first turn. */
+export function connectNextStep(agent) {
+    switch (agent) {
+        case "claude":
+            return "Restart Claude Code.";
+        case "codex":
+            return "Restart Codex, open /hooks, approve Lore's hooks, then start a fresh session.";
+        case "cursor":
+            return "Restart Cursor and enable the lore-native MCP server (lore_context and lore_complete).";
+        case "opencode":
+            return "Restart OpenCode.";
+        case "copilot":
+        case "copilot-cli":
+            return "Restart Copilot CLI.";
+        case "copilot-vscode":
+            return "Restart the VS Code session.";
+        case "polytoken":
+            return "Restart Polytoken.";
+        case "devin":
+            return "Run lore devin cli setup, then open a new terminal.";
+        case "cowork":
+        case "t3code":
+            return "Restart your agent and complete a turn.";
+    }
+}
+export function formatConnectResult(result) {
+    const captureSummary = result.capture.folders === null ? "all projects allowed by the workspace"
+        : result.capture.folders.length ? result.capture.folders.join(", ") : "paused — choose folders with --folder <path>";
+    const installed = result.installedAgents.join(", ");
+    const lines = [
+        result.alreadyConnected
+            ? `Already connected to ${result.identity.workspaceName} for ${installed}; nothing changed.`
+            : `access authorized; installed: ${installed}`,
+        ...(result.keptAgents.length ? [`kept: ${result.keptAgents.join(", ")}`] : []),
+        `api_url: ${result.apiUrl}`,
+        `config: ${result.config}`,
+        `capture: ${captureSummary}${result.capture.excludedFolders.length ? `; excluded: ${result.capture.excludedFolders.join(", ")}` : ""}`,
+        ...result.installedAgents.map((agent) => `Next step for ${agent}: ${connectNextStep(agent)}`),
+        result.dashboardUrl === undefined
+            ? `Send one message in ${result.folder}, then run lore doctor to confirm recording.`
+            : `Send one message in ${result.folder}, then open ${result.dashboardUrl}/connect to confirm recording.`,
+        ...(result.skillFiles.length ? ["Choose lore in your agent’s skills to find knowledge or remember this session."] : []),
+        ...(result.recoveryNotice ? [result.recoveryNotice] : []),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ];
+    return `${lines.join("\n")}\n`;
+}
 async function connectCommand(args) {
     const parsed = parseConnectArguments(args);
     if (parsed === null) {
@@ -2020,9 +2118,7 @@ async function connectCommand(args) {
     });
     if (authorization)
         await acknowledgeDeviceAuthorization(apiUrl, authorization);
-    const captureSummary = result.capture.folders === null ? "all projects allowed by the workspace"
-        : result.capture.folders.length ? result.capture.folders.join(", ") : "paused — choose folders with --folder <path>";
-    writeResult(result, parsed.json, `access authorized; integrations installed: ${result.agents.join(", ")}\napi_url: ${result.apiUrl}\nconfig: ${result.config}\ncapture: ${captureSummary}${result.capture.excludedFolders.length ? `; excluded: ${result.capture.excludedFolders.join(", ")}` : ""}\nRestart your agent and complete a turn, then run lore doctor to verify recording.\n${result.skillFiles.length ? 'Choose lore in your agent’s skills to find knowledge or remember this session.\n' : ''}${result.recoveryNotice ? `${result.recoveryNotice}\n` : ""}${result.warnings.map((warning) => `warning: ${warning}\n`).join("")}`);
+    writeResult(result, parsed.json, formatConnectResult(result));
 }
 async function queueCount(paths) {
     try {
@@ -2042,6 +2138,26 @@ export function credentialReliabilityWorkspaceKey(apiUrl, token) {
         .digest("hex")
         .slice(0, 32)}`;
 }
+/** Unrecoverable dead letters are kept this long for diagnosis, then pruned by doctor. */
+export const DEAD_LETTER_RETENTION_MS = 14 * 24 * 60 * 60_000;
+async function pruneUnrecoverableDeadLetters(config, paths) {
+    if (config === null) {
+        return 0;
+    }
+    try {
+        const store = new ReliabilityStore(reliabilityWorkspaceKey(config), {
+            home: paths.home,
+            ...(config.connectionId ? { connectionId: config.connectionId } : {}),
+        });
+        return await store.pruneDeadLetters({
+            olderThan: new Date(Date.now() - DEAD_LETTER_RETENTION_MS),
+        });
+    }
+    catch {
+        // The reliability-store check reports an unusable store.
+        return 0;
+    }
+}
 async function inspectReliabilityStore(config, paths) {
     if (config === null) {
         return { inspection: null, error: null };
@@ -2114,6 +2230,7 @@ async function inspectRuntimeInstallation(required, paths) {
         "retrieval-task.js": resolve(dirname(paths.runtime), "retrieval-task.js"),
         "runtime-redaction.js": resolve(dirname(paths.runtime), "runtime-redaction.js"),
         "user-message.js": resolve(dirname(paths.runtime), "user-message.js"),
+        "host-envelopes.js": resolve(dirname(paths.runtime), "host-envelopes.js"),
         "approach-guidance.js": resolve(dirname(paths.runtime), "approach-guidance.js"),
         "skill-guidance.js": resolve(dirname(paths.runtime), "skill-guidance.js"),
         "repository.js": paths.runtimeRepository,
@@ -2347,6 +2464,19 @@ async function statusData(paths, cwd) {
         externalSurfaces: EXTERNAL_SURFACES,
     };
 }
+/**
+ * Per-reason breakdown of local context-retrieval failures and the most
+ * recent one. Reasons are a fixed runtime vocabulary (timeout, http_<status>,
+ * network, snapshot_unverified, binding_mismatch, ...) and never prompt text.
+ */
+function formatRetrievalFailureDiagnostics(retrieval) {
+    const reasons = Object.entries(retrieval?.failureReasons ?? {})
+        .sort(([reasonA, countA], [reasonB, countB]) => countB - countA || reasonA.localeCompare(reasonB))
+        .map(([reason, count]) => `${reason}=${count}`);
+    const last = retrieval?.lastFailure ?? null;
+    return (`local_retrieval_failure_reasons: ${reasons.length === 0 ? "-" : reasons.join(" ")}\n` +
+        `last_retrieval_failure: ${last === null ? "-" : `${last.reason} (${last.path} request, agent ${last.agent}, at ${last.at})`}\n`);
+}
 async function statusCommand(args) {
     const parsed = parseOutputArguments(args, STATUS_HELP, "status");
     if (parsed === null) {
@@ -2364,7 +2494,8 @@ async function statusCommand(args) {
     const metricRate = (value) => value === null || value === undefined
         ? "-"
         : `${(value * 100).toFixed(1)}%`;
-    writeResult(data, parsed.json, `connected: ${data.connected ? "yes" : "no"}\ncurrent_folder: ${data.folderAccess.allowed ? "allowed" : "off"} (${data.folderAccess.reason})\napi_url: ${data.apiUrl ?? "-"}\nconfig_mode: ${data.configMode ?? "-"}\nruntime: ${data.runtimeRequired ? (data.runtimeInstalled ? `installed (${data.runtimeVersion})` : data.runtimeVersion === null ? "missing" : `stale (${data.runtimeVersion})`) : "not required"}\ndurable_outbox: ${data.reliability?.outbox.total ?? 0} ready=${data.reliability?.outbox.ready ?? 0} auth_blocked=${data.reliability?.outbox.authBlocked ?? 0} dead=${data.reliability?.outbox.dead ?? 0}\noldest_capture: ${data.reliability?.outbox.oldestEnqueuedAt ?? "-"}\ncontext_snapshots: ${data.reliability?.cache.context ?? 0}\noldest_context_snapshot: ${data.reliability?.cache.oldestContextWrittenAt ?? "-"}\npolicy_snapshots: ${data.reliability?.cache.policy ?? 0}\nlocal_context_fallback_rate: ${metricRate(data.reliability?.operational.retrieval.fallbackRate)}\nlocal_guard_coverage: ${metricRate(data.reliability?.operational.guard.coverageRate)}\nlocal_guard_failures: ${data.reliability?.operational.guard.failures ?? 0}\nlocal_retrieval_failures: ${data.reliability?.operational.retrieval.failed ?? 0}\n${data.reliabilityError === null ? "" : `reliability_error: ${data.reliabilityError}\n`}${agentLines}\n${externalSurfaceLines}\n`);
+    const retrievalFailureLines = formatRetrievalFailureDiagnostics(data.reliability?.operational.retrieval);
+    writeResult(data, parsed.json, `connected: ${data.connected ? "yes" : "no"}\ncurrent_folder: ${data.folderAccess.allowed ? "allowed" : "off"} (${data.folderAccess.reason})\napi_url: ${data.apiUrl ?? "-"}\nconfig_mode: ${data.configMode ?? "-"}\nruntime: ${data.runtimeRequired ? (data.runtimeInstalled ? `installed (${data.runtimeVersion})` : data.runtimeVersion === null ? "missing" : `stale (${data.runtimeVersion})`) : "not required"}\ndurable_outbox: ${data.reliability?.outbox.total ?? 0} ready=${data.reliability?.outbox.ready ?? 0} auth_blocked=${data.reliability?.outbox.authBlocked ?? 0} dead=${data.reliability?.outbox.dead ?? 0}\noldest_capture: ${data.reliability?.outbox.oldestEnqueuedAt ?? "-"}\ncontext_snapshots: ${data.reliability?.cache.context ?? 0}\noldest_context_snapshot: ${data.reliability?.cache.oldestContextWrittenAt ?? "-"}\npolicy_snapshots: ${data.reliability?.cache.policy ?? 0}\nlocal_context_fallback_rate: ${metricRate(data.reliability?.operational.retrieval.fallbackRate)}\nlocal_guard_coverage: ${metricRate(data.reliability?.operational.guard.coverageRate)}\nlocal_guard_failures: ${data.reliability?.operational.guard.failures ?? 0}\nlocal_retrieval_failures: ${data.reliability?.operational.retrieval.failed ?? 0}\n${retrievalFailureLines}${data.reliabilityError === null ? "" : `reliability_error: ${data.reliabilityError}\n`}${agentLines}\n${externalSurfaceLines}\n`);
 }
 async function disconnectCommand(args) {
     const parsed = parseOutputArguments(args, DISCONNECT_HELP, "disconnect");
@@ -2430,6 +2561,7 @@ export async function disconnectInstallation(paths = getLorePaths(), preservePen
         rm(resolve(dirname(paths.runtime), "retrieval-task.js"), { force: true }),
         rm(resolve(dirname(paths.runtime), "runtime-redaction.js"), { force: true }),
         rm(resolve(dirname(paths.runtime), "user-message.js"), { force: true }),
+        rm(resolve(dirname(paths.runtime), "host-envelopes.js"), { force: true }),
         rm(resolve(dirname(paths.runtime), "skill-guidance.js"), { force: true }),
         rm(paths.runtimeInvocationHealthWriter, { force: true }),
         rm(paths.runtimeVersion, { force: true }),
@@ -2441,6 +2573,59 @@ export async function disconnectInstallation(paths = getLorePaths(), preservePen
     ]);
     return { connected: false, changedHookFiles, backups };
 }
+/**
+ * Server-side queue health. Dead embedding jobs name the operator fix: once the
+ * provider is repaired, `lore embeddings repair` retries them without waiting
+ * for the reconciler's backoff.
+ */
+export function operationalMetricsCheck(metrics) {
+    const captureBacklog = metrics.captureReplay.captureExtraction.pending +
+        metrics.captureReplay.captureExtraction.running;
+    const embeddingBacklog = metrics.captureReplay.memoryEmbedding.pending +
+        metrics.captureReplay.memoryEmbedding.running;
+    const embeddingDeadLetters = metrics.captureReplay.memoryEmbedding.dead;
+    const deadLetters = metrics.captureReplay.captureExtraction.dead + embeddingDeadLetters;
+    const detectedFailures = metrics.silentFailures.count +
+        metrics.guard.failures +
+        deadLetters;
+    return {
+        name: "server-operational-metrics",
+        status: metrics.silentFailures.count > 0 || deadLetters > 0
+            ? "error"
+            : metrics.guard.failures > 0 ||
+                captureBacklog > 0 ||
+                embeddingBacklog > 0
+                ? "warning"
+                : "ok",
+        detail: `${detectedFailures} detected failure(s), ${captureBacklog} capture and ${embeddingBacklog} embedding job(s) in backlog; ${metrics.guard.latency.samples} Guard latency sample(s)` +
+            (embeddingDeadLetters > 0
+                ? `; ${embeddingDeadLetters} dead embedding job(s): fix the embedding provider, then run lore embeddings repair`
+                : ""),
+    };
+}
+/**
+ * Local outbox health. Dead letters that can never be replayed (an old snapshot
+ * format or a permanent rejection) are a note, not an error: replaying them
+ * cannot help, and doctor prunes them after the retention window.
+ */
+export function durableOutboxCheck(outbox, pruned = 0) {
+    const unexplained = outbox.dead - outbox.unrecoverable;
+    const retentionDays = Math.round(DEAD_LETTER_RETENTION_MS / (24 * 60 * 60_000));
+    return {
+        name: "durable-capture-outbox",
+        status: outbox.authBlocked > 0 || unexplained > 0
+            ? "error"
+            : outbox.ready > 0 || outbox.inFlight > 0 || outbox.unrecoverable > 0
+                ? "warning"
+                : "ok",
+        detail: `${outbox.total} total; ${outbox.ready} ready, ${outbox.authBlocked} authentication-blocked, ${outbox.dead} dead-letter` +
+            (outbox.unrecoverable > 0
+                ? `; note: ${outbox.unrecoverable} dead letter(s) cannot be replayed (old snapshot format or permanent rejection) and are pruned after ${retentionDays} days`
+                : "") +
+            (pruned > 0 ? `; pruned ${pruned} unrecoverable dead letter(s) older than ${retentionDays} days` : "") +
+            (outbox.oldestFailure ? `; oldest failure (${outbox.oldestFailure.attempts} attempts): ${outbox.oldestFailure.message}` : ""),
+    };
+}
 async function apiChecks(config) {
     const readinessUrl = `${config.apiUrl}/health/ready`;
     let readiness;
@@ -2505,27 +2690,7 @@ async function apiChecks(config) {
         if (!response.ok) {
             throw new Error("Operational metrics request failed");
         }
-        const metrics = OperationalMetricsResponseSchema.parse(await response.json());
-        const captureBacklog = metrics.captureReplay.captureExtraction.pending +
-            metrics.captureReplay.captureExtraction.running;
-        const embeddingBacklog = metrics.captureReplay.memoryEmbedding.pending +
-            metrics.captureReplay.memoryEmbedding.running;
-        const deadLetters = metrics.captureReplay.captureExtraction.dead +
-            metrics.captureReplay.memoryEmbedding.dead;
-        const detectedFailures = metrics.silentFailures.count +
-            metrics.guard.failures +
-            deadLetters;
-        checks.push({
-            name: "server-operational-metrics",
-            status: metrics.silentFailures.count > 0 || deadLetters > 0
-                ? "error"
-                : metrics.guard.failures > 0 ||
-                    captureBacklog > 0 ||
-                    embeddingBacklog > 0
-                    ? "warning"
-                    : "ok",
-            detail: `${detectedFailures} detected failure(s), ${captureBacklog} capture and ${embeddingBacklog} embedding job(s) in backlog; ${metrics.guard.latency.samples} Guard latency sample(s)`,
-        });
+        checks.push(operationalMetricsCheck(OperationalMetricsResponseSchema.parse(await response.json())));
     }
     catch {
         checks.push({
@@ -2556,6 +2721,7 @@ async function doctorCommand(args) {
     }
     const paths = getLorePaths();
     const config = await diagnosticConfig(paths, process.cwd());
+    const prunedDeadLetters = await pruneUnrecoverableDeadLetters(config, paths);
     const status = await statusData(paths, process.cwd());
     const checks = [{ name: "capture-folder", status: status.folderAccess.allowed ? "ok" : "warning", detail: status.folderAccess.allowed ? status.folderAccess.reason : `Recording is off here: ${status.folderAccess.reason}. Run lore scope check <folder> to verify a selected folder.` }];
     checks.push({
@@ -2658,18 +2824,7 @@ async function doctorCommand(args) {
             "not initialized",
     });
     if (status.reliability !== null) {
-        checks.push({
-            name: "durable-capture-outbox",
-            status: status.reliability.outbox.authBlocked > 0 ||
-                status.reliability.outbox.dead > 0
-                ? "error"
-                : status.reliability.outbox.ready > 0 ||
-                    status.reliability.outbox.inFlight > 0
-                    ? "warning"
-                    : "ok",
-            detail: `${status.reliability.outbox.total} total; ${status.reliability.outbox.ready} ready, ${status.reliability.outbox.authBlocked} authentication-blocked, ${status.reliability.outbox.dead} dead-letter` +
-                (status.reliability.outbox.oldestFailure ? `; oldest failure (${status.reliability.outbox.oldestFailure.attempts} attempts): ${status.reliability.outbox.oldestFailure.message}` : ""),
-        });
+        checks.push(durableOutboxCheck(status.reliability.outbox, prunedDeadLetters));
         checks.push({
             name: "verified-snapshot-cache",
             status: status.reliability.trustKeys > 0 ? "ok" : "warning",
@@ -2682,6 +2837,16 @@ async function doctorCommand(args) {
             status: detectedFailures > 0 ? "warning" : "ok",
             detail: `${detectedFailures} detected failure(s); Guard coverage ${operational.guard.coverageRate === null ? "not yet sampled" : `${(operational.guard.coverageRate * 100).toFixed(1)}%`}, context fallback ${operational.retrieval.fallbackRate === null ? "not yet sampled" : `${(operational.retrieval.fallbackRate * 100).toFixed(1)}%`}`,
         });
+        const retrievalReasons = Object.entries(operational.retrieval.failureReasons)
+            .sort(([reasonA, countA], [reasonB, countB]) => countB - countA || reasonA.localeCompare(reasonB));
+        const lastRetrievalFailure = operational.retrieval.lastFailure;
+        checks.push({
+            name: "context-retrieval-failures",
+            status: retrievalReasons.length > 0 ? "warning" : "ok",
+            detail: retrievalReasons.length === 0
+                ? "no live retrieval failures recorded"
+                : `${retrievalReasons.map(([reason, count]) => `${reason}=${count}`).join(", ")}; last ${lastRetrievalFailure === null ? "unknown" : `${lastRetrievalFailure.reason} on ${lastRetrievalFailure.path} request (${lastRetrievalFailure.agent}) at ${lastRetrievalFailure.at}`}`,
+        });
     }
     const incompleteInvocations = status.agents.filter((agent) => agent.configured && agent.invocation.state === "incomplete").length;
     const failedInvocations = status.agents.filter((agent) => agent.configured && agent.invocation.state === "failed").length;
@@ -2727,6 +2892,9 @@ async function printCommandHelp(path) {
         case "doctor":
             process.stdout.write(DOCTOR_HELP);
             return;
+        case "embeddings":
+            await runEmbeddingsCommand(args, null);
+            return;
         case "disconnect":
             process.stdout.write(DISCONNECT_HELP);
             return;
@@ -2739,6 +2907,9 @@ async function printCommandHelp(path) {
         case "ask":
             await runAskCommand(args, null);
             return;
+        case "learnings":
+            await runLearningsCommand(args, null);
+            return;
         case "remember":
             await runRememberCommand(args, null);
             return;
@@ -2823,7 +2994,7 @@ async function executeCli(args = process.argv.slice(2)) {
     const helpIndex = args.findIndex((value, index) => index > 0 && (separator < 0 || index < separator) && (value === "--help" || value === "-h"));
     if (helpIndex > 0) {
         const subcommand = args[1];
-        const grouped = ["connect", "config", "guard", "recovery", "github", "devin", "host", "self-host", "scope"].includes(command ?? "");
+        const grouped = ["connect", "config", "embeddings", "guard", "recovery", "github", "devin", "host", "self-host", "scope"].includes(command ?? "");
         await printCommandHelp([command, ...(grouped && subcommand && !subcommand.startsWith("-") ? [subcommand] : [])]);
         return;
     }
@@ -2836,7 +3007,7 @@ async function executeCli(args = process.argv.slice(2)) {
         return;
     }
     const commandArgs = args.slice(1);
-    if (["ask", "remember", "share", "resume", "continue", "approach", "skill"].includes(command) && !(command === "skill" && commandArgs[0] === "discover")) {
+    if (["ask", "learnings", "remember", "share", "resume", "continue", "approach", "skill"].includes(command) && !(command === "skill" && commandArgs[0] === "discover")) {
         const decision = await checkDirectory(process.cwd(), getLorePaths(["approach", "skill"].includes(command) ? process.env.LORE_HOME : undefined).home);
         if (!decision.allowed)
             throw new Error(`Lore is off in this folder. ${decision.reason}`);
@@ -2876,6 +3047,9 @@ async function executeCli(args = process.argv.slice(2)) {
         case "ask":
             await runAskCommand(commandArgs, await readConnectorConfig(getLorePaths(), process.cwd()));
             return;
+        case "learnings":
+            await runLearningsCommand(commandArgs, await readConnectorConfig(getLorePaths(), process.cwd()));
+            return;
         case "remember":
             await runRememberCommand(commandArgs, await readConnectorConfig(getLorePaths(), process.cwd()));
             return;
@@ -2940,6 +3114,9 @@ async function executeCli(args = process.argv.slice(2)) {
         case "doctor":
             await doctorCommand(commandArgs);
             return;
+        case "embeddings":
+            await runEmbeddingsCommand(commandArgs, await readConnectorConfig(getLorePaths(), process.cwd()));
+            return;
         case "self-host":
             await runSelfHostCommand(commandArgs, process.env, {
                 connect: async (request) => {