@adea-ai/plugins 4.0.0 → 4.0.6

package/src/harness.test.ts

@@ -129,34 +129,6 @@ describe('Control Plane installation plan v2', () => {
     assert.equal(plan.compatibility, 'partial')
     assert.ok(plan.disabled.some((item) => item.component === 'hooks'))
   })
-  it('preserves instance data across releases and harnesses but isolates other instances', () => {
-    const first = createInstallationPlan(input())
-    const updatedPkg = packageFixture({ 'CHANGELOG.md': 'A new release.' })
-    const updated = createInstallationPlan({
-      ...input(updatedPkg),
-      releaseId: `release:${'c'.repeat(64)}`,
-      profile: profile({ harness: 'another-harness' }),
-    })
-    assert.equal(first.dataKey, updated.dataKey)
-    assert.notEqual(first.packageKey, updated.packageKey)
-    assert.notEqual(
-      first.dataKey,
-      createInstallationPlan({ ...input(), instanceId: 'workspace-b/user-a' }).dataKey
-    )
-    assert.notEqual(
-      first.dataKey,
-      createInstallationPlan({ ...input(), pluginId: 'plugin:other:issues' }).dataKey
-    )
-  })
-  it('does not reuse a package cache across source commits with potentially different file modes', () => {
-    const original = input()
-    const other = { ...original, source: { ...original.source, commitSha: 'c'.repeat(40) } }
-    assert.notEqual(
-      createInstallationPlan(original).packageKey,
-      createInstallationPlan(other).packageKey
-    )
-    assert.equal(createInstallationPlan(original).dataKey, createInstallationPlan(other).dataKey)
-  })
   it('rejects mismatched source provenance and unversioned capability claims', () => {
     const args = input()
     assert.throws(() =>
@@ -442,7 +414,7 @@ const MATRIX: {
     disabled: ['mcp:api'],
   },
   {
-    name: 'the same package is adopted partially when the caller opts in',
+    name: 'a package missing one native transport is adopted partially on opt-in',
     pkg: 'full',
     profile: 'nativeWithoutHttp',
     allowPartial: true,
@@ -483,7 +455,7 @@ const MATRIX: {
     disabled: ['hooks'],
   },
   {
-    name: 'the same package is adopted partially when the caller opts in',
+    name: 'a package with a non-portable extra is adopted partially on opt-in',
     pkg: 'withHooks',
     profile: 'native',
     allowPartial: true,
@@ -560,10 +532,11 @@ describe('upgrade identity isolation', () => {
     )
 
     // An upgraded package (new bytes) is a different PACKAGE, under the same
-    // instance data: the data is preserved across the upgrade.
+    // instance data: the data is preserved across the upgrade and the harness.
     const upgraded = createInstallationPlan({
       ...input(packageFixture({ 'CHANGELOG.md': 'A new release.' })),
       releaseId: `release:${'c'.repeat(64)}`,
+      profile: profile({ harness: 'another-harness' }),
     })
     assert.notEqual(first.packageKey, upgraded.packageKey)
     assert.equal(first.dataKey, upgraded.dataKey)
@@ -575,7 +548,6 @@ describe('upgrade identity isolation', () => {
     const rereleased = createInstallationPlan({ ...base, releaseId: `release:${'d'.repeat(64)}` })
     assert.equal(first.packageKey, rereleased.packageKey)
     assert.equal(first.dataKey, rereleased.dataKey)
-    assert.notEqual(first.releaseId, rereleased.releaseId)
 
     // A different source commit is a different package identity under the same
     // instance data.

package/src/harness.ts

@@ -9,7 +9,8 @@ import {
   type InstallationPlan,
 } from './agent-plugins-schema.js'
 import type { Catalog } from './schema.js'
-import { verifyPortableCatalog, PACKAGE_METADATA_KEY } from './portable-catalog.js'
+import { PACKAGE_METADATA_KEY } from './agent-plugins-schema.js'
+import { verifyPortableCatalog } from './portable-verify.js'
 import { verifyAgentPackage, validateServer } from './agent-plugins-catalog.js'
 
 export interface InstallationInput {

package/src/icon-mirror.ts

@@ -1,9 +1,11 @@
 import { promises as fs } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 import type { Catalog } from './schema.js'
-import { byteDigest, type PublishedAsset } from './index.js'
+import { byteDigest } from './digest.js'
 import { iconAssetName, inspectIconBytes, type IconContentType } from './icons.js'
 import type { ConsumerIndex } from './consumer-index.js'
+import { writeFileAtomically } from './fs-atomic.js'
+import { publishedAssetOf, type PublishedAsset } from './integrity-manifest.js'
 
 /**
  * Where an icon's bytes come from, so a mirror needs no tree walk and no
@@ -35,7 +37,7 @@ export type IconSource =
       readonly homepage: string
     }
 
-export interface IconMirrorResult {
+interface IconMirrorResult {
   /** Icons whose verified bytes are present in the assets directory. */
   readonly staged: readonly PublishedAsset[]
   /** Icons that could not be staged, with the reason, never silently dropped. */
@@ -44,22 +46,27 @@ export interface IconMirrorResult {
 
 /**
  * Maps every mirrored icon back to the exact commit it was resolved from, by
- * matching the digest the product advertises. Canonical variants are inspected
- * first, mirroring the order product records were built in.
+ * matching the digest the product advertises. Retain each distinct pinned
+ * origin so the mirror can try another source if one is unavailable.
  */
 export function resolveIconSources(
   catalog: Pick<Catalog, 'plugins'>,
   index: ConsumerIndex
 ): readonly IconSource[] {
-  const byAsset = new Map<string, IconSource>()
+  const byAsset = new Map<string, IconSource[]>()
+  const add = (source: IconSource) => {
+    const candidates = byAsset.get(source.asset) ?? []
+    if (!candidates.some((candidate) => JSON.stringify(candidate) === JSON.stringify(source)))
+      candidates.push(source)
+    byAsset.set(source.asset, candidates)
+  }
   for (const plugin of catalog.plugins) {
     for (const release of plugin.availableReleases) {
       const icon = release.icon
       if (!icon) continue
       const asset = iconAssetName(icon.digest, icon.contentType)
-      if (byAsset.has(asset)) continue
       if (icon.kind === 'favicon') {
-        byAsset.set(asset, {
+        add({
           kind: 'favicon',
           asset,
           digest: icon.digest,
@@ -74,7 +81,7 @@ export function resolveIconSources(
         release.pluginSubdirectory && release.pluginSubdirectory !== '.'
           ? release.pluginSubdirectory
           : ''
-      byAsset.set(asset, {
+      add({
         kind: 'content',
         asset,
         digest: icon.digest,
@@ -88,14 +95,12 @@ export function resolveIconSources(
       })
     }
   }
-  const sources: IconSource[] = []
+  const selected = new Set<string>()
   for (const product of Object.values(index.products)) {
     const icon = product.icon
-    if (!icon) continue
-    const source = byAsset.get(icon.asset)
-    if (source) sources.push(source)
+    if (icon) selected.add(icon.asset)
   }
-  return sources.toSorted((left, right) => left.asset.localeCompare(right.asset))
+  return [...selected].toSorted().flatMap((asset) => byAsset.get(asset) ?? [])
 }
 
 /**
@@ -112,66 +117,51 @@ export async function stageIconAssets(input: {
   /** Reads the icon bytes for a source; live fetches raw content, offline reads fixtures. */
   readonly readBytes: (source: IconSource) => Promise<Uint8Array>
 }): Promise<IconMirrorResult> {
-  const staged: PublishedAsset[] = []
-  const skipped: { asset: string; reason: string }[] = []
+  const staged = new Map<string, PublishedAsset>()
+  const skipped = new Map<string, string>()
+  const skip = (asset: string, reason: string) => {
+    if (!skipped.has(asset)) skipped.set(asset, reason)
+  }
   await fs.mkdir(input.assetsDirectory, { recursive: true })
   for (const source of input.sources) {
-    const destination = join(input.assetsDirectory, source.asset)
-    const existing = await fs.readFile(destination).catch(() => undefined)
-    if (existing && byteDigest(existing) === source.digest) {
-      staged.push(publishedAssetOf(source))
-      continue
-    }
-    if (existing) {
-      skipped.push({ asset: source.asset, reason: 'ASSET_CONFLICT' })
-      continue
-    }
-    let bytes: Uint8Array
-    try {
-      bytes = await input.readBytes(source)
-    } catch (error) {
-      skipped.push({
-        asset: source.asset,
-        reason: `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`,
-      })
+    if (staged.has(source.asset)) continue
+    const existing = await stagedState(input.assetsDirectory, source.asset, source.digest)
+    if (existing === 'conflict') {
+      skip(source.asset, 'ASSET_CONFLICT')
       continue
     }
-    const inspected = inspectIconBytes(bytes)
-    if (!('contentType' in inspected)) {
-      skipped.push({ asset: source.asset, reason: inspected.rejected })
-      continue
-    }
-    if (inspected.contentType !== source.contentType) {
-      skipped.push({ asset: source.asset, reason: 'CONTENT_TYPE_CHANGED' })
-      continue
-    }
-    if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
-      skipped.push({ asset: source.asset, reason: 'DIGEST_MISMATCH' })
-      continue
+    if (existing === 'absent') {
+      let bytes: Uint8Array
+      try {
+        bytes = await input.readBytes(source)
+      } catch (error) {
+        skip(
+          source.asset,
+          `FETCH_FAILED: ${error instanceof Error ? error.message : String(error)}`
+        )
+        continue
+      }
+      const inspected = inspectIconBytes(bytes)
+      if (!('contentType' in inspected)) {
+        skip(source.asset, inspected.rejected)
+        continue
+      }
+      if (inspected.contentType !== source.contentType) {
+        skip(source.asset, 'CONTENT_TYPE_CHANGED')
+        continue
+      }
+      if (byteDigest(bytes) !== source.digest || bytes.byteLength !== source.bytes) {
+        skip(source.asset, 'DIGEST_MISMATCH')
+        continue
+      }
+      await writeFileAtomically(join(input.assetsDirectory, source.asset), bytes)
     }
-    await fs.mkdir(dirname(destination), { recursive: true })
-    await fs.writeFile(destination, bytes)
-    staged.push(publishedAssetOf(source))
+    staged.set(source.asset, publishedAssetOf(source))
+    skipped.delete(source.asset)
   }
-  // Distinct assets: two products can share one mark, and the catalog declares
-  // each asset once.
-  return { staged: dedupeAssets(staged), skipped }
-}
-
-function dedupeAssets(assets: readonly PublishedAsset[]): readonly PublishedAsset[] {
-  const unique = new Map<string, PublishedAsset>()
-  for (const asset of assets) unique.set(asset.name, asset)
-  return [...unique.values()]
-}
-
-function publishedAssetOf(source: IconSource): PublishedAsset {
   return {
-    name: source.asset,
-    digest: source.digest,
-    bytes: source.bytes,
-    contentType: source.contentType,
-    kind: source.kind,
-    origin: source.kind === 'content' ? source.sourcePath : source.url,
+    staged: [...staged.values()],
+    skipped: [...skipped].map(([asset, reason]) => ({ asset, reason })),
   }
 }
 
@@ -188,9 +178,25 @@ export async function stageIconBytes(
   asset: string,
   bytes: Uint8Array
 ): Promise<void> {
-  const destination = join(assetsDirectory, asset)
-  const existing = await fs.readFile(destination).catch(() => undefined)
-  if (existing && byteDigest(existing) === byteDigest(bytes)) return
-  await fs.mkdir(dirname(destination), { recursive: true })
-  await fs.writeFile(destination, bytes)
+  // These bytes are the ones the digest was computed from, so they replace a
+  // differing file rather than fail the build over it.
+  if ((await stagedState(assetsDirectory, asset, byteDigest(bytes))) === 'present') return
+  await fs.mkdir(assetsDirectory, { recursive: true })
+  await writeFileAtomically(join(assetsDirectory, asset), bytes)
+}
+
+/** Whether a content-addressed asset is already staged with the expected bytes. */
+async function stagedState(
+  directory: string,
+  asset: string,
+  digest: string
+): Promise<'absent' | 'present' | 'conflict'> {
+  let existing: Uint8Array
+  try {
+    existing = await fs.readFile(join(directory, asset))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return 'absent'
+    throw error
+  }
+  return byteDigest(existing) === digest ? 'present' : 'conflict'
 }

package/src/icons.test.ts

@@ -138,10 +138,6 @@ describe('icon asset names', () => {
     expect(iconAssetName(`sha256:${'b'.repeat(64)}`, 'image/svg+xml')).toBe(
       `icon-${'b'.repeat(32)}.svg`
     )
-    // Identical bytes always resolve to the same asset, so caches stay warm.
-    expect(iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')).toBe(
-      iconAssetName(`sha256:${'c'.repeat(64)}`, 'image/webp')
-    )
   })
 
   test('refuses a content type it cannot name', () => {

package/src/icons.ts

@@ -1,3 +1,4 @@
+import { digestHex } from './digest.js'
 /**
  * Compile-time icon resolution.
  *
@@ -209,14 +210,13 @@ const EXTENSION_BY_CONTENT_TYPE: Readonly<Record<IconContentType, string>> = {
 }
 
 /**
- * Content-addressed asset name. Release assets cannot contain `/`, so the
- * digest prefix and extension form one flat name that any release can host.
+ * Content-addressed asset name. Published names are flat (no `/`), so the
+ * digest and extension form one name that is safe as a file and a URL segment.
  */
 export function iconAssetName(digest: string, contentType: IconContentType): string {
   const extension = EXTENSION_BY_CONTENT_TYPE[contentType]
   if (!extension) throw new Error(`ICON_CONTENT_TYPE_UNSUPPORTED: ${contentType}`)
-  const hex = digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest
-  return `icon-${hex.slice(0, 32)}.${extension}`
+  return `icon-${digestHex(digest).slice(0, 32)}.${extension}`
 }
 
 /**

package/src/index.test.ts

@@ -1,4 +1,5 @@
 import { chmod, mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { execFileSync } from 'node:child_process'
 import { readdirSync, readFileSync } from 'node:fs'
 import { gzipSync } from 'node:zlib'
 import { pack } from 'tar-stream'
@@ -21,6 +22,7 @@ import {
   type CategoryMap,
   type ProductAliases,
   type ResolvedSource,
+  type GeneratedArtifacts,
 } from './index.js'
 import {
   parseJsonDocument,
@@ -106,6 +108,9 @@ const policy: CatalogPolicy = {
   ],
 }
 
+/** Upstream failures retry immediately, so retry tests do not wait out real backoff. */
+const RETRY_NOW = { 'retry-after': '0' }
+
 function stubFetch(handler: (url: string) => Response | Promise<Response>) {
   const original = globalThis.fetch
   const calls: string[] = []
@@ -231,6 +236,23 @@ describe('source adapters', () => {
     expect(gitSource.kind === 'git' ? gitSource.subdirectory : undefined).toBe('plugins/demo')
   })
 
+  test('leaves out entries with an unsupported source kind and keeps the rest', () => {
+    const parsed = parseMarketplaceManifest(
+      {
+        plugins: [
+          { name: 'xcode', source: { source: 'command', command: 'install-xcode-plugin' } },
+          { name: 'demo', source: './plugins/demo' },
+        ],
+      },
+      sources[0]!
+    )
+    expect(parsed.entries.map((entry) => entry.name)).toEqual(['demo'])
+    expect(parsed.unsupportedEntries).toEqual(['xcode: command'])
+    expect(() => parseSourceSpec({ source: 'command' }, sources[0]!, 'xcode')).toThrow(
+      'PLUGIN_SOURCE_KIND_UNSUPPORTED'
+    )
+  })
+
   test('rejects duplicate keys, traversal, and unsupported URL schemes', () => {
     expect(() => parseJsonDocument('{"plugins":[],"plugins":[]}')).toThrow('JSON_DUPLICATE_KEY')
     expect(() => parseSourceSpec({ source: 'local', path: '../outside' }, sources[0]!)).toThrow(
@@ -466,6 +488,106 @@ describe('deterministic catalog synchronization', () => {
     }
   })
 
+  test.skipIf(process.platform === 'win32')(
+    'pins annotated and lightweight tags to the target commit',
+    async () => {
+      const root = await mkdtemp(join(tmpdir(), 'plugin-tag-pin-'))
+      const repo = join(root, 'repository')
+      const bin = join(root, 'bin')
+      const originalPath = process.env.PATH
+      const originalGit = process.env.ADEA_TEST_REAL_GIT
+      const originalRepo = process.env.ADEA_TEST_TAG_REPO
+      const originalFetch = globalThis.fetch
+      const realGit = execFileSync('which', ['git'], { encoding: 'utf8' }).trim()
+      const git = (...args: string[]) =>
+        execFileSync(realGit, ['-C', repo, ...args], { encoding: 'utf8' }).trim()
+      try {
+        await mkdir(repo)
+        await mkdir(bin)
+        git('init', '-q', '-b', 'main')
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'commit',
+          '--allow-empty',
+          '-qm',
+          'fixture'
+        )
+        git(
+          '-c',
+          'user.name=Fixture',
+          '-c',
+          'user.email=fixture@example.invalid',
+          'tag',
+          '-a',
+          'annotated',
+          '-m',
+          'fixture'
+        )
+        git('tag', 'lightweight')
+        const commit = git('rev-parse', 'HEAD')
+        expect(git('rev-parse', 'refs/tags/annotated')).not.toBe(commit)
+        const sourceSha = '5'.repeat(40)
+        const source: SourceConfig = {
+          ...sources[0]!,
+          sourceId: 'tag-fixture',
+          repositoryUrl: 'https://github.com/acme/marketplace',
+          manifestPath: 'marketplace.json',
+        }
+        const script = join(bin, 'git')
+        await writeFile(
+          script,
+          `#!/bin/sh\nif [ "$2" = "${source.repositoryUrl}" ]; then\n  printf '%s\\t%s\\n' '${sourceSha}' "$3"\nelse\n  shift 2\n  exec "$ADEA_TEST_REAL_GIT" ls-remote "$ADEA_TEST_TAG_REPO" "$@"\nfi\n`
+        )
+        await chmod(script, 0o700)
+        process.env.ADEA_TEST_REAL_GIT = realGit
+        process.env.ADEA_TEST_TAG_REPO = repo
+        process.env.PATH = `${bin}:${originalPath ?? ''}`
+        for (const ref of ['refs/tags/annotated', 'refs/tags/lightweight', 'refs/heads/main']) {
+          const manifest = JSON.stringify({
+            plugins: [
+              {
+                name: 'remote',
+                source: { source: 'git', url: 'https://github.com/acme/remote-plugin', ref },
+              },
+            ],
+          })
+          globalThis.fetch = (async (_url: unknown) => new Response(manifest)) as typeof fetch
+          const loaded: string[] = []
+          const result = await synchronize({
+            sources: [source],
+            categoryMap,
+            productAliases,
+            policy,
+            mode: 'live',
+            snapshotLoader: {
+              load: async (_url, sha) => {
+                loaded.push(sha)
+                return {
+                  files: new Map([['plugin.json', new TextEncoder().encode('{"name":"Remote"}')]]),
+                  symlinks: [],
+                }
+              },
+            },
+          })
+          expect(result.lock?.sources[0]?.pluginPins[0]?.resolvedCommitSha).toBe(commit)
+          expect(loaded).toEqual([commit])
+        }
+      } finally {
+        globalThis.fetch = originalFetch
+        if (originalPath === undefined) delete process.env.PATH
+        else process.env.PATH = originalPath
+        if (originalGit === undefined) delete process.env.ADEA_TEST_REAL_GIT
+        else process.env.ADEA_TEST_REAL_GIT = originalGit
+        if (originalRepo === undefined) delete process.env.ADEA_TEST_TAG_REPO
+        else process.env.ADEA_TEST_TAG_REPO = originalRepo
+        await rm(root, { recursive: true, force: true })
+      }
+    }
+  )
+
   test.skipIf(process.platform === 'win32')(
     'refreshes floating external refs even when the marketplace head is unchanged',
     async () => {
@@ -602,35 +724,24 @@ describe('deterministic catalog synchronization', () => {
     verifyArtifacts(result.artifacts!)
   })
 
-  test('keeps a failed build from producing a new artifact set', async () => {
-    const first = await synchronize({
-      sources,
-      categoryMap,
-      productAliases,
-      policy,
-      mode: 'offline',
-      fixtureRoot: join(process.cwd(), 'fixtures'),
-    })
-    const outputDirectory = join(await mkdtemp(join(tmpdir(), 'plugin-lkg-')), 'generated')
-    await writeArtifacts(outputDirectory, first.artifacts!)
-    const previousCatalog = await readFile(join(outputDirectory, 'catalog.v1.json'), 'utf8')
-    await expect(
-      synchronize({
-        sources,
-        categoryMap,
-        productAliases,
-        policy,
-        mode: 'offline',
-        fixtureRoot: join(process.cwd(), 'fixtures'),
-        snapshotLoader: {
-          load: async () => {
-            throw new Error('UPSTREAM_FETCH_FAILED')
-          },
-        },
-      })
-    ).rejects.toThrow('UPSTREAM_FETCH_FAILED')
-    expect(first.artifacts?.['catalog.v1.json']).toContain(first.catalog?.catalogId)
-    expect(await readFile(join(outputDirectory, 'catalog.v1.json'), 'utf8')).toBe(previousCatalog)
+  test('preserves an existing recovery directory when writing artifacts', async () => {
+    const parent = await mkdtemp(join(tmpdir(), 'plugin-recovery-'))
+    const output = join(parent, 'generated')
+    const backup = `${output}.previous`
+    try {
+      await mkdir(backup)
+      await writeFile(join(backup, 'keep.txt'), 'recover me')
+      const artifacts = { 'catalog.v1.json': '{}' } as unknown as GeneratedArtifacts
+      await expect(writeArtifacts(output, artifacts)).rejects.toThrow('CATALOG_RECOVERY_REQUIRED')
+      expect(await readFile(join(backup, 'keep.txt'), 'utf8')).toBe('recover me')
+      await mkdir(output)
+      await writeFile(join(output, 'current.txt'), 'current')
+      await expect(writeArtifacts(output, artifacts)).rejects.toThrow('CATALOG_RECOVERY_REQUIRED')
+      expect(await readFile(join(backup, 'keep.txt'), 'utf8')).toBe('recover me')
+      expect(await readFile(join(output, 'current.txt'), 'utf8')).toBe('current')
+    } finally {
+      await rm(parent, { recursive: true, force: true })
+    }
   })
 })
 
@@ -640,11 +751,16 @@ describe('identity, classification, and harness contracts', () => {
       stablePluginId('cursor-official', 'gmail')
     )
     expect(stablePluginId('--OpenAI--', '---Gmail---')).toBe('plugin:openai:gmail')
-    expect(
-      stableReleaseId('https://github.com/acme/a', 'plugins/x', 'a'.repeat(40), digest('same'))
-    ).toBe(
-      stableReleaseId('https://github.com/acme/a', 'plugins/x', 'a'.repeat(40), digest('same'))
+    const releaseId = stableReleaseId(
+      'https://github.com/acme/a',
+      'plugins/x',
+      'a'.repeat(40),
+      digest('same')
     )
+    expect(releaseId).toMatch(/^release:[a-f0-9]{64}$/)
+    expect(
+      stableReleaseId('https://github.com/acme/a', 'plugins/x', 'a'.repeat(40), digest('other'))
+    ).not.toBe(releaseId)
     expect(
       bytesDigest(
         new Map([
@@ -674,15 +790,25 @@ describe('filesystem safety', () => {
     expect(snapshot.symlinks).toEqual(['plugin'])
   })
 
-  test('enforces file and archive-like size limits', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'plugins-size-'))
-    await mkdir(join(root, 'plugin'), { recursive: true })
-    await writeFile(join(root, 'plugin', 'large.txt'), '1234567890')
-    const snapshot = await snapshotFromDirectory(root, 'plugin')
-    expect(snapshot.files.size).toBe(1)
-    expect(() => {
-      if ([...snapshot.files.values()][0]!.byteLength > 5) throw new Error('PLUGIN_FILE_TOO_LARGE')
-    }).toThrow('PLUGIN_FILE_TOO_LARGE')
+  test('skips a plugin with a file over the size limit', async () => {
+    const result = await synchronize({
+      sources,
+      categoryMap,
+      productAliases,
+      policy: { ...policy, maxFileBytes: 5 },
+      mode: 'offline',
+      fixtureRoot: join(process.cwd(), 'fixtures'),
+      snapshotLoader: {
+        load: async () => ({
+          files: new Map([['large.txt', new TextEncoder().encode('1234567890')]]),
+          symlinks: [],
+        }),
+      },
+    })
+    const reasons = result.changeReport.skippedPlugins.map((skipped) => skipped.reasonCode)
+    expect(reasons.length).toBeGreaterThan(0)
+    expect(new Set(reasons)).toEqual(new Set(['PLUGIN_FILE_TOO_LARGE']))
+    expect(result.catalog?.plugins).toEqual([])
   })
 })
 
@@ -736,7 +862,7 @@ describe('upstream fetch quarantine', () => {
     const stub = stubFetch(async (url) => {
       if (url === treeUrl) {
         treeCalls += 1
-        if (treeCalls < 3) return new Response('busy', { status: 500 })
+        if (treeCalls < 3) return new Response('busy', { status: 500, headers: RETRY_NOW })
         return jsonResponse(treePayload(['plugins/demo/plugin.json']))
       }
       if (isArchive(url))
@@ -755,7 +881,7 @@ describe('upstream fetch quarantine', () => {
 
   test('quarantines a plugin when the repository tree stays unavailable', async () => {
     const stub = stubFetch((url) => {
-      if (url === treeUrl) return new Response('down', { status: 500 })
+      if (url === treeUrl) return new Response('down', { status: 500, headers: RETRY_NOW })
       return new Response('unexpected', { status: 500 })
     })
     try {
@@ -799,7 +925,7 @@ describe('upstream fetch quarantine', () => {
       if (isArchive(url))
         return recovered
           ? tarballResponse([{ path: 'plugins/demo/plugin.json', body: manifestBytes }])
-          : new Response('broken', { status: 500 })
+          : new Response('broken', { status: 500, headers: RETRY_NOW })
       return new Response('unexpected', { status: 200 })
     })
     try {
@@ -1031,7 +1157,7 @@ describe('upstream fetch quarantine', () => {
   })
 
   test('fails closed when every plugin in a source is unreachable', async () => {
-    const stub = stubFetch(() => new Response('down', { status: 500 }))
+    const stub = stubFetch(() => new Response('down', { status: 500, headers: RETRY_NOW }))
     try {
       await expect(
         buildCatalog({