@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/catalog/marketplaces.service.js

@@ -1,19 +1,36 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { randomUUID } from "node:crypto";
-import { CATALOG_ITEM_NAME_RE, marketplaceEntryVersion, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, SDK_VERSION, SEMVER_VERSION_RE, } from "@capybara-hq/plugin-sdk";
+import { CATALOG_ITEM_NAME_RE, marketplaceEntryDeprecation, marketplaceEntryVersion, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, pluginDescription, SDK_VERSION, SEMVER_VERSION_RE, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
 import { MARKETPLACE_MAX_MIRRORS } from "../config/schema.js";
 import { ConfigError } from "../config/types.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
-import { DEPLOYMENT_SECRETS_ORG } from "../extensions/deployment-config.js";
+import { DEPLOYMENT_SECRETS_ORG } from "../extensions/deployment-config-store.js";
 import { audit } from "../identity/audit.js";
-import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER, KEYRING } from "../infra/tokens.js";
 import { KERNEL_VERSION } from "../version.js";
 import { CLAUDE_PLUGIN_FILE } from "./claude/manifest.js";
 import { CLAUDE_MARKETPLACE_FILE, parseClaudeMarketplace, } from "./claude/marketplace.js";
 import { expandGitUrl, GitSourceError, gitErrorDetails, gitLocationIdentity, gitUrlIdentity, normalGitPath, readGitTreeAndOids, resolveGitCommit, } from "./git-source.js";
+import { CatalogSourceLock } from "./locks.js";
 import { fetchMarketplaceManifest, MarketplaceFetchError, MarketplaceInvalidError, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
+import { checkMarketplaceIcon, fetchMarketplaceIcon, gitIconPaths, MARKETPLACE_ICON_CONCURRENCY, MARKETPLACE_ICON_FETCHES_MAX, MARKETPLACE_ICON_MAX_BYTES, MARKETPLACE_ICON_RETRY_MS, marketplaceIconUrl, wantedIcons, } from "./marketplace-icons.js";
 import { compareVersions, newestFirst, sameRelease } from "./versions.js";
 /** 官方清单来源的 id。 */
 export const OFFICIAL_MARKETPLACE_ID = "official";
@@ -227,6 +244,20 @@ export function headsToResolve(entries, imported, config, max) {
 export const HOST_VERSIONS = { kernel: KERNEL_VERSION, sdk: SDK_VERSION };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export const entryCompatible = (e) => e.minKernel === undefined || semver.gte(HOST_VERSIONS.kernel, e.minKernel);
+/** Whether the marketplace marks the entry deprecated (`deprecated: true` or with a reason). */
+export const entryDeprecated = (e) => marketplaceEntryDeprecation(e) !== null;
+/**
+ * Refuses importing (or requesting) a deprecated marketplace entry: 409
+ * `marketplace.entry_deprecated`, its reason in the message and details.
+ */
+export function assertEntryNotDeprecated(e) {
+    const d = marketplaceEntryDeprecation(e);
+    if (d === null)
+        return;
+    const version = marketplaceEntryVersion(e);
+    throw new ApiError("marketplace.entry_deprecated", `${e.name}${version !== null ? `@${version}` : ""} is deprecated by its marketplace` +
+        `${d.reason !== null ? `: ${d.reason}` : ""}; import another version`, [{ entry: e.name, version, reason: d.reason }]);
+}
 /**
  * The form of a marketplace address (spec §5.1): `owner/repo` (expanded to GitHub), an https URL
  * whose path ends in `.git`, or any URL with `form: "git"` is a git repository; anything else
@@ -266,7 +297,7 @@ export function hostAllowed(host, config) {
     return allowed.length === 0 || allowed.includes(host.toLowerCase());
 }
 /** Why an entry is not importable from a marketplace of `form`, or undefined when it is. */
-function unimportable(e, form, config) {
+export function unimportable(e, form, config) {
     if ("path" in e.source && form !== "git")
         return "path_needs_git_marketplace";
     const host = entrySourceHost(e);
@@ -276,10 +307,30 @@ function unimportable(e, form, config) {
 }
 /** 来源是否生效：本身启用，official 还要配置没关。 */
 export const sourceEffective = (row, config) => row.enabled && (!row.builtin || config.marketplaces.official.enabled);
+/**
+ * The default entry of a marketplace plugin (`version` `""`: the entry without a version), the
+ * same order as the web's market row (`groupMarketplaceEntries`, apps/web/src/lib/catalog.ts):
+ * the newest `usable` versioned entry, a stable version before a prerelease; else the entry
+ * without a version that is not deprecated; else the newest versioned one that is not deprecated;
+ * else the entry without a version; else the newest.
+ */
+export function pickDefaultEntry(entries, o) {
+    const versioned = entries
+        .filter((e) => e.version !== "")
+        .sort((a, b) => newestFirst(a.version, b.version));
+    const bare = entries.filter((e) => e.version === "");
+    return (versioned.find((e) => o.usable(e) && semver.prerelease(e.version) === null) ??
+        versioned.find(o.usable) ??
+        bare.find((e) => !o.deprecated(e)) ??
+        versioned.find((e) => !o.deprecated(e)) ??
+        bare[0] ??
+        versioned[0]);
+}
 /**
  * Reads a marketplace entry for import: `version` given -> the entry listing that version; omitted
- * -> the newest compatible versioned entry, else the entry without a version, else the newest
- * versioned one (refused later as incompatible). Marketplace missing -> `marketplace.not_found`;
+ * -> {@link pickDefaultEntry} over the compatible, importable entries that are not deprecated
+ * (a fallback is refused later as incompatible or deprecated). Marketplace missing ->
+ * `marketplace.not_found`;
  * marketplace disabled (official offline included), entry or version missing ->
  * `marketplace.entry_not_found`.
  */
@@ -309,13 +360,13 @@ export async function loadMarketplaceEntry(db, config, sourceId, name, version)
         pickedRow = entries.find((e) => e.version === version);
     }
     else {
-        const versioned = entries
-            .filter((e) => e.version !== "")
-            .sort((a, b) => newestFirst(a.version, b.version));
-        pickedRow =
-            versioned.find((e) => entryCompatible(e.entry)) ??
-                entries.find((e) => e.version === "") ??
-                versioned[0];
+        pickedRow = pickDefaultEntry(entries, {
+            // compatible, importable, not deprecated
+            usable: (e) => entryCompatible(e.entry) &&
+                unimportable(e.entry, src.form, config) === undefined &&
+                !entryDeprecated(e.entry),
+            deprecated: (e) => entryDeprecated(e.entry),
+        });
     }
     const picked = pickedRow?.entry;
     if (!picked) {
@@ -337,19 +388,37 @@ export async function loadMarketplaceEntry(db, config, sourceId, name, version)
     };
 }
 /**
- * Marketplaces (D16 / C25 / C26, `/api/v1/admin/marketplaces/*`, enterprise admins only): the official
+ * Marketplaces (D16 / C25 / C26, `/api/v1/admin/marketplaces/*`, super admins only): the official
  * marketplace (config `marketplaces.official.*`, synced at startup into the marketplace with id
- * `official`) and enterprise marketplaces (PG, optional token in secrets). A refresh (maintenance
+ * `official`) and custom marketplaces (PG, optional token in secrets). A refresh (maintenance
  * job `catalogs-refresh` every `marketplaces.refreshIntervalMinutes` minutes, or manual) tries the main
  * URL and then the mirrors with If-None-Match; on success it replaces that marketplace's cached
  * entries as a whole, when all fail (an invalid manifest included) it keeps the previous ones with
  * status `error`. A status change audits `marketplace.refreshed` and logs once. Stateless, shared
  * by every replica.
  */
-export class MarketplacesService {
-    d;
-    constructor(d) {
-        this.d = d;
+let MarketplacesService = class MarketplacesService {
+    kdb;
+    adminLock;
+    sourceLock;
+    config;
+    keyring;
+    log;
+    txHost;
+    constructor(kdb, 
+    /** The super admin lock (identity/super-admin.ts): joins the caller's transaction. */
+    adminLock, sourceLock, config, keyring, log, txHost) {
+        this.kdb = kdb;
+        this.adminLock = adminLock;
+        this.sourceLock = sourceLock;
+        this.config = config;
+        this.keyring = keyring;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    get db() {
+        return this.kdb.db;
     }
     /**
      * Creates / updates the official marketplace from config (name, URL, its form per
@@ -360,14 +429,14 @@ export class MarketplacesService {
      * without the schema).
      */
     async syncOfficialFromConfig() {
-        const o = this.d.config().marketplaces.official;
+        const o = this.config.get().marketplaces.official;
         const { form, url } = marketplaceForm(o.url);
         if (form === "git" && o.mirrors.length > 0) {
             throw new ConfigError("invalid configuration:\n  - marketplaces.official.mirrors: a git marketplace has no mirrors (point marketplaces.official.url at a mirror repository instead)");
         }
         const mirrors = JSON.stringify(o.mirrors);
         const same = sql `marketplaces.url = excluded.url AND marketplaces.form = excluded.form`;
-        await this.d.db
+        await this.db
             .insertInto("marketplaces")
             .values({
             id: OFFICIAL_MARKETPLACE_ID,
@@ -393,7 +462,7 @@ export class MarketplacesService {
     }
     /** 全部来源（official 在前，其余按创建时间）。 */
     async list() {
-        const rows = (await this.d.db
+        const rows = (await this.db
             .selectFrom("marketplaces")
             .selectAll()
             .orderBy("builtin", "desc")
@@ -403,7 +472,7 @@ export class MarketplacesService {
         return this.views(rows);
     }
     async get(id) {
-        const row = (await this.d.db
+        const row = (await this.db
             .selectFrom("marketplaces")
             .selectAll()
             .where("id", "=", id)
@@ -413,7 +482,7 @@ export class MarketplacesService {
         return (await this.views([row]))[0];
     }
     /**
-     * Adds an enterprise marketplace (audit `marketplace.added`). URL and mirrors must be https,
+     * Adds a custom marketplace (audit `marketplace.added`). URL and mirrors must be https,
      * without user info. The form follows {@link marketplaceForm}; a git marketplace may name a `ref`
      * (branch or tag, default the remote HEAD) and has no mirrors.
      */
@@ -425,44 +494,67 @@ export class MarketplacesService {
         if (input.token !== undefined)
             this.checkToken(input.token);
         const id = randomUUID();
-        await this.d.db.transaction().execute(async (trx) => {
-            await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            await trx
-                .insertInto("marketplaces")
-                .values({
-                id,
+        await this.writeAdd(actor, id, { ...input, name, form, url }, opts);
+        return this.get(id);
+    }
+    /**
+     * The read-only checks of {@link add}, for the `Platform` tool's precheck (before the card): the
+     * name, URL and git fields as `add` checks them (throws `validation_failed`), then the source
+     * that has the same URL and ref already, if any (adding a duplicate is allowed; the tool points
+     * the agent at the existing source instead).
+     */
+    async checkAdd(input) {
+        this.checkName(input.name);
+        const { form, url } = marketplaceForm(input.url);
+        this.checkUrls(url, []);
+        this.checkGitFields(form, input.ref ?? null, []);
+        const same = await this.db
+            .selectFrom("marketplaces")
+            .select(["id", "name"])
+            .where("url", "=", url)
+            .where("ref", input.ref === undefined ? "is" : "=", input.ref ?? null)
+            .executeTakeFirst();
+        return same ?? null;
+    }
+    async writeAdd(actor, id, input, opts) {
+        const { name, url, form } = input;
+        const t = this.db;
+        await this.adminLock.lockAndAuthorize(actor);
+        await t
+            .insertInto("marketplaces")
+            .values({
+            id,
+            name,
+            url,
+            form,
+            ref: input.ref ?? null,
+            mirrors: JSON.stringify(input.mirrors ?? []),
+            builtin: false,
+            enabled: true,
+            created_by: actor,
+        })
+            .execute();
+        if (input.token !== undefined) {
+            await this.secrets().set(DEPLOYMENT_SECRETS_ORG, tokenKey(id), input.token);
+        }
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "marketplace.added",
+            target: id,
+            detail: {
                 name,
                 url,
                 form,
-                ref: input.ref ?? null,
-                mirrors: JSON.stringify(input.mirrors ?? []),
-                builtin: false,
-                enabled: true,
-                created_by: actor,
-            })
-                .execute();
-            if (input.token !== undefined) {
-                await this.secrets(trx).set(DEPLOYMENT_SECRETS_ORG, tokenKey(id), input.token);
-            }
-            await audit(trx, {
-                actorAccountId: actor,
-                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                action: "marketplace.added",
-                target: id,
-                detail: {
-                    name,
-                    url,
-                    form,
-                    ...(input.ref !== undefined && { ref: input.ref }),
-                    mirrors: input.mirrors ?? [],
-                    hasToken: input.token !== undefined,
-                },
-            });
+                ...(input.ref !== undefined && { ref: input.ref }),
+                mirrors: input.mirrors ?? [],
+                hasToken: input.token !== undefined,
+                ...opts.auditDetail,
+            },
         });
-        return this.get(id);
     }
     /**
-     * Updates an enterprise marketplace (audit `marketplace.updated`, listing the changed fields, the
+     * Updates a custom marketplace (audit `marketplace.updated`, listing the changed fields, the
      * token's value never recorded; not written when unchanged). `token: null` clears the token.
      * Official only takes `enabled`, any other field -> `marketplace.builtin`. Changing the URL, form
      * or ref clears the ETag and the last commit (the next refresh reads everything again); a new URL
@@ -472,129 +564,131 @@ export class MarketplacesService {
      */
     async update(actor, id, patch, opts = {}) {
         const name = patch.name !== undefined ? this.checkName(patch.name) : undefined;
-        await this.d.db.transaction().execute(async (trx) => {
-            await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            const row = (await trx
-                .selectFrom("marketplaces")
-                .selectAll()
-                .where("id", "=", id)
-                .forUpdate()
-                .executeTakeFirst());
-            if (!row)
-                throw notFound();
-            if (row.builtin &&
-                (name !== undefined ||
-                    patch.url !== undefined ||
-                    patch.form !== undefined ||
-                    patch.ref !== undefined ||
-                    patch.mirrors !== undefined ||
-                    patch.token !== undefined)) {
-                throw builtinErr("changed");
-            }
-            const target = patch.url !== undefined || patch.form !== undefined
-                ? marketplaceForm(patch.url ?? row.url, patch.form)
-                : { form: row.form, url: row.url };
-            // Switching form clears the other form's fields unless the patch sets them: the ref when
-            // becoming http, the mirrors when becoming git
-            const switched = target.form !== row.form;
-            const ref = patch.ref !== undefined ? patch.ref : switched && target.form === "http" ? null : row.ref;
-            const mirrors = patch.mirrors ?? (switched && target.form === "git" ? [] : row.mirrors);
-            this.checkUrls(target.url, mirrors);
-            this.checkGitFields(target.form, ref, mirrors);
-            if (typeof patch.token === "string")
-                this.checkToken(patch.token);
-            const changed = [];
-            const set = {};
-            if (name !== undefined && name !== row.name) {
-                set.name = name;
-                changed.push("name");
-            }
-            if (target.url !== row.url) {
-                set.url = target.url;
-                changed.push("url");
-            }
-            if (target.form !== row.form) {
-                set.form = target.form;
-                changed.push("form");
-            }
-            if (ref !== row.ref) {
-                set.ref = ref;
-                changed.push("ref");
-            }
-            if (set.url !== undefined || set.form !== undefined || set.ref !== undefined) {
-                set.etag = null;
-                set.last_commit = null;
-            }
-            if (JSON.stringify(mirrors) !== JSON.stringify(row.mirrors)) {
-                set.mirrors = JSON.stringify(mirrors);
-                changed.push("mirrors");
-            }
-            if (patch.enabled !== undefined && patch.enabled !== row.enabled) {
-                set.enabled = patch.enabled;
-                changed.push("enabled");
-            }
-            if (Object.keys(set).length > 0) {
-                await trx.updateTable("marketplaces").set(set).where("id", "=", id).execute();
-            }
-            if (patch.token !== undefined) {
-                const secrets = this.secrets(trx);
-                const had = (await secrets.get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) !== null;
-                if (patch.token === null) {
-                    if (had) {
-                        await secrets.delete(DEPLOYMENT_SECRETS_ORG, tokenKey(id));
-                        changed.push("token");
-                    }
-                }
-                else {
-                    await secrets.set(DEPLOYMENT_SECRETS_ORG, tokenKey(id), patch.token);
+        await this.writeUpdate(actor, id, name, patch, opts);
+        return this.get(id);
+    }
+    async writeUpdate(actor, id, name, patch, opts) {
+        const t = this.db;
+        await this.adminLock.lockAndAuthorize(actor);
+        const row = (await t
+            .selectFrom("marketplaces")
+            .selectAll()
+            .where("id", "=", id)
+            .forUpdate()
+            .executeTakeFirst());
+        if (!row)
+            throw notFound();
+        if (row.builtin &&
+            (name !== undefined ||
+                patch.url !== undefined ||
+                patch.form !== undefined ||
+                patch.ref !== undefined ||
+                patch.mirrors !== undefined ||
+                patch.token !== undefined)) {
+            throw builtinErr("changed");
+        }
+        const target = patch.url !== undefined || patch.form !== undefined
+            ? marketplaceForm(patch.url ?? row.url, patch.form)
+            : { form: row.form, url: row.url };
+        // Switching form clears the other form's fields unless the patch sets them: the ref when
+        // becoming http, the mirrors when becoming git
+        const switched = target.form !== row.form;
+        const ref = patch.ref !== undefined ? patch.ref : switched && target.form === "http" ? null : row.ref;
+        const mirrors = patch.mirrors ?? (switched && target.form === "git" ? [] : row.mirrors);
+        this.checkUrls(target.url, mirrors);
+        this.checkGitFields(target.form, ref, mirrors);
+        if (typeof patch.token === "string")
+            this.checkToken(patch.token);
+        const changed = [];
+        const set = {};
+        if (name !== undefined && name !== row.name) {
+            set.name = name;
+            changed.push("name");
+        }
+        if (target.url !== row.url) {
+            set.url = target.url;
+            changed.push("url");
+        }
+        if (target.form !== row.form) {
+            set.form = target.form;
+            changed.push("form");
+        }
+        if (ref !== row.ref) {
+            set.ref = ref;
+            changed.push("ref");
+        }
+        if (set.url !== undefined || set.form !== undefined || set.ref !== undefined) {
+            set.etag = null;
+            set.last_commit = null;
+        }
+        if (JSON.stringify(mirrors) !== JSON.stringify(row.mirrors)) {
+            set.mirrors = JSON.stringify(mirrors);
+            changed.push("mirrors");
+        }
+        if (patch.enabled !== undefined && patch.enabled !== row.enabled) {
+            set.enabled = patch.enabled;
+            changed.push("enabled");
+        }
+        if (Object.keys(set).length > 0) {
+            await t.updateTable("marketplaces").set(set).where("id", "=", id).execute();
+        }
+        if (patch.token !== undefined) {
+            const secrets = this.secrets();
+            const had = (await secrets.get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) !== null;
+            if (patch.token === null) {
+                if (had) {
+                    await secrets.delete(DEPLOYMENT_SECRETS_ORG, tokenKey(id));
                     changed.push("token");
                 }
             }
-            if (changed.length === 0)
-                return;
-            await audit(trx, {
-                actorAccountId: actor,
-                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                action: "marketplace.updated",
-                target: id,
-                detail: {
-                    changed,
-                    ...(set.enabled !== undefined && { enabled: set.enabled }),
-                    ...(set.url !== undefined && { url: set.url }),
-                    ...(set.form !== undefined && { form: set.form }),
-                    ...(set.ref !== undefined && { ref: set.ref }),
-                },
-            });
+            else {
+                await secrets.set(DEPLOYMENT_SECRETS_ORG, tokenKey(id), patch.token);
+                changed.push("token");
+            }
+        }
+        if (changed.length === 0)
+            return;
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "marketplace.updated",
+            target: id,
+            detail: {
+                changed,
+                ...(set.enabled !== undefined && { enabled: set.enabled }),
+                ...(set.url !== undefined && { url: set.url }),
+                ...(set.form !== undefined && { form: set.form }),
+                ...(set.ref !== undefined && { ref: set.ref }),
+                ...opts.auditDetail,
+            },
         });
-        return this.get(id);
     }
     /**
-     * Deletes an enterprise marketplace (audit `marketplace.removed`): its cached entries and token
+     * Deletes a custom marketplace (audit `marketplace.removed`): its cached entries and token
      * are deleted; imported catalog items are kept (their marketplace becomes null). Official can
      * only be disabled -> `marketplace.builtin`.
      */
     async remove(actor, id, opts = {}) {
-        await this.d.db.transaction().execute(async (trx) => {
-            await lockEnterpriseAdminsAndAuthorize(trx, actor);
-            const row = await trx
-                .selectFrom("marketplaces")
-                .select(["builtin", "name", "url"])
-                .where("id", "=", id)
-                .forUpdate()
-                .executeTakeFirst();
-            if (!row)
-                throw notFound();
-            if (row.builtin)
-                throw builtinErr("deleted");
-            await trx.deleteFrom("marketplaces").where("id", "=", id).execute();
-            await this.secrets(trx).delete(DEPLOYMENT_SECRETS_ORG, tokenKey(id));
-            await audit(trx, {
-                actorAccountId: actor,
-                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                action: "marketplace.removed",
-                target: id,
-                detail: { name: row.name, url: row.url },
-            });
+        const t = this.db;
+        await this.adminLock.lockAndAuthorize(actor);
+        const row = await t
+            .selectFrom("marketplaces")
+            .select(["builtin", "name", "url"])
+            .where("id", "=", id)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        if (row.builtin)
+            throw builtinErr("deleted");
+        await t.deleteFrom("marketplaces").where("id", "=", id).execute();
+        await this.secrets().delete(DEPLOYMENT_SECRETS_ORG, tokenKey(id));
+        await audit(t, {
+            actorAccountId: actor,
+            ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+            action: "marketplace.removed",
+            target: id,
+            detail: { name: row.name, url: row.url, ...opts.auditDetail },
         });
     }
     /**
@@ -609,8 +703,8 @@ export class MarketplacesService {
      * (the message gives each URL's failure).
      */
     async refresh(id, signal, actor, opts = {}) {
-        const config = this.d.config();
-        const row = (await this.d.db
+        const config = this.config.get();
+        const row = (await this.db
             .selectFrom("marketplaces")
             .selectAll()
             .where("id", "=", id)
@@ -624,7 +718,7 @@ export class MarketplacesService {
         }
         const token = row.builtin
             ? undefined
-            : ((await this.secrets(this.d.db).get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) ?? undefined);
+            : ((await this.secrets().get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) ?? undefined);
         const tokenOrigin = new URL(row.url).origin;
         const errors = [];
         // the API code of each failed URL (undefined: an ordinary fetch failure)
@@ -660,7 +754,7 @@ export class MarketplacesService {
                     etag: row.etag,
                     ...(token !== undefined && { token, tokenOrigin }),
                     maxBytes: config.marketplaces.maxIndexBytes,
-                    timeoutMs: this.d.fetchTimeoutMs ?? MARKETPLACE_FETCH_TIMEOUT_MS,
+                    timeoutMs: MARKETPLACE_FETCH_TIMEOUT_MS,
                     net: marketplaceNetPolicy(config),
                     signal,
                 });
@@ -688,89 +782,35 @@ export class MarketplacesService {
             ? new Map()
             : await this.resolveHeads(id, outcome === "not_modified" ? undefined : outcome.manifest.plugins, { url: row.url, token }, signal);
         const lastError = status === "error" ? errors.join("\n").slice(0, MAX_ERROR_CHARS) : null;
-        const from = await this.d.db.transaction().execute(async (trx) => {
-            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.catalog-source:${id}`}))`.execute(trx);
-            const cur = await trx
-                .selectFrom("marketplaces")
-                .select(["last_status", "url", "mirrors", "form", "ref", "last_commit"])
-                .where("id", "=", id)
-                .forUpdate()
-                .executeTakeFirst();
-            if (!cur)
-                throw notFound();
-            // The admin changed the URL / mirrors during the fetch: what we fetched is the old address's
-            // content, so write no entries, ETag or status (the next refresh uses the new address)
-            if (cur.url !== row.url ||
-                cur.form !== row.form ||
-                cur.ref !== row.ref ||
-                // another refresh wrote a commit meanwhile: ours may be older, never move it back
-                cur.last_commit !== row.last_commit ||
-                JSON.stringify(cur.mirrors) !== JSON.stringify(row.mirrors)) {
-                return "stale";
-            }
-            if (outcome !== undefined && outcome !== "not_modified") {
-                await this.replaceEntries(trx, id, outcome.manifest.plugins, outcome.trees, outcome.overlays);
-            }
-            if (outcome !== undefined) {
-                // heads not resolved this time are unknown again (never a stale head)
-                await trx
-                    .updateTable("marketplace_entries")
-                    .set({ head_commit: null, tree_oid: null })
-                    .where("source_id", "=", id)
-                    .where("head_commit", "is not", null)
-                    .execute();
-            }
-            for (const [key, head] of heads) {
-                const [name, version] = key.split("\0");
-                await trx
-                    .updateTable("marketplace_entries")
-                    .set({ head_commit: head.commit, tree_oid: head.tree })
-                    .where("source_id", "=", id)
-                    .where("name", "=", name)
-                    .where("version", "=", version)
-                    .execute();
-            }
-            await trx
-                .updateTable("marketplaces")
-                .set({
-                last_status: status,
-                last_error: lastError,
-                last_refreshed_at: sql `now()`,
-                ...(outcome !== undefined &&
-                    outcome !== "not_modified" && {
-                    etag: outcome.etag,
-                    last_commit: outcome.commit ?? null,
-                    owner_name: outcome.manifest.owner?.name ?? null,
-                    skipped: JSON.stringify(outcome.skipped ?? []),
-                }),
-            })
-                .where("id", "=", id)
-                .execute();
-            if (cur.last_status !== status) {
-                await audit(trx, {
-                    ...(actor !== undefined && { actorAccountId: actor }),
-                    ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
-                    action: "marketplace.refreshed",
-                    target: id,
-                    detail: {
-                        from: cur.last_status,
-                        to: status,
-                        ...(lastError !== null && { error: lastError }),
-                    },
-                });
-            }
-            return cur.last_status;
-        });
+        const from = await this.recordRefresh(row, { outcome, heads, status, lastError }, actor, opts);
         if (from === "stale") {
-            this.d.log.info("marketplace changed during refresh; result discarded", { marketplace: id });
+            this.log.info("marketplace changed during refresh; result discarded", { marketplace: id });
             return this.get(id);
         }
+        if (outcome !== undefined) {
+            // a failed icon never fails the refresh: the entry shows its initial
+            try {
+                await this.syncIcons(row, outcome === "not_modified" ? undefined : outcome.icons, signal);
+                // only now is the commit fully synced: a refresh at it may be not_modified from here on
+                if (outcome !== "not_modified" && outcome.commit !== undefined) {
+                    await this.db
+                        .updateTable("marketplaces")
+                        .set({ icons_commit: outcome.commit })
+                        .where("id", "=", id)
+                        .where("last_commit", "=", outcome.commit)
+                        .execute();
+                }
+            }
+            catch (err) {
+                this.log.warn("marketplace icons not updated", { marketplace: id, err });
+            }
+        }
         if (from !== status) {
             if (status === "error") {
-                this.d.log.warn("marketplace refresh failed", { marketplace: id, error: lastError });
+                this.log.warn("marketplace refresh failed", { marketplace: id, error: lastError });
             }
             else {
-                this.d.log.info("marketplace refreshed", { marketplace: id });
+                this.log.info("marketplace refreshed", { marketplace: id });
             }
         }
         if (status === "error" && opts.throwOnError) {
@@ -784,8 +824,9 @@ export class MarketplacesService {
     }
     /**
      * Reads a git marketplace (spec §5.1): resolves `ref` (default the remote HEAD); the same commit
-     * as the last refresh -> `not_modified` (nothing else is fetched). Otherwise only what the root
-     * needs is read, in this order: `.capybara-plugin/marketplace.json` (at most
+     * as the last refresh, whose path icons were stored too (`icons_commit`) -> `not_modified`
+     * (nothing else is fetched; a commit whose icons were not stored is read again). Otherwise only
+     * what the root needs is read, in this order: `.capybara-plugin/marketplace.json` (at most
      * `marketplaces.maxIndexBytes`, validated like an http manifest); `.claude-plugin/marketplace.json`
      * (a Claude Code marketplace: each entry's component fields and `strict` become its overlay, and
      * entries Capybara cannot store are `skipped`); else a single-plugin repo (the root has
@@ -794,7 +835,7 @@ export class MarketplacesService {
      * (Decision 3). Throws {@link GitSourceError} or {@link MarketplaceInvalidError}.
      */
     async fetchGit(row, token, signal) {
-        const config = this.d.config();
+        const config = this.config.get();
         const options = {
             net: marketplaceNetPolicy(config),
             maxBytes: config.packages.maxBytes,
@@ -803,12 +844,12 @@ export class MarketplacesService {
         };
         const loc = { url: row.url, ...(row.ref !== null && { ref: row.ref }) };
         const commit = await resolveGitCommit(loc, options);
-        if (commit === row.last_commit)
+        if (commit === row.last_commit && commit === row.icons_commit)
             return "not_modified";
         const MANIFEST = ".capybara-plugin/marketplace.json";
         let hasSkills = false;
         const dec = (b) => new TextDecoder().decode(b);
-        const { files, trees } = await readGitTreeAndOids({ url: row.url, commit }, {
+        const { files, trees, blobs: icons, } = await readGitTreeAndOids({ url: row.url, commit }, {
             ...options,
             include: (path, type) => {
                 if (path === "skills" && type === "tree")
@@ -824,6 +865,13 @@ export class MarketplacesService {
             trees: (read) => read.has(MANIFEST) || !read.has(CLAUDE_MARKETPLACE_FILE)
                 ? pathEntryDirs(read.get(MANIFEST), config.marketplaces.maxIndexBytes)
                 : claudePathEntryDirs(read.get(CLAUDE_MARKETPLACE_FILE), config.marketplaces.maxIndexBytes, config.marketplaces.allowInsecureLoopback),
+            // the icon files the entries name (a Claude Code marketplace names none)
+            blobs: {
+                paths: (read) => read.has(MANIFEST) || !read.has(CLAUDE_MARKETPLACE_FILE)
+                    ? gitIconPaths(read, MANIFEST, config.marketplaces.maxIndexBytes, MARKETPLACE_ICON_FETCHES_MAX)
+                    : [],
+                maxBytes: MARKETPLACE_ICON_MAX_BYTES,
+            },
         });
         const raw = files.get(MANIFEST);
         const claudeRaw = files.get(CLAUDE_MARKETPLACE_FILE);
@@ -881,9 +929,16 @@ export class MarketplacesService {
                 if ("errors" in m) {
                     throw new MarketplaceInvalidError(`the repository is a single plugin, but its ${PLUGIN_MANIFEST_FILE} is invalid: ${m.errors.slice(0, 5).join("; ")}`, m.errors);
                 }
+                const d = pluginDescription(m.description);
                 entry = {
                     name: m.name,
-                    summary: { en: m.description.slice(0, SUMMARY_MAX) },
+                    summary: {
+                        en: d.en.slice(0, SUMMARY_MAX),
+                        ...(d.zh !== undefined && { zh: d.zh.slice(0, SUMMARY_MAX) }),
+                    },
+                    ...(m.displayName !== undefined && { displayName: m.displayName }),
+                    // the plugin's own icon, read from the same commit
+                    ...(m.icon !== undefined && { icon: `./${normalGitPath(m.icon)}` }),
                     version: m.version,
                     source: { path: "." },
                 };
@@ -903,7 +958,7 @@ export class MarketplacesService {
             }
             manifest = { schemaVersion: 1, name: row.name, plugins: [entry] };
         }
-        return { manifest, etag: null, commit, trees };
+        return { manifest, etag: null, commit, trees, icons };
     }
     /**
      * Resolves the branch heads of the entries {@link headsToResolve} picks (at most
@@ -914,9 +969,9 @@ export class MarketplacesService {
      * entry unknown (never fails the refresh). Returns `name\0version` -> head.
      */
     async resolveHeads(id, fresh, m, signal) {
-        const config = this.d.config();
+        const config = this.config.get();
         const listed = fresh ??
-            (await this.d.db
+            (await this.db
                 .selectFrom("marketplace_entries")
                 .select("entry")
                 .where("source_id", "=", id)
@@ -925,7 +980,7 @@ export class MarketplacesService {
         const names = [...new Set(listed.filter((e) => "git" in e.source).map((e) => e.name))];
         if (names.length === 0)
             return out;
-        const imported = await this.d.db
+        const imported = await this.db
             .selectFrom("catalog_items as i")
             .innerJoin("catalog_item_versions as v", "v.item_id", "i.id")
             .select(["i.name", "v.version", "v.source", "v.source_ref", "v.integrity", "v.source_detail"])
@@ -933,7 +988,7 @@ export class MarketplacesService {
             .where("i.name", "in", names)
             .execute();
         const todo = headsToResolve(listed, imported, config, MARKETPLACE_HEADS_MAX);
-        const timeoutMs = this.d.fetchTimeoutMs ?? MARKETPLACE_FETCH_TIMEOUT_MS;
+        const timeoutMs = MARKETPLACE_FETCH_TIMEOUT_MS;
         const queue = [...todo];
         await Promise.all(Array.from({ length: Math.min(HEADS_CONCURRENCY, queue.length) }, async () => {
             for (let e = queue.shift(); e !== undefined; e = queue.shift()) {
@@ -959,7 +1014,7 @@ export class MarketplacesService {
                 }
                 catch (err) {
                     // a head lookup never fails the refresh: that entry stays unknown
-                    this.d.log.warn("cannot resolve the branch head of a marketplace entry", {
+                    this.log.warn("cannot resolve the branch head of a marketplace entry", {
                         marketplace: id,
                         entry: e.name,
                         error: err instanceof Error ? err.message : String(err),
@@ -969,14 +1024,207 @@ export class MarketplacesService {
         }));
         return out;
     }
-    /** The token of an enterprise marketplace (undefined without one; official never has one). */
+    /**
+     * Brings the marketplace's stored icons (`marketplace_icons`) in line with its stored entries
+     * after a refresh (outside any transaction: downloads first, then one short write). A repository
+     * path (git marketplaces) is taken from `fresh`, the files of the commit just read, and kept as
+     * stored when the commit did not change (`fresh` undefined). A URL is downloaded only when it is
+     * not stored yet (its content is treated as fixed), at most {@link MARKETPLACE_ICON_FETCHES_MAX}
+     * per refresh, under the marketplace network rules and `marketplaces.allowedHosts`, never with
+     * the token. A failed download is remembered (`marketplace_icon_failures`) and retried only after
+     * {@link MARKETPLACE_ICON_RETRY_MS}, URLs never tried first, so broken URLs never starve the
+     * cap. An icon that is missing, too large or not a real svg / png is skipped and logged; icons
+     * (and failures) no entry names any more are deleted.
+     */
+    async syncIcons(row, fresh, signal) {
+        const config = this.config.get();
+        const entries = await this.db
+            .selectFrom("marketplace_entries")
+            .select("entry")
+            .where("source_id", "=", row.id)
+            .execute();
+        const { paths, urls } = wantedIcons(entries.map((r) => r.entry), row.form);
+        const have = new Set((await this.db
+            .selectFrom("marketplace_icons")
+            .select("ref")
+            .where("source_id", "=", row.id)
+            .execute()).map((r) => r.ref));
+        // the URLs that failed before, oldest failure first, and whether their backoff is over
+        const failures = await this.db
+            .selectFrom("marketplace_icon_failures")
+            .select([
+            "ref",
+            sql `failed_at <= now() - make_interval(secs => ${MARKETPLACE_ICON_RETRY_MS / 1000})`.as("due"),
+        ])
+            .where("source_id", "=", row.id)
+            .orderBy("failed_at")
+            .orderBy("ref")
+            .execute();
+        const failedBefore = new Map(failures.map((f) => [f.ref, f.due]));
+        const put = [];
+        const keep = new Set();
+        const problems = [];
+        for (const ref of paths) {
+            if (fresh === undefined) {
+                if (have.has(ref))
+                    keep.add(ref);
+                continue;
+            }
+            const data = fresh.get(ref.slice(2));
+            const r = data === undefined
+                ? `${ref} is not a file of at most ${MARKETPLACE_ICON_MAX_BYTES} bytes in the repository`
+                : checkMarketplaceIcon(ref, data);
+            if (typeof r === "string")
+                problems.push({ icon: ref, problem: r });
+            else
+                put.push({ ref, icon: r });
+        }
+        // IPv6 hostnames come bracketed from URL; allowedHosts entries are written without brackets
+        const hostOf = (url) => new URL(url).hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+        const neverTried = [];
+        for (const url of urls) {
+            if (have.has(url)) {
+                keep.add(url);
+                continue;
+            }
+            const host = hostOf(url);
+            if (!hostAllowed(host, config)) {
+                problems.push({ icon: url, problem: `${host} is not in marketplaces.allowedHosts` });
+            }
+            else if (!failedBefore.has(url)) {
+                neverTried.push(url);
+            }
+        }
+        // retries after the never-tried URLs, oldest failure first, within the cap
+        const retries = failures
+            .filter((f) => f.due && urls.has(f.ref) && !have.has(f.ref))
+            .map((f) => f.ref)
+            .filter((url) => hostAllowed(hostOf(url), config));
+        const toFetch = [...neverTried, ...retries].slice(0, MARKETPLACE_ICON_FETCHES_MAX);
+        const net = marketplaceNetPolicy(config);
+        const queue = [...toFetch];
+        const failed = [];
+        await Promise.all(Array.from({ length: Math.min(MARKETPLACE_ICON_CONCURRENCY, queue.length) }, async () => {
+            for (let url = queue.shift(); url !== undefined; url = queue.shift()) {
+                if (signal.aborted)
+                    return;
+                const r = await fetchMarketplaceIcon(url, { net, signal });
+                if (typeof r === "string") {
+                    problems.push({ icon: url, problem: r });
+                    // an aborted refresh says nothing about the URL
+                    if (!signal.aborted)
+                        failed.push(url);
+                }
+                else
+                    put.push({ ref: url, icon: r });
+            }
+        }));
+        if (problems.length > 0) {
+            this.log.warn("marketplace icons skipped", {
+                marketplace: row.id,
+                count: problems.length,
+                problems: problems.slice(0, 5),
+            });
+        }
+        const gone = [...have].filter((ref) => !keep.has(ref) && !put.some((p) => p.ref === ref));
+        // failures of URLs now stored or named by no entry
+        const cleared = [...failedBefore.keys()].filter((ref) => !urls.has(ref) || put.some((p) => p.ref === ref));
+        if (put.length > 0 || gone.length > 0 || failed.length > 0 || cleared.length > 0) {
+            await this.writeIcons(row.id, { put, gone, failed, cleared });
+        }
+    }
+    /**
+     * Writes a refresh's icons: upserts `put`, deletes `gone`, records the `failed` downloads and
+     * forgets the `cleared` failures (see {@link syncIcons}).
+     */
+    async writeIcons(id, w) {
+        const t = this.db;
+        if (w.gone.length > 0) {
+            await t
+                .deleteFrom("marketplace_icons")
+                .where("source_id", "=", id)
+                .where("ref", "in", w.gone)
+                .execute();
+        }
+        for (const { ref, icon } of w.put) {
+            const values = {
+                sha256: icon.sha256,
+                content_type: icon.contentType,
+                data: Buffer.from(icon.data),
+                fetched_at: sql `now()`,
+            };
+            await t
+                .insertInto("marketplace_icons")
+                .values({ source_id: id, ref, ...values })
+                .onConflict((oc) => oc.columns(["source_id", "ref"]).doUpdateSet(values))
+                .execute();
+        }
+        if (w.cleared.length > 0) {
+            await t
+                .deleteFrom("marketplace_icon_failures")
+                .where("source_id", "=", id)
+                .where("ref", "in", w.cleared)
+                .execute();
+        }
+        // sorted: two replicas refreshing at once lock the rows in the same order
+        for (const ref of [...w.failed].sort()) {
+            await t
+                .insertInto("marketplace_icon_failures")
+                .values({ source_id: id, ref })
+                .onConflict((oc) => oc.columns(["source_id", "ref"]).doUpdateSet({
+                failed_at: sql `now()`,
+                attempts: sql `marketplace_icon_failures.attempts + 1`,
+            }))
+                .execute();
+        }
+    }
+    /**
+     * A stored marketplace icon by its sha256 (the address the entries carry); not stored ->
+     * `catalog.icon_not_found`. Read from PG, never from the network. `browsable` (the org route):
+     * the marketplace must also be one the org browse lists (effective), else not found.
+     */
+    async icon(id, sha256, opts = {}) {
+        if (opts.browsable) {
+            // the org browse lists enabled marketplaces only (official also needs the config on)
+            const m = await this.db
+                .selectFrom("marketplaces")
+                .select(["builtin", "enabled"])
+                .where("id", "=", id)
+                .executeTakeFirst();
+            if (!m || !sourceEffective(m, this.config.get())) {
+                throw new ApiError("catalog.icon_not_found", "This marketplace has no such icon");
+            }
+        }
+        const row = /^[0-9a-f]{64}$/.test(sha256)
+            ? await this.db
+                .selectFrom("marketplace_icons")
+                .select(["content_type", "data"])
+                .where("source_id", "=", id)
+                .where("sha256", "=", sha256)
+                .limit(1)
+                .executeTakeFirst()
+            : undefined;
+        if (!row)
+            throw new ApiError("catalog.icon_not_found", "This marketplace has no such icon");
+        // checked again on read, like a catalog icon (`readCatalogIcon`): PG may have been changed
+        const data = new Uint8Array(row.data);
+        const checked = checkMarketplaceIcon(row.content_type === "image/svg+xml" ? "icon.svg" : "icon.png", data);
+        if (typeof checked === "string") {
+            throw new ApiError("internal", `Stored marketplace icon is invalid: ${checked}`);
+        }
+        if (checked.sha256 !== sha256) {
+            throw new ApiError("internal", "Stored marketplace icon does not match its recorded hash");
+        }
+        return { contentType: checked.contentType, data };
+    }
+    /** The token of a custom marketplace (undefined without one; official never has one). */
     async token(id) {
-        return (await this.secrets(this.d.db).get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) ?? undefined;
+        return (await this.secrets().get(DEPLOYMENT_SECRETS_ORG, tokenKey(id))) ?? undefined;
     }
     /** Refreshes every effective marketplace (maintenance job `catalogs-refresh`), one failing not stopping the rest. */
     async refreshAll(signal) {
-        const config = this.d.config();
-        const rows = await this.d.db
+        const config = this.config.get();
+        const rows = await this.db
             .selectFrom("marketplaces")
             .select(["id", "builtin", "enabled"])
             .orderBy("id")
@@ -990,7 +1238,7 @@ export class MarketplacesService {
                 await this.refresh(r.id, signal);
             }
             catch (err) {
-                this.d.log.error("marketplace refresh crashed", { marketplace: r.id, err });
+                this.log.error("marketplace refresh crashed", { marketplace: r.id, err });
             }
         }
     }
@@ -1000,9 +1248,11 @@ export class MarketplacesService {
      * first), marketplace, at most {@link MARKETPLACE_ENTRIES_MAX}; `truncated` means there are more
      * (the UI suggests narrowing the filter).
      */
-    async entries(q = {}) {
-        const config = this.d.config();
-        let query = this.d.db
+    async entries(q = {}, 
+    /** The URL of a stored marketplace icon (default: the admin route). */
+    iconUrl = marketplaceIconUrl) {
+        const config = this.config.get();
+        let query = this.db
             .selectFrom("marketplace_entries as e")
             .innerJoin("marketplaces as s", "s.id", "e.source_id")
             .select([
@@ -1034,6 +1284,8 @@ export class MarketplacesService {
                 eb(sql `coalesce(e.npm, '')`, "ilike", like),
                 eb(sql `e.entry->'summary'->>'en'`, "ilike", like),
                 eb(sql `coalesce(e.entry->'summary'->>'zh', '')`, "ilike", like),
+                eb(sql `coalesce(e.entry->'displayName'->>'en', '')`, "ilike", like),
+                eb(sql `coalesce(e.entry->'displayName'->>'zh', '')`, "ilike", like),
             ]));
         }
         const fetched = await query.execute();
@@ -1043,7 +1295,7 @@ export class MarketplacesService {
             a.source_id.localeCompare(b.source_id));
         if (rows.length === 0)
             return { items: [], truncated: false };
-        const items = await this.d.db
+        const items = await this.db
             .selectFrom("catalog_items as i")
             .leftJoin("catalog_item_versions as v", "v.item_id", "i.id")
             .select([
@@ -1078,6 +1330,16 @@ export class MarketplacesService {
             a.imported.sort(newestFirst);
             a.versions = a.imported.map((v) => v.version);
         }
+        const iconRows = await this.db
+            .selectFrom("marketplace_icons")
+            .select(["source_id", "ref", "sha256"])
+            .where("source_id", "in", [...new Set(rows.map((r) => r.source_id))])
+            .execute();
+        const iconOf = new Map(iconRows.map((i) => [`${i.source_id}\0${i.ref}`, i.sha256]));
+        const iconUrlOf = (sourceId, ref) => {
+            const sha = ref === undefined ? undefined : iconOf.get(`${sourceId}\0${ref}`);
+            return sha === undefined ? null : iconUrl(sourceId, sha);
+        };
         const views = rows.map((r) => {
             const e = r.entry;
             const version = marketplaceEntryVersion(e);
@@ -1092,17 +1354,25 @@ export class MarketplacesService {
                 name: r.name,
                 version,
                 summary: e.summary,
+                displayName: e.displayName ?? null,
                 minKernel: e.minKernel ?? null,
                 homepage: e.homepage ?? null,
                 permissions: e.permissions ?? null,
                 source: e.source,
+                deprecated: marketplaceEntryDeprecation(e),
                 format: r.claude === null ? "capybara" : "claude-code",
                 compatible,
                 importable,
                 ...(reason !== undefined && { reason }),
                 adopted: adopted ? { itemId: adopted.itemId, versions: [...adopted.versions] } : null,
-                newerAvailable: compatible && version !== null && top !== undefined && compareVersions(version, top) > 0,
+                icon: iconUrlOf(r.source_id, e.icon),
+                newerAvailable: compatible &&
+                    !entryDeprecated(e) &&
+                    version !== null &&
+                    top !== undefined &&
+                    compareVersions(version, top) > 0,
                 contentChanged: adopted !== null &&
+                    !entryDeprecated(e) &&
                     entryContentChanged(e, {
                         marketplaceId: r.source_id,
                         headCommit: r.head_commit,
@@ -1114,14 +1384,96 @@ export class MarketplacesService {
         });
         return { items: views, truncated };
     }
+    /**
+     * Writes a refresh's result under the marketplace's lock (entries, heads, status, the status
+     * change audit); `stale` when the marketplace changed during the fetch (nothing is written).
+     */
+    async recordRefresh(row, r, actor, opts) {
+        const { id } = row;
+        const { outcome, heads, status, lastError } = r;
+        await this.sourceLock.lock(id);
+        const t = this.db;
+        const cur = await t
+            .selectFrom("marketplaces")
+            .select(["last_status", "url", "mirrors", "form", "ref", "last_commit"])
+            .where("id", "=", id)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!cur)
+            throw notFound();
+        // The admin changed the URL / mirrors during the fetch: what we fetched is the old address's
+        // content, so write no entries, ETag or status (the next refresh uses the new address)
+        if (cur.url !== row.url ||
+            cur.form !== row.form ||
+            cur.ref !== row.ref ||
+            // another refresh wrote a commit meanwhile: ours may be older, never move it back
+            cur.last_commit !== row.last_commit ||
+            JSON.stringify(cur.mirrors) !== JSON.stringify(row.mirrors)) {
+            return "stale";
+        }
+        if (outcome !== undefined && outcome !== "not_modified") {
+            await this.replaceEntries(id, outcome.manifest.plugins, outcome.trees, outcome.overlays);
+        }
+        if (outcome !== undefined) {
+            // heads not resolved this time are unknown again (never a stale head)
+            await t
+                .updateTable("marketplace_entries")
+                .set({ head_commit: null, tree_oid: null })
+                .where("source_id", "=", id)
+                .where("head_commit", "is not", null)
+                .execute();
+        }
+        for (const [key, head] of heads) {
+            const [name, version] = key.split("\0");
+            await t
+                .updateTable("marketplace_entries")
+                .set({ head_commit: head.commit, tree_oid: head.tree })
+                .where("source_id", "=", id)
+                .where("name", "=", name)
+                .where("version", "=", version)
+                .execute();
+        }
+        await t
+            .updateTable("marketplaces")
+            .set({
+            last_status: status,
+            last_error: lastError,
+            last_refreshed_at: sql `now()`,
+            ...(outcome !== undefined &&
+                outcome !== "not_modified" && {
+                etag: outcome.etag,
+                last_commit: outcome.commit ?? null,
+                owner_name: outcome.manifest.owner?.name ?? null,
+                skipped: JSON.stringify(outcome.skipped ?? []),
+            }),
+        })
+            .where("id", "=", id)
+            .execute();
+        if (cur.last_status !== status) {
+            await audit(t, {
+                ...(actor !== undefined && { actorAccountId: actor }),
+                ...(opts.actorTokenId !== undefined && { actorTokenId: opts.actorTokenId }),
+                action: "marketplace.refreshed",
+                target: id,
+                detail: {
+                    from: cur.last_status,
+                    to: status,
+                    ...(lastError !== null && { error: lastError }),
+                    ...opts.auditDetail,
+                },
+            });
+        }
+        return cur.last_status;
+    }
     /**
      * Replaces the entries of a marketplace; `trees` (a git marketplace) gives each path entry the
      * tree oid of its directory.
      */
-    async replaceEntries(trx, id, entries, trees, overlays) {
-        await trx.deleteFrom("marketplace_entries").where("source_id", "=", id).execute();
+    async replaceEntries(id, entries, trees, overlays) {
+        const t = this.db;
+        await t.deleteFrom("marketplace_entries").where("source_id", "=", id).execute();
         for (let i = 0; i < entries.length; i += INSERT_BATCH) {
-            await trx
+            await t
                 .insertInto("marketplace_entries")
                 .values(entries.slice(i, i + INSERT_BATCH).map((e) => ({
                 source_id: id,
@@ -1138,15 +1490,15 @@ export class MarketplacesService {
     async views(rows) {
         if (rows.length === 0)
             return [];
-        const config = this.d.config();
+        const config = this.config.get();
         const ids = rows.map((r) => r.id);
-        const counts = await this.d.db
+        const counts = await this.db
             .selectFrom("marketplace_entries")
             .select(["source_id", (eb) => eb.fn.countAll().as("n")])
             .where("source_id", "in", ids)
             .groupBy("source_id")
             .execute();
-        const tokens = await this.d.db
+        const tokens = await this.db
             .selectFrom("secrets")
             .select("key")
             .where("namespace", "=", SECRETS_NAMESPACE)
@@ -1176,8 +1528,9 @@ export class MarketplacesService {
             createdAt: r.created_at.toISOString(),
         }));
     }
-    secrets(db) {
-        return createSecrets(db, this.d.keyring, SECRETS_NAMESPACE);
+    /** The deployment secrets on the current context's handle (the transaction, else the pool). */
+    secrets() {
+        return createSecrets(this.db, this.keyring, SECRETS_NAMESPACE);
     }
     checkName(name) {
         const n = name.trim();
@@ -1187,7 +1540,7 @@ export class MarketplacesService {
         return n;
     }
     checkUrls(url, mirrors) {
-        const allow = this.d.config().marketplaces.allowInsecureLoopback;
+        const allow = this.config.get().marketplaces.allowInsecureLoopback;
         if (mirrors.length > MARKETPLACE_MAX_MIRRORS) {
             throw new ApiError("validation_failed", `at most ${MARKETPLACE_MAX_MIRRORS} mirrors`);
         }
@@ -1214,4 +1567,33 @@ export class MarketplacesService {
             throw new ApiError("validation_failed", `token must be 1–${MAX_TOKEN_CHARS} characters without line breaks`);
         }
     }
-}
+};
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "writeAdd", null);
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "writeUpdate", null);
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "remove", null);
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "writeIcons", null);
+__decorate([
+    Transactional()
+], MarketplacesService.prototype, "recordRefresh", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], MarketplacesService.prototype, "replaceEntries", null);
+MarketplacesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(SuperAdminLock)),
+    __param(2, Inject(CatalogSourceLock)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(KEYRING)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(TransactionHost))
+], MarketplacesService);
+export { MarketplacesService };