docs(plugins): classify aggregate failures against the frozen baseline

# Conflicts:
#	application/i18n/locales/en/core.ts
#	application/i18n/locales/es/core.ts
#	application/i18n/locales/ru/core.ts
#	application/i18n/locales/zh-CN/core.ts
#	application/i18n/locales/zh-TW/core.ts

.github/workflows/test.yml

@@ -49,6 +49,12 @@ jobs:
       - name: Verify Codex App Server schema
         run: npm run check:codex-app-server-schema
 
+      - name: Verify plugin contract and runtime boundaries
+        run: |
+          npm run check:plugin-contract
+          npm run test:plugin-runtime
+          node --test --import tsx components/settings/tabs/Plugin*.test.tsx
+
       - name: Test
         run: npm test
 

AGENTS.md

@@ -106,10 +106,13 @@ Placement rules (`resolveAgentKinds` in `toolSurfaces.cjs`):
 
 **Harness domain (`catalog/harness.cjs`):** Catty executes these locally in `capabilityTools.executeLocalCattyCapability`. The read-only `harness.terminal.read_context` also exposes `netcatty/readContext` to MCP, with scope validation before and after the existing renderer bridge call. It reuses the sidebar reader through the screen snapshot registry (80 rows by default, maximum 300); no script or command runs. Other harness tools remain Catty-only. `harness.web.search` is omitted when web search is not configured.
 
-## Plugin host runtime (internal preview)
+## Plugin host runtime
 
-The phase-2 plugin host lives under `electron/plugins/` and is disabled unless
-`NETCATTY_PLUGIN_DEV=1` is present at application launch. Public wire and package
+The plugin host under `electron/plugins/` exposes browser-only packages in normal
+Settings. `NETCATTY_PLUGIN_DEV=1` admits advanced development packages, without
+granting their permissions. Admission and default placement share
+`domain/pluginRuntimePolicy.cjs`; permission explanations shared with native
+prompts live in `domain/pluginPermissionDescriptions.cjs`. Public wire and package
 types still come only from `packages/plugin-contract/schema/`; do not add a
 second private RPC shape when extending the host.
 

application/AppHandlers.connect.test.ts

@@ -7,9 +7,8 @@ import {
   handleKeyboardInteractiveSubmitImpl,
   handleTrayPanelConnectRequestImpl,
 } from './app/AppHandlers.ts';
-import { resolveHostAuth } from '../domain/sshAuth.ts';
 import { resolveShellSetting } from '../lib/useDiscoveredShells.ts';
-import type { Host, Identity } from '../types';
+import type { Host } from '../types';
 
 const baseHost: Host = {
   id: 'host-1',
@@ -195,219 +194,6 @@ test('keyboard-interactive submit can save login password for the session host',
   assert.equal(bridgeResponses.length, 1);
 });
 
-test('keyboard-interactive submit detaches keychain identity when remembering a password change', async () => {
-  const sharedIdentity: Identity = {
-    id: 'id-1',
-    label: 'shared',
-    username: 'root',
-    authMethod: 'password',
-    password: 'stale-keychain-password',
-    created: 0,
-  };
-  let hosts: Host[] = [{
-    ...baseHost,
-    identityId: 'id-1',
-    password: 'old-host-password',
-    savePassword: false,
-  }];
-  let queue = [{
-    requestId: 'ki-rotate',
-    sessionId: 'session-1',
-    hostname: baseHost.hostname,
-    allowSavePassword: true,
-  }];
-  let identityUpdates = 0;
-
-  // resolveHostAuth prefers identity.password, so the stale keychain secret
-  // shadows whatever is already stored on the host.
-  assert.equal(
-    resolveHostAuth({ host: hosts[0], keys: [], identities: [sharedIdentity] }).password,
-    'stale-keychain-password',
-  );
-
-  await handleKeyboardInteractiveSubmitImpl(
-    () => ({
-      hosts,
-      identities: [sharedIdentity],
-      keyboardInteractiveQueue: queue,
-      netcattyBridge: {
-        get: () => ({
-          respondKeyboardInteractive: () => ({ success: true }),
-        }),
-      },
-      sessions: [{
-        id: 'session-1',
-        hostId: baseHost.id,
-        hostname: baseHost.hostname,
-      }],
-      setKeyboardInteractiveQueue: (updater: (items: typeof queue) => typeof queue) => {
-        queue = updater(queue);
-      },
-      t: (key: string) => key,
-      toast: { error: () => {} },
-      updateHosts: (nextHosts: Host[]) => {
-        hosts = nextHosts;
-      },
-      updateIdentities: () => {
-        identityUpdates += 1;
-      },
-    }),
-    'ki-rotate',
-    ['rotated-password'],
-    'rotated-password',
-  );
-
-  assert.equal(hosts[0].identityId, '');
-  assert.equal(hosts[0].password, 'rotated-password');
-  assert.equal(hosts[0].savePassword, true);
-  assert.equal(hosts[0].username, baseHost.username);
-  assert.equal(identityUpdates, 0);
-  assert.equal(sharedIdentity.password, 'stale-keychain-password');
-  assert.equal(
-    resolveHostAuth({ host: hosts[0], keys: [], identities: [sharedIdentity] }).password,
-    'rotated-password',
-  );
-  assert.deepEqual(queue, []);
-});
-
-test('keyboard-interactive submit snapshots a different keychain username when remembering a password', async () => {
-  const sharedIdentity: Identity = {
-    id: 'id-1',
-    label: 'shared',
-    username: 'deploy',
-    authMethod: 'password',
-    password: 'stale-keychain-password',
-    created: 0,
-  };
-  let hosts: Host[] = [{
-    ...baseHost,
-    username: 'root',
-    identityId: 'id-1',
-    password: 'old-host-password',
-    savePassword: false,
-  }];
-  let queue = [{
-    requestId: 'ki-rotate-user',
-    sessionId: 'session-1',
-    hostname: baseHost.hostname,
-    allowSavePassword: true,
-  }];
-  let identityUpdates = 0;
-
-  await handleKeyboardInteractiveSubmitImpl(
-    () => ({
-      hosts,
-      identities: [sharedIdentity],
-      keyboardInteractiveQueue: queue,
-      netcattyBridge: {
-        get: () => ({
-          respondKeyboardInteractive: () => ({ success: true }),
-        }),
-      },
-      sessions: [{
-        id: 'session-1',
-        hostId: baseHost.id,
-        hostname: baseHost.hostname,
-      }],
-      setKeyboardInteractiveQueue: (updater: (items: typeof queue) => typeof queue) => {
-        queue = updater(queue);
-      },
-      t: (key: string) => key,
-      toast: { error: () => {} },
-      updateHosts: (nextHosts: Host[]) => {
-        hosts = nextHosts;
-      },
-      updateIdentities: () => {
-        identityUpdates += 1;
-      },
-    }),
-    'ki-rotate-user',
-    ['new-password'],
-    'new-password',
-  );
-
-  assert.equal(hosts[0].identityId, '');
-  assert.equal(hosts[0].password, 'new-password');
-  assert.equal(hosts[0].savePassword, true);
-  assert.equal(hosts[0].username, 'deploy');
-  assert.equal(identityUpdates, 0);
-  assert.equal(sharedIdentity.username, 'deploy');
-  assert.equal(sharedIdentity.password, 'stale-keychain-password');
-  const resolved = resolveHostAuth({ host: hosts[0], keys: [], identities: [sharedIdentity] });
-  assert.equal(resolved.password, 'new-password');
-  assert.equal(resolved.username, 'deploy');
-  assert.deepEqual(queue, []);
-});
-
-test('keyboard-interactive submit fills a blank host username from the keychain identity', async () => {
-  const sharedIdentity: Identity = {
-    id: 'id-1',
-    label: 'shared',
-    username: 'alice',
-    authMethod: 'password',
-    password: 'stale-keychain-password',
-    created: 0,
-  };
-  let hosts: Host[] = [{
-    ...baseHost,
-    username: '',
-    identityId: 'id-1',
-    password: 'old-host-password',
-    savePassword: false,
-  }];
-  let queue = [{
-    requestId: 'ki-blank-user',
-    sessionId: 'session-1',
-    hostname: baseHost.hostname,
-    allowSavePassword: true,
-  }];
-  let identityUpdates = 0;
-
-  await handleKeyboardInteractiveSubmitImpl(
-    () => ({
-      hosts,
-      identities: [sharedIdentity],
-      keyboardInteractiveQueue: queue,
-      netcattyBridge: {
-        get: () => ({
-          respondKeyboardInteractive: () => ({ success: true }),
-        }),
-      },
-      sessions: [{
-        id: 'session-1',
-        hostId: baseHost.id,
-        hostname: baseHost.hostname,
-      }],
-      setKeyboardInteractiveQueue: (updater: (items: typeof queue) => typeof queue) => {
-        queue = updater(queue);
-      },
-      t: (key: string) => key,
-      toast: { error: () => {} },
-      updateHosts: (nextHosts: Host[]) => {
-        hosts = nextHosts;
-      },
-      updateIdentities: () => {
-        identityUpdates += 1;
-      },
-    }),
-    'ki-blank-user',
-    ['new-password'],
-    'new-password',
-  );
-
-  assert.equal(hosts[0].identityId, '');
-  assert.equal(hosts[0].username, 'alice');
-  assert.equal(hosts[0].password, 'new-password');
-  assert.equal(hosts[0].savePassword, true);
-  assert.equal(identityUpdates, 0);
-  assert.equal(sharedIdentity.username, 'alice');
-  assert.equal(sharedIdentity.password, 'stale-keychain-password');
-  const resolved = resolveHostAuth({ host: hosts[0], keys: [], identities: [sharedIdentity] });
-  assert.equal(resolved.password, 'new-password');
-  assert.equal(resolved.username, 'alice');
-  assert.deepEqual(queue, []);
-});
-
 test('keyboard-interactive submit does not save secondary password when allowSavePassword is false', async () => {
   let hosts: Host[] = [{
     ...baseHost,

application/app/AppHandlers.ts

@@ -393,7 +393,6 @@ export async function handleKeyboardInteractiveSubmitImpl(
   const {
     hosts,
     hostsRef,
-    identities,
     keyboardInteractiveQueue,
     sessions,
     setKeyboardInteractiveQueue,
@@ -425,27 +424,12 @@ export async function handleKeyboardInteractiveSubmitImpl(
     // Save password to host if requested - never for second-factor / EDR prompts
     // (allowSavePassword === false) so a secondary secret cannot overwrite the
     // host login password (#2150 / Codex review on #2151).
-    // Detach a Keychain identity when one is attached. resolveHostAuth prefers
-    // identity.password and identity.username, so snapshot the identity username
-    // onto the host before clearing identityId (#3982). Same as
-    // applyVaultHostUpdate's password detach. Do not mutate the identity.
     if (savePassword && host && request?.allowSavePassword !== false) {
-      updateHosts(latestHosts.map((h: Host) => {
-        if (h.id !== host.id) return h;
-        const identity = h.identityId
-          ? identities?.find((item: { id?: string; username?: string }) => item.id === h.identityId)
-          : undefined;
-        const detachedUsername = identity?.username?.trim();
-        return {
-          ...h,
-          password: savePassword,
-          savePassword: true,
-          ...(h.identityId ? {
-            identityId: '',
-            ...(detachedUsername ? { username: detachedUsername } : {}),
-          } : {}),
-        };
-      }));
+      updateHosts(latestHosts.map((h: Host) => h.id === host.id ? {
+        ...h,
+        password: savePassword,
+        savePassword: true,
+      } : h));
     }
     // Remove from queue by requestId
     setKeyboardInteractiveQueue(prev => prev.filter(r => r.requestId !== requestId));

application/app/AppSideEffects.tsx

@@ -716,7 +716,7 @@ export function AppSideEffects() {
   }, [isVaultInitialized, pendingTrayPanelConnectHostIds]);
 
   // Handle keyboard-interactive submit
-  const handleKeyboardInteractiveSubmit = useCallback((requestId: string, responses: string[], savePassword?: string) => { return handleKeyboardInteractiveSubmitImpl(() => ({ hosts, hostsRef, identities, keyboardInteractiveQueue, netcattyBridge, requestId, responses, savePassword, sessions, setKeyboardInteractiveQueue, t, toast, updateHosts }), requestId, responses, savePassword); }, [identities, keyboardInteractiveQueue, sessions, hosts, t, updateHosts]);
+  const handleKeyboardInteractiveSubmit = useCallback((requestId: string, responses: string[], savePassword?: string) => { return handleKeyboardInteractiveSubmitImpl(() => ({ hosts, hostsRef, keyboardInteractiveQueue, netcattyBridge, requestId, responses, savePassword, sessions, setKeyboardInteractiveQueue, t, toast, updateHosts }), requestId, responses, savePassword); }, [keyboardInteractiveQueue, sessions, hosts, t, updateHosts]);
 
   // Handle keyboard-interactive cancel
   const handleKeyboardInteractiveCancel = useCallback((requestId: string) => { return handleKeyboardInteractiveCancelImpl(() => ({ netcattyBridge, requestId, setKeyboardInteractiveQueue, t, toast }), requestId); }, [t]);

application/i18n/locales/en/core.ts

@@ -1235,8 +1235,64 @@ Highlight the focused split pane:
   'deepLink.jms.invalid': 'Invalid JumpServer link',
   'deepLink.jms.unsupported': 'Unsupported JumpServer protocol: {{protocol}}',
   'settings.tab.plugins': 'Plugins',
-  'settings.plugins.title': 'Plugin settings',
-  'settings.plugins.description': 'Native, validated settings contributed by development plugins.',
+  "settings.plugins.manager.installed": "Installed plugins",
+  "settings.plugins.manager.import": "Import .ncpkg",
+  "settings.plugins.manager.preview": "Imported packages stay disabled until you review and enable them.",
+  "settings.plugins.manager.empty": "Import a local plugin package to get started.",
+  "settings.plugins.manager.enabled": "Enabled",
+  "settings.plugins.manager.disabled": "Disabled",
+  "settings.plugins.manager.enable": "Enable",
+  "settings.plugins.manager.disable": "Disable",
+  "settings.plugins.manager.remove": "Uninstall",
+  "settings.plugins.manager.removeNote": "Uninstall removes package code and local KV data. User-owned settings, secrets and sync sidecars are retained.",
+  "settings.plugins.permissions.title": "Active grants",
+  "settings.plugins.permissions.refresh": "Refresh",
+  "settings.plugins.permissions.loading": "Loading grants...",
+  "settings.plugins.permissions.empty": "No active grants. One-use decisions are not retained.",
+  "settings.plugins.permissions.always": "Until revoked",
+  "settings.plugins.permissions.application": "Until Netcatty exits",
+  "settings.plugins.permissions.session": "Until the session closes",
+  "settings.plugins.permissions.audit": "Recent security events (up to 100)",
+  "settings.plugins.permissions.revoke": "Disable and revoke all grants",
+  "settings.plugins.permissions.revokeNote": "This disables the plugin, cancels its work, and removes saved grants. Enable it again to request new access.",
+  "settings.plugins.permissions.unavailable": "Plugin permission management is unavailable",
+  "settings.plugins.manager.permissions": "Declared permissions",
+  "settings.plugins.manager.permissionNote": "From the manifest, not a grant. Enabled allows lazy activation; required permissions are requested before first activation and optional permissions when used. Sensitive operations still pass host checks.",
+  "settings.plugins.manager.noPermissions": "No privileged permissions declared.",
+  "settings.plugins.manager.required": "Required",
+  "settings.plugins.manager.optional": "Optional",
+  "settings.plugins.manager.browser": "Browser runtime: privileged access goes through host permission brokers.",
+  "settings.plugins.manager.advanced": "Advanced runtime: full Node filesystem and network authority. Broker permissions cannot restrict this access. Development preview only.",
+  "settings.plugins.manager.data": "Local KV stays on this device. Only non-secret settings explicitly marked for sync participate in encrypted cloud sidecars. Packages and permission grants do not sync.",
+  "settings.plugins.market.results": "{count} plugins",
+  "settings.plugins.manager.lastError": "Last recorded error",
+  "settings.plugins.market.offline": "Registry unavailable. Showing the last valid catalog or bundled examples. Installation is unavailable until refresh succeeds.",
+  "settings.plugins.manager.details": "View details",
+  "settings.plugins.manager.noDescription": "No description provided.",
+  "settings.plugins.market.installed": "Installed",
+  "settings.plugins.market.sourceBadge": "Source example",
+  "settings.plugins.market.title": "Marketplace",
+  "settings.plugins.market.note": "Curated open-source plugins. Review is not a security certification. Updates are manual.",
+  "settings.plugins.market.back": "All plugins",
+  "settings.plugins.market.install": "Install this version (disabled)",
+  "settings.plugins.market.installNote": "This replaces and stops the installed version. Review its permissions in Installed plugins before enabling.",
+  "settings.plugins.market.sourceOnly": "First-party source example. Build with the local CLI and import the .ncpkg; no downloadable release has been published.",
+  "settings.plugins.market.readmeNote": "Pinned to the commit above. HTML is inert and remote images are not loaded. Written by the plugin author.",
+  "settings.plugins.manager.noVault": "System key storage is unavailable. Secret and credential operations are blocked; browsing and non-secret plugins still work.",
+  "settings.plugins.manager.sensitive": "Sensitive access: review the data and resource scope before granting.",
+  "settings.plugins.manager.dual": "Browser is the default runtime. This package also includes a Node entrypoint with full device authority; developer mode only.",
+  "settings.plugins.manager.advancedDeclaration": "Browser entrypoint with advanced permission declarations. Not eligible for normal browser-only mode; review every declared permission.",
+  "settings.plugins.market.retry": "Retry",
+  "settings.plugins.market.empty": "No catalog entries are available. You can still import a local browser plugin.",
+  "settings.plugins.market.emptyReadme": "This README is empty.",
+  "settings.plugins.market.search": "Search name, author or description",
+  "settings.plugins.market.noResults": "No matching plugins. Try another search.",
+  "settings.plugins.market.manifest": "Compatibility and permissions",
+  "settings.plugins.manager.unbounded": "No narrower resource scope is declared. Check the actual scope in the permission prompt.",
+  "settings.plugins.openView": "Open",
+  "settings.plugins.openManager": "Open plugin manager",
+  "settings.plugins.title": "Plugins",
+  "settings.plugins.description": "Manage your plugins and explore the catalog.",
   'settings.plugins.loading': 'Loading plugin settings…',
   'settings.plugins.empty': 'No enabled plugin contributes settings.',
   'settings.plugins.scopeContext': 'Open this setting in its {scope} context.',

application/i18n/locales/es/core.ts

@@ -1235,8 +1235,64 @@ Resalta el panel dividido enfocado:
   'deepLink.jms.invalid': 'Enlace JumpServer inválido',
   'deepLink.jms.unsupported': 'Protocolo JumpServer no compatible: {{protocol}}',
   'settings.tab.plugins': 'Plugins',
-  'settings.plugins.title': 'Configuración de plugins',
-  'settings.plugins.description': 'Ajustes nativos y validados que aportan los plugins de desarrollo.',
+  "settings.plugins.manager.installed": "Plugins instalados",
+  "settings.plugins.manager.import": "Importar .ncpkg",
+  "settings.plugins.manager.preview": "Los paquetes importados permanecen desactivados hasta que los revises y actives.",
+  "settings.plugins.manager.empty": "Importa un paquete local para empezar.",
+  "settings.plugins.manager.enabled": "Activado",
+  "settings.plugins.manager.disabled": "Desactivado",
+  "settings.plugins.manager.enable": "Activar",
+  "settings.plugins.manager.disable": "Desactivar",
+  "settings.plugins.manager.remove": "Desinstalar",
+  "settings.plugins.manager.removeNote": "La desinstalación elimina el código y los datos KV locales. Se conservan los ajustes del usuario, los secretos y los datos auxiliares de sincronización.",
+  "settings.plugins.permissions.title": "Autorizaciones activas",
+  "settings.plugins.permissions.refresh": "Actualizar",
+  "settings.plugins.permissions.loading": "Cargando autorizaciones...",
+  "settings.plugins.permissions.empty": "No hay autorizaciones activas. Las decisiones de un solo uso no se conservan.",
+  "settings.plugins.permissions.always": "Hasta su revocación",
+  "settings.plugins.permissions.application": "Hasta cerrar Netcatty",
+  "settings.plugins.permissions.session": "Hasta cerrar la sesión",
+  "settings.plugins.permissions.audit": "Eventos de seguridad recientes (hasta 100)",
+  "settings.plugins.permissions.revoke": "Desactivar y revocar todas las autorizaciones",
+  "settings.plugins.permissions.revokeNote": "Desactiva el complemento, cancela su trabajo y elimina las autorizaciones guardadas. Actívelo para solicitar acceso de nuevo.",
+  "settings.plugins.permissions.unavailable": "La gestión de permisos no está disponible",
+  "settings.plugins.manager.permissions": "Permisos declarados",
+  "settings.plugins.manager.permissionNote": "Del manifiesto, no es una autorización. Activado permite la activación diferida; los permisos obligatorios se solicitan antes del primer uso y los opcionales cuando se necesitan. Las operaciones sensibles siguen verificándose.",
+  "settings.plugins.manager.noPermissions": "No se han declarado permisos privilegiados.",
+  "settings.plugins.manager.required": "Obligatorio",
+  "settings.plugins.manager.optional": "Opcional",
+  "settings.plugins.manager.browser": "Entorno de navegador: el acceso privilegiado pasa por los controles de permisos del anfitrión.",
+  "settings.plugins.manager.advanced": "Entorno avanzado: acceso completo de Node al sistema de archivos y a la red. Los permisos del intermediario no restringen este acceso. Solo para desarrollo.",
+  "settings.plugins.manager.data": "Los datos KV permanecen en este dispositivo. Solo los ajustes no secretos marcados para sincronización participan en los datos auxiliares cifrados. Los paquetes y las autorizaciones no se sincronizan.",
+  "settings.plugins.market.results": "{count} plugins",
+  "settings.plugins.manager.lastError": "Último error registrado",
+  "settings.plugins.market.offline": "El registro no está disponible. Se muestra el último catálogo válido o los ejemplos incluidos. La instalación requiere una actualización correcta.",
+  "settings.plugins.manager.details": "Ver detalles",
+  "settings.plugins.manager.noDescription": "No se proporcionó una descripción.",
+  "settings.plugins.market.installed": "Instalado",
+  "settings.plugins.market.sourceBadge": "Ejemplo de código",
+  "settings.plugins.market.title": "Catálogo",
+  "settings.plugins.market.note": "Plugins de código abierto seleccionados. La revisión no certifica su seguridad. Las actualizaciones son manuales.",
+  "settings.plugins.market.back": "Todos los plugins",
+  "settings.plugins.market.install": "Instalar esta versión (desactivada)",
+  "settings.plugins.market.installNote": "Esto reemplaza y detiene la versión instalada. Revisa sus permisos antes de activarla.",
+  "settings.plugins.market.sourceOnly": "Ejemplo propio con código fuente. Compílalo con la CLI local e importa el .ncpkg; no hay versión publicada para descargar.",
+  "settings.plugins.market.readmeNote": "Fijado al commit indicado. El HTML no se ejecuta y las imágenes remotas no se cargan. Contenido del autor.",
+  "settings.plugins.manager.noVault": "El almacén de claves del sistema no está disponible. Se bloquean secretos y credenciales; el catálogo y los plugins que no los usan siguen disponibles.",
+  "settings.plugins.manager.sensitive": "Acceso sensible: revisa los datos y el alcance antes de autorizar.",
+  "settings.plugins.manager.dual": "El navegador es la opción predeterminada. El paquete también incluye una entrada Node con acceso completo al dispositivo; solo para desarrollo.",
+  "settings.plugins.manager.advancedDeclaration": "Entrada de navegador con permisos avanzados declarados. No se admite en el modo normal; revisa cada permiso.",
+  "settings.plugins.market.retry": "Reintentar",
+  "settings.plugins.market.empty": "No hay entradas en el catálogo. Puedes importar un plugin local de navegador.",
+  "settings.plugins.market.emptyReadme": "Este README está vacío.",
+  "settings.plugins.market.search": "Buscar nombre, autor o descripción",
+  "settings.plugins.market.noResults": "No hay plugins coincidentes. Prueba otra búsqueda.",
+  "settings.plugins.market.manifest": "Compatibilidad y permisos",
+  "settings.plugins.manager.unbounded": "No se declara un alcance de recursos más limitado. Revisa el alcance real en la solicitud de permiso.",
+  "settings.plugins.openView": "Abrir",
+  "settings.plugins.openManager": "Abrir gestor de plugins",
+  "settings.plugins.title": "Plugins",
+  "settings.plugins.description": "Gestiona tus plugins y explora el catálogo.",
   'settings.plugins.loading': 'Cargando ajustes del plugin…',
   'settings.plugins.empty': 'Ningún plugin activado aporta ajustes.',
   'settings.plugins.scopeContext': 'Abre este ajuste en su contexto de {scope}.',

application/i18n/locales/ru/core.ts

@@ -1130,8 +1130,64 @@ export const ruCoreMessages: Messages = {
   'deepLink.jms.unsupported': 'Неподдерживаемый протокол JumpServer: {{protocol}}',
 
   'settings.tab.plugins': 'Плагины',
-  'settings.plugins.title': 'Настройки плагинов',
-  'settings.plugins.description': 'Проверенные нативные настройки от плагинов разработки.',
+  "settings.plugins.manager.installed": "Установленные плагины",
+  "settings.plugins.manager.import": "Импорт .ncpkg",
+  "settings.plugins.manager.preview": "Импортированные пакеты отключены до проверки и включения.",
+  "settings.plugins.manager.empty": "Импортируйте локальный пакет плагина.",
+  "settings.plugins.manager.enabled": "Включён",
+  "settings.plugins.manager.disabled": "Отключён",
+  "settings.plugins.manager.enable": "Включить",
+  "settings.plugins.manager.disable": "Отключить",
+  "settings.plugins.manager.remove": "Удалить",
+  "settings.plugins.manager.removeNote": "Удаление очищает код пакета и локальные данные KV. Настройки пользователя, секреты и данные синхронизации сохраняются.",
+  "settings.plugins.permissions.title": "Действующие разрешения",
+  "settings.plugins.permissions.refresh": "Обновить",
+  "settings.plugins.permissions.loading": "Загрузка разрешений...",
+  "settings.plugins.permissions.empty": "Действующих разрешений нет. Одноразовые решения не сохраняются.",
+  "settings.plugins.permissions.always": "До отзыва",
+  "settings.plugins.permissions.application": "До выхода из Netcatty",
+  "settings.plugins.permissions.session": "До закрытия сеанса",
+  "settings.plugins.permissions.audit": "Последние события безопасности (до 100)",
+  "settings.plugins.permissions.revoke": "Отключить и отозвать все разрешения",
+  "settings.plugins.permissions.revokeNote": "Плагин будет отключён, его задачи отменены, а сохранённые разрешения удалены. Включите его для нового запроса доступа.",
+  "settings.plugins.permissions.unavailable": "Управление разрешениями недоступно",
+  "settings.plugins.manager.permissions": "Заявленные разрешения",
+  "settings.plugins.manager.permissionNote": "Из манифеста, а не предоставленные права. Включение допускает отложенную активацию; обязательные разрешения запрашиваются перед ней, необязательные — при использовании. Чувствительные операции проверяются приложением.",
+  "settings.plugins.manager.noPermissions": "Привилегированные разрешения не заявлены.",
+  "settings.plugins.manager.required": "Обязательно",
+  "settings.plugins.manager.optional": "Необязательно",
+  "settings.plugins.manager.browser": "Браузерная среда: привилегированный доступ проходит через проверку разрешений приложения.",
+  "settings.plugins.manager.advanced": "Расширенная среда: полный доступ Node к файловой системе и сети. Разрешения посредника не ограничивают этот доступ. Только для разработки.",
+  "settings.plugins.manager.data": "Данные KV остаются на устройстве. Синхронизируются только явно отмеченные несекретные настройки в зашифрованных данных. Пакеты и разрешения не синхронизируются.",
+  "settings.plugins.market.results": "Плагинов: {count}",
+  "settings.plugins.manager.lastError": "Последняя записанная ошибка",
+  "settings.plugins.market.offline": "Реестр недоступен. Показан последний корректный каталог или встроенные примеры. Для установки необходимо успешно обновить каталог.",
+  "settings.plugins.manager.details": "Подробнее",
+  "settings.plugins.manager.noDescription": "Описание не предоставлено.",
+  "settings.plugins.market.installed": "Установлен",
+  "settings.plugins.market.sourceBadge": "Пример исходного кода",
+  "settings.plugins.market.title": "Каталог",
+  "settings.plugins.market.note": "Отобранные плагины с открытым кодом. Проверка не гарантирует безопасность. Обновления выполняются вручную.",
+  "settings.plugins.market.back": "Все плагины",
+  "settings.plugins.market.install": "Установить эту версию (отключённой)",
+  "settings.plugins.market.installNote": "Установленная версия будет заменена и остановлена. Проверьте разрешения перед включением.",
+  "settings.plugins.market.sourceOnly": "Пример из этого проекта. Соберите локальной CLI и импортируйте .ncpkg; готовый пакет для скачивания не опубликован.",
+  "settings.plugins.market.readmeNote": "Зафиксирован указанный коммит. HTML не выполняется, внешние изображения не загружаются. Текст автора плагина.",
+  "settings.plugins.manager.noVault": "Системное хранилище ключей недоступно. Операции с секретами и учётными данными заблокированы; каталог и плагины без секретов доступны.",
+  "settings.plugins.manager.sensitive": "Чувствительный доступ: проверьте данные и область ресурсов перед разрешением.",
+  "settings.plugins.manager.dual": "По умолчанию используется браузерная среда. Пакет также содержит вход Node с полным доступом к устройству; только для разработчиков.",
+  "settings.plugins.manager.advancedDeclaration": "Браузерная точка входа с заявленными расширенными разрешениями. Не допускается в обычном режиме; проверьте все разрешения.",
+  "settings.plugins.market.retry": "Повторить",
+  "settings.plugins.market.empty": "Каталог пуст. Можно импортировать локальный браузерный плагин.",
+  "settings.plugins.market.emptyReadme": "Этот README пуст.",
+  "settings.plugins.market.search": "Поиск по имени, автору или описанию",
+  "settings.plugins.market.noResults": "Совпадений нет. Измените запрос.",
+  "settings.plugins.market.manifest": "Совместимость и разрешения",
+  "settings.plugins.manager.unbounded": "Более узкая область ресурсов не заявлена. Проверьте фактическую область в запросе разрешения.",
+  "settings.plugins.openView": "Открыть",
+  "settings.plugins.openManager": "Открыть управление плагинами",
+  "settings.plugins.title": "Плагины",
+  "settings.plugins.description": "Управляйте плагинами и просматривайте каталог.",
   'settings.plugins.loading': 'Загрузка настроек плагинов…',
   'settings.plugins.empty': 'Включённые плагины не предоставляют настройки.',
   'settings.plugins.scopeContext': 'Откройте эту настройку в контексте {scope}.',

application/i18n/locales/zh-CN/core.ts

@@ -1150,8 +1150,64 @@ Vaults 标签保持扁平，不使用这块背景。
   'qs.localShells': '本地 Shell',
   'qs.default': '默认',
   'settings.tab.plugins': '插件',
-  'settings.plugins.title': '插件设置',
-  'settings.plugins.description': '由开发插件提供、经 Netcatty 原生组件验证的设置。',
+  "settings.plugins.manager.installed": "已安装插件",
+  "settings.plugins.manager.import": "导入 .ncpkg",
+  "settings.plugins.manager.preview": "导入的插件保持停用，请检查后再启用。",
+  "settings.plugins.manager.empty": "导入本地插件包以开始使用。",
+  "settings.plugins.manager.enabled": "已启用",
+  "settings.plugins.manager.disabled": "已停用",
+  "settings.plugins.manager.enable": "启用",
+  "settings.plugins.manager.disable": "停用",
+  "settings.plugins.manager.remove": "卸载",
+  "settings.plugins.manager.removeNote": "卸载会移除插件代码和本地 KV 数据，保留用户设置、秘密存储和同步 sidecar。",
+  "settings.plugins.permissions.title": "实际授权",
+  "settings.plugins.permissions.refresh": "刷新",
+  "settings.plugins.permissions.loading": "正在读取授权...",
+  "settings.plugins.permissions.empty": "没有有效授权。单次决定不会保留。",
+  "settings.plugins.permissions.always": "直到撤销",
+  "settings.plugins.permissions.application": "直到退出 Netcatty",
+  "settings.plugins.permissions.session": "直到会话关闭",
+  "settings.plugins.permissions.audit": "最近的安全事件（最多 100 条）",
+  "settings.plugins.permissions.revoke": "停用并撤销全部授权",
+  "settings.plugins.permissions.revokeNote": "此操作会停用插件、取消其工作并删除已保存的授权。重新启用后可申请新授权。",
+  "settings.plugins.permissions.unavailable": "插件授权管理不可用",
+  "settings.plugins.manager.permissions": "声明的权限",
+  "settings.plugins.manager.permissionNote": "来自 manifest，不代表已授权。启用表示允许按需激活；必需权限在首次激活前申请，可选权限在用到时申请。敏感操作仍受宿主检查。",
+  "settings.plugins.manager.noPermissions": "未声明特权权限。",
+  "settings.plugins.manager.required": "必需",
+  "settings.plugins.manager.optional": "可选",
+  "settings.plugins.manager.browser": "浏览器运行时：特权访问通过宿主权限代理。",
+  "settings.plugins.manager.advanced": "高级运行时：拥有完整 Node 文件系统和网络能力，代理权限无法限制这些访问。仅供开发预览。",
+  "settings.plugins.manager.data": "本地 KV 仅保留在此设备。只有明确标记为同步的非秘密设置进入加密云 sidecar。插件包和权限授权不参与同步。",
+  "settings.plugins.market.results": "{count} 个插件",
+  "settings.plugins.manager.lastError": "上次记录的错误",
+  "settings.plugins.market.offline": "官方目录暂时不可用，正在显示上次有效目录或内置示例。刷新成功前不能从市场安装。",
+  "settings.plugins.manager.details": "查看详情",
+  "settings.plugins.manager.noDescription": "作者暂未提供功能简介。",
+  "settings.plugins.market.installed": "已安装",
+  "settings.plugins.market.sourceBadge": "源码示例",
+  "settings.plugins.market.title": "插件市场",
+  "settings.plugins.market.note": "精选开源插件。审核不代表安全认证，更新由你手动确认。",
+  "settings.plugins.market.back": "所有插件",
+  "settings.plugins.market.install": "安装此版本（保持停用）",
+  "settings.plugins.market.installNote": "这会替换并停止已安装版本。请在已安装列表检查权限后再启用。",
+  "settings.plugins.market.sourceOnly": "第一方源码示例。请用本地 CLI 构建并导入 .ncpkg；尚未发布可下载发行包。",
+  "settings.plugins.market.readmeNote": "固定到上面的提交。HTML 不执行，远程图片不加载。内容由插件作者提供。",
+  "settings.plugins.manager.noVault": "系统密钥存储不可用。秘密和凭据操作被阻止；浏览市场和不使用秘密的插件仍可使用。",
+  "settings.plugins.manager.sensitive": "敏感访问：授权前请检查涉及的数据和资源范围。",
+  "settings.plugins.manager.dual": "默认使用浏览器运行时，但包中还包含拥有完整设备权限的 Node 入口；仅限开发者模式。",
+  "settings.plugins.manager.advancedDeclaration": "浏览器入口声明了高级权限。不适用于普通浏览器插件模式；请逐项检查声明权限。",
+  "settings.plugins.market.retry": "重试",
+  "settings.plugins.market.empty": "目录暂无插件，仍可导入本地浏览器插件。",
+  "settings.plugins.market.emptyReadme": "README 内容为空。",
+  "settings.plugins.market.search": "搜索名称、作者或描述",
+  "settings.plugins.market.noResults": "没有匹配插件，请尝试其他关键词。",
+  "settings.plugins.market.manifest": "兼容性与权限",
+  "settings.plugins.manager.unbounded": "未声明更细的资源范围。请在权限提示中检查实际授权范围。",
+  "settings.plugins.openView": "打开",
+  "settings.plugins.openManager": "打开插件管理",
+  "settings.plugins.title": "插件",
+  "settings.plugins.description": "管理已安装插件，浏览精选目录。",
   'settings.plugins.loading': '正在加载插件设置…',
   'settings.plugins.empty': '当前没有已启用插件提供设置。',
   'settings.plugins.scopeContext': '请在对应的 {scope} 上下文中打开此设置。',

application/i18n/locales/zh-TW/core.ts

@@ -1153,9 +1153,65 @@ Vaults 分頁維持扁平，不使用這塊背景。
   'qs.default': '預設',
 
   'settings.tab.plugins': '外掛程式',
-  'settings.plugins.title': '外掛程式設定',
-  'settings.plugins.description': '由開發外掛程式提供、經 Netcatty 原生元件驗證的設定。',
+  "settings.plugins.manager.installed": "已安裝插件",
+  "settings.plugins.manager.import": "導入 .ncpkg",
+  "settings.plugins.manager.preview": "導入的插件保持停用，請檢查後再啟用。",
+  "settings.plugins.manager.empty": "導入本地插件包以開始使用。",
+  "settings.plugins.manager.enabled": "已啟用",
+  "settings.plugins.manager.disabled": "已停用",
+  "settings.plugins.manager.enable": "啟用",
+  "settings.plugins.manager.disable": "停用",
+  "settings.plugins.manager.remove": "卸載",
+  "settings.plugins.manager.removeNote": "卸載會移除插件代碼和本地 KV 數據，保留用戶設置、秘密存儲和同步 sidecar。",
+  "settings.plugins.permissions.title": "實際授權",
+  "settings.plugins.permissions.refresh": "重新整理",
+  "settings.plugins.permissions.loading": "正在讀取授權...",
+  "settings.plugins.permissions.empty": "沒有有效授權。單次決定不會保留。",
+  "settings.plugins.permissions.always": "直到撤銷",
+  "settings.plugins.permissions.application": "直到退出 Netcatty",
+  "settings.plugins.permissions.session": "直到工作階段關閉",
+  "settings.plugins.permissions.audit": "最近的安全事件（最多 100 筆）",
+  "settings.plugins.permissions.revoke": "停用並撤銷全部授權",
+  "settings.plugins.permissions.revokeNote": "此操作會停用外掛、取消其工作並刪除已儲存的授權。重新啟用後可申請新授權。",
+  "settings.plugins.permissions.unavailable": "外掛授權管理無法使用",
+  "settings.plugins.manager.permissions": "聲明的權限",
+  "settings.plugins.manager.permissionNote": "來自 manifest，不代表已授權。啟用表示允許按需激活；必需權限在首次激活前申請，可選權限在用到時申請。敏感操作仍受宿主檢查。",
+  "settings.plugins.manager.noPermissions": "未聲明特權權限。",
+  "settings.plugins.manager.required": "必需",
+  "settings.plugins.manager.optional": "可選",
+  "settings.plugins.manager.browser": "瀏覽器運行時：特權訪問通過宿主權限代理。",
+  "settings.plugins.manager.advanced": "高級運行時：擁有完整 Node 文件系統和網絡能力，代理權限無法限制這些訪問。僅供開發預覽。",
+  "settings.plugins.manager.data": "本地 KV 僅保留在此設備。只有明確標記為同步的非秘密設置進入加密雲 sidecar。插件包和權限授權不參與同步。",
+  "settings.plugins.manager.unbounded": "未宣告更細的資源範圍。請在權限提示中檢查實際授權範圍。",
+  "settings.plugins.openView": "開啟",
+  "settings.plugins.openManager": "開啟插件管理",
+  "settings.plugins.title": "插件",
+  "settings.plugins.description": "管理已安裝插件，瀏覽精選目錄。",
   'settings.plugins.loading': '正在載入外掛程式設定…',
+  "settings.plugins.market.results": "{count} 個插件",
+  "settings.plugins.manager.lastError": "上次記錄的錯誤",
+  "settings.plugins.market.offline": "官方目錄暫時無法使用，正在顯示上次有效目錄或內建範例。重新整理成功前無法從市場安裝。",
+  "settings.plugins.manager.details": "查看詳情",
+  "settings.plugins.manager.noDescription": "作者尚未提供功能簡介。",
+  "settings.plugins.market.installed": "已安裝",
+  "settings.plugins.market.sourceBadge": "原始碼範例",
+  "settings.plugins.market.title": "插件市場",
+  "settings.plugins.market.note": "精選開源插件。審核不代表安全認證，更新由你手動確認。",
+  "settings.plugins.market.back": "所有插件",
+  "settings.plugins.market.install": "安裝此版本（保持停用）",
+  "settings.plugins.market.installNote": "這會替換並停止已安裝版本。請在已安裝列表檢查權限後再啟用。",
+  "settings.plugins.market.sourceOnly": "第一方源碼示例。請用本地 CLI 構建並導入 .ncpkg；尚未發佈可下載發行包。",
+  "settings.plugins.market.readmeNote": "固定到上面的提交。HTML 不執行，遠程圖片不加載。內容由插件作者提供。",
+  "settings.plugins.manager.noVault": "系統密鑰存儲不可用。秘密和憑據操作被阻止；瀏覽市場和不使用秘密的插件仍可使用。",
+  "settings.plugins.manager.sensitive": "敏感訪問：授權前請檢查涉及的數據和資源範圍。",
+  "settings.plugins.manager.dual": "默認使用瀏覽器運行時，但包中還包含擁有完整設備權限的 Node 入口；僅限開發者模式。",
+  "settings.plugins.manager.advancedDeclaration": "瀏覽器入口聲明瞭高級權限。不適用於普通瀏覽器插件模式；請逐項檢查聲明權限。",
+  "settings.plugins.market.retry": "重試",
+  "settings.plugins.market.empty": "目錄暫無插件，仍可導入本地瀏覽器插件。",
+  "settings.plugins.market.emptyReadme": "README 內容為空。",
+  "settings.plugins.market.search": "搜索名稱、作者或描述",
+  "settings.plugins.market.noResults": "沒有匹配插件，請嘗試其他關鍵詞。",
+  "settings.plugins.market.manifest": "兼容性與權限",
   'settings.plugins.empty': '目前沒有已啟用外掛程式提供設定。',
   'settings.plugins.scopeContext': '請在對應的 {scope} 情境中開啟此設定。',
   'settings.plugins.pressKeybinding': '請按下組合鍵',

application/state/usePluginBrandIcon.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+import { netcattyBridge } from '../../infrastructure/services/netcattyBridge';
+
+type Raster = { light: string; dark?: string };
+export function usePluginBrandIcon(plugin?: NetcattyInstalledPlugin): Raster | null {
+  const pluginId = plugin?.id;
+  const kind = plugin?.manifest?.icon?.kind;
+  const key = JSON.stringify([pluginId, plugin?.activeVersion, plugin?.archiveSha256, plugin?.runtime?.quarantinedAt, plugin?.manifest?.icon]);
+  const [loaded, setLoaded] = useState<{ key: string; value: Raster | null } | null>(null);
+  useEffect(() => {
+    if (!pluginId || kind !== 'package') return;
+    let cancelled = false;
+    void netcattyBridge.get()?.getPluginBrandIcon?.(pluginId).then((value) => {
+      if (!cancelled) setLoaded({ key, value });
+    }).catch(() => { if (!cancelled) setLoaded({ key, value: null }); });
+    return () => { cancelled = true; };
+  }, [key, pluginId, kind]);
+  return loaded?.key === key ? loaded.value : null;
+}

application/state/usePluginCatalog.test.ts

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+import { usePluginCatalog } from './usePluginCatalog';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (cause: Error) => void;
+  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+  return { promise, resolve, reject };
+}
+
+test('README failures clear on retry/switch and stale requests cannot replace the selected entry', async (context) => {
+  const original = Object.getOwnPropertyDescriptor(globalThis, 'window');
+  const calls: Array<{ id: string; request: ReturnType<typeof deferred<string>> }> = [];
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: {
+    netcatty: {
+      listPluginCatalog: async () => ({ entries: [], source: "builtin", error: null }),
+      getPluginCatalogReadme: (id: string) => { const request = deferred<string>(); calls.push({ id, request }); return request.promise; },
+    },
+  } });
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  context.after(() => {
+    if (original) Object.defineProperty(globalThis, 'window', original); else Reflect.deleteProperty(globalThis, 'window');
+    Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+  });
+  let state!: ReturnType<typeof usePluginCatalog>;
+  let renders = 0;
+  function Probe({ id }: { id: string }) { state = usePluginCatalog(id); renders++; return null; }
+  let renderer!: ReactTestRenderer;
+  await act(async () => { renderer = create(React.createElement(Probe, { id: 'first' })); });
+  assert.equal(state.readmeStatus, 'loading');
+  await act(async () => calls[0].request.reject(new Error('temporary failure')));
+  assert.equal(state.readmeStatus, 'error');
+  assert.match(state.readmeError!, /temporary failure/);
+  await act(async () => state.retryReadme());
+  assert.equal(state.readmeStatus, 'loading'); assert.equal(state.readmeError, null);
+  await act(async () => calls[1].request.resolve(''));
+  assert.equal(state.readmeStatus, 'ready'); assert.equal(state.readme, ''); assert.equal(state.readmeError, null);
+  await act(async () => state.retryReadme());
+  await act(async () => renderer.update(React.createElement(Probe, { id: 'second' })));
+  assert.equal(state.readmeError, null);
+  await act(async () => calls[3].request.resolve('# Second'));
+  await act(async () => calls[2].request.reject(new Error('stale failure')));
+  assert.equal(state.readme, '# Second'); assert.equal(state.readmeError, null);
+  await act(async () => state.retryReadme());
+  await act(async () => renderer.unmount());
+  const unmountedRenders = renders;
+  await act(async () => calls[4].request.resolve('late content'));
+  assert.equal(renders, unmountedRenders);
+});
+
+test('offline snapshot stays browsable, retry clears warning, and operations bind the selected token', async (context) => {
+  const original = Object.getOwnPropertyDescriptor(globalThis, 'window');
+  const entry = { id: 'com.test.registry', selectionToken: 'first' } as NetcattyPluginCatalogEntry;
+  let offline = true;
+  const reads: unknown[][] = []; const installs: unknown[][] = [];
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: {
+    dispatchEvent() {}, netcatty: {
+      listPluginCatalog: async () => ({ entries: [{ ...entry, selectionToken: offline ? 'first' : 'second' }], source: offline ? 'cached' : 'registry', error: offline ? 'offline' : null }),
+      getPluginCatalogReadme: async (...args: unknown[]) => { reads.push(args); return '# Pinned'; },
+      installCatalogPlugin: async (...args: unknown[]) => { installs.push(args); },
+    },
+  } });
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  context.after(() => {
+    if (original) Object.defineProperty(globalThis, 'window', original); else Reflect.deleteProperty(globalThis, 'window');
+    Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+  });
+  let state!: ReturnType<typeof usePluginCatalog>;
+  function Probe() { state = usePluginCatalog(entry.id); return null; }
+  let renderer!: ReactTestRenderer;
+  await act(async () => { renderer = create(React.createElement(Probe)); });
+  assert.equal(state.entries.length, 1); assert.equal(state.listStatus, 'ready'); assert.equal(state.listError, 'offline');
+  assert.equal(state.source, 'cached');
+  offline = false;
+  await act(async () => state.retryList());
+  assert.equal(state.listError, null); assert.equal(state.source, 'registry');
+  assert.deepEqual(reads.at(-1), [entry.id, 'second']);
+  await act(async () => state.install(entry.id));
+  assert.deepEqual(installs, [[entry.id, 'second']]);
+  await act(async () => renderer.unmount());
+});

application/state/usePluginCatalog.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from 'react';
+import { netcattyBridge } from '../../infrastructure/services/netcattyBridge';
+
+type ReadmeState = { id: string; token?: string; attempt: number; status: 'loading' | 'ready' | 'error'; text: string; error: string | null };
+export function usePluginCatalog(selectedId: string | null) {
+  const [entries, setEntries] = useState<NetcattyPluginCatalogEntry[]>([]);
+  const [listStatus, setListStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+  const [source, setSource] = useState<NetcattyPluginCatalogSnapshot['source']>('builtin');
+  const [listError, setListError] = useState<string | null>(null);
+  const [listAttempt, setListAttempt] = useState(0);
+  const [readmeState, setReadmeState] = useState<ReadmeState | null>(null);
+  const [readmeAttempt, setReadmeAttempt] = useState(0);
+  const [installError, setInstallError] = useState<{ id: string; message: string } | null>(null);
+  const [busy, setBusy] = useState(false);
+  const installing = useRef(false);
+  const mounted = useRef(false);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+  useEffect(() => {
+    let active = true;
+    setListStatus('loading'); setListError(null);
+    void (async () => {
+      try {
+        const bridge = netcattyBridge.get();
+        if (!bridge?.listPluginCatalog) throw new Error('Catalog browsing unavailable');
+        const list = await bridge.listPluginCatalog();
+        if (active) { setEntries(list.entries); setSource(list.source); setListError(list.error); setListStatus('ready'); }
+      } catch (cause) { if (active) { setListStatus('error'); setListError(String(cause)); } }
+    })();
+    return () => { active = false; };
+  }, [listAttempt]);
+  const selectionToken = entries.find((entry) => entry.id === selectedId)?.selectionToken;
+  useEffect(() => {
+    if (!selectedId) return;
+    let active = true;
+    const base = { id: selectedId, token: selectionToken, attempt: readmeAttempt, text: '', error: null };
+    setReadmeState({ ...base, status: 'loading' });
+    void (async () => {
+      try {
+        const bridge = netcattyBridge.get();
+        if (!bridge?.getPluginCatalogReadme) throw new Error('README retrieval unavailable');
+        const text = await bridge.getPluginCatalogReadme(selectedId, selectionToken);
+        if (active) setReadmeState({ ...base, status: 'ready', text });
+      } catch (cause) { if (active) setReadmeState({ ...base, status: 'error', error: String(cause) }); }
+    })();
+    return () => { active = false; };
+  }, [selectedId, selectionToken, readmeAttempt]);
+  const currentReadme = readmeState?.id === selectedId && readmeState.token === selectionToken && readmeState.attempt === readmeAttempt ? readmeState : null;
+  return {
+    entries, listStatus, listError, source,
+    readme: currentReadme?.status === 'ready' ? currentReadme.text : null,
+    readmeStatus: currentReadme?.status ?? (selectedId ? 'loading' : 'idle'),
+    readmeError: currentReadme?.error ?? null,
+    error: installError?.id === selectedId ? installError.message : null,
+    busy,
+    retryList: () => setListAttempt((attempt) => attempt + 1),
+    retryReadme: () => setReadmeAttempt((attempt) => attempt + 1),
+    async install(id: string) {
+      if (installing.current) return;
+      installing.current = true;
+      setBusy(true); setInstallError(null);
+      try {
+        const bridge = netcattyBridge.require();
+        if (!bridge.installCatalogPlugin) throw new Error('Catalog installation unavailable');
+        await bridge.installCatalogPlugin(id, entries.find((entry) => entry.id === id)?.selectionToken);
+        window.dispatchEvent(new Event('netcatty:plugin-packages-changed'));
+      } catch (cause) { if (mounted.current) setInstallError({ id, message: String(cause) }); }
+      finally { installing.current = false; if (mounted.current) setBusy(false); }
+    },
+  };
+}

application/state/usePluginManager.ts

@@ -0,0 +1,59 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { netcattyBridge } from '../../infrastructure/services/netcattyBridge';
+
+export function usePluginManager() {
+  const [plugins, setPlugins] = useState<NetcattyInstalledPlugin[]>([]);
+  const [available, setAvailable] = useState(false);
+  const [credentialStorageAvailable, setCredentialStorageAvailable] = useState<boolean | undefined>();
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const generation = useRef(0);
+  const mutation = useRef(false);
+  const refresh = useCallback(async () => {
+    const current = ++generation.current;
+    const bridge = netcattyBridge.get();
+    const status = await bridge?.getPluginRuntimeStatus?.();
+    const list = status?.available ? await bridge?.listPlugins?.() ?? [] : [];
+    if (current !== generation.current) return;
+    setAvailable(status?.available === true);
+    setCredentialStorageAvailable(status?.credentialStorageAvailable);
+    setPlugins(list);
+  }, []);
+  useEffect(() => {
+    const update = () => { void refresh().catch((cause) => setError(String(cause))); };
+    update();
+    const unsubscribe = netcattyBridge.get()?.onPluginContributionsChanged?.(update);
+    window.addEventListener('netcatty:plugin-packages-changed', update);
+    const refreshGeneration = generation;
+    return () => { refreshGeneration.current++; unsubscribe?.(); window.removeEventListener('netcatty:plugin-packages-changed', update); };
+  }, [refresh]);
+  const run = useCallback(async (action: (bridge: NetcattyBridge) => Promise<unknown>) => {
+    if (mutation.current) return;
+    mutation.current = true;
+    setBusy(true);
+    setError(null);
+    try { await action(netcattyBridge.require()); }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+    finally {
+      try { await refresh(); } catch (cause) { setError(String(cause)); }
+      mutation.current = false;
+      setBusy(false);
+    }
+  }, [refresh]);
+  return {
+    plugins, available, busy, error, credentialStorageAvailable, refresh,
+    importPackage: () => run(async (bridge) => {
+      if (!bridge.selectFile || !bridge.installPluginPackage) throw new Error('Plugin import unavailable');
+      const path = await bridge.selectFile('Import plugin package', undefined, [{ name: 'Netcatty plugin', extensions: ['ncpkg'] }]);
+      if (path) await bridge.installPluginPackage(path, { enable: false });
+    }),
+    setEnabled: (id: string, enabled: boolean) => run(async (bridge) => {
+      if (!bridge.setPluginEnabled) throw new Error('Plugin management unavailable');
+      return bridge.setPluginEnabled(id, enabled);
+    }),
+    uninstall: (id: string) => run(async (bridge) => {
+      if (!bridge.uninstallPlugin) throw new Error('Plugin management unavailable');
+      return bridge.uninstallPlugin(id);
+    }),
+  };
+}

build/installer.nsh

@@ -1,14 +1,3 @@
-!macro customInit
-  ; #3946: external MCP hosts launch Netcatty.exe with ELECTRON_RUN_AS_NODE=1
-  ; via netcatty-external-mcp.cmd. Those processes can outlive the host UI as
-  ; orphans and keep $INSTDIR locked, so the in-app updater hangs (AppHangB1).
-  ; Force-kill leftover Netcatty.exe before files are replaced. Do not pass /T:
-  ; electron-updater spawns this installer as a child of the UI Netcatty.exe,
-  ; and /T would terminate the installer itself. Ignore a missing process.
-  nsExec::ExecToLog "taskkill /F /IM Netcatty.exe"
-  Pop $0
-!macroend
-
 !macro customInstall
   ; Open a selected folder in a new Netcatty local terminal.
   ; Args go after `--` so Electron/Chromium does not swallow them. Use

components/KeyboardInteractiveModal.remember.test.tsx

@@ -1,138 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import React from "react";
-import type { Host, Identity } from "../types";
-import { handleKeyboardInteractiveSubmitImpl } from "../application/app/AppHandlers";
-import { createTerminalSessionStarters } from "./terminal/runtime/createTerminalSessionStarters";
-import { createPromptLineBreakState } from "./terminal/runtime/promptLineBreak";
-import { createDomRenderer, dispatchDomEvent, installDomEnvironment } from "./test-support/renderReactDom";
-
-const noop = () => {};
-
-test("KI remember input preserves the reconnect account and leaves shared hosts unchanged", async (t) => {
-  const dom = installDomEnvironment();
-  const globals = {
-    MutationObserver: dom.window.MutationObserver,
-    NodeFilter: dom.window.NodeFilter,
-    HTMLInputElement: dom.window.HTMLInputElement,
-    localStorage: dom.window.localStorage,
-  };
-  const previous = new Map(Object.keys(globals).map((key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)]));
-  for (const [key, value] of Object.entries(globals)) Object.defineProperty(globalThis, key, { configurable: true, value });
-  const { KeyboardInteractiveModal } = await import("./KeyboardInteractiveModal");
-  const { I18nProvider } = await import("../application/i18n/I18nProvider");
-  const renderer = await createDomRenderer(dom.document);
-  try {
-    for (const scenario of [
-      { name: "differing usernames", hostUsername: "old-account", identityUsername: "fixtureki", remember: true },
-      { name: "blank host username", hostUsername: "", identityUsername: "fixtureki", remember: true },
-      { name: "blank identity username", hostUsername: "fixtureki", identityUsername: "  ", remember: true },
-      { name: "no identity", hostUsername: "fixtureki", identityUsername: undefined, remember: true },
-      { name: "remember unchecked", hostUsername: "old-account", identityUsername: "fixtureki", remember: false },
-      { name: "secondary password", hostUsername: "old-account", identityUsername: "fixtureki", remember: true, allowSavePassword: false },
-    ]) {
-      await t.test(scenario.name, async () => {
-        const identity: Identity = {
-          id: "shared", label: "Fixture", username: scenario.identityUsername ?? "",
-          authMethod: "password", password: "fixture-old", created: 0,
-        };
-        const identities = scenario.identityUsername === undefined ? [] : [identity];
-        const originalIdentity = { ...identity };
-        const host: Host = {
-          id: "changed", label: "Fixture", hostname: "127.0.0.1", username: scenario.hostUsername,
-          tags: [], os: "linux", protocol: "ssh", authMethod: "password",
-          password: "fixture-host-old", savePassword: false,
-          ...(identities.length ? { identityId: identity.id } : {}),
-        };
-        const otherHost = { ...host, id: "unchanged", label: "Other fixture" };
-        let hosts = [host, otherHost];
-        let updates = 0;
-        const request = {
-          requestId: `ki-${scenario.name}`, sessionId: "fixture-session", hostname: host.hostname,
-          name: "Password expiry", instructions: "", prompts: [{ prompt: "New password:", echo: false }],
-          allowSavePassword: scenario.allowSavePassword ?? true,
-        };
-        let queue = [request];
-        const responses: unknown[][] = [];
-        await renderer.render(
-          <I18nProvider locale="en">
-            <KeyboardInteractiveModal request={request} onCancel={() => false}
-              onSubmit={(requestId, values, savePassword) => handleKeyboardInteractiveSubmitImpl(() => ({
-                hosts, identities, keyboardInteractiveQueue: queue,
-                sessions: [{ id: "fixture-session", hostId: host.id, hostname: host.hostname }],
-                netcattyBridge: { get: () => ({ respondKeyboardInteractive: (...args: unknown[]) => {
-                  responses.push(args);
-                  return { success: true };
-                } }) },
-                setKeyboardInteractiveQueue: (updater: (items: typeof queue) => typeof queue) => { queue = updater(queue); },
-                updateHosts: (next: Host[]) => { updates += 1; hosts = next; },
-                t: (key: string) => key, toast: { error: (message: string) => assert.fail(message) },
-              }), requestId, values, savePassword)} />
-          </I18nProvider>,
-        );
-        const input = dom.document.querySelector<HTMLInputElement>("#ki-prompt-0");
-        assert.ok(input);
-        Object.getOwnPropertyDescriptor(dom.window.HTMLInputElement.prototype, "value")!.set!.call(input, "fixture-new");
-        await dispatchDomEvent(input, new dom.window.Event("input", { bubbles: true }));
-        const checkbox = dom.document.querySelector<HTMLInputElement>('input[type="checkbox"]');
-        if (scenario.allowSavePassword === false) assert.equal(checkbox, null);
-        else {
-          assert.ok(checkbox);
-          assert.equal(checkbox.checked, false);
-          if (scenario.remember) await dispatchDomEvent(checkbox, new dom.window.MouseEvent("click", { bubbles: true }));
-        }
-        const submit = [...dom.document.querySelectorAll("button")].find((button) => button.textContent === "Submit");
-        assert.ok(submit);
-        await dispatchDomEvent(submit, new dom.window.MouseEvent("click", { bubbles: true }));
-        assert.deepEqual(responses, [[request.requestId, ["fixture-new"], false]]);
-        assert.deepEqual(queue, []);
-        const saved = scenario.remember && scenario.allowSavePassword !== false;
-        assert.equal(updates, saved ? 1 : 0);
-        assert.equal(hosts[0].identityId, saved && identities.length ? "" : host.identityId);
-        assert.equal(hosts[0].password, saved ? "fixture-new" : host.password);
-        assert.equal(hosts[0].savePassword, saved);
-        assert.equal(hosts[1], otherHost);
-        assert.deepEqual(identity, originalIdentity);
-
-        // Exercise the reconnect launcher that builds the actual SSH bridge request.
-        for (const [index, candidate] of hosts.entries()) {
-          let started: { username: string; password?: string } | undefined;
-          const ctx = {
-            host: candidate, identities, keys: [], knownHosts: [], resolvedChainHosts: [],
-            sessionId: `reconnect-${index}`, terminalSettings: {},
-            sessionRef: { current: null }, hasConnectedRef: { current: true },
-            hasRunStartupCommandRef: { current: true }, disposeDataRef: { current: null },
-            disposeExitRef: { current: null }, fitAddonRef: { current: null },
-            serializeAddonRef: { current: null }, pendingAuthRef: { current: null },
-            promptLineBreakStateRef: { current: createPromptLineBreakState() }, sudoAutofillRef: { current: null },
-            updateStatus: noop, setStatus: noop, setError: noop, setNeedsAuth: noop,
-            setAuthRetryMessage: noop, setAuthPassword: noop, setProgressLogs: noop,
-            setProgressValue: noop, setChainProgress: noop,
-            terminalBackend: {
-              backendAvailable: () => true,
-              startSSHSession: async (options: { username: string; password?: string }) => { started = options; return `reconnect-${index}`; },
-              onSessionData: () => noop, onSessionExit: () => noop, onChainProgress: () => noop,
-              writeToSession: noop, resizeSession: noop,
-            },
-          };
-          await createTerminalSessionStarters(ctx as never).startSSH({
-            cols: 80, rows: 24, write: noop, writeln: noop, scrollToBottom: noop,
-          } as never);
-          assert.ok(started);
-          assert.equal(started.username, scenario.identityUsername?.trim() || scenario.hostUsername);
-          assert.equal(started.password, saved && index === 0 ? "fixture-new" : identities.length ? "fixture-old" : "fixture-host-old");
-        }
-        // A fresh request resets the checkbox and submitting state for the next case.
-        await renderer.render(<I18nProvider locale="en"><KeyboardInteractiveModal request={null} onSubmit={() => false} onCancel={() => false} /></I18nProvider>);
-      });
-    }
-  } finally {
-    await renderer.unmount();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    for (const [key, descriptor] of previous) {
-      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
-      else Reflect.deleteProperty(globalThis, key);
-    }
-    dom.cleanup();
-  }
-});

components/QuickSwitcher.pluginContributions.test.tsx

@@ -151,3 +151,24 @@ test('plugin palette items keep repeated placements independently addressable',
     commandId: 'com.example.palette.run',
   }]);
 });
+
+test('packaged Starter contributions are discoverable through the real palette builder', async (context) => {
+  const { createRequire } = await import('node:module');
+  const { mkdtempSync, rmSync } = await import('node:fs');
+  const { tmpdir } = await import('node:os');
+  const { join } = await import('node:path');
+  const require = createRequire(import.meta.url);
+  const { PluginDatabase } = require('../electron/plugins/database.cjs');
+  const { PluginContributionService } = require('../electron/plugins/contributionService.cjs');
+  const manifest = JSON.parse(readFileSync(new URL('../examples/plugins/starter-netcatty/netcatty.plugin.json', import.meta.url), 'utf8'));
+  const root = mkdtempSync(join(tmpdir(), 'starter-palette-'));
+  const database = new PluginDatabase(join(root, 'plugins.sqlite'));
+  context.after(() => { database.close(); rmSync(root, { recursive: true, force: true }); });
+  database.installVersion({ pluginId: manifest.id, version: manifest.version, manifest, archiveSha256: 'a'.repeat(64), packageRelativePath: 'starter' }, { enable: true });
+  const service = new PluginContributionService({ database, runtimeSupervisor: {}, secretStore: {}, getLocale: () => 'en' });
+  const items = buildPluginPaletteItems(service.snapshot().plugins, 'Starter');
+  assert.ok(items.some((item) => item.type === 'plugin-command' && item.commandId === 'com.netcatty.starter.greet'));
+  assert.ok(items.some((item) => item.type === 'plugin-view' && item.id === 'com.netcatty.starter.panel'));
+  database.setEnabled(manifest.id, false);
+  assert.equal(buildPluginPaletteItems(service.snapshot().plugins, 'Starter').length, 0);
+});

components/plugins/PluginBrandIcon.tsx

@@ -0,0 +1,26 @@
+import React, { useState } from 'react';
+import { Package } from 'lucide-react';
+import { usePluginBrandIcon } from '../../application/state/usePluginBrandIcon';
+import { PluginContributionIcon } from './PluginContributionIcon';
+import { resolveCatalogBrandIcon } from './catalogBrandIcons';
+
+export function PluginBrandIcon({ plugin, entry, size = 32, className = '' }: {
+  plugin?: NetcattyInstalledPlugin;
+  entry?: NetcattyPluginCatalogEntry;
+  size?: number;
+  className?: string;
+}) {
+  const manifest = plugin?.manifest ?? entry?.manifest;
+  const icon = manifest?.icon;
+  const key = JSON.stringify([plugin?.id, plugin?.activeVersion, plugin?.archiveSha256, plugin?.runtime?.quarantinedAt, icon]);
+  const loaded = usePluginBrandIcon(plugin);
+  const [failed, setFailed] = useState<string | null>(null);
+  const raster = plugin ? loaded : entry ? resolveCatalogBrandIcon(entry) : null;
+  const imageKey = JSON.stringify([key, raster]);
+  if (icon?.kind === 'theme') return <PluginContributionIcon icon={icon} size={size} className={className} />;
+  if (!raster || failed === imageKey) return <Package size={size} className={className} aria-hidden="true" data-plugin-brand="fallback" />;
+  return <span className={`inline-flex shrink-0 ${className}`} style={{ width: size, height: size }} aria-hidden="true" data-plugin-brand="package">
+    <img src={raster.light} alt="" width={size} height={size} className={raster.dark ? 'h-full w-full object-contain dark:hidden' : 'h-full w-full object-contain'} onError={() => setFailed(imageKey)} />
+    {raster.dark && <img src={raster.dark} alt="" width={size} height={size} className="hidden h-full w-full object-contain dark:block" onError={() => setFailed(imageKey)} />}
+  </span>;
+}

components/plugins/PluginContributionIcon.tsx

@@ -60,7 +60,7 @@ export function PluginContributionIcon({
   const packageIcon = usePluginContributionIcon(pluginId, icon);
 
   if (icon?.kind === 'theme') {
-    const Icon = THEME_ICONS[icon.name] ?? Puzzle;
+    const Icon = Object.hasOwn(THEME_ICONS, icon.name) ? THEME_ICONS[icon.name] : Puzzle;
     return <Icon size={size} className={className} aria-hidden="true" data-plugin-icon-kind="theme" />;
   }
   if (packageIcon) {

components/plugins/catalog-brand-icons.json

@@ -0,0 +1,17 @@
+[
+  {
+    "id": "com.netcatty.starter",
+    "version": "0.1.2",
+    "repository": "binaricat/Netcatty",
+    "commit": "f4a6b205adca486d4e9cda0270e13a9ff0afd7be",
+    "icon": {
+      "kind": "package",
+      "light": "assets/logo-light.png",
+      "dark": "assets/logo-dark.png"
+    },
+    "light": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAADMElEQVR4nO2d200cQRAAmwuAGJAcF3E4BsfhuCwRAwEYf9lGyz5mdqZf01WfSNydqJreYbUMIgAAAFCRJ8s3e3v//WH5fpl5eX6YuFF9E4TPQysIlRdFvB6zQ5j6Yoi3Y1YIU14E8X6MhvAY/QDI92X05z8UAPJjMOLh1vhAfFx6LwndEwD5sen10xUA8nPQ42l4Ewi5aQ6A1Z+LVl9NASA/Jy3eLgNAfm6u/LEHKM5pAKz+NTjzyAQozmEArP61OPLJBCjObgCs/jXZ88oEKA4BFIcAivMlAK7/a7P1ywQoDgEUhwCKQwDFIYDiEEBxCKA4YQL49v2n90coSYgA/sonAnvcA9hKJwJbXAM4kk0EdrgFcCWZCGxwCaBVLhHoYx5Ar1Qi0MU0gLsyiUAP0wB+/Xi9/b1EoIP5JYAIYuGyCSSCOLj9GkgEMXC9EUQE/rjfCiYCX9wDECECT0IEIEIEXoQJQIQIPAgVgAgRWBMuABEisCRkACJEYEXYAESIwILQAYgQgTbhAxAhAk1SBCBCBFqkCUCECDRIFYDI/QhG4lmZdAGI9MtE/jEpAxBpl4r8c9IGwKPlc0gZAI+WzyNdADxaPpdUAYxIZC+wT5oAkK9DigCQr0f4AJCvS+gAkK9P2ACQb0PIAJBvR7gAkG9LqACQb0+YAJDvQ4gAkO+HewDI9yXkOYEtIH8OYc8JPAP58wh9TuAeyJ9L+HMCP4P8+aQ4J1AE+VqkOCcQ+Xo8bb9g8Y8jeyaBhXzvx8WsA395fvzzHvqcQFa+PmHPCUS+DSHPCUS+He63greykW+LewAi/6Uj354QAYgg34swAYAPBFAclxtB4Iv7jSCIAwEUhwCKQwDFIYDiEEBxCKA4BFCcLwF8vkkA67H1ywQoDgEUhwCKsxsA+4A12fPKBCjOYQBMgbU48skEKM5pAEyBNTjzyAQozmUATIHcXPlrmgBEkJMWb82XACLIRasv9gDF6QqAKZCDHk/dE4AIYtPrZ0gmf0QSh7sLc2gPwDSIwYiH4U0gEfgy+vOfKo9Lgh2zFp7K6iUEPWZPXNXxTQjz0LrUml6/CaId9lYAAKDMHwpGNG+oRdPRAAAAAElFTkSuQmCC",
+    "lightSha256": "ec7bcd5e470ee3d3d9f7f77d120a4de7496a9c0ba984094f84e560d240bea947",
+    "dark": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAADMElEQVR4nO2cO07EMBQAH4iSk1FyBmokToJEzRkoOdn2UCHQko8d+/3yZvrdrJjxi4kiiwAAAEBFbiwvdv/w/GV5vcxcPt9M3KheBOHz0ApC5UsRr8fsEKZ+GeLtmBXClC9BvB+jIdyO/gDk+zL69x8KAPkxGPFwaHwgPi69t4TuCYD82PT66QoA+Tno8TS8CYTcNAfA6s9Fq6+mAJCfkxZvuwEgPzd7/tgDFGczAFb/OdjyyAQozmoArP5zseaTCVCcxQBY/edkySsToDgEUBwCKM6/ALj/n5trv0yA4hBAcQigOARQHAIoDgEUhwCKEyaAj/dX759QkhAB/MgnAnvcA7iWTgS2uAawJpsI7HALYE8yEdjgEkCrXCLQxzyAXqlEoItpAEdlEoEepgE8Pr0c/iwR6GB+CyCCWLhsAokgDm7/BhJBDFwfBBGBP+6PgonAF/cARIjAkxABiBCBF2ECECECD0IFIEIE1oQLQIQILAkZgAgRWBE2ABEisCB0ACJEoE34AESIQJMUAYgQgRZpAhAhAg1SBSByPIKReM5MugBE+mUif52UAYi0S0X+NmkD4NXyOaQMgFfL55EuAF4tn0uqAEYkshdYJk0AyNchRQDI1yN8AMjXJXQAyNcnbADItyFkAMi3I1wAyLclVADItydMAMj3IUQAyPfDPQDk+xLynMAWkD+HsOcEboH8eYQ+J3AJ5M8l/DmBf0H+fFKcEyiCfC1SnBOIfD3urC/4+PTSNQks5Hu/LuYZeOhzAln5+oQ9JxD5NoQ8JxD5drg/Cr6WjXxb3AMQ+ZWOfHtCBCCCfC/CBAA+EEBxzB8ERaTy7YcJUBwCKA4BFIcAikMAxSGA4hBAcQigOP8CuHy+3Xj8ELDh2i8ToDgEUBwCKM5iAOwDzsmSVyZAcVYDYAqcizWfTIDibAbAFDgHWx6ZAMXZDYApkJs9f00TgAhy0uKt+RZABLlo9cUeoDhdATAFctDjqXsCEEFsev0Mybx/eP4a+TzM4+jCHNoDMA1iMOJheBNIBL6M/v2nyuOWYMeshaeyeglBj9kTV3V8E8I8tG61pvdvgmiHvRUAACjzDQ0NL/vgx29SAAAAAElFTkSuQmCC",
+    "darkSha256": "7a897a67ae6b652339c77a113d1c759919776fead82d2eefd0238d3c05ba87fe"
+  }
+]

components/plugins/catalogBrandIcons.ts

@@ -0,0 +1,9 @@
+import previews from './catalog-brand-icons.json';
+
+/** Only bundled reviewed assets; catalog data never becomes an image URL. */
+export function resolveCatalogBrandIcon(entry: NetcattyPluginCatalogEntry): { light: string; dark?: string } | null {
+  const preview = previews.find((item) => item.id === entry.id && item.version === entry.version
+    && item.repository === entry.repository && item.commit === entry.commit
+    && JSON.stringify(item.icon) === JSON.stringify(entry.manifest.icon));
+  return preview ? { light: preview.light, dark: preview.dark } : null;
+}

components/settings/tabs/PluginBrandIcon.test.tsx

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { inspectPluginBrandIcon } from '@netcatty/plugin-contract';
+import { PluginBrandIcon } from '../../plugins/PluginBrandIcon';
+import { resolveCatalogBrandIcon } from '../../plugins/catalogBrandIcons';
+import previews from '../../plugins/catalog-brand-icons.json';
+
+const preview = previews[0];
+const entry = { ...preview, manifest: { icon: preview.icon } } as unknown as NetcattyPluginCatalogEntry;
+test('reviewed catalog brand previews bind version, source and declaration, never arbitrary URLs', () => {
+  assert.ok(resolveCatalogBrandIcon(entry));
+  const catalog = JSON.parse(readFileSync(new URL('../../../electron/plugins/catalog.json', import.meta.url), 'utf8')) as NetcattyPluginCatalogEntry[];
+  assert.ok(resolveCatalogBrandIcon(catalog.find((item) => item.id === preview.id)!));
+  for (const replacement of [{ version: '9.0.0' }, { commit: '0'.repeat(40) }, { repository: 'untrusted/plugin' }, { manifest: { icon: { kind: 'package', light: 'https://attacker.invalid/a.png' } } }]) {
+    assert.equal(resolveCatalogBrandIcon({ ...entry, ...replacement } as NetcattyPluginCatalogEntry), null);
+  }
+  for (const theme of ['light', 'dark'] as const) {
+    const bytes = Buffer.from(preview[theme].split(',')[1], 'base64');
+    assert.equal(createHash('sha256').update(bytes).digest('hex'), preview[`${theme}Sha256`]);
+    assert.equal(inspectPluginBrandIcon(bytes, preview.icon[theme]).width, 128);
+    assert.deepEqual(bytes, readFileSync(new URL(`../../../examples/plugins/starter-netcatty/${preview.icon[theme]}`, import.meta.url)));
+  }
+  const html = renderToStaticMarkup(<PluginBrandIcon entry={entry} />);
+  assert.match(html, /data-plugin-brand="package"/);
+  assert.match(html, /dark:hidden/);
+  assert.match(html, /dark:block/);
+  assert.doesNotMatch(html, /src="https?:/);
+  assert.match(renderToStaticMarkup(<PluginBrandIcon />), /data-plugin-brand="fallback"/);
+});
+test('installed brand uses metadata only, rejects stale responses, and falls back after image errors', async () => {
+  const oldWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+  const previousAct = (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT;
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+  const requests: Array<(v: { light: string }) => void> = [];
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: { netcatty: { getPluginBrandIcon: () => new Promise((resolve) => requests.push(resolve)) } } });
+  const plugin = { id: 'com.netcatty.starter', enabled: false, activeVersion: '1.0.0', archiveSha256: 'a', runtime: {}, manifest: { icon: preview.icon } } as NetcattyInstalledPlugin;
+  let renderer: ReactTestRenderer | undefined;
+  try {
+    await act(async () => { renderer = create(<PluginBrandIcon plugin={plugin} />); });
+    assert.equal(requests.length, 1);
+    await act(async () => { renderer!.update(<PluginBrandIcon plugin={{ ...plugin, archiveSha256: 'b' }} />); });
+    await act(async () => requests[0]({ light: preview.light }));
+    assert.equal(renderer!.root.findAllByType('img').length, 0);
+    await act(async () => requests[1]({ light: preview.light }));
+    assert.equal(renderer!.root.findAllByType('img').length, 1);
+    await act(async () => renderer!.root.findByType('img').props.onError());
+    assert.equal(renderer!.root.findAllByType('img').length, 0);
+    await act(async () => { renderer!.update(<PluginBrandIcon />); });
+    assert.equal(renderer!.root.findAllByType('img').length, 0);
+  } finally {
+    await act(async () => renderer?.unmount());
+    if (oldWindow) Object.defineProperty(globalThis, 'window', oldWindow); else Reflect.deleteProperty(globalThis, 'window');
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = previousAct;
+  }
+});
+
+
+test('disabled brand theme names cannot resolve Object prototype members', () => {
+  for (const name of ['constructor', '__proto__', 'toString', 'valueOf', 'hasOwnProperty']) {
+    const plugin = { id: 'com.test.theme', enabled: false, activeVersion: '1.0.0', runtime: {}, manifest: { icon: { kind: 'theme', name } } } as NetcattyInstalledPlugin;
+    const html = renderToStaticMarkup(<PluginBrandIcon plugin={plugin} />);
+    assert.match(html, /lucide-puzzle/);
+    assert.doesNotMatch(html, /<img/);
+  }
+});

components/settings/tabs/PluginInstalledGrid.test.tsx

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+import { I18nProvider } from '../../../application/i18n/I18nProvider';
+import { PluginPackageManager } from './PluginPackageManager';
+import type { usePluginManager } from '../../../application/state/usePluginManager';
+
+test('installed grid filters, opens one detail and restores search, scroll and card focus without pill navigation', async () => {
+  const globals = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previous = globals.IS_REACT_ACT_ENVIRONMENT; globals.IS_REACT_ACT_ENVIRONMENT = true;
+  const raf = globalThis.requestAnimationFrame;
+  const frames: FrameRequestCallback[] = [];
+  globalThis.requestAnimationFrame = (fn) => { frames.push(fn); return frames.length; };
+  const selections: unknown[] = []; const toggles: unknown[] = []; const focus: string[] = [];
+  const pane = { scrollTop: 160 };
+  const plugins = ['Alpha', 'Beta'].map((name) => ({ id: `com.test.${name.toLowerCase()}`, enabled: false, activeVersion: '1.0.0',
+    manifest: { name, publisher: 'Example', description: `${name} safely formats synthetic greetings without accessing hosts or secrets.`, license: 'MIT', main: { browser: 'index.js' }, engines: { api: '0.1.0-internal', netcatty: '*' } },
+    runtime: { lastError: name === 'Beta' ? 'Incompatible version' : null },
+  })) as NetcattyInstalledPlugin[];
+  const manager = { available: true, plugins, busy: false, setEnabled: async (...args: unknown[]) => { toggles.push(args); } } as unknown as ReturnType<typeof usePluginManager>;
+  let renderer!: ReactTestRenderer;
+  try {
+    await act(async () => { renderer = create(<I18nProvider locale="en"><PluginPackageManager manager={manager} onSelectionChange={(id) => selections.push(id)} /></I18nProvider>, {
+      createNodeMock: (element) => element.type === 'section' ? {
+        closest: () => pane,
+        querySelector: () => ({ focus: () => focus.push('detail') }),
+        querySelectorAll: () => plugins.map((plugin) => ({ dataset: { pluginCard: plugin.id }, focus: () => focus.push(plugin.id) })),
+      } : null,
+    }); });
+    const cards = () => renderer.root.findAllByType('button').filter((node) => node.props['data-plugin-card']);
+    assert.equal(cards().length, 2);
+    const alphaCard = renderer.root.findAllByType('article')[0];
+    assert.match(JSON.stringify(renderer.toJSON()), /Alpha safely formats synthetic greetings/);
+    assert.ok(alphaCard.findAllByType('p').some((node) => node.children.includes('Example')), 'author has its own line');
+    assert.ok(alphaCard.findAllByType('p').some((node) => node.props.className?.includes('line-clamp-3')), 'card description is bounded');
+    assert.match(JSON.stringify(renderer.toJSON()), /MIT/);
+    assert.match(JSON.stringify(renderer.toJSON()), /Incompatible version/);
+    assert.ok(renderer.root.findAllByType('div').some((node) => node.props.className?.includes('repeat(auto-fill')));
+    const pill = renderer.root.findAllByType('button').find((node) => node.props['aria-pressed'] !== undefined)!;
+    await act(async () => pill.props.onClick());
+    assert.deepEqual(toggles, [[plugins[0].id, true]]); assert.deepEqual(selections, []);
+    await act(async () => renderer.root.findByType('input').props.onChange({ target: { value: 'Alpha' } }));
+    assert.equal(cards().length, 1);
+    await act(async () => cards()[0].props.onClick()); frames.splice(0).forEach((fn) => fn(0));
+    assert.deepEqual(selections, [plugins[0].id]); assert.equal(pane.scrollTop, 0); assert.equal(focus.at(-1), 'detail');
+    assert.equal(renderer.root.findAllByType('input').length, 0);
+    assert.match(JSON.stringify(renderer.toJSON()), /Declared permissions/);
+    assert.ok(renderer.root.findByType('article').findAllByType('p').some((node) => node.props.className?.includes('whitespace-pre-wrap')), 'detail shows the complete description');
+    const back = renderer.root.findAllByType('button').find((node) => node.children.includes('Installed plugins'))!;
+    await act(async () => back.props.onClick()); frames.splice(0).forEach((fn) => fn(0));
+    assert.equal(renderer.root.findByType('input').props.value, 'Alpha'); assert.equal(cards().length, 1);
+    assert.equal(pane.scrollTop, 160); assert.equal(focus.at(-1), plugins[0].id);
+    await act(async () => renderer.root.findByType('input').props.onChange({ target: { value: 'none' } }));
+    assert.equal(cards().length, 0);
+    await act(async () => renderer.unmount());
+  } finally { globals.IS_REACT_ACT_ENVIRONMENT = previous; globalThis.requestAnimationFrame = raf; }
+});

components/settings/tabs/PluginManagementDialog.interaction.test.tsx

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { JSDOM } from 'jsdom';
+
+// Exercise the real Radix portal/focus lifecycle, rather than a mocked Dialog.
+test('plugin manager is single-instance, closes with Escape, restores focus and remounts on reopen', async () => {
+  const dom = new JSDOM('<!doctype html><html><body><div id="root"></div></body></html>', { pretendToBeVisual: true, url: 'http://localhost' });
+  const previous = new Map<string, PropertyDescriptor | undefined>();
+  const install = (key: string, value: unknown) => {
+    previous.set(key, Object.getOwnPropertyDescriptor(globalThis, key));
+    Object.defineProperty(globalThis, key, { configurable: true, writable: true, value });
+  };
+  for (const key of ['window', 'document', 'navigator', 'HTMLElement', 'HTMLInputElement', 'Element', 'Node', 'NodeFilter', 'MutationObserver', 'CustomEvent', 'Event', 'KeyboardEvent', 'MouseEvent']) {
+    install(key, key === 'window' ? dom.window : dom.window[key as keyof typeof dom.window]);
+  }
+  install('getComputedStyle', dom.window.getComputedStyle.bind(dom.window));
+  install('requestAnimationFrame', dom.window.requestAnimationFrame.bind(dom.window));
+  install('cancelAnimationFrame', dom.window.cancelAnimationFrame.bind(dom.window));
+  install('IS_REACT_ACT_ENVIRONMENT', true);
+  const { default: React, act, useEffect } = await import('react');
+  const { createRoot } = await import('react-dom/client');
+  const { I18nProvider } = await import('../../../application/i18n/I18nProvider');
+  const { PluginManagementDialog } = await import('./PluginManagementDialog');
+  const root = createRoot(document.getElementById('root')!);
+  let mounts = 0;
+  let unmounts = 0;
+  function Content() {
+    useEffect(() => { mounts++; return () => { unmounts++; }; }, []);
+    return <input aria-label="Plugin search" defaultValue="" />;
+  }
+  const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
+  const click = async (element: HTMLElement) => { await act(async () => { element.click(); await settle(); }); };
+  try {
+    await act(async () => { root.render(<I18nProvider locale="en"><PluginManagementDialog><Content /></PluginManagementDialog></I18nProvider>); });
+    const trigger = document.querySelector<HTMLButtonElement>('button')!;
+    assert.equal(document.querySelector('[role="dialog"]'), null);
+    assert.equal(mounts, 0, 'closed settings entry does not mount manager subscriptions');
+    trigger.focus();
+    await click(trigger);
+    assert.equal(document.querySelectorAll('[role="dialog"]').length, 1);
+    assert.equal(mounts, 1);
+    assert.equal(document.activeElement?.getAttribute('aria-label'), 'Plugin search');
+    assert.equal(document.querySelector('[role="dialog"]')?.contains(document.querySelector('[data-settings-scroll-pane]')), true);
+    await act(async () => { root.render(<I18nProvider locale="en"><PluginManagementDialog><Content /></PluginManagementDialog></I18nProvider>); });
+    assert.equal(document.querySelectorAll('[role="dialog"]').length, 1);
+    assert.equal(mounts, 1, 'rerender does not spawn another manager');
+    const closeButton = document.querySelector<HTMLButtonElement>('[role="dialog"] button[data-dialog-close]:not([aria-hidden])')!;
+    await act(async () => {
+      closeButton.focus();
+      closeButton.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true, cancelable: true }));
+    });
+    assert.equal(document.activeElement?.getAttribute('aria-label'), 'Plugin search', 'Tab wraps inside the modal');
+    await act(async () => { document.activeElement!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); await settle(); });
+    assert.equal(document.querySelector('[role="dialog"]'), null);
+    assert.equal(document.activeElement, trigger);
+    assert.equal(unmounts, 1);
+    await click(trigger);
+    assert.equal(mounts, 2);
+    await click(document.querySelector<HTMLButtonElement>('[role="dialog"] button[data-dialog-close]:not([aria-hidden])')!);
+    assert.equal(document.querySelector('[role="dialog"]'), null);
+    assert.equal(document.activeElement, trigger);
+    assert.equal(unmounts, 2);
+    let handedOff = false;
+    await act(async () => root.render(<I18nProvider locale="en"><PluginManagementDialog>{(handoff) => <button onClick={() => handoff(() => {
+      handedOff = true;
+      assert.equal(document.querySelector('[role="dialog"]'), null);
+      assert.notEqual(document.body.style.pointerEvents, 'none');
+    })}>Open contributed settings view</button>}</PluginManagementDialog></I18nProvider>));
+    await click(trigger);
+    await click(document.querySelector<HTMLButtonElement>('[role="dialog"] button:not([data-dialog-close])')!);
+    assert.equal(handedOff, true, 'external view opens only after modal ownership is released');
+  } finally {
+    await act(async () => root.unmount());
+    dom.window.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+});

components/settings/tabs/PluginManagementDialog.tsx

@@ -0,0 +1,38 @@
+import React, { useRef, useState } from 'react';
+import { useI18n } from '../../../application/i18n/I18nProvider';
+import { Button } from '../../ui/button';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '../../ui/dialog';
+
+/** Uses the existing renderer and host bridge; opening the manager never starts a plugin. */
+export function PluginManagementDialog({ children }: {
+  children: React.ReactNode | ((handoff: (action: () => void) => void) => React.ReactNode);
+}) {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(false);
+  const pendingHandoff = useRef<(() => void) | null>(null);
+  const handoff = (action: () => void) => { pendingHandoff.current = action; setOpen(false); };
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger asChild>
+        <Button variant="outline">{t('settings.plugins.openManager')}</Button>
+      </DialogTrigger>
+      <DialogContent onCloseAutoFocus={(event) => {
+        const action = pendingHandoff.current;
+        pendingHandoff.current = null;
+        if (action) {
+          event.preventDefault();
+          // Wait for Radix to release modal pointer/focus ownership before opening
+          // the existing external plugin view host (including exit animations).
+          queueMicrotask(action);
+        }
+      }} className="flex h-[min(88dvh,900px)] w-[calc(100vw-2rem)] max-w-[1180px] flex-col gap-0 overflow-hidden p-0">
+        <DialogHeader className="shrink-0 border-b px-6 py-4 pr-12 text-left">
+          <DialogTitle>{t('settings.plugins.title')}</DialogTitle>
+        </DialogHeader>
+        <div data-settings-scroll-pane className="min-h-0 flex-1 overflow-y-auto overscroll-contain p-4 sm:p-6">
+          {typeof children === 'function' ? children(handoff) : children}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

components/settings/tabs/PluginMarketplace.interaction.test.tsx

@@ -0,0 +1,146 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React, { useState } from 'react';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { readFileSync } from 'node:fs';
+import { I18nProvider } from '../../../application/i18n/I18nProvider';
+import { PluginMarketplaceContent } from './PluginMarketplace';
+import type { usePluginCatalog } from '../../../application/state/usePluginCatalog';
+
+const entries = ['Alpha', 'Beta'].map((name) => ({
+  id: `com.example.${name.toLowerCase()}`, name, author: 'Example', version: '1.0.0', license: 'MIT',
+  description: `${name} local utility`, repository: 'example/plugins', commit: 'a'.repeat(40),
+  manifest: { manifestVersion: 1, id: `com.example.${name.toLowerCase()}`, name, version: '1.0.0', publisher: 'Example', engines: { netcatty: '>=1.0.0', api: '0.1.0-internal' }, main: { browser: 'index.js' }, permissions: { required: ['settings.read'] } },
+})) as NetcattyPluginCatalogEntry[];
+const catalog = {
+  entries, source: 'registry', listStatus: 'ready', listError: null, readme: '# Author documentation', readmeStatus: 'ready', readmeError: null,
+  error: null, busy: false, retryList() {}, retryReadme() {}, async install() {},
+} as ReturnType<typeof usePluginCatalog>;
+
+test('catalog keeps search during selection/back, switches detail, and displays real installed state', async () => {
+  const previousRaf = globalThis.requestAnimationFrame;
+  globalThis.requestAnimationFrame = (callback) => { callback(0); return 0; };
+  const actGlobal = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previousActEnvironment = actGlobal.IS_REACT_ACT_ENVIRONMENT;
+  actGlobal.IS_REACT_ACT_ENVIRONMENT = true;
+  let renderer: ReactTestRenderer;
+  function Harness() {
+    const [selected, setSelected] = useState<string | null>(null);
+    return <I18nProvider locale="en"><PluginMarketplaceContent catalog={catalog} selected={selected} onSelect={setSelected}
+      installed={[{ id: entries[0].id, activeVersion: '0.9.0', enabled: false, runtime: { lastError: 'Incompatible with this host' } } as NetcattyInstalledPlugin]} /></I18nProvider>;
+  }
+  try {
+    await act(async () => { renderer = create(<Harness />); });
+    const cards = () => renderer.root.findAll((node) => node.type === 'button' && Boolean(node.props['data-plugin-id']));
+    const input = () => renderer.root.findByType('input');
+    assert.equal(cards().length, 2);
+    await act(async () => input().props.onChange({ target: { value: 'Alpha' } }));
+    assert.equal(cards().length, 1);
+    await act(async () => cards()[0].props.onClick());
+    assert.equal(renderer.root.findByType('article').props['aria-label'], 'Alpha');
+    assert.equal(cards()[0].props['aria-current'], 'true');
+    const detailText = JSON.stringify(renderer.toJSON());
+    assert.match(detailText, /0.9.0/);
+    assert.match(detailText, /Disabled/);
+    assert.match(detailText, /Incompatible with this host/);
+    assert.match(detailText, /Last recorded error/);
+    assert.match(cards()[0].props.className, /bg-primary\/10/);
+    assert.match(cards()[0].props.className, /border-primary\/40/);
+    assert.doesNotMatch(cards()[0].props.className, /bg-accent|text-accent-foreground/);
+    assert.match(detailText, /1 plugins/);
+    assert.equal(renderer.root.findAllByType('details').length, 0, 'permissions are not hidden in a disclosure');
+    assert.equal(renderer.root.findAll((node) => node.type === 'button' && node.children.includes('Install this version (disabled)')).length, 0, 'source-only cards have no install action');
+    const back = () => renderer.root.findAllByType('button').find((node) => node.children.includes('All plugins'))!;
+    await act(async () => back().props.onClick());
+    assert.equal(renderer.root.findAllByType('article').length, 0);
+    assert.equal(input().props.value, 'Alpha');
+    await act(async () => input().props.onChange({ target: { value: '' } }));
+    await act(async () => cards()[0].props.onClick());
+    await act(async () => cards()[1].props.onClick());
+    assert.equal(renderer.root.findByType('article').props['aria-label'], 'Beta');
+    assert.equal(cards()[1].props['aria-current'], 'true');
+    assert.equal(cards()[0].props['aria-current'], undefined);
+    await act(async () => input().props.onChange({ target: { value: 'no match' } }));
+    assert.equal(cards().length, 0);
+    assert.equal(renderer.root.findByType('article').props['aria-label'], 'Beta', 'filtering does not erase the selected detail');
+    await act(async () => back().props.onClick());
+    assert.equal(input().props.value, 'no match');
+    await act(async () => renderer.unmount());
+  } finally {
+    globalThis.requestAnimationFrame = previousRaf;
+    actGlobal.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+  }
+});
+
+
+test('README failure leaves the permissions and source visible, before the failure message', () => {
+  const html = renderToStaticMarkup(<I18nProvider locale="en"><PluginMarketplaceContent
+    catalog={{ ...catalog, readmeStatus: 'error', readme: null, readmeError: 'Network unavailable' }}
+    selected={entries[0].id} onSelect={() => {}} installed={[]} /></I18nProvider>);
+  assert.match(html, /Compatibility and permissions/);
+  assert.match(html, /settings.read/);
+  assert.match(html, /not a grant/);
+  assert.match(html, /Build with the local CLI/);
+  assert.ok(html.indexOf('settings.read') < html.indexOf('Network unavailable'));
+  assert.match(html, /Retry/);
+  assert.doesNotMatch(html, /<details/);
+});
+
+test('responsive layout is scoped to marketplace content width, with a narrow detail-only fallback', () => {
+  const css = readFileSync(new URL('./plugin-marketplace.css', import.meta.url), 'utf8');
+  assert.match(css, /\.plugin-marketplace \{ container-type: inline-size;/);
+  assert.match(css, /@container \(min-width: 820px\)/);
+  assert.match(css, /grid-template-columns: 248px minmax\(0, 1fr\)/);
+  assert.match(css, /plugin-marketplace-browser--selected \.plugin-marketplace-catalog \{ display: none;/);
+});
+
+test('narrow detail starts at the top and back restores the settings scroll and card focus', async () => {
+  const previousRaf = globalThis.requestAnimationFrame;
+  globalThis.requestAnimationFrame = (callback) => { callback(0); return 0; };
+  const actGlobal = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previousActEnvironment = actGlobal.IS_REACT_ACT_ENVIRONMENT;
+  actGlobal.IS_REACT_ACT_ENVIRONMENT = true;
+  const pane = { scrollTop: 450 };
+  let focused = false;
+  const list = { scrollTop: 0, closest: (selector: string) => selector === '.plugin-marketplace' ? { clientWidth: 700 } : pane,
+    querySelectorAll: () => [{ dataset: { pluginId: entries[0].id }, focus: () => { focused = true; } }] };
+  let renderer!: ReactTestRenderer;
+  function Harness() {
+    const [selected, setSelected] = useState<string | null>(null);
+    return <I18nProvider locale="en"><PluginMarketplaceContent catalog={catalog} selected={selected} onSelect={setSelected} installed={[]} /></I18nProvider>;
+  }
+  try {
+    await act(async () => { renderer = create(<Harness />, { createNodeMock: (element) => element.type === 'div' ? list : { scrollTo() {}, focus() {} } }); });
+    const card = renderer.root.findAll((node) => node.type === 'button' && node.props['data-plugin-id'] === entries[0].id)[0];
+    await act(async () => card.props.onClick());
+    assert.equal(pane.scrollTop, 0);
+    const back = renderer.root.findAllByType('button').find((node) => node.children.includes('All plugins'))!;
+    await act(async () => back.props.onClick());
+    assert.equal(pane.scrollTop, 450);
+    assert.equal(focused, true);
+    await act(async () => renderer.unmount());
+  } finally {
+    globalThis.requestAnimationFrame = previousRaf;
+    actGlobal.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+  }
+});
+
+test('offline catalog warning keeps details visible and disables market installation', () => {
+  const downloadable = { ...entries[0], artifact: { url: 'https://github.com/example/plugin/releases/download/v1/plugin.ncpkg', sha256: 'a'.repeat(64) } };
+  const html = renderToStaticMarkup(<I18nProvider locale="en"><PluginMarketplaceContent
+    catalog={{ ...catalog, entries: [downloadable], listError: 'Registry offline', source: 'cached' }}
+    selected={downloadable.id} onSelect={() => {}} installed={[]} /></I18nProvider>);
+  assert.match(html, /Registry offline/);
+  assert.match(html, /Installation is unavailable until refresh succeeds/);
+  assert.match(html, /Compatibility and permissions/);
+  assert.match(html, /<button[^>]*disabled=""[^>]*>Install this version/);
+  assert.match(html, /Retry/);
+});
+
+test('manual refresh remains available after success and is disabled while loading', () => {
+  const ready = renderToStaticMarkup(<I18nProvider locale="en"><PluginMarketplaceContent catalog={catalog} selected={null} onSelect={() => {}} installed={[]} /></I18nProvider>);
+  assert.match(ready, />Refresh<\/button>/);
+  const loading = renderToStaticMarkup(<I18nProvider locale="en"><PluginMarketplaceContent catalog={{ ...catalog, listStatus: 'loading' }} selected={null} onSelect={() => {}} installed={[]} /></I18nProvider>);
+  assert.match(loading, /<button[^>]*disabled=""[^>]*>Refresh<\/button>/);
+});

components/settings/tabs/PluginMarketplace.test.ts

@@ -0,0 +1,9 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { filterPluginCatalog } from './PluginMarketplace';
+test('catalog search matches name, author and description without case sensitivity', () => {
+  const entries = [{ id: 'a', name: 'Starter', author: 'Netcatty', description: 'Local greeting' }] as NetcattyPluginCatalogEntry[];
+  for (const query of ['starter', 'NETCATTY', ' greeting ']) assert.equal(filterPluginCatalog(entries, query).length, 1);
+  assert.equal(filterPluginCatalog(entries, 'unrelated').length, 0);
+  assert.equal(filterPluginCatalog(entries, '').length, 1);
+});

components/settings/tabs/PluginMarketplace.tsx

@@ -0,0 +1,107 @@
+import React, { useRef, useState } from 'react';
+import { PluginBrandIcon } from '../../plugins/PluginBrandIcon';
+import { ArrowLeft } from 'lucide-react';
+import { useI18n } from '../../../application/i18n/I18nProvider';
+import { usePluginCatalog } from '../../../application/state/usePluginCatalog';
+import { Input } from '../../ui/input';
+import { Button } from '../../ui/button';
+import { SettingCard } from '../settings-ui';
+import { PluginPackageDetails } from './PluginPackageManager';
+import { PluginReadme } from './PluginReadme';
+
+export function PluginMarketplace({ installed = [] }: { installed?: NetcattyInstalledPlugin[] }) {
+  const [selected, setSelected] = useState<string | null>(null);
+  const catalog = usePluginCatalog(selected);
+  return <PluginMarketplaceContent catalog={catalog} installed={installed} selected={selected} onSelect={setSelected} />;
+}
+
+// The browser owns only presentation state; installation and README policy stay in the existing hook.
+export function PluginMarketplaceContent({ catalog, installed, selected, onSelect }: {
+  catalog: ReturnType<typeof usePluginCatalog>;
+  installed: NetcattyInstalledPlugin[];
+  selected: string | null;
+  onSelect: (id: string | null) => void;
+}) {
+  const { t } = useI18n();
+  const [search, setSearch] = useState('');
+  const listRef = useRef<HTMLDivElement>(null);
+  const detailRef = useRef<HTMLElement>(null);
+  const lastSelection = useRef<string | null>(null);
+  const listScroll = useRef(0);
+  const pageScroll = useRef(0);
+  const entry = catalog.entries.find((item) => item.id === selected);
+  const filtered = filterPluginCatalog(catalog.entries, search);
+  const installedEntry = installed.find((item) => item.id === entry?.id);
+  const choose = (id: string) => {
+    listScroll.current = listRef.current?.scrollTop ?? 0;
+    if (!entry) pageScroll.current = listRef.current?.closest('[data-settings-scroll-pane]')?.scrollTop ?? 0;
+    lastSelection.current = id;
+    onSelect(id);
+    requestAnimationFrame(() => {
+      detailRef.current?.scrollTo?.(0, 0);
+      const container = listRef.current?.closest<HTMLElement>('.plugin-marketplace');
+      const pane = listRef.current?.closest('[data-settings-scroll-pane]');
+      if (container && container.clientWidth < 820 && pane) pane.scrollTop = 0;
+      detailRef.current?.focus({ preventScroll: true });
+    });
+  };
+  const back = () => {
+    onSelect(null);
+    requestAnimationFrame(() => {
+      if (listRef.current) {
+        listRef.current.scrollTop = listScroll.current;
+        const pane = listRef.current.closest('[data-settings-scroll-pane]');
+        if (pane) pane.scrollTop = pageScroll.current;
+        const button = Array.from(listRef.current.querySelectorAll<HTMLButtonElement>('[data-plugin-id]'))
+          .find((item) => item.dataset.pluginId === lastSelection.current);
+        button?.focus({ preventScroll: true });
+      }
+    });
+  };
+  return <section className="plugin-marketplace space-y-4" aria-label={t('settings.plugins.market.title')}>
+    <div className="flex items-start justify-between gap-3"><p className="text-xs text-muted-foreground">{t('settings.plugins.market.note')}</p><Button variant="outline" size="sm" disabled={catalog.listStatus === 'loading'} onClick={catalog.retryList}>{t('common.refresh')}</Button></div>
+    {catalog.listStatus === 'ready' && catalog.listError && <div role="status" className="space-y-2 rounded-lg border p-3 text-xs text-muted-foreground"><p>{t('settings.plugins.market.offline')}</p><p>{catalog.listError}</p><Button variant="outline" size="sm" onClick={catalog.retryList}>{t('settings.plugins.market.retry')}</Button></div>}
+    {catalog.error && <p role="alert" className="text-xs text-destructive">{catalog.error}</p>}
+    <div className={`plugin-marketplace-browser${entry ? ' plugin-marketplace-browser--selected' : ''}`}>
+      <div className="plugin-marketplace-catalog space-y-3" ref={listRef}>
+        <Input value={search} onChange={(event) => setSearch(event.target.value)} placeholder={t('settings.plugins.market.search')} aria-label={t('settings.plugins.market.search')} />
+        {catalog.listStatus === 'ready' && <p className="text-xs text-muted-foreground" aria-live="polite">{t('settings.plugins.market.results', { count: filtered.length })}</p>}
+        {catalog.listStatus === 'ready' && catalog.entries.length > 0 && filtered.length === 0 && <p className="rounded-lg border border-dashed p-6 text-center text-sm text-muted-foreground">{t('settings.plugins.market.noResults')}</p>}
+        {catalog.listStatus === 'loading' && <p className="text-xs text-muted-foreground">{t('settings.plugins.loading')}</p>}
+        {catalog.listStatus === 'error' && <div role="alert" className="space-y-2 text-xs text-destructive"><p>{catalog.listError}</p><Button variant="outline" size="sm" onClick={catalog.retryList}>{t('settings.plugins.market.retry')}</Button></div>}
+        {catalog.listStatus === 'ready' && catalog.entries.length === 0 && <p className="text-xs text-muted-foreground">{t('settings.plugins.market.empty')}</p>}
+        <div className="plugin-marketplace-grid">{filtered.map((item) => {
+          const isInstalled = installed.some((plugin) => plugin.id === item.id);
+          return <button key={item.id} type="button" data-plugin-id={item.id} aria-current={selected === item.id ? 'true' : undefined} onClick={() => choose(item.id)}
+            className={`min-w-0 flex flex-col gap-3 rounded-lg border p-4 text-left ${entry ? '' : 'min-h-[200px]'} transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${selected === item.id ? 'border-primary/40 bg-primary/10 text-foreground' : 'border-border bg-card hover:bg-muted/50'}`}>
+            <div className="flex items-start gap-2"><PluginBrandIcon entry={item} size={32} className="mt-0.5 shrink-0 text-muted-foreground" /><span className="min-w-0 break-words text-sm font-semibold">{item.name}</span></div>
+            <p className="break-words text-xs text-muted-foreground">{item.author}</p>
+            <p className="line-clamp-3 break-words text-sm leading-5 text-muted-foreground">{item.description}</p>
+            <div className="mt-auto flex flex-wrap items-center justify-between gap-2 pt-1 text-xs text-muted-foreground"><span>{item.version} · {item.license}</span><span className="text-foreground">{t('settings.plugins.manager.details')}</span></div>
+            <div className="flex flex-wrap gap-2 text-xs text-muted-foreground">{isInstalled && <span className="rounded bg-muted px-2 py-0.5 text-foreground">{t('settings.plugins.market.installed')}</span>}{!item.artifact && <span className="rounded border px-2 py-0.5">{t('settings.plugins.market.sourceBadge')}</span>}</div>
+          </button>;
+        })}</div>
+      </div>
+      {entry && <article key={entry.id} ref={detailRef} tabIndex={-1} aria-label={entry.name} className="plugin-marketplace-detail min-w-0 space-y-5 rounded-lg border bg-card p-4 focus:outline-none">
+        <Button variant="ghost" size="sm" onClick={back}><ArrowLeft size={14} className="mr-2" />{t('settings.plugins.market.back')}</Button>
+        <div className="space-y-2"><div className="flex items-center gap-3"><PluginBrandIcon entry={entry} size={48} /><h4 className="break-words text-xl font-semibold">{entry.name}</h4></div><p className="text-xs text-muted-foreground">{entry.author} · {entry.version} · {entry.license}</p>
+          {installedEntry && <p className="text-xs text-muted-foreground">{t('settings.plugins.market.installed')} · {installedEntry.activeVersion} · {t(installedEntry.enabled ? 'settings.plugins.manager.enabled' : 'settings.plugins.manager.disabled')}</p>}
+        </div>
+        {installedEntry?.runtime?.lastError && <p role="status" className="break-words text-xs text-destructive">{t('settings.plugins.manager.lastError')}: {installedEntry.runtime.lastError}</p>}
+        <p className="text-sm leading-6 text-muted-foreground">{entry.description}</p>
+        <a className="block break-all text-xs text-primary underline underline-offset-4" href={`https://github.com/${entry.repository}/tree/${entry.commit}`} target="_blank" rel="noopener noreferrer">{entry.repository} @ {entry.commit.slice(0, 12)}</a>
+        {entry.artifact ? <div className="space-y-2"><p className="text-xs text-muted-foreground">{t('settings.plugins.market.installNote')}</p><Button size="sm" disabled={catalog.busy || Boolean(catalog.listError)} onClick={() => void catalog.install(entry.id)}>{t('settings.plugins.market.install')}</Button></div> : <p className="rounded-lg bg-muted/40 p-3 text-xs leading-5">{t('settings.plugins.market.sourceOnly')}</p>}
+        <SettingCard padded><h4 className="mb-3 text-sm font-semibold">{t('settings.plugins.market.manifest')}</h4><PluginPackageDetails plugin={{ id: entry.id, activeVersion: entry.version, enabled: false, manifest: entry.manifest, archiveSha256: entry.artifact?.sha256, runtime: { status: 'stopped', kind: null, lastError: null, quarantinedAt: null } }} /></SettingCard>
+        <div className="min-w-0 border-t pt-4"><h4 className="text-sm font-semibold">README</h4><p className="mt-2 text-xs text-muted-foreground">{t('settings.plugins.market.readmeNote')}</p>{catalog.readmeStatus === 'loading' && <p className="mt-3 text-xs text-muted-foreground">{t('settings.plugins.loading')}</p>}
+          {catalog.readmeStatus === 'error' && <div role="alert" className="mt-3 space-y-2 text-xs text-destructive"><p>{catalog.readmeError}</p><Button variant="outline" size="sm" onClick={catalog.retryReadme}>{t('settings.plugins.market.retry')}</Button></div>}
+          {catalog.readmeStatus === 'ready' && (catalog.readme?.trim() ? <PluginReadme markdown={catalog.readme} /> : <p className="mt-3 text-xs text-muted-foreground">{t('settings.plugins.market.emptyReadme')}</p>)}
+        </div>
+      </article>}
+    </div>
+  </section>;
+}
+
+export function filterPluginCatalog(entries: NetcattyPluginCatalogEntry[], query: string) {
+  const needle = query.trim().toLocaleLowerCase();
+  return entries.filter((entry) => `${entry.name} ${entry.author} ${entry.description}`.toLocaleLowerCase().includes(needle));
+}

components/settings/tabs/PluginPackageManager.test.tsx

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { I18nProvider } from '../../../application/i18n/I18nProvider';
+import { PluginPackageDetails } from './PluginPackageManager';
+
+test('package detail renders manifest resources as text and explains advanced authority', () => {
+  const plugin = {
+    id: 'com.example.synthetic', enabled: false, activeVersion: '1.0.0',
+    archiveSha256: 'a'.repeat(64),
+    manifest: {
+      manifestVersion: 1, id: 'com.example.synthetic', name: 'synthetic', version: '1.0.0', publisher: 'example',
+      engines: { netcatty: '>=1.0.0 <2.0.0', api: '0.1.0-internal' },
+      main: { node: 'index.js' },
+      permissions: { required: [{ permission: 'network', resources: ['https://example.com'], reason: '<script>attack()</script>' }] },
+    },
+    runtime: { status: 'stopped', kind: null, lastError: null, quarantinedAt: null },
+  } as NetcattyInstalledPlugin;
+  const html = renderToStaticMarkup(<I18nProvider locale="en"><PluginPackageDetails plugin={plugin} /></I18nProvider>);
+  assert.match(html, /full Node filesystem and network authority/);
+  assert.match(html, /https:\/\/example.com/);
+  assert.match(html, /&lt;script&gt;/);
+  assert.doesNotMatch(html, /<script>/);
+  assert.match(html, /not a grant/);
+  assert.match(html, /aaaaaaaaaaaaaaaa/);
+});

components/settings/tabs/PluginPackageManager.tsx

@@ -0,0 +1,122 @@
+import { describePluginPermission } from '@/domain/pluginPermissionDescriptions.cjs';
+import { describePluginRuntime } from '@/domain/pluginRuntimePolicy.cjs';
+import React, { useRef, useState } from 'react';
+import { PluginPermissionPanel } from './PluginPermissionPanel';
+import { PluginBrandIcon } from '../../plugins/PluginBrandIcon';
+import { ArrowLeft } from 'lucide-react';
+import { usePluginManager } from '../../../application/state/usePluginManager';
+import { useI18n } from '../../../application/i18n/I18nProvider';
+import { Button } from '../../ui/button';
+import { Input } from '../../ui/input';
+
+export function PluginPackageDetails({ plugin }: { plugin: NetcattyInstalledPlugin }) {
+  const { t, resolvedLocale } = useI18n();
+  const manifest = plugin.manifest;
+  if (!manifest) return null;
+  const permissions = [
+    ...(manifest.permissions?.required ?? []).map((value) => ({ value, required: true })),
+    ...(manifest.permissions?.optional ?? []).map((value) => ({ value, required: false })),
+  ];
+  const policy = describePluginRuntime(manifest);
+  const runtimeKind = plugin.runtime.kind ?? policy.defaultRuntimeKind;
+  const runtimeLabel = runtimeKind === 'utility' ? 'advanced'
+    : policy.hasNode ? 'dual' : policy.declaresAdvanced ? 'advancedDeclaration' : 'browser';
+  return <div className="space-y-4 border-t border-border/60 pt-4 text-sm">
+    <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-xs">
+      <dt className="text-muted-foreground">ID</dt><dd className="break-all font-mono">{plugin.id}</dd>
+      <dt className="text-muted-foreground">Netcatty</dt><dd>{manifest.engines.netcatty}</dd>
+      <dt className="text-muted-foreground">API</dt><dd>{manifest.engines.api}</dd>
+      <dt className="text-muted-foreground">SHA-256</dt><dd className="break-all font-mono">{plugin.archiveSha256 ?? '-'}</dd>
+    </dl>
+    <p className={!policy.browserOnly ? 'text-destructive' : 'text-muted-foreground'}>{t(`settings.plugins.manager.${runtimeLabel}`)}</p>
+    <div className="space-y-2">
+      <h4 className="font-medium">{t('settings.plugins.manager.permissions')}</h4>
+      <p className="text-xs text-muted-foreground">{t('settings.plugins.manager.permissionNote')}</p>
+      {permissions.length === 0 && <p className="text-xs text-muted-foreground">{t('settings.plugins.manager.noPermissions')}</p>}
+      {permissions.map(({ value, required }, index) => {
+        const id = typeof value === 'string' ? value : value.permission;
+        const description = describePluginPermission(id, resolvedLocale);
+        return <div key={index} className="rounded-md bg-muted/40 p-3">
+        <div className="flex justify-between gap-3"><span className="text-sm font-medium">{description.label}</span><span className="text-xs text-muted-foreground">{t(required ? 'settings.plugins.manager.required' : 'settings.plugins.manager.optional')}</span></div>
+        <p className="mt-1 text-xs text-muted-foreground">{description.description}</p>
+        <code className="mt-1 block break-all text-[10px] text-muted-foreground">{id}</code>
+        {description.sensitive && <p className="mt-1 text-xs font-medium text-destructive">{t('settings.plugins.manager.sensitive')}</p>}
+        {(typeof value === 'string' || value.resources.length === 0) && <p className="mt-1 text-xs">{t('settings.plugins.manager.unbounded')}</p>}
+        {typeof value !== 'string' && <><p className="mt-1 whitespace-pre-wrap break-all text-xs">{value.resources.join('\n')}</p>{value.reason && <p className="mt-1 text-xs text-muted-foreground">{value.reason}</p>}</>}
+      </div>; })}
+    </div>
+    <p className="text-xs text-muted-foreground">{t('settings.plugins.manager.data')}</p>
+  </div>;
+}
+
+export function PluginPackageManager({ manager, onSelectionChange }: { manager: ReturnType<typeof usePluginManager>; onSelectionChange?: (id: string | null) => void }) {
+  const { t, resolvedLocale } = useI18n();
+  const [selected, setSelected] = useState<string | null>(null);
+  const [search, setSearch] = useState('');
+  const rootRef = useRef<HTMLElement>(null);
+  const scrollTop = useRef(0);
+  const lastSelection = useRef<string | null>(null);
+  const selectedPlugin = manager.plugins.find((plugin) => plugin.id === selected);
+  const nameOf = (plugin: NetcattyInstalledPlugin) => typeof plugin.manifest?.displayName === 'string' ? plugin.manifest.displayName : plugin.manifest?.displayName?.[resolvedLocale] ?? plugin.manifest?.displayName?.en ?? plugin.manifest?.name ?? plugin.id;
+  const descriptionOf = (plugin: NetcattyInstalledPlugin) => {
+    const value = plugin.manifest?.description;
+    return typeof value === 'string' ? value : value?.[resolvedLocale] ?? value?.en ?? '';
+  };
+  const choose = (id: string | null) => {
+    const pane = rootRef.current?.closest<HTMLElement>('[data-settings-scroll-pane]');
+    if (id) { scrollTop.current = pane?.scrollTop ?? 0; lastSelection.current = id; }
+    setSelected(id); setRemoving(null); onSelectionChange?.(id);
+    requestAnimationFrame(() => {
+      if (pane) pane.scrollTop = id ? 0 : scrollTop.current;
+      if (id) rootRef.current?.querySelector<HTMLElement>('[data-plugin-detail]')?.focus({ preventScroll: true });
+      else Array.from(rootRef.current?.querySelectorAll<HTMLButtonElement>('[data-plugin-card]') ?? []).find((button) => button.dataset.pluginCard === lastSelection.current)?.focus({ preventScroll: true });
+    });
+  };
+  const visible = selectedPlugin ? [selectedPlugin] : manager.plugins.filter((plugin) => [nameOf(plugin), plugin.manifest?.publisher, plugin.manifest?.description, plugin.id].some((value) => JSON.stringify(value ?? '').toLocaleLowerCase().includes(search.trim().toLocaleLowerCase())));
+  const [removing, setRemoving] = useState<string | null>(null);
+  if (!manager.available) return null;
+  return <section ref={rootRef} className="space-y-4" aria-label={t('settings.plugins.manager.installed')}>
+    <p className="text-xs text-muted-foreground">{t('settings.plugins.manager.preview')}</p>
+    {selectedPlugin && <Button variant="ghost" size="sm" onClick={() => choose(null)}><ArrowLeft size={14} className="mr-2" />{t('settings.plugins.manager.installed')}</Button>}
+    {!selectedPlugin && manager.plugins.length > 0 && <Input value={search} onChange={(event) => setSearch(event.target.value)} placeholder={t('settings.plugins.market.search')} aria-label={t('settings.plugins.market.search')} />}
+    {!selectedPlugin && manager.plugins.length > 0 && visible.length === 0 && <p className="p-6 text-center text-sm text-muted-foreground">{t('settings.plugins.market.noResults')}</p>}
+    {manager.error && <p role="alert" className="text-sm text-destructive">{manager.error}</p>}
+    {!manager.plugins.length && <div className="rounded-xl border border-dashed border-border p-8 text-center text-sm text-muted-foreground">{t('settings.plugins.manager.empty')}</div>}
+    <div className={selectedPlugin ? 'space-y-4' : 'grid grid-cols-[repeat(auto-fill,minmax(min(100%,280px),1fr))] gap-3'}>
+    {visible.map((plugin) => <article key={plugin.id} data-plugin-detail={selectedPlugin ? true : undefined} tabIndex={selectedPlugin ? -1 : undefined} aria-label={nameOf(plugin)} className={`min-w-0 rounded-lg border bg-card p-4 focus:outline-none ${selectedPlugin ? 'space-y-4' : 'flex min-h-[200px] flex-col gap-3'}`}>
+      <div className="flex flex-wrap items-center gap-3">
+        <div className="flex h-12 w-12 shrink-0 items-center justify-center"><PluginBrandIcon plugin={plugin} size={32} /></div>
+        <button type="button" data-plugin-card={plugin.id} className="min-w-0 flex-1 rounded text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" aria-expanded={selected === plugin.id} onClick={() => choose(selected === plugin.id ? null : plugin.id)}>
+          <div className="break-words text-sm font-medium">{nameOf(plugin)}</div>
+
+        </button>
+        <Button variant="ghost" size="sm" type="button"
+          className={`h-7 shrink-0 rounded-full border-0 px-3 text-xs focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background ${plugin.enabled ? 'bg-primary/10 hover:bg-primary/15' : 'bg-muted/60 text-muted-foreground hover:bg-muted hover:text-foreground'}`}
+          style={plugin.enabled ? { color: 'color-mix(in srgb, hsl(var(--primary)) 40%, hsl(var(--foreground)))' } : undefined}
+          aria-pressed={plugin.enabled} aria-busy={manager.busy}
+          aria-label={`${t(plugin.enabled ? 'settings.plugins.manager.disable' : 'settings.plugins.manager.enable')} ${plugin.manifest?.name ?? plugin.id}`}
+          title={t(plugin.enabled ? 'settings.plugins.manager.disable' : 'settings.plugins.manager.enable')}
+          disabled={manager.busy} onClick={() => void manager.setEnabled(plugin.id, !plugin.enabled)}>
+          {t(plugin.enabled ? 'settings.plugins.manager.enabled' : 'settings.plugins.manager.disabled')}
+        </Button>
+      </div>
+      {plugin.manifest?.publisher && <p className="break-words text-xs text-muted-foreground">{plugin.manifest.publisher}</p>}
+      <p className={`break-words text-sm leading-5 text-muted-foreground ${selectedPlugin ? 'whitespace-pre-wrap' : 'line-clamp-3'}`}>{descriptionOf(plugin) || t('settings.plugins.manager.noDescription')}</p>
+      {!selectedPlugin ? <div className="mt-auto flex flex-wrap items-center justify-between gap-2 pt-1">
+        <p className="break-words text-xs text-muted-foreground">{plugin.activeVersion}{plugin.manifest?.license ? ` · ${plugin.manifest.license}` : ''}</p>
+        <Button variant="ghost" size="sm" className="h-7 px-2 text-xs" onClick={() => choose(plugin.id)} aria-label={`${t('settings.plugins.manager.details')} ${nameOf(plugin)}`}>{t('settings.plugins.manager.details')}</Button>
+      </div> : <p className="text-xs text-muted-foreground">{plugin.activeVersion}{plugin.manifest?.license ? ` · ${plugin.manifest.license}` : ''}</p>}
+      {plugin.runtime.lastError && <p role="status" className="break-words text-xs text-destructive">{t('settings.plugins.manager.lastError')}: {plugin.runtime.lastError}</p>}
+      {selected === plugin.id && <>
+        <PluginPackageDetails plugin={plugin} />
+        <PluginPermissionPanel key={plugin.id} pluginId={plugin.id} onChanged={async () => { await manager.refresh(); }} />
+        {removing === plugin.id ? <div className="space-y-2 rounded-lg border border-destructive/30 p-3">
+          <p className="text-xs">{t('settings.plugins.manager.removeNote')}</p>
+          <Button variant="destructive" size="sm" disabled={manager.busy} onClick={() => { void manager.uninstall(plugin.id); setRemoving(null); }}>{t('settings.plugins.manager.remove')}</Button>
+          <Button variant="ghost" size="sm" onClick={() => setRemoving(null)}>{t('common.cancel')}</Button>
+        </div> : <Button variant="ghost" size="sm" disabled={manager.busy} onClick={() => setRemoving(plugin.id)}>{t('settings.plugins.manager.remove')}</Button>}
+      </>}
+    </article>)}
+    </div>
+  </section>;
+}

components/settings/tabs/PluginPermissionPanel.test.tsx

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { JSDOM } from 'jsdom';
+
+test('permission panel refreshes real grants, revokes once, and keeps stale reads from replacing new results', async () => {
+  const dom = new JSDOM('<!doctype html><html><body><div id="root"></div></body></html>', { pretendToBeVisual: true, url: 'http://localhost' });
+  const previous = new Map<string, PropertyDescriptor | undefined>();
+  const install = (key: string, value: unknown) => {
+    previous.set(key, Object.getOwnPropertyDescriptor(globalThis, key));
+    Object.defineProperty(globalThis, key, { configurable: true, writable: true, value });
+  };
+  for (const key of ['window', 'document', 'navigator', 'HTMLElement', 'Element', 'Node', 'Event', 'MouseEvent']) {
+    install(key, key === 'window' ? dom.window : dom.window[key as keyof typeof dom.window]);
+  }
+  install('IS_REACT_ACT_ENVIRONMENT', true);
+  const { default: React, act } = await import('react');
+  const { createRoot } = await import('react-dom/client');
+  const { I18nProvider } = await import('../../../application/i18n/I18nProvider');
+  const { PluginPermissionPanel } = await import('./PluginPermissionPanel');
+  const root = createRoot(document.getElementById('root')!);
+  const initial = {
+    grants: [{ permission: 'network', resource: 'https://synthetic.invalid/<text>', resourceKind: 'exact', scope: 'always' as const, sessionId: null, grantedAt: 1 }],
+    audit: [{ event: 'permission.used', createdAt: 2, permission: 'network' }],
+  };
+  let reads = 0;
+  let revokes = 0;
+  let changed = 0;
+  let staleRead: (value: typeof initial) => void = () => {};
+  let releaseRevoke: () => void = () => {};
+  const revokePending = new Promise<void>((resolve) => { releaseRevoke = resolve; });
+  Object.assign(dom.window, { netcatty: {
+    async getPluginPermissions(id: string) {
+      assert.equal(id, 'com.example.synthetic');
+      reads++;
+      if (reads === 2) return new Promise<typeof initial>((resolve) => { staleRead = resolve; });
+      return reads > 2 ? { grants: [], audit: [] } : initial;
+    },
+    async revokePluginPermissions(id: string) { assert.equal(id, 'com.example.synthetic'); revokes++; await revokePending; },
+  } });
+  const button = (text: string) => Array.from(document.querySelectorAll<HTMLButtonElement>('button')).find((item) => item.textContent === text)!;
+  try {
+    await act(async () => root.render(<I18nProvider locale="en"><PluginPermissionPanel pluginId="com.example.synthetic" onChanged={async () => { changed++; }} /></I18nProvider>));
+    assert.match(document.body.textContent!, /synthetic.invalid/);
+    assert.equal(document.querySelector('text'), null, 'resource is rendered as plain text');
+    assert.match(document.body.textContent!, /Until revoked/);
+    await act(async () => { button('Refresh').click(); });
+    await act(async () => {
+      button('Disable and revoke all grants').click();
+      button('Disable and revoke all grants').click();
+    });
+    assert.equal(revokes, 1);
+    assert.equal(button('Refresh').disabled, true);
+    await act(async () => { releaseRevoke(); });
+    assert.equal(changed, 1);
+    assert.match(document.body.textContent!, /No active grants/);
+    await act(async () => { staleRead(initial); });
+    assert.doesNotMatch(document.body.textContent!, /synthetic.invalid/);
+    Object.assign(dom.window, { netcatty: { async getPluginPermissions() { throw new Error('synthetic read failed'); } } });
+    await act(async () => { button('Refresh').click(); });
+    assert.match(document.querySelector('[role="alert"]')?.textContent ?? '', /synthetic read failed/);
+  } finally {
+    await act(async () => root.unmount());
+    dom.window.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+});

components/settings/tabs/PluginPermissionPanel.tsx

@@ -0,0 +1,75 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { netcattyBridge } from '../../../infrastructure/services/netcattyBridge';
+import { useI18n } from '../../../application/i18n/I18nProvider';
+import { describePluginPermission } from '../../../domain/pluginPermissionDescriptions.cjs';
+import { Button } from '../../ui/button';
+
+/** Host UI only. Plugin views cannot query or mutate this security state. */
+export function PluginPermissionPanel({ pluginId, onChanged }: {
+  pluginId: string;
+  onChanged: () => Promise<void>;
+}) {
+  const { t, resolvedLocale } = useI18n();
+  const [snapshot, setSnapshot] = useState<NetcattyPluginPermissionSnapshot | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const generation = useRef(0);
+  const pending = useRef(false);
+  const refresh = useCallback(async () => {
+    const current = ++generation.current;
+    setError(null);
+    try {
+      const bridge = netcattyBridge.require();
+      if (!bridge.getPluginPermissions) throw new Error(t('settings.plugins.permissions.unavailable'));
+      const result = await bridge.getPluginPermissions(pluginId);
+      if (current === generation.current) setSnapshot(result);
+    } catch (cause) {
+      if (current === generation.current) setError(cause instanceof Error ? cause.message : String(cause));
+    }
+  }, [pluginId, t]);
+  useEffect(() => {
+    const requestGeneration = generation;
+    void refresh();
+    return () => { requestGeneration.current++; };
+  }, [refresh]);
+  const revoke = async () => {
+    if (pending.current) return;
+    pending.current = true;
+    setBusy(true);
+    setError(null);
+    try {
+      const bridge = netcattyBridge.require();
+      if (!bridge.revokePluginPermissions) throw new Error(t('settings.plugins.permissions.unavailable'));
+      await bridge.revokePluginPermissions(pluginId);
+      await onChanged();
+      await refresh();
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)); }
+    finally { pending.current = false; setBusy(false); }
+  };
+  return <section className="space-y-3 border-t border-border/60 pt-4 text-sm" aria-label={t('settings.plugins.permissions.title')}>
+    <div className="flex flex-wrap items-center justify-between gap-2">
+      <h4 className="font-medium">{t('settings.plugins.permissions.title')}</h4>
+      <Button variant="ghost" size="sm" disabled={busy} onClick={() => void refresh()}>{t('settings.plugins.permissions.refresh')}</Button>
+    </div>
+    {error && <p role="alert" className="text-xs text-destructive">{error}</p>}
+    {!snapshot && !error && <p role="status">{t('settings.plugins.permissions.loading')}</p>}
+    {snapshot && <>
+      {snapshot.grants.length === 0 && <p className="text-xs text-muted-foreground">{t('settings.plugins.permissions.empty')}</p>}
+      {snapshot.grants.map((grant, index) => <div key={index} className="rounded-md bg-muted/40 p-3 text-xs">
+        <p className="font-medium">{describePluginPermission(grant.permission, resolvedLocale).label}</p>
+        <p className="whitespace-pre-wrap break-all font-mono">{grant.resource}</p>
+        <p>{t(`settings.plugins.permissions.${grant.scope}`)}{grant.sessionId ? ` · ${grant.sessionId}` : ''}</p>
+        <time dateTime={new Date(grant.grantedAt).toISOString()}>{new Date(grant.grantedAt).toLocaleString(resolvedLocale)}</time>
+      </div>)}
+      <details className="text-xs">
+        <summary className="cursor-pointer">{t('settings.plugins.permissions.audit')}</summary>
+        <ol className="mt-2 space-y-1">{snapshot.audit.map((entry, index) => <li key={index} className="break-words">
+          <time dateTime={new Date(entry.createdAt).toISOString()}>{new Date(entry.createdAt).toLocaleString(resolvedLocale)}</time>{' · '}
+          {entry.event}{entry.permission ? ` · ${entry.permission}` : ''}{entry.scope ? ` · ${entry.scope}` : ''}
+        </li>)}</ol>
+      </details>
+      <p className="text-xs text-muted-foreground">{t('settings.plugins.permissions.revokeNote')}</p>
+      <Button variant="destructive" size="sm" disabled={busy} onClick={() => void revoke()}>{t('settings.plugins.permissions.revoke')}</Button>
+    </>}
+  </section>;
+}

components/settings/tabs/PluginReadme.test.tsx

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { PluginReadme } from './PluginReadme';
+
+test('README never creates active HTML, remote media or script links', () => {
+  const html = renderToStaticMarkup(<PluginReadme markdown={'# Example\n\n<script>alert(1)</script>\n\n<img src="https://tracker.example/pixel">\n\n![track](https://tracker.example/x.svg)\n\n[run](javascript:alert%281%29)\n\n[docs](https://example.com)\n\n```html\n<iframe src="file:///secret">\n```'} />);
+  assert.doesNotMatch(html, /<(script|img|iframe|svg)\b/);
+  assert.doesNotMatch(html, /href="(javascript|file):/);
+  assert.match(html, /href="https:\/\/example.com"/);
+  assert.match(html, /rel="noopener noreferrer"/);
+  assert.match(html, /&lt;script&gt;/);
+});

components/settings/tabs/PluginReadme.tsx

@@ -0,0 +1,37 @@
+import React, { useMemo } from 'react';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import type { RootContent, Root } from 'mdast';
+
+function renderNode(node: Root | RootContent, key: number, depth = 0): React.ReactNode {
+  if (depth > 24) return null;
+  const children = 'children' in node ? node.children.map((child, index) => renderNode(child as RootContent, index, depth + 1)) : null;
+  switch (node.type) {
+    case 'root': return <React.Fragment key={key}>{children}</React.Fragment>;
+    case 'heading': return <h4 key={key} className="mt-5 font-semibold">{children}</h4>;
+    case 'paragraph': return <p key={key} className="my-2 leading-relaxed">{children}</p>;
+    case 'text': return node.value;
+    case 'strong': return <strong key={key}>{children}</strong>;
+    case 'emphasis': return <em key={key}>{children}</em>;
+    case 'inlineCode': return <code key={key} className="rounded bg-muted px-1">{node.value}</code>;
+    case 'code': return <pre key={key} className="my-3 overflow-auto rounded-lg bg-muted p-3 text-xs"><code>{node.value}</code></pre>;
+    case 'list': return <ul key={key} className="my-2 list-disc pl-5">{children}</ul>;
+    case 'listItem': return <li key={key}>{children}</li>;
+    case 'blockquote': return <blockquote key={key} className="border-l-2 pl-3 text-muted-foreground">{children}</blockquote>;
+    case 'break': return <br key={key} />;
+    case 'thematicBreak': return <hr key={key} />;
+    case 'link': {
+      let safe = false;
+      try { const url = new URL(node.url); safe = url.protocol === 'https:' && !url.username && !url.password; } catch { /* relative and unsafe links stay text */ }
+      return safe ? <a key={key} href={node.url} target="_blank" rel="noopener noreferrer" className="underline">{children}</a> : <span key={key}>{children}</span>;
+    }
+    // Never embed HTML, media, SVG, iframes, remote images, or reference URLs.
+    case 'image': return <span key={key} className="text-muted-foreground">[{node.alt ?? 'image'}]</span>;
+    case 'html': return <span key={key}>{node.value}</span>;
+    default: return <React.Fragment key={key}>{children}</React.Fragment>;
+  }
+}
+
+export function PluginReadme({ markdown }: { markdown: string }) {
+  const tree = useMemo(() => fromMarkdown(markdown.slice(0, 256 * 1024)), [markdown]);
+  return <div className="break-words text-sm">{renderNode(tree, 0)}</div>;
+}

components/settings/tabs/PluginStatePill.test.tsx

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import React from 'react';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+import { I18nProvider } from '../../../application/i18n/I18nProvider';
+import { PluginPackageManager } from './PluginPackageManager';
+import type { usePluginManager } from '../../../application/state/usePluginManager';
+
+test('state pill exposes actual state, opposite action, focus styling and pending disable without granting permissions', async () => {
+  const globals = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
+  const previous = globals.IS_REACT_ACT_ENVIRONMENT; globals.IS_REACT_ACT_ENVIRONMENT = true;
+  const calls: unknown[] = [];
+  const plugin = { id: 'com.test.pill', activeVersion: '1.0.0', enabled: true, manifest: { name: 'Pill' }, runtime: {} } as NetcattyInstalledPlugin;
+  const manager = { available: true, plugins: [plugin], busy: false, setEnabled: async (...args: unknown[]) => { calls.push(args); } } as unknown as ReturnType<typeof usePluginManager>;
+  let renderer: ReactTestRenderer;
+  const render = (enabled: boolean, busy = false) => <I18nProvider locale="en"><PluginPackageManager manager={{ ...manager, busy, plugins: [{ ...plugin, enabled }] }} /></I18nProvider>;
+  try {
+    await act(async () => { renderer = create(render(true)); });
+    const pill = () => renderer.root.findAllByType('button').find((node) => node.props['aria-pressed'] !== undefined)!;
+    assert.equal(pill().props['aria-pressed'], true);
+    const logoSlot = renderer.root.findAllByType('div').find((node) => node.props.className === 'flex h-12 w-12 shrink-0 items-center justify-center');
+    assert.ok(logoSlot, 'logo keeps its 48px layout slot without an extra decorative background');
+    assert.equal(pill().props['aria-label'], 'Disable Pill');
+    assert.ok(pill().children.includes('Enabled'));
+    assert.match(pill().props.className, /rounded-full/);
+    assert.match(pill().props.className, /border-0/);
+    assert.doesNotMatch(pill().props.className, /border-primary|border-border/);
+    assert.match(pill().props.className, /bg-primary\/10/);
+    assert.match(pill().props.className, /focus-visible:ring-2/);
+    assert.match(pill().props.style.color, /--primary/);
+    await act(async () => pill().props.onClick());
+    assert.deepEqual(calls, [['com.test.pill', false]]);
+    await act(async () => renderer.update(render(false, true)));
+    assert.equal(pill().props['aria-pressed'], false);
+    assert.equal(pill().props['aria-label'], 'Enable Pill');
+    assert.ok(pill().children.includes('Disabled'));
+    assert.equal(pill().props.disabled, true);
+    assert.equal(pill().props['aria-busy'], true);
+    assert.match(pill().props.className, /bg-muted/);
+    assert.equal(pill().props.style, undefined);
+    await act(async () => renderer.unmount());
+  } finally { globals.IS_REACT_ACT_ENVIRONMENT = previous; }
+});

components/settings/tabs/SettingsPluginsTab.tsx

@@ -1,9 +1,14 @@
+import { usePluginManager } from '../../../application/state/usePluginManager';
+import { PluginManagementDialog } from './PluginManagementDialog';
+import { PluginMarketplace } from './PluginMarketplace';
+import { PluginPackageManager } from './PluginPackageManager';
 import { FolderOpen } from 'lucide-react';
 import React, { useEffect, useMemo, useState } from 'react';
 
 import { normalizePluginKeyboardEvent } from '../../../application/state/pluginKeybindings';
 import { usePluginContributions } from '../../../application/state/usePluginContributions';
 import { useI18n } from '../../../application/i18n/I18nProvider';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../../ui/tabs';
 import { Button } from '../../ui/button';
 import { Input } from '../../ui/input';
 import { SettingsAnchor, SettingsTabContent } from '../settings-ui';
@@ -278,8 +283,11 @@ export function PluginSettingField({
   );
 }
 
-export default function SettingsPluginsTab() {
+function PluginManagementContent({ handoff }: { handoff: (action: () => void) => void }) {
   const { t } = useI18n();
+  const manager = usePluginManager();
+  const [selectedInstalled, setSelectedInstalled] = useState<string | null>(null);
+  const [pluginView, setPluginView] = useState<'installed' | 'marketplace'>('installed');
   const availableFonts = useAvailableFonts();
   const scopeCatalog = usePluginSettingScopeCatalog();
   const [scopeIds, setScopeIds] = useState<Partial<Record<NetcattyPluginSettingScopeKind, string>>>({});
@@ -292,21 +300,26 @@ export default function SettingsPluginsTab() {
   }), [scopeIds]);
   const contributions = usePluginContributions(query);
   const contextualScopes = useMemo(() => new Set(contributions.snapshot.plugins
+    .filter((plugin) => plugin.id === selectedInstalled)
     .flatMap((plugin) => plugin.settings.map((setting) => setting.scope))
     .filter((scope): scope is NetcattyPluginSettingScopeKind => scope !== 'application')),
-  [contributions.snapshot.plugins]);
-  const hasVisibleContributions = contributions.snapshot.plugins.some((plugin) => (
-    plugin.settings.some((setting) => setting.visible)
-    || plugin.views.some((view) => view.visible && view.location === 'settings')
-  ));
+  [contributions.snapshot.plugins, selectedInstalled]);
+
 
   return (
-    <SettingsTabContent value="plugins">
-      <SettingsAnchor anchorId="plugins-root" className="mx-auto w-full max-w-3xl space-y-6 px-8 py-8">
-        <div>
-          <h2 className="text-xl font-semibold">{t('settings.plugins.title')}</h2>
-          <p className="mt-1 text-sm text-muted-foreground">{t('settings.plugins.description')}</p>
+    <div className="space-y-5">
+        <Tabs value={pluginView} onValueChange={(value) => { setSelectedInstalled(null); setPluginView(value as 'installed' | 'marketplace'); }} className="space-y-5">
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <TabsList className="h-auto flex-wrap justify-start bg-muted/50">
+            <TabsTrigger value="installed">{t('settings.plugins.manager.installed')} <span className="ml-2 text-muted-foreground">{manager.plugins.length}</span></TabsTrigger>
+            <TabsTrigger value="marketplace">{t('settings.plugins.market.title')}</TabsTrigger>
+          </TabsList>
+          <Button variant="outline" size="sm" disabled={!manager.available || manager.busy} onClick={() => { setPluginView('installed'); void manager.importPackage(); }}><FolderOpen size={14} className="mr-2" />{t('settings.plugins.manager.import')}</Button>
         </div>
+        {manager.credentialStorageAvailable === false && <p role="status" className="text-xs text-muted-foreground">{t('settings.plugins.manager.noVault')}</p>}
+        <TabsContent value="marketplace" className="m-0 space-y-6"><PluginMarketplace installed={manager.plugins} /></TabsContent>
+        <TabsContent value="installed" className="m-0 space-y-6">
+        <PluginPackageManager manager={manager} onSelectionChange={setSelectedInstalled} />
         {contextualScopes.size > 0 && (
           <section className="grid gap-3 rounded-lg border border-border/70 bg-muted/10 p-4 sm:grid-cols-2" aria-label={t('settings.plugins.scopeTargets')}>
             {[...contextualScopes].map((kind) => (
@@ -326,7 +339,7 @@ export default function SettingsPluginsTab() {
         )}
         {contributions.loading && <p className="text-sm text-muted-foreground">{t('settings.plugins.loading')}</p>}
         {contributions.error && <p role="alert" className="text-sm text-destructive">{contributions.error.message}</p>}
-        {contributions.snapshot.plugins.map((plugin) => {
+        {contributions.snapshot.plugins.filter((plugin) => plugin.id === selectedInstalled).map((plugin) => {
           const settings = plugin.settings.filter((setting) => setting.visible);
           const views = plugin.views.filter((view) => view.visible && view.location === 'settings');
           if (!settings.length && !views.length) return null;
@@ -356,18 +369,32 @@ export default function SettingsPluginsTab() {
                     <div className="font-mono text-[10px] text-muted-foreground">{view.id}</div>
                     </div>
                   </div>
-                  <Button type="button" variant="outline" size="sm" onClick={() => requestOpenPluginView({
+                  <Button type="button" variant="outline" size="sm" onClick={() => handoff(() => requestOpenPluginView({
                     viewId: view.id,
                     context: { 'netcatty.surface': 'settings' },
-                  })}>{t('common.open')}</Button>
+                  }))}>{t('settings.plugins.openView')}</Button>
                 </div>
               ))}
             </section>
           );
         })}
-        {!contributions.loading && contributions.available && !hasVisibleContributions && (
-          <p className="text-sm text-muted-foreground">{t('settings.plugins.empty')}</p>
-        )}
+        </TabsContent>
+        </Tabs>
+    </div>
+  );
+}
+
+
+export default function SettingsPluginsTab() {
+  const { t } = useI18n();
+  return (
+    <SettingsTabContent value="plugins">
+      <SettingsAnchor anchorId="plugins-root" className="space-y-5">
+        <div>
+          <h2 className="text-xl font-semibold">{t('settings.plugins.title')}</h2>
+          <p className="mt-1 text-sm text-muted-foreground">{t('settings.plugins.description')}</p>
+        </div>
+        <PluginManagementDialog>{(handoff) => <PluginManagementContent handoff={handoff} />}</PluginManagementDialog>
       </SettingsAnchor>
     </SettingsTabContent>
   );

components/settings/tabs/plugin-marketplace.css

@@ -0,0 +1,13 @@
+/* Container breakpoints account for the Settings sidebar, unlike viewport breakpoints. */
+.plugin-marketplace { container-type: inline-size; }
+.plugin-marketplace-browser { display: grid; gap: 16px; min-width: 0; }
+.plugin-marketplace-catalog { min-width: 0; }
+.plugin-marketplace-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr)); gap: 12px; }
+.plugin-marketplace-browser--selected .plugin-marketplace-catalog { display: none; }
+.plugin-marketplace-detail { overflow-wrap: anywhere; }
+@container (min-width: 820px) {
+  .plugin-marketplace-browser--selected { grid-template-columns: 248px minmax(0, 1fr); align-items: start; }
+  .plugin-marketplace-browser--selected .plugin-marketplace-catalog { display: block; max-height: min(680px, 65vh); overflow-y: auto; padding: 2px; }
+  .plugin-marketplace-browser--selected .plugin-marketplace-grid { grid-template-columns: minmax(0, 1fr); }
+  .plugin-marketplace-browser--selected .plugin-marketplace-detail { max-height: min(680px, 65vh); overflow-y: auto; }
+}

components/terminal/TerminalView.test.tsx

@@ -10,11 +10,9 @@ import {
   formatTerminalTitleConnectionAddress,
   focusTerminalFromDisconnectedNotice,
   getLineTimestampToggleHostUpdate,
-  resolveLineTimestampGutterLayout,
   resolveNetworkDeviceTipRightInset,
   resolveTerminalRightInset,
   resolveTerminalTopOffsets,
-  subscribeTerminalAlternateScreenChanges,
   shouldBlockTerminalReconnectForTarget,
   shouldEnableStatusBarDisconnect,
   shouldEnableStatusBarReconnect,
@@ -184,127 +182,6 @@ test("line timestamp toolbar toggle is hidden when timestamps are unavailable",
   assert.equal(shouldShowLineTimestampToolbarToggle(true, undefined), false);
 });
 
-test("line timestamp gutter reserves no space while the alternate screen is active", () => {
-  assert.deepEqual(resolveLineTimestampGutterLayout({
-    showLineTimestampGutter: true,
-    alternateScreenActive: true,
-    gutterWidth: 72,
-  }), { enabled: false, width: 0 });
-  assert.deepEqual(resolveLineTimestampGutterLayout({
-    showLineTimestampGutter: true,
-    alternateScreenActive: false,
-    gutterWidth: 72,
-  }), { enabled: true, width: 72 });
-  assert.deepEqual(resolveLineTimestampGutterLayout({
-    showLineTimestampGutter: false,
-    alternateScreenActive: false,
-    gutterWidth: 72,
-  }), { enabled: false, width: 0 });
-
-  const source = readFileSync(new URL("./TerminalView.tsx", import.meta.url), "utf8");
-  assert.match(source, /const activeLineTimestampGutterWidth = lineTimestampGutterLayout\.width/);
-  assert.match(source, /enabled=\{lineTimestampGutterLayout\.enabled\}/);
-  assert.doesNotMatch(source, /enabled=\{showLineTimestampGutter\}/);
-  assert.match(source, /aria-pressed=\{showLineTimestampGutter\}/);
-  assert.doesNotMatch(source, /aria-pressed=\{[^}]*alternateScreenActive/);
-});
-
-type AlternateScreenWatchTerm = {
-  buffer: { active: { type: string } };
-  onRender: (callback: () => void) => { dispose: () => void };
-};
-
-function createAlternateScreenWatchTerm(type: "normal" | "alternate") {
-  const renders: Array<() => void> = [];
-  let disposed = 0;
-  const term: AlternateScreenWatchTerm = {
-    buffer: { active: { type } },
-    onRender(callback) {
-      renders.push(callback);
-      return { dispose: () => { disposed += 1; } };
-    },
-  };
-  return {
-    term,
-    renders,
-    disposeCount: () => disposed,
-  };
-}
-
-test("alternate screen enter and leave drive the timestamp gutter", (t) => {
-  const watched = createAlternateScreenWatchTerm("normal");
-  const seen: boolean[] = [];
-  const stop = subscribeTerminalAlternateScreenChanges(
-    () => watched.term,
-    (active) => { seen.push(active); },
-  );
-  t.after(stop);
-
-  assert.deepEqual(seen, [false]);
-  watched.term.buffer.active.type = "alternate";
-  watched.renders[0]();
-  watched.renders[0]();
-  watched.term.buffer.active.type = "normal";
-  watched.renders[0]();
-  assert.deepEqual(seen, [false, true, false]);
-
-  stop();
-  assert.equal(watched.disposeCount(), 1);
-  watched.term.buffer.active.type = "alternate";
-  watched.renders[0]();
-  assert.deepEqual(seen, [false, true, false]);
-});
-
-test("alternate screen watch attaches after the terminal runtime exists", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const watched = createAlternateScreenWatchTerm("alternate");
-  let current: AlternateScreenWatchTerm | null = null;
-  const seen: boolean[] = [];
-  const stop = subscribeTerminalAlternateScreenChanges(
-    () => current,
-    (active) => { seen.push(active); },
-  );
-  t.after(() => {
-    stop();
-    t.mock.timers.reset();
-  });
-
-  assert.deepEqual(seen, [false]);
-  current = watched.term;
-  t.mock.timers.tick(50);
-  assert.deepEqual(seen, [false, true]);
-  assert.equal(watched.renders.length, 1);
-  t.mock.timers.tick(500);
-  assert.equal(watched.renders.length, 1);
-  assert.deepEqual(seen, [false, true]);
-});
-
-test("alternate screen watch follows a replacement terminal runtime", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const first = createAlternateScreenWatchTerm("alternate");
-  const second = createAlternateScreenWatchTerm("normal");
-  let current: AlternateScreenWatchTerm = first.term;
-  const seen: boolean[] = [];
-  const stop = subscribeTerminalAlternateScreenChanges(
-    () => current,
-    (active) => { seen.push(active); },
-  );
-  t.after(() => {
-    stop();
-    t.mock.timers.reset();
-  });
-
-  assert.deepEqual(seen, [true]);
-  current = second.term;
-  t.mock.timers.tick(250);
-  assert.deepEqual(seen, [true, false]);
-  assert.equal(first.disposeCount(), 1);
-  assert.equal(second.renders.length, 1);
-  second.term.buffer.active.type = "alternate";
-  second.renders[0]();
-  assert.deepEqual(seen, [true, false, true]);
-});
-
 test("selection AI overlay honors the visibility preference", () => {
   const overlayPosition = { left: 120, top: 80 };
   const addSelection = () => {};

components/terminal/TerminalView.tsx

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
-import type { Terminal as XTerm } from '@xterm/xterm';
 import { ChevronsLeft, GripVertical, Minimize2, Network, PanelLeft, X as XIcon } from 'lucide-react';
 import { isTerminalSensitiveInputActive } from './runtime/terminalSensitiveInputRegistry';
 import { isSessionReconnectDisabled } from '../top-tabs/SessionTabContextMenuContent';
@@ -19,7 +18,6 @@ import {
   resolveTerminalTimestampGutterColor,
   resolveTerminalTimestampGutterWidth,
 } from './TerminalTimestampGutter';
-import { isTerminalAlternateScreenActive } from './terminalHibernateRuntime';
 import {
   Dialog,
   DialogContent,
@@ -124,108 +122,6 @@ export function shouldShowLineTimestampToolbarToggle(
   return lineTimestampsAvailable !== false && Boolean(onUpdateHost);
 }
 
-export function resolveLineTimestampGutterLayout({
-  showLineTimestampGutter,
-  alternateScreenActive,
-  gutterWidth,
-}: {
-  showLineTimestampGutter: boolean;
-  alternateScreenActive: boolean;
-  gutterWidth: number;
-}): { enabled: boolean; width: number } {
-  const enabled = showLineTimestampGutter && !alternateScreenActive;
-  return { enabled, width: enabled ? gutterWidth : 0 };
-}
-
-const ALTERNATE_SCREEN_ATTACH_RETRY_MS = 50;
-const ALTERNATE_SCREEN_RUNTIME_WATCH_MS = 250;
-
-type TerminalAlternateScreenDisposable = { dispose: () => void };
-
-type TerminalAlternateScreenWatchTarget = {
-  buffer?: { active?: { type?: string } };
-  onRender?: (callback: () => void) => TerminalAlternateScreenDisposable;
-};
-
-const readAlternateScreenActive = (
-  term: TerminalAlternateScreenWatchTarget | null | undefined,
-): boolean => {
-  try {
-    if (!term?.buffer?.active) return false;
-    return isTerminalAlternateScreenActive(term as XTerm);
-  } catch {
-    return false;
-  }
-};
-
-/**
- * Alternate-screen programs intentionally skip timestamp recording. onRender
- * collapses and restores the gutter immediately. The timer attaches once xterm
- * exists and follows a replacement runtime after hibernate or reconnect.
- */
-export function subscribeTerminalAlternateScreenChanges(
-  getTerm: () => TerminalAlternateScreenWatchTarget | null | undefined,
-  onChange: (alternateScreenActive: boolean) => void,
-): () => void {
-  let disposed = false;
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  let renderDisposable: TerminalAlternateScreenDisposable | null = null;
-  let attachedTerm: TerminalAlternateScreenWatchTarget | null = null;
-  let lastActive: boolean | null = null;
-
-  const publish = (active: boolean) => {
-    if (disposed || lastActive === active) return;
-    lastActive = active;
-    onChange(active);
-  };
-
-  const detachRender = () => {
-    renderDisposable?.dispose();
-    renderDisposable = null;
-  };
-
-  const watch = () => {
-    if (disposed) return;
-    if (timer !== null) {
-      clearTimeout(timer);
-      timer = null;
-    }
-
-    const term = getTerm() ?? null;
-    if (term !== attachedTerm) {
-      detachRender();
-      attachedTerm = term;
-      if (term?.onRender) {
-        renderDisposable = term.onRender(() => {
-          if (disposed) return;
-          const current = getTerm() ?? null;
-          if (current !== term) {
-            watch();
-            return;
-          }
-          publish(readAlternateScreenActive(current));
-        });
-      }
-    }
-
-    publish(readAlternateScreenActive(term));
-    if (disposed) return;
-    const delay = term?.onRender
-      ? ALTERNATE_SCREEN_RUNTIME_WATCH_MS
-      : ALTERNATE_SCREEN_ATTACH_RETRY_MS;
-    timer = setTimeout(watch, delay);
-  };
-
-  watch();
-
-  return () => {
-    disposed = true;
-    if (timer !== null) clearTimeout(timer);
-    detachRender();
-    attachedTerm = null;
-  };
-}
-
 /** Keep the tab/pane; only tear down the live transport. */
 export function shouldEnableStatusBarDisconnect(
   status: 'connecting' | 'connected' | 'disconnected' | undefined,
@@ -590,11 +486,6 @@ function TerminalViewInner({ ctx, isPaneMagnified = false }: { ctx: TerminalView
   }, [hostTimestampsEnabled, timestampOverride]);
   const showLineTimestampGutter = lineTimestampsAvailable !== false
     && (timestampOverride ?? hostTimestampsEnabled);
-  const [alternateScreenActive, setAlternateScreenActive] = useState(false);
-  useEffect(() => subscribeTerminalAlternateScreenChanges(
-    () => termRef.current,
-    setAlternateScreenActive,
-  ), [sessionId, status, termRef]);
   const lineTimestampColor = resolveTerminalTimestampGutterColor(effectiveTheme.colors);
   const [lineTimestampGutterWidth, setLineTimestampGutterWidth] = useState(() => (
     resolveTerminalTimestampGutterWidth({ fontSize: effectiveFontSize })
@@ -606,12 +497,7 @@ function TerminalViewInner({ ctx, isPaneMagnified = false }: { ctx: TerminalView
   const handleLineTimestampGutterWidthChange = useCallback((width: number) => {
     setLineTimestampGutterWidth((current) => (current === width ? current : width));
   }, []);
-  const lineTimestampGutterLayout = resolveLineTimestampGutterLayout({
-    showLineTimestampGutter,
-    alternateScreenActive,
-    gutterWidth: lineTimestampGutterWidth,
-  });
-  const activeLineTimestampGutterWidth = lineTimestampGutterLayout.width;
+  const activeLineTimestampGutterWidth = showLineTimestampGutter ? lineTimestampGutterWidth : 0;
   const lineTimestampToggleLabel = showLineTimestampGutter
     ? t("terminal.toolbar.timestampsDisable")
     : t("terminal.toolbar.timestampsEnable");
@@ -1200,7 +1086,7 @@ function TerminalViewInner({ ctx, isPaneMagnified = false }: { ctx: TerminalView
           <TerminalTimestampGutter
             termRef={termRef}
             containerRef={containerRef}
-            enabled={lineTimestampGutterLayout.enabled}
+            enabled={showLineTimestampGutter}
             top={terminalContentTop}
             left={terminalBodyInset}
             bottom={terminalBottomInset}

components/terminal/keywordHighlight.test.ts

@@ -5,7 +5,6 @@ import { createRequire } from "node:module";
 import type { SerializeAddon as SerializeAddonType } from "@xterm/addon-serialize";
 import type { Terminal as XTermType } from "@xterm/xterm";
 
-import { DEFAULT_KEYWORD_HIGHLIGHT_RULES } from "../../domain/models/terminal.ts";
 import { writeTerminalDataWithLineTimestamps } from "./runtime/terminalLineTimestamps.ts";
 import {
   noteTerminalOutputPressureData,
@@ -82,76 +81,6 @@ test("new output is colored on the written cells without decorations", async ()
   term.dispose();
 });
 
-test("keyword highlight skips cells whose PTY foreground is already colored", async () => {
-  // Starship directory segments set a truecolor foreground (#3940). Those
-  // cells must keep the PTY color; only default-foreground matches are recolored.
-  const unixPath = DEFAULT_KEYWORD_HIGHLIGHT_RULES.find((entry) => entry.id === "unix-path");
-  assert.ok(unixPath);
-  const keywordRgb = Number.parseInt(unixPath.color.slice(1), 16);
-  const cream = 0xfbf1c7;
-  const yellow = 0xfabd2f;
-  const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 });
-  const highlighter = new KeywordHighlighter(term);
-  highlighter.setRules([unixPath], true);
-  await write(
-    term,
-    "\x1b[38;2;251;241;199m\x1b[48;2;250;189;47m/opt\x1b[0m"
-    + " \x1b[38;5;220m/mnt\x1b[0m"
-    + " \x1b[31m/bin\x1b[0m"
-    + " /var",
-  );
-
-  const tokenCells = (text: string) => {
-    const line = term.buffer.active.getLine(0);
-    const index = (line?.translateToString(true) ?? "").indexOf(text);
-    assert.ok(index >= 0, text);
-    return Array.from({ length: text.length }, (_, offset) => {
-      const cell = line?.getCell(index + offset);
-      assert.ok(cell, `${text}[${offset}]`);
-      return cell;
-    });
-  };
-
-  for (const cell of tokenCells("/opt")) {
-    assert.equal(cell.isFgRGB(), true);
-    assert.equal(cell.getFgColorMode(), 0x3000000);
-    assert.equal(cell.getFgColor(), cream);
-    assert.equal(cell.isBgRGB(), true);
-    assert.equal(cell.getBgColor(), yellow);
-  }
-  for (const cell of tokenCells("/mnt")) {
-    assert.equal(cell.isFgPalette(), true);
-    assert.equal(cell.getFgColorMode(), 0x2000000);
-    assert.equal(cell.getFgColor(), 220);
-  }
-  for (const cell of tokenCells("/bin")) {
-    assert.equal(cell.isFgPalette(), true);
-    assert.equal(cell.getFgColorMode(), 0x1000000);
-    assert.equal(cell.getFgColor(), 1);
-  }
-  for (const cell of tokenCells("/var")) {
-    assert.equal(cell.isFgRGB(), true);
-    assert.equal(cell.getFgColor(), keywordRgb);
-  }
-
-  highlighter.setRules([{ ...unixPath, color: "#60A5FA" }], true);
-  await highlighter.whenSettled();
-  assert.equal(tokenCells("/opt")[0]?.getFgColor(), cream);
-  assert.equal(tokenCells("/mnt")[0]?.getFgColor(), 220);
-  assert.equal(tokenCells("/bin")[0]?.getFgColor(), 1);
-  assert.equal(tokenCells("/var")[0]?.getFgColor(), BLUE);
-
-  highlighter.setRules([{ ...unixPath, color: "#60A5FA" }], false);
-  await highlighter.whenSettled();
-  assert.equal(tokenCells("/opt")[0]?.getFgColor(), cream);
-  assert.equal(tokenCells("/mnt")[0]?.getFgColor(), 220);
-  assert.equal(tokenCells("/bin")[0]?.getFgColor(), 1);
-  assert.equal(tokenCells("/var")[0]?.getFgColor(), -1);
-
-  highlighter.dispose();
-  term.dispose();
-});
-
 test("ordinary Enter output does not revisit existing history", async () => {
   const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 });
   const highlighter = new KeywordHighlighter(term);

components/terminal/keywordHighlight.ts

@@ -67,7 +67,6 @@ const CELL_INDICES = 3;
 const CELL_CONTENT = 0;
 const CELL_FG = 1;
 const STYLE_MASK = 0xfc000000;
-const CM_MASK = 0x3000000;
 const CM_RGB = 0x3000000;
 const MAX_PLUGIN_HIGHLIGHT_SCAN_CHARS = 4_096;
 const MAX_PLUGIN_HIGHLIGHT_MATCHES_PER_WRITE = 256;
@@ -1062,13 +1061,7 @@ export class KeywordHighlighter implements IDisposable {
       const dataIndex = x * CELL_INDICES;
       const content = internal._data[dataIndex + CELL_CONTENT];
       const currentFg = internal._data[dataIndex + CELL_FG];
-      // A cell already carrying a PTY palette/truecolor foreground (starship
-      // directory segments, ANSI logs) must keep that color. Keyword RGB is
-      // only for the default foreground.
-      const maskedForContent = originals.mask[x] === 1 && originals.content[x] === content;
-      const ptyFg = maskedForContent ? originals.fg[x] : currentFg;
-      if ((ptyFg & CM_MASK) !== 0) continue;
-      if (!maskedForContent) {
+      if (!originals.mask[x] || originals.content[x] !== content) {
         originals.fg[x] = currentFg;
         originals.content[x] = content;
         originals.mask[x] = 1;

docs/plugin-platform/batch1-verification.md

@@ -0,0 +1,98 @@
+# Batch 1 aggregate failure comparison
+
+Frozen base: `e5bd294cddbf58dfe04c646b6291933d980498fd`. Current:
+`9af123e5d7bdb15771d69fb427faacf32c46dfb3`. Same Node 24.19.0 executable,
+same installed dependency tree, same sandbox and environment. Tests use existing
+synthetic fixtures. No home/cache permission or native-build bypass was added.
+
+The 39 entries below were observed before stopping the local full suite.
+Later runner failures caused by that explicit termination are excluded. This
+is not a successful aggregate run and is not proof that every full-suite test
+was executed. The full suite was stopped after existing/environmental failures
+to avoid presenting an incomplete run as green.
+
+## Bounded comparison result
+
+Targeted test-name patterns selected the original 39 failures across 15 files.
+Thirty-eight fail on both frozen base and current with matching failure titles
+and key error signatures. The persistence-volume assertion passes on both.
+Three additional paired repetitions of that assertion also pass on both: four
+passing runs per side including the initial comparison. Its code is unchanged;
+the aggregate-only result remains a timing-sensitive limitation, not an
+established current-only regression.
+
+The first baseline rerun reproduced 11 entries: rows 1-2 and 4-12. It did not
+reproduce row 3. No new source change fixes unrelated baseline failures.
+
+| Rows | Signature and classification |
+| --- | --- |
+| 1-2, 14-16, 27-33, 35-39 | Host temp-dir creation fails outside writable roots (`ENOENT` from `tempDirBridge`). Both revisions fail. Environment constraint |
+| 4-9 | Markdown comparison falls back to source; expected rich-preview elements are absent. Both revisions fail. Existing baseline/dependency behavior; no source repair in this scope |
+| 10-12 | Native `pty.node` missing from normal build/prebuild lookup. Both revisions fail. Dependency/native setup constraint |
+| 13 | UI algorithm list includes `ssh-ed25519-cert-v01@openssh.com` but installed ssh2 rejects it. Both revisions fail. Existing baseline/dependency behavior |
+| 17-26 | Cursor discovery/SDK expectations differ (`false` vs `true`, then expected installation/auth DTO). Both revisions fail with matching assertion signatures. Existing environment/dependency behavior; no real account accessed |
+| 34 | Electron bootstrap fetch fails and the binary is not installed. Both revisions fail. Dependency/network setup constraint |
+| 3 | Persistence writes exceed aggregate threshold; isolated baseline/current and three repetitions each pass. Aggregate-only timing-sensitive assertion; no current-only failure reproduced |
+
+## Original titles and first error
+
+| # | Test file | Original title | First key error | Paired result |
+| --- | --- | --- | --- | --- |
+| 1 | `application/state/sftp/dedicatedTransferResume.test.ts` | large-history replace recovery retransfers retained completed children into its empty stage: late=false | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 2 | `application/state/sftp/dedicatedTransferResume.test.ts` | large-history replace recovery retransfers retained completed children into its empty stage: late=true | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 3 | `application/state/sftpTransferCenterStore.test.ts` | large directory progress coalesces synchronous persistence work | AssertionError [ERR_ASSERTION]: expected bounded persistence volume, wrote 2638624 characters for a 588644-character snapshot | base/current pass; aggregate-only |
+| 4 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | literal Markdown comparisons render without changing the note source | AssertionError [ERR_ASSERTION]: a comparison must render as ordinary text | base/current same failure |
+| 5 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | comparison variants render in paragraphs, tables and alongside HTML | assert.ok(!querySourceFallback(rootNode)) is false | base/current same failure |
+| 6 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | issue 3205 author note survives source, preview and edit without rewriting | AssertionError [ERR_ASSERTION]: preview must render the author's note | base/current same failure |
+| 7 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | editing a comparison emits Markdown that can be reopened | assert.ok(editable): actual null | base/current same failure |
+| 8 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | preview task checkboxes still save explicit changes without rewriting comparisons | assert.ok(task): actual null | base/current same failure |
+| 9 | `components/notes/InlineMarkdownEditor.unrenderableMarkdown.test.tsx` | switching between a comparison note and an unsupported note keeps the fallback scoped | assert.ok(!querySourceFallback(rootNode)) is false | base/current same failure |
+| 10 | `components/terminal/runtime/serialInputSequences.test.ts` | components/terminal/runtime/serialInputSequences.test.ts | Failed to load native module: pty.node | base/current same failure |
+| 11 | `components/terminal/runtime/terminalLinePaste.test.ts` | components/terminal/runtime/terminalLinePaste.test.ts | Failed to load native module: pty.node | base/current same failure |
+| 12 | `components/terminal/runtime/terminalPasteCancellation.test.ts` | components/terminal/runtime/terminalPasteCancellation.test.ts | Failed to load native module: pty.node | base/current same failure |
+| 13 | `domain/sshAlgorithmList.test.ts` | SUPPORTED_ALGORITHMS_BY_CATEGORY only lists algorithms ssh2 will actually accept | AssertionError [ERR_ASSERTION]: ssh-ed25519-cert-v01@openssh.com (serverHostKey) is in the UI list but ssh2 would reject it | base/current same failure |
+| 14 | `electron/bridges/ai/liveShellProbe.test.cjs` | Bash invoked as sh cleans probe history | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 15 | `electron/bridges/ai/liveShellProbe.test.cjs` | Bash invoked as renamed-bash cleans probe history | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 16 | `electron/bridges/aiBridge.externalContext.test.cjs` | electron/bridges/aiBridge.externalContext.test.cjs | ENOENT creating host temp directory from sshBridge import | base/current same failure |
+| 17 | `electron/bridges/aiBridge.test.cjs` | resolve-cli reports Cursor Agent CLI on PATH as installed without CLI login | AssertionError [ERR_ASSERTION]: Expected values to be strictly equal: | base/current same failure |
+| 18 | `electron/bridges/aiBridge.test.cjs` | resolve-cli reports Cursor SDK installed but unavailable without an API key | AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal: | base/current same failure |
+| 19 | `electron/bridges/aiBridge.test.cjs` | resolve-cli separates Cursor SDK installation from API key availability | AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal: | base/current same failure |
+| 20 | `electron/bridges/aiBridge.test.cjs` | resolve-cli ignores custom Cursor paths and stores the SDK sentinel path | AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal: | base/current same failure |
+| 21 | `electron/bridges/aiBridge.test.cjs` | resolve-cli exposes Cursor SDK support when installed and authenticated | AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal: | base/current same failure |
+| 22 | `electron/bridges/aiBridge.test.cjs` | resolve-cli exposes Cursor SDK support when API key is saved in settings | AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal: | base/current same failure |
+| 23 | `electron/bridges/aiBridge.test.cjs` | resolve-cli reports settings as Cursor auth source when settings and env keys both exist | AssertionError [ERR_ASSERTION]: Expected values to be strictly equal: | base/current same failure |
+| 24 | `electron/bridges/aiBridge.test.cjs` | resolve-cli can refresh shell env before resolving Cursor | AssertionError [ERR_ASSERTION]: Expected values to be strictly equal: | base/current same failure |
+| 25 | `electron/bridges/aiBridge.test.cjs` | discover exposes Cursor SDK support when API key is saved in settings | AssertionError [ERR_ASSERTION]: Expected values to be strictly equal: | base/current same failure |
+| 26 | `electron/bridges/aiBridge.test.cjs` | discover can refresh shell env before scanning Cursor | AssertionError [ERR_ASSERTION]: Expected values to be strictly equal: | base/current same failure |
+| 27 | `electron/bridges/aiBridge/sdk/copilotDriver.test.cjs` | listCopilotModels resolves a Windows .cmd shim to the copilot JS entry before the SDK sees it | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 28 | `electron/bridges/aiBridge/sdk/copilotDriver.test.cjs` | listCopilotModels retains the official loader when its platform runtime is unavailable | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 29 | `electron/bridges/aiBridge/sdk/copilotDriver.test.cjs` | resolveCopilotPlatformExecutable resolves the platform package exe from the loader root | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 30 | `electron/bridges/aiBridge/sdk/copilotDriver.test.cjs` | resolveCopilotExecutableForSdk resolves npm's copilot.ps1 wrapper to the JS entry on Windows | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 31 | `electron/bridges/aiBridge/sdk/copilotDriver.test.cjs` | connectCopilotStdioPath directly selects the official loader's native runtime | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 32 | `electron/bridges/aiBridge/sdk/opencodeDriver.startup.test.cjs` | OpenCode releases the process-env gate after spawning separate catalog profiles | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 33 | `electron/bridges/aiBridge/sdk/opencodeDriver.test.cjs` | createOpenCodeProcessEnv prefers an existing opencode binary | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 34 | `electron/bridges/aiEchoSuppressionOrdering.test.cjs` | electron/bridges/aiEchoSuppressionOrdering.test.cjs | fetch failed; Electron failed to install correctly | base/current same failure |
+| 35 | `electron/bridges/autoUpdateBridge.test.cjs` | recognizes packaged Linux FPM formats as auto-update capable | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 36 | `electron/bridges/autoUpdateBridge.test.cjs` | allows the update check to reach electron-updater for a packaged Linux deb | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 37 | `electron/bridges/autoUpdateBridge.test.cjs` | keeps the manual-update fallback for an unmarked Linux package | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 38 | `electron/bridges/autoUpdateBridge.test.cjs` | keeps AppImage auto-update support on Linux | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+| 39 | `electron/bridges/autoUpdateBridge.test.cjs` | install handler reports package-manager failures and restores the app state | ENOENT creating host temp directory from tempDirBridge | base/current same failure |
+
+## Reproduction method
+
+For each file above, run the existing test with the same title pattern in each
+checkout. Pass the title pattern as an argument, without interpolating it as
+shell code. Native/import failures occur before the title filter can execute.
+
+```sh
+node --test --import tsx --test-reporter=tap --test-name-pattern "<escaped original title>" <test file>
+```
+
+The comparison used bounded 90-second subprocess deadlines. None reached that
+deadline. The persistence repeat used the same existing test and a 60-second
+deadline. It added no load generator or attack payload.
+
+All 15 test files and the business modules responsible for these signatures
+are unchanged by batch 1. This classification does not resolve the two
+independently reported grant-management review findings; those receive
+separate source fixes and tests.

docs/plugin-platform/capability-coverage.md

@@ -0,0 +1,82 @@
+# Sandbox capability coverage
+
+This matrix tracks expansion from Draft #3951 at
+`e5bd294cddbf58dfe04c646b6291933d980498fd`. Each accepted item requires a
+canonical schema, generated SDK, broker, permission policy, quota and audit,
+host adapter, lifecycle cleanup, synthetic boundary tests, review, and exact-SHA
+CI. Enumeration in a manifest is not a working API. Status `planned` does not
+mean complete. Existing APIs remain available.
+
+## Coverage matrix
+
+| Subsystem | Working API at baseline | Enumeration or missing adapter | Accepted bounded entry | Data and action risk | Authorization resource | Revocation, audit, quota | Verification and disposition |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Authorization management | Engine `listGrants`, `revokeAll`, database audit | Manager shows declarations only | Host-only grant list, bounded audit summary, disable and revoke | Paths, session IDs, grant metadata are sensitive | Exact plugin ID, trusted app sender | Serialized manager mutation, disable before revoke, runtime teardown, retained audit | Batch 1 implemented: host/manager/UI tests. Native acceptance pending. No plugin RPC for managing grants |
+| Network and credential leases | `network.request`, `credentials.createLease`, single-use host redemption | SDK request omits lease and authorization fields | Canonical request types matching broker | Network mutation and credentials | Exact origin plus secret reference and operation | Existing timeout, redirects, byte quotas, runtime checks, lease TTL | Batch 1 implemented: canonical schema and SDK, synthetic fixture and lease tests, feature negotiation. Native acceptance pending. No plaintext secret API |
+| Commands, menus, toolbar, status bar, views | `commands.execute`, settings, context keys, view state and messages, UI contributions | No editor or SFTP menu slots | Existing contribution system | Plugin text and arguments may be sensitive | Namespaced contributions and permissions | Existing lifecycle, rate and message limits | Existing tests. New context menu slots planned with bounded context DTOs |
+| Terminal providers | Decorations, links, completion, snapshots through provider requests | Session change delivery follows prior provider request and non-once grant | Preserve providers. Standalone selected-session watch planned | Hostnames, session state, endpoint identity | Host-selected session, runtime identity | Session-close and revoke cleanup, bounded event rate | Existing provider tests. Ordinary views cannot independently subscribe today |
+| Current context and host picker | Host context keys are boolean state | `vault.metadata` enumeration is not generic SDK | Selected host/session DTO from an explicit whitelist | Labels and endpoint metadata are sensitive | Host-owned user-action context, selected host/session | TTL, runtime and session invalidation, redacted audit | Planned. Never reuse agent `sanitizeHostForAgent` as plugin DTO |
+| Terminal selection and input draft | Provider-supplied snapshots, completion suggestions | No explicit selection-share or draft API | User shares selection, plugin proposes a visible editable draft | Terminal plaintext, accidental execution | Host action token plus exact live session/endpoint | Single-use token, size cap, no plaintext audit, active identity before commit | Planned. Reject Enter/control characters for draft insertion. No full history or direct shell |
+| Native interactions and clipboard | Native permission dialogs | Clipboard enum only. No quick-pick/input/progress/toast SDK | Host-owned prompts, explicit copy/paste with preview | Clipboard and input may contain secrets, prompt spam | Host action context plus clipboard direction | Cancellation, request count and byte caps, runtime cleanup | Planned. No background reads or trusted plugin `userGesture` boolean |
+| Local filesystem | Read file, stat, overwrite existing regular file | Directory listing lacks same-handle native adapter | Keep current boundary, evaluate file picker handles | Arbitrary local file content and writes | Canonical exact path or selected file handle | Inode checks, no symlink alias, bounded bytes, active runtime | Existing filesystem tests. Directory enumeration and new arbitrary-path creation deferred until portable safe native adapter exists |
+| SFTP and remote files | No generic plugin API | `sftp.read` and `sftp.write` enumerated only | Host-selected session/path/mode/TTL handles, read and explicit save/upload | Remote secrets and destructive overwrite | Live endpoint identity, exact path, read/write split | Cancel streams, byte quota, overwrite confirmation, close/revoke cleanup | Batch 2 planned. Never forward arbitrary MCP catalog or session ID alone |
+| Editor and Notes | No plugin document API | No versioned snapshot or edit preview | Explicit snapshot and versioned proposed edit | Document secrets, lost updates, executable files | Selected document plus revision and action token | Version conflict check, preview, bounded bytes, revocation | Planned evaluation after shared action context. No unattended edits |
+| Snippets and scripts | Provider import drafts only | No generic read/run API | Explicit selection and create draft | Script contents may contain secrets. Running executes commands | Selected item, read versus draft write | Preview, byte cap, no automatic execution | Planned evaluation. Script `run` and onConnect modification deferred |
+| Connections and authentication | Connection/authentication providers, opaque credentials, streams | Generic host open/connect absent | Existing providers remain | Connect can execute saved onConnect scripts | Provider operation plus live endpoint and credential lease | Existing provider lifecycle, streams and quotas | Existing tests. Generic connect is a write/execution capability, deferred pending explicit execution design |
+| Sync and storage | Local namespaced KV, encrypted-object sync providers, opt-in setting sidecars | No general KV cloud sync | Existing opt-in provider protocol | Conflicts, deletes, credential access | Provider/account/object, settings scope | Existing limits and lifecycle, non-cascade metadata | Existing sync tests. General KV sync deferred until conflict/delete/quota/migration policy is defined |
+| Vault and keychain | Credential references and import preview/commit | Metadata/write enums do not grant a generic Vault SDK | Only user-selected whitelist DTOs and drafts | Notes, environmentVariables, startupCommand, keys and credentials | Selected object plus field/direction | Explicit preview, identity checks, redacted audit | Full Vault export and secret reads deferred indefinitely. No agent field-exclusion DTO reuse |
+| System manager and Docker | No plugin system API | Agent/MCP adapters are separate authority | Typed read-only summaries excluding args/env/inspect | Process command lines and Docker inspect can expose secrets | Selected live session and summary kind | Bounded result, endpoint identity, cancellation | Planned evaluation. Arbitrary process/inspect forwarding deferred |
+| Port forwarding | No generic plugin API | Existing agent start is write-sensitive | Selected rule status and open host form | Rule endpoints and local exposure | Selected rule plus host action | Bounded DTO, session close and revoke | Planned evaluation. Direct start deferred until binding/listener approval design |
+| Themes, settings, appearance, i18n | Terminal theme/background Providers, isolated view CSS, scoped settings and environment updates | No host global theme contribution. Personal customCSS is not plugin authority | Accepted ThemePack stage: static palette registry, source-labelled selector, window-local preview, revision-safe apply/cancel/reset, static terminal linkage | Unreadable colors and misleading security UI. Nineteen UiThemeTokens fields are not independent: primary/accent/ring and foregrounds derive from the effective accent | User explicitly selects a theme. Separate static contribution enablement from code permissions; no generic appearance.write or runtime activation | Immutable version/hash, bounded JSON, preview owner/token/revision, disable/update/uninstall fallback, no implicit sync, fixed host security appearance | [ThemePack design](./theme-packs-design.md) accepted for implementation after current A work; unfinished until contract, security boundary, lifecycle, contrast, samples and native gates pass. No arbitrary DOM/CSS, remote assets, free layout or security UI customization |
+| Transfer center | Host transfer queue exists, no plugin entry | No ownership-bound task API | Observe and cancel only plugin-created tasks | Paths and host endpoints reveal user data. Cancel may leave partial files | Own transfer handle plus source/destination authority | Shared backpressure, cancel/close cleanup, honest partial status | Planned with batch 2. Do not broadcast or cancel other tasks |
+| AI, MCP, automation | Host agent catalog and harness exist separately | No generic plugin AI or tool forwarding | Selection-to-proposal workflow through the same controlled primitives | Content disclosure, account authority and model cost | Explicit content sharing plus service origin/budget | No inherited history, tools, account, or hidden cron | Controlled workflow planned. Generic host AI and visible schedules deferred to distinct product decision |
+| Known hosts, app lock and global security | Host security management UI | No plugin management API | Future allowlisted security-page navigation | Host-key trust, unlock, keys and security policy affect all sessions | Host navigation action only | No mutation or sensitive DTO | Security policy mutation, private-key reads, auto-trust and unlocking deferred indefinitely |
+| Plugin blob/cache | Local KV exists | No exclusive blob cache | Evaluate bounded plugin-owned cache when a real workflow needs it | Disk growth and lifecycle ambiguity | Plugin namespace, no arbitrary path | Size quota, eviction and uninstall policy required | Deferred until a concrete larger-than-KV workflow establishes value and retention policy |
+| Distribution and runtimes | Browser-only public catalog, immutable packages, advanced developer gate | Signing/trust and release remain separate phase | Retain existing boundary | Package execution and publisher trust | Pinned catalog selection, hash, engine/features | Existing install transaction, quarantine and cleanup | No merge/release. Do not extend to arbitrary Node, IPC, shell, or global capabilities |
+
+## Delivery order and stopping rule
+
+1. Batch 1: actual authorization management plus network contract consistency.
+   Keep the existing manager layout. Add one independent permission panel.
+2. Batch 1b: host action context, native interactions, selected context and terminal
+   sharing/drafts. A plugin-supplied gesture is never authority.
+3. Batch 2: SFTP selected-file handles and explicit transfer destinations.
+4. Deliver the separately reviewed [declarative ThemePack stage](./theme-packs-design.md), including protected security surfaces, contrast gates, revision-safe preview/apply/reset, and safe fallback.
+5. Reassess editor, Notes, snippets, menus, system summaries, and port forwarding
+   using the tested host-action and resource primitives.
+
+Stop only when every row is implemented and tested, reasonably deferred with a
+specific boundary and rationale, or awaiting a concrete user decision. A
+planned row remains unfinished. Native screenshots and recordings belong to
+the parent thread. Real credentials, hosts, or transfers require approval for a
+specific target there. Synthetic checks do not establish native acceptance.
+
+## Batch 1 evidence and next workflow
+
+The independent permission panel adds only an import and a detail mount to
+`components/settings/tabs/PluginPackageManager.tsx`. It uses the manager hook's
+new `refresh()` after host revocation. Marketplace layout remains owned by the
+parallel UI layer. Five locale files contain the panel strings.
+
+The next usable workflow is a browser plugin that asks a host quick-pick/input
+question, then explicitly copies its result or asks the user to share clipboard
+text. The host displays the plugin source and action before reading or writing.
+A canonical `HostInteractionRequest` and bounded result carry only text/choice
+IDs. The host owns request IDs, requester webContents, runtime/version, TTL,
+cancellation, and the consent result. The renderer cannot reply for another
+window. Plugin `userGesture` values are ignored. Runtime/revoke shutdown aborts
+all outstanding prompts and ignores late replies. A shared prompt primitive
+then supports selected host/session context, selection share, and input drafts.
+
+Before proceeding to the sensitive context/terminal and SFTP entries, the
+native path must prove consent, cancellation, quota, and identity binding with
+synthetic data. UI screenshots and real-resource approval remain parent-owned.
+
+Baseline code references: `electron/plugins/hostService.cjs`,
+`secureCapabilities.cjs`, `permissionEngine.cjs`, `terminalProviderService.cjs`,
+`filesystemBroker.cjs`, `extensionProviderService.cjs`,
+`packages/plugin-sdk/src/index.ts`, and
+`packages/plugin-contract/schema/plugin-contract.schema.json`. Host business
+implementations under `electron/capabilities/catalog/` are reference material,
+not plugin authority. `infrastructure/ai/vaultAgentBridgeClient.ts` is not a
+plugin DTO sanitizer.

docs/plugin-platform/community-catalog.md

@@ -0,0 +1,106 @@
+# Curated plugin catalog
+
+The catalog lives in `electron/plugins/catalog.json` in this repository. There
+is no new marketplace account service or external directory repository. It is
+shipped with the app; catalog changes become available with an app update.
+Normal Settings exposes browser-only management and catalog browsing. Advanced
+local packages require `NETCATTY_PLUGIN_DEV=1`; that flag never grants permissions.
+Native acceptance and security/distribution review remain required before merge.
+
+## Submit or update a plugin
+
+Open a PR changing one entry. Provide:
+
+- Stable reverse-domain plugin ID, author, name and short description.
+- Public GitHub source repository and explicit license matching the package.
+- Exact version, full 40-character source commit and relative README `.md` path.
+- The complete validated manifest: engine/API ranges, required/optional permissions,
+  bounded resources, features and data/sync declarations must match package bytes.
+- Optional published artifact URL and SHA-256. No artifact means a source-only
+  example: the UI does not offer installation. Do not invent an artifact URL.
+- A concise change log, permission diff, supported OS test results, and synthetic
+  reproduction instructions. Current public runtime eligibility is browser-only
+  on the host platforms; native/platform-specific companions are excluded.
+
+Use the local CLI from the repository root:
+
+```sh
+npm ci
+npm run build:plugin-packages
+node packages/plugin-cli/dist/cli.js validate examples/plugins/hello-netcatty
+node packages/plugin-cli/dist/cli.js pack examples/plugins/hello-netcatty --out /tmp/hello-netcatty.ncpkg
+node packages/plugin-cli/dist/cli.js validate /tmp/hello-netcatty.ncpkg
+```
+
+The catalog contains first-party source examples: Plugin Starter for minimal
+settings/command use, and Hello Netcatty for terminal provider demonstrations.
+No downloadable release is fabricated or published by this change. A maintainer
+must verify real artifact provenance before adding the artifact object.
+
+## Enforced install boundary
+
+The renderer sends only a catalog ID. The main process selects the shipped
+entry, downloads over HTTPS from approved GitHub hosts with bounded size/time
+and redirects, checks SHA-256, and hands a private file to the same serialized
+PluginManager and PackageStore used for local imports. The immutable staged
+snapshot is hashed again before any version switch. Its exact ID/version,
+license and full manifest must match the catalog. Unknown permissions fail
+canonical schema validation. Browser-only eligibility rejects Node entrypoints,
+companions, raw terminal interceptors and advanced runtime declarations.
+
+The directory is a curated integrity assertion, not a publisher signature.
+Unsigned runtime grants remain bound to package digest. No latest fallback and
+no background code updates exist. Installing an update stops the old version;
+the new version remains disabled until reviewed and explicitly enabled. Required
+permissions are mediated again by the existing runtime permission engine.
+Local advanced development packages require the developer flag and use the existing permission model;
+this does not grant advanced privileges or make Node a sandbox.
+
+README is fetched only from the selected commit, on opening details. Redirects
+are refused and responses are limited to 256 KiB. Rendering constructs a small
+allowlist of React elements from Markdown; HTML remains escaped text and images
+are not fetched. Only explicit HTTPS links can be opened. README content is
+untrusted author documentation; permissions come from the manifest.
+
+## Review and maintenance
+
+CI now runs canonical plugin contract drift checks and the runtime suite,
+including catalog validation and install-boundary regression tests.
+Run `node --test electron/plugins/catalogService.test.cjs` and the plugin
+contract/runtime tests for every entry change. Review actual package/source
+provenance and permission/resource differences manually on first submission and
+sensitive updates. Packaging validation includes traversal/integrity checks but
+is not a malware audit. Human review is mandatory before adding an artifact;
+there is no automated acceptance bot in this slice.
+
+Authors maintain their plugins, document data handling and respond to security
+reports. Maintainers may remove entries or decline updates. Directory checks
+are limited checks, not a safety certification, legal waiver or a promise to
+repair third-party plugins. No third-party terms are copied here.
+
+## Data and lifecycle
+
+Local KV is per-plugin and does not sync. Only explicitly syncable non-secret
+settings enter encrypted sidecars; machine paths, grants, packages, runtime
+state and secrets do not become cloud authority. Existing sidecar conflict and
+account isolation mechanisms are reused. A generic KV sync API remains a separate
+schema/migration decision.
+
+Incompatible host/API/features disable plugins before lazy contributions are
+published, retain package/data and record a reason. A compatible downgrade never
+automatically re-enables them. Disable stops runtime and contributions; uninstall
+removes package code and local KV, while user-owned settings/secrets/sidecars
+remain. Existing crash quarantine and generation-bound cancellation apply.
+
+Missing OS-backed key storage blocks secrets/credentials, without blocking
+catalog browsing or non-secret plugins. The Settings manager reports this state;
+never switch to plaintext storage or disable Chromium sandboxing for a demo.
+
+## When permission prompts appear
+
+Enabled is an availability switch, not a security review or a grant. A lazy
+plugin can become enabled without starting code. Its first command/provider use
+starts the runtime; required permissions are authorized at that activation
+boundary. Optional permissions are requested when a broker operation needs them.
+Missing/denied decisions fail closed. Never interpret an Enabled badge as proof
+that terminal, credential, network or filesystem access has been approved.

docs/plugin-platform/contract-and-sdk.md

@@ -1,6 +1,6 @@
 # Netcatty plugin contract and SDK
 
-Status: internal preview (`0.1.0-internal`)
+Status: internal preview (`0.1.0-internal.1`; legacy `0.1.0-internal` remains offered)
 Tracking issue: [#2269](https://github.com/binaricat/Netcatty/issues/2269)
 
 Phases 2 and 3 consume this contract in the isolated host runtime and secure
@@ -615,3 +615,18 @@ npm run build:plugin-packages
 
 The complete application checks remain mandatory because workspace and root
 dependency changes affect installation and release builds.
+
+
+## Plugin brand icons (internal revision 0.1.0-internal.1)
+
+Optional top-level `icon` reuses `IconReference` from contributions. A package
+using it must require `metadata.brand-icon` and an API range accepting
+`0.1.0-internal.1` but excluding `0.1.0-internal`. See
+[the author guide](plugin-icons.md) for bounds and packaging commands.
+
+The host still offers the previous wire revision to plugins with no top-level
+icon whose range matches only that revision. Compatibility selection returns the
+negotiated API version and runtime initialization uses and verifies that exact
+version. Host version bounds remain independently enforced; unknown required
+features still fail closed. No old manifest is rewritten and no permission grant
+is migrated by this revision.

docs/plugin-platform/native-acceptance.md

@@ -0,0 +1,47 @@
+# Native Electron handoff
+
+Repository: binaricat/Netcatty. Frozen baseline: 0256e7471d66bbbca077c361ef379d7b11ce8465.
+Stack: feat/plugin-compatibility-review -> feat/plugin-settings-manager -> feat/plugin-curated-catalog.
+Use the final catalog branch for all three slices. Do not merge or release.
+
+1. Check out the branch on the approved desktop. Run npm ci and npm run build.
+2. Build the first-party sample:
+   npm run build:plugin-packages
+   node packages/plugin-cli/dist/cli.js pack examples/plugins/starter-netcatty --out /tmp/starter-netcatty.ncpkg
+   node packages/plugin-cli/dist/cli.js validate /tmp/starter-netcatty.ncpkg
+3. Launch the actual Electron binary without NETCATTY_PLUGIN_DEV and with a new disposable
+   --user-data-dir path, keeping Chromium sandbox enabled. Use the desktop's working
+   display and safe configuration; never --no-sandbox or real profiles/accounts.
+4. Settings > Plugins: record Community plugins list and Plugin Starter details.
+   Open README: actual pinned first-party GitHub retrieval; HTML inert, no remote images.
+   It intentionally says source-only: no downloadable artifact/release was invented.
+5. Import /tmp/starter-netcatty.ncpkg. It must remain disabled. Expand the installed
+   item: manifest permissions/resources, sensitive markers, Netcatty/API ranges,
+   SHA-256. Enable allows lazy activation; it does not grant permissions.
+   First command/view use prompts before runtime creation. Denying must not run code.
+6. With approved non-advanced permissions for the first-party example, edit Greeting
+   and open Starter: Greeting Panel (入门：问候面板) in the command palette.
+   Click Show greeting (显示问候语) and record the preference rendered in the panel.
+   No real host, cloud account, terminal credentials, runtime.advanced or third-party code.
+   Use Starter 0.1.1 or later. Its menus/views permissions support only the declared
+   command and sandboxed panel; do not expect terminal output.
+7. Disable, re-enable, close/restart the app with the same synthetic profile. Confirm
+   settings persist. Re-import same .ncpkg and verify it stops and stays disabled.
+8. Uninstall only the synthetic plugin using the two-step confirmation. Code/local KV
+   are removed; user-owned settings/secrets/sync sidecars have documented retention.
+9. On machines without a usable OS vault, the manager shows a downgrade notice;
+   secrets remain blocked but browsing and non-secret examples work.
+
+Compatibility upgrade/downgrade, required-feature changes, integrity mismatch,
+manifest mismatch, Node rejection, cleanup and traversal have automated synthetic
+coverage. Do not claim the above native steps were executed on this executor.
+
+This executor's native launch failed at Chromium's SUID sandbox configuration:
+chrome-sandbox is not root-owned mode 4755. No sandbox weakening was attempted.
+Native video is pending on the parent task's working desktop.
+
+10. Use the same AI-settings-style subpages: Installed and Community. Search by
+    name/author/description, open details and return. Verify README error/retry UI
+    if network is unavailable; do not bypass the network restriction.
+11. Inspect human-readable permission name, effect, scope, required/optional and
+    risk. Enabled means eligible for lazy activation, not permissions granted.

docs/plugin-platform/plugin-icons-proposal.md

@@ -0,0 +1,54 @@
+# Plugin manager window and brand icons
+
+Status: historical design investigation. The manager dialog and the accepted brand-icon design are now implemented. See [the current author guide](plugin-icons.md) for the shipped contract and bounds. The sections below preserve the original investigation and recommendations.
+
+## Manager window
+
+Settings > Plugins keeps an explicit Open plugin manager entry. The existing Radix Dialog opens a modal in the current renderer, up to 1180px wide and 88dvh high. Installed and Community, local import, manifest permissions and README remain inside it. Closing releases the mounted manager hooks; reopening starts at Installed. Detail Back stays inside the manager and preserves the Community search. Escape closes the manager and restores focus to its trigger.
+
+This uses the existing theme, dialog focus handling, plugin host and trusted bridge. A separate Electron BrowserWindow would require another renderer lifecycle, preload/context provisioning and trusted-sender review without providing a needed capability here. No window IPC, plugin runtime or grants are added.
+
+## Existing icon support
+
+- `packages/plugin-contract/schema/plugin-contract.schema.json`: `IconReference` is either a host-owned theme icon or a package icon with `light` and optional `dark` paths. It exists on commands, menus and views. `PluginManifest` has no top-level icon and rejects unknown properties.
+- `packages/plugin-cli/src/manifest.ts` validates contribution icon paths. `archive.ts` checks the declared resources during packaging and archive inspection. Missing files and unsafe paths are rejected.
+- `electron/plugins/contributionIconService.cjs` checks declaration ownership and current installed version before and after loading. It requires enabled/non-quarantined status, but does not require a running runtime. It reads a verified package root through `pluginProtocol.cjs` containment/realpath checks. Current input/output limits are 512 KiB, source edge 4096px, 16 megapixels, output edge 64px. Formats include PNG/WebP and SVG, JPEG, GIF, ICO.
+- `contributionIconRasterizer.cjs` decodes in a disposable sandboxed, network-denied BrowserWindow and returns bounded PNG data. Its SVG inspection is not a general SVG sanitizer; isolation/CSP/rasterization remain essential.
+- `application/state/usePluginContributionIcon.ts` discards stale requests. `components/plugins/PluginContributionIcon.tsx` selects light/dark images or a Puzzle fallback.
+- `PluginMarketplace.tsx` currently uses the host Package glyph. The catalog has no separately verified logo asset. Installed/detail surfaces do not expose a plugin brand logo.
+
+An author can already add a contribution icon (inside a command/menu/view):
+
+```json
+"icon": { "kind": "package", "light": "assets/action.png", "dark": "assets/action-dark.png" }
+```
+
+Include both files in the package and run CLI validate/pack. This changes that contribution's icon, not its market listing logo.
+
+## Proposed minimal brand-icon contract
+
+Reuse `IconReference`, adding an **optional** `PluginManifest.icon`; do not invent a URL/logo string format. A package brand icon would look like this after support ships:
+
+```json
+"icon": {
+  "kind": "package",
+  "light": "assets/logo.png",
+  "dark": "assets/logo-dark.webp"
+}
+```
+
+Recommended first version:
+
+- Static PNG or WebP, transparent background if desired; recommend a square 128–256px image. Enforce 256 KiB per source and a 512px maximum edge, validate MIME/signature and decoded dimensions, reject animated input, output bounded raster PNG. A single `light` asset works in both themes; `dark` is optional. Host theme icons can reuse the existing allowlist without package I/O.
+- Relative package paths only: no URL, absolute/drive/UNC paths, traversal, backslash, NUL, symlink escape or archive special entries. Do not read arbitrary renderer-supplied paths. Verify exact package hash/version and declaration on each uncached resolution; key caches by package identity/hash/theme, and discard stale results on update/uninstall.
+- Old plugins omit the field and continue to work with one shared host fallback. Per `contract-and-sdk.md`, adding this optional field requires an API/schema revision. New packages using it must declare the matching API range and required feature, plus a minimum host version that understands it: older strict schemas will reject an unknown field. Do not promise new-manifest compatibility with older hosts.
+- Extend the single contract and regenerate its consumers. Extend CLI path enumeration and both pack/archive checks; enforce image bounds during validation/import, not only in the UI. Reuse contained-file reads and the bounded rasterizer instead of adding file:// or runtime resource access in the application renderer.
+- Separate brand-image availability from contribution availability. Verified installed packages may show a logo while disabled without enabling or activating code. Do not loosen the existing contribution-icon enabled gate globally. Share the decoding implementation through a narrow brand-image operation that resolves the active installed declaration itself.
+- For uninstalled market entries, do not execute or install a plugin to obtain its logo. Use a small, catalog-reviewed static asset bundled with Netcatty, with its source commit and digest bound to that catalog version; absent assets use the same fallback. In particular the two current source-only examples have no downloadable artifact to extract. A later remote asset transport would need its own bounded allowlist/hash/redirect/cache policy and is outside this first proposal.
+- Use one brand-icon component in catalog cards, catalog details and installed lists/details. On decode/read failure keep the fallback and metadata/actions usable; do not fall back to a remote URL. Icons are decorative, with plugin names remaining accessible text.
+
+Do not add brand SVG support initially. Existing contribution SVG support is not removed. SVG brings XML/CSS/external-reference, filter and decoding complexity; supporting it for distribution means retaining isolated offline rasterization, bounded dimensions/time/concurrency and malformed/hostile-source tests. Raster PNG/WebP covers the initial need with less format complexity, though image decoders still require limits and isolation.
+
+## Validation required before implementing brand icons
+
+Contract/CLI tests should cover old manifests, optional fields, missing files, both themes, spoofed MIME, animation, oversized/zero dimensions, archive traversal and symlinks. Host tests should cover disabled installed packages without activation, source-only catalog fallback, stale update/uninstall results and no remote fetch. UI/native checks should cover all three surfaces, broken-image fallback, light/dark themes and accessible names. No new host, filesystem, network or terminal permission should be granted for displaying a verified logo.

docs/plugin-platform/plugin-icons.md

@@ -0,0 +1,81 @@
+# Add a plugin brand icon
+
+Brand icons appear on Community cards/details and Installed lists/details. They
+are optional; plugins without them retain a host-owned fallback. An icon does
+not activate code or grant plugin permissions.
+
+## Declare the icon
+
+Use the existing `IconReference` shape at the top level of `netcatty.plugin.json`:
+
+```json
+{
+  "engines": { "netcatty": ">=0.0.0", "api": ">=0.1.0-internal.1 <0.2.0" },
+  "features": { "required": ["metadata.brand-icon"] },
+  "icon": {
+    "kind": "package",
+    "light": "assets/logo-light.png",
+    "dark": "assets/logo-dark.webp"
+  }
+}
+```
+
+This is a manifest fragment. Preserve the required ID, name, version, publisher,
+main and other fields. The host-version value above is for this repository's
+unreleased development build (version 0.0.0); use the actual first supporting
+Netcatty release as your lower bound when it is assigned. Do not invent a release
+number. The API range and required feature enforce support in the meantime.
+
+Alternatively use a host-owned theme glyph, for example
+`"icon": { "kind": "theme", "name": "terminal" }`, with the same API/feature
+requirements. Theme glyphs use the existing host allowlist; unknown names fall back safely.
+
+## Prepare files
+
+Use a static PNG or WebP. A square transparent 128×128 or 256×256 image is
+recommended. Each source must be at most 256 KiB, with both dimensions between
+1 and 512 pixels. `dark` is optional; otherwise `light` is used in both themes.
+Use lowercase `.png` / `.webp` extensions matching the encoded bytes. Animated
+PNG/WebP and SVG are not accepted for brand icons. Existing contribution icons
+are unchanged, including their separately isolated SVG support.
+
+Paths are relative to the package root. URLs, absolute paths, traversal,
+backslashes and symlinks escaping the package are not supported. Include each
+referenced file in the package. No external image URL is loaded as a fallback.
+The host performs offline isolated decoding and displays a bounded PNG result;
+invalid or unreadable images fall back to the host glyph.
+
+## Validate and package
+
+From this repository, after building your plugin:
+
+```sh
+npm run build:plugin-packages
+node packages/plugin-cli/dist/cli.js validate examples/plugins/starter-netcatty
+node packages/plugin-cli/dist/cli.js compatibility examples/plugins/starter-netcatty --netcatty 0.0.0 --api 0.1.0-internal.1 --features metadata.brand-icon
+node packages/plugin-cli/dist/cli.js pack examples/plugins/starter-netcatty --out /tmp/starter-netcatty.ncpkg
+```
+
+Directory validation, packaging and imported-archive validation check declared
+brand files and bounds. The host reads installed metadata by plugin ID and
+verified package identity, not a renderer-provided file path. Disabled packages
+can display their icon; quarantined, missing or changed packages fall back. The
+existing enabled-only contribution icon service gate is not relaxed.
+
+## Community previews
+
+For an uninstalled plugin, the directory maintainer includes a reviewed raster
+preview in the application bundle. The preview binds the plugin ID, version,
+repository, source commit and icon declaration. Its bytes and SHA-256 are checked
+against the reviewed source files in tests. The current Starter preview uses its
+first-party source assets; source-only listings do not pretend to have a release
+artifact. Missing or mismatched previews use the same fallback, without fetching
+an image from the author's server. Submit the source assets and updated directory
+metadata through the existing repository PR review process.
+
+## Compatibility
+
+This is API/schema revision `0.1.0-internal.1`. An older host rejects the unknown
+manifest field or missing required feature. The new host continues to offer
+`0.1.0-internal` for legacy plugins without the new field, including exact old
+API ranges. Existing plugins need no manifest or data migration.

docs/plugin-platform/registry-client.md

@@ -0,0 +1,56 @@
+# Official registry client
+
+The Community page refreshes the fixed endpoint
+`https://raw.githubusercontent.com/binaricat/netcatty-plugins/main/catalog.json`
+in the main process. The renderer cannot choose a registry URL. This endpoint
+must be published separately; client implementation and synthetic tests do not
+prove the repository or an online artifact is available.
+
+## Catalog contract
+
+`catalog.json` is an array of at most 1,000 current entries. Each entry supplies
+`id`, `version`, `name`, `description`, `author`, `repository` (`owner/repository`),
+`commit` (full 40-character SHA), `license`, `readme` (relative Markdown path),
+and `manifest`. Optional `artifact` contains `url` and SHA-256 `sha256`.
+Unknown catalog-entry and artifact fields are rejected. The whole JSON value,
+including manifest defaults, uses the existing 128-level / 100,000-value budget
+and finite-number validation. The existing manifest schema, browser-only distribution policy, identity/version
+and license checks apply. Source-only entries remain build-and-import examples.
+No download counts, ratings, or timestamps are invented. Brand previews remain
+bundled and reviewed; arbitrary author image URLs are never loaded.
+
+Reads are anonymous HTTPS, redirect-free for the registry, bounded to 2 MiB,
+and time out after 30 seconds. All entries must validate, safely clone, and generate every selection token before
+atomically replacing the current snapshot. Invalid JSON/schema, network failure, and oversized responses
+leave the previous good snapshot intact. Errors and Retry remain visible. The Community header also has Refresh, including
+when the last refresh succeeded; it is disabled while a request is pending.
+The last good catalog is retained **in memory for this application session**;
+a fresh offline launch uses bundled examples. There is no new disk cache,
+database migration, cloud sync record, or credential requirement.
+
+## Selection and installation
+
+Each returned entry has a host-generated `selectionToken` covering its complete
+JSON contents. This is a concurrency check, **not a signature or trust proof**.
+README requests must still match that selection and fetch its pinned source
+commit. A changed entry requires refresh and renewed review.
+
+A manual install must first refresh the official catalog successfully and match
+the selected token again. Failed refresh is browse-only, even if the cached
+entry has an artifact. Withdrawal, version changes, permission changes, README
+changes, or artifact hash changes cannot silently replace the selected package.
+Archive download then uses the existing approved-host, size, exact SHA-256,
+manifest and package validation pipeline. Installation leaves the plugin disabled;
+existing authorization gates still apply on activation/use.
+
+`index.json` release history and withdrawal records are not consumed by this
+first client. Removing an entry does **not** disable, uninstall, update, or delete
+data from an already installed plugin. There are no background code updates.
+
+## Verification boundary
+
+Service regressions use synthetic network responses and package bytes; the
+existing package manager tests cover archive admission. No third-party plugin,
+real credential, real sync account, or live registry write is used. Native QA
+must separately verify the visible offline/retry state and eventual real catalog
+availability once the repository is published.

docs/plugin-platform/review-2026-10.md

@@ -0,0 +1,79 @@
+# Plugin platform implementation review
+
+Baseline: main `0256e7471d66bbbca077c361ef379d7b11ce8465` (2026-10-26).
+
+## Existing capabilities and gaps
+
+| Area | Implemented source | Remaining boundary |
+| --- | --- | --- |
+| Contract, SDK, package CLI | `packages/plugin-contract/schema`, `packages/plugin-sdk`, `packages/plugin-cli` | Internal API `0.1.0-internal`; no public API stability promise |
+| Runtime | `electron/plugins/browserPluginRuntime.cjs`, `utilityPluginRuntime.cjs`, `hostBootstrap.cjs` | Entire host remains development opt-in; advanced utility is ambient Node authority, not a fine-grained sandbox |
+| Permissions | `permissionEngine.cjs`, `hostRpcRegistry.cjs`, `secureCapabilities.cjs` | Broker checks at privileged boundary; unsigned principal bound to package digest; verified publisher/distribution not implemented |
+| UI contributions | `contributionService.cjs`, `components/plugins`, `SettingsPluginsTab.tsx` | Commands, menus, keybindings, settings and views exist; current Settings page is contributed settings, not a package manager/marketplace |
+| Terminal | `terminalProviderService.cjs`, `terminalDataPipelineService.cjs` | Completion/link/visual providers and lifecycle; interceptors require privileged utility placement; not arbitrary terminal object access |
+| Connection, authentication, importer | `extensionProviderService.cjs`, `application/state/pluginExtensionBridge.ts` | Existing operation-bound provider integration; not general vault/SFTP/clipboard CRUD |
+| Sync | `pluginSyncSidecarService.cjs`, `application/pluginSyncSidecarBridge.ts` | Opt-in non-secret settings and account/CRDT sidecars; ordinary KV is local, package code/permissions/secrets are not cloud authority |
+| Compatibility | `plugin-cli/src/compatibility.ts`, `packageStore.cjs`, `runtimeSupervisor.cjs` | Install/start checks existed; startup reconciliation and lazy re-enable checks missing |
+| Local package | `packageStore.cjs`, CLI `pack`, first-party `examples/plugins/hello-netcatty` | Immutable snapshot, hash/integrity validation and safe extraction exist; no ordinary import management UI |
+| Distribution | No public catalog implementation | Version/hash/pinned README, review workflow, manual update UI still needed |
+
+Historical merged steps: #2276 contract/SDK; #2303 runtime; #2315 permission/security;
+#2324 UI contributions; #2338 terminal providers; #2402 privileged terminal pipeline;
+#2413 connection/auth/importers; #2713 sync; #2748 and #2752 sync follow-up fixes.
+The repository AGENTS.md runtime section describes an earlier phase and must not
+be mistaken for a complete current capability inventory. No repository `.agents/skills`
+directory was present at this baseline.
+
+## Small implementation slices
+
+1. Reconcile host/API/features compatibility before contribution enumeration;
+   disable incompatible plugins and retain package/data, record the reason;
+   block lazy re-enable. Do not auto-enable after a host downgrade.
+2. Reuse the existing Settings Plugins tab and management IPC for installed
+   packages, manifest-derived permissions, version/hash and lifecycle actions;
+   local import starts disabled for review. Keep native permission mediation.
+3. Add a lightweight first-party catalog and pinned safe README detail renderer,
+   shared package verification, digest-bound manual update flow and author docs.
+   Do not introduce remote accounts, reviews, payments or a new repository.
+4. Reproduce the actual Electron flow with synthetic data and the first-party
+   sample; transfer source/build instructions if GUI is unavailable here.
+
+## Decisions and explicit release gates
+
+User approved public source plus a clear license for catalog entries, and manual
+confirmation of plugin updates. Private local packages remain separate.
+
+User-approved public v1 eligibility: browser runtime only. Utility Node, native
+companions and raw terminal interceptors retain the development preview path.
+This excludes advanced provider implementations requiring Node/native binaries;
+ordinary browser contributions, broker-backed networking and providers remain
+possible. No existing local advanced development path is removed.
+
+After product review, normal Settings now admits browser-only packages. The
+`NETCATTY_PLUGIN_DEV=1` flag gates advanced local packages only; their existing
+permission prompts remain mandatory. Shared host/UI classification preserves
+browser-first placement for dual-entry packages while excluding them from normal
+admission. Native acceptance remains pending. Passing tests is not proof of
+security isolation. Do not describe utility processes as broker-constrained.
+
+A future KV sync feature needs an explicit manifest opt-in schema, size limits,
+namespace and schema-version migrations, deterministic conflict/deletion rules,
+account switching semantics and secret exclusion. It is deliberately not silently
+enabled in this iteration. Reuse existing settings sidecars for small preferences.
+
+Catalog entries should bind ID, repository, license, author, version, commit,
+artifact SHA-256 and URL, platform/engine ranges, permissions and README revision.
+A hash mismatch must fail rather than fall back to latest. README must not execute
+HTML or automatically fetch remote media. Directory PR checks are a bounded
+review process, not a security certification or a guarantee that maintainers will
+repair third-party plugins.
+
+## Validation at the implementation stage
+
+The full repository TypeScript check has 773 diagnostics on both the frozen main
+and this implementation. After normalizing worktree paths and line shifts, no
+new diagnostics were introduced. This existing debt includes plugin integration
+types and should be addressed in a separate API-drift cleanup rather than being
+hidden by changing public contracts opportunistically. Canonical contract drift
+checking and plugin runtime tests pass for this implementation; native Electron
+UI acceptance is tracked separately in `native-acceptance.md`.

docs/plugin-platform/security-and-permissions.md

@@ -226,3 +226,30 @@ after durable user data can exist.
 - PR 9 supplies signed publisher principals and trust policy through placement;
   signed identity changes force a fresh grant instead of widening an unsigned
   grant silently.
+
+## Inspect and revoke actual grants
+
+The installed package detail separates declared permissions from **Active
+grants**. The host-only panel lists resource, scope, session (when applicable),
+and grant time. One-use decisions do not appear as retained grants. Refresh
+reads the engine again. Recent security events include at most 100 entries and
+project only event, time, permission, and scope. Arbitrary database details,
+operation IDs, terminal content, and credential material never cross this UI
+boundary.
+
+**Disable and revoke all grants** runs through the manager mutation queue. It
+persists disabled state before revoking grants, invalidates contributions, and
+waits for runtime shutdown. Existing runtime teardown cancels RPC, streams,
+leases, providers, and companions. A containment failure is reported as a
+failure and leaves the plugin disabled. Explicit enable requests fresh access.
+This management bridge is available only to the trusted app renderer. It is
+not a plugin RPC method and grants no plugin authority over another package.
+
+`PluginNetworkRequest` and `PluginNetworkResponse` now derive from the canonical
+schema. `credentialLease` and `authorization` describe the existing host lease
+injection path. Hosts advertise `network.credential-lease` for discovery without
+changing existing API versions or disabling legacy requests. Plugins may
+require that feature or handle its absence. Optional authorization defaults to
+Bearer. Basic authorization accepts a bounded username. Plaintext is redeemed
+only inside the host after origin permission and operation binding checks.
+See the [synthetic fixture](../../examples/plugins/lease-http/README.md).

docs/plugin-platform/theme-packs-design.md

@@ -0,0 +1,215 @@
+# Declarative theme packs
+
+Status: proposed implementation plan. No theme contribution or theme permission
+is implemented by this document. The baseline is Draft #3951 at
+`e5bd294cddbf58dfe04c646b6291933d980498fd`; batch 1 grants and network contracts
+are reviewed separately in Draft #3955.
+
+## Scope and existing behavior
+
+A theme pack supplies validated color data. Users preview, apply, cancel, or
+reset it through the host Appearance UI. Selecting a theme never starts a
+plugin runtime or approves its function permissions. This extends whole-app
+appearance alongside existing `terminal.theme` and `terminal.background`
+Providers and isolated view styles.
+
+Personal `customCSS` is a user-owned advanced setting, not a third-party plugin
+surface. This plan introduces no stylesheet, selector, DOM, font URL, image URL,
+script, layout, notification, or background permission.
+
+`UiThemeTokens` has 19 fields. They are not independent controls:
+`buildAppThemeCssVars()` assigns one effective accent to primary, accent, and
+ring and computes both accent foregrounds. The initial theme contract preserves
+this relationship. It must not accept independent primary, primaryForeground,
+accentForeground, or ring overrides and then silently discard them.
+
+## Contract and package admission
+
+The proposed feature is `appearance.theme-packs`. Its schema definitions,
+generated SDK exports, runtime/package compatibility, and documentation move
+together. Plan an internal schema/API revision with legacy negotiation retained;
+do not change the current batch 1 API just to publish this proposal. Old hosts
+reject a pack that requires the unknown feature before registration.
+
+A proposed `contributes.themes` entry contains:
+
+| Field | Meaning and validation |
+| --- | --- |
+| `id` | Contribution ID under the owning plugin namespace |
+| `label` | Existing bounded localized-text contract |
+| `variant` | `light`, `dark`, `hc-light`, or `hc-dark` |
+| `path` | Canonical package-relative JSON path inside the immutable installed version |
+
+A theme JSON document contains a schema revision, a variant-matching built-in
+base ID, bounded color overrides, and an optional static terminal palette.
+It contains no cross-plugin includes, arbitrary file references, inheritance
+chains, or remote resources. Resolve the validated base and overrides into one
+immutable complete palette before registration. Never retain partially valid
+entries from a failed theme document.
+
+The initial allowed UI overrides are `background`, `foreground`, `card`,
+`cardForeground`, `popover`, `popoverForeground`, `secondary`,
+`secondaryForeground`, `muted`, `mutedForeground`, `accent`, `destructive`,
+`destructiveForeground`, `border`, and `input`. Accept only opaque `#RRGGBB`
+colors. The host converts them to its internal HSL representation. Reject
+unknown keys, alpha, CSS expressions, `url()`, `var()`, `@import`, non-finite
+values, and custom properties. Do not pass author strings to CSS parsing.
+
+The optional terminal palette uses the existing `TerminalThemeColorName`
+allowlist. It merges with a host default and is validated independently.
+Static terminal colors require neither a session snapshot nor a Provider call.
+
+Initial bounds for implementation and tests are 32 themes per package,
+64 KiB per JSON file, 2 MiB total theme JSON, depth 8, and one active preview per
+window. These are proposed defaults, not existing limits. The schema and host
+must share the final constants. No font, image, or video assets enter v1.
+
+### Static admission must remain distinct from code activation
+
+The present manifest requires `main` and browser-only policy expects a browser
+entrypoint. Removing either check without a separate package variant is unsafe.
+
+For the first usable slice, a sample can retain a no-op browser entrypoint.
+Static theme registration must not invoke it. Theme enablement has a separate
+host-owned state from function/code enablement. Installing a pack keeps both
+off until a user opts into the corresponding contribution. Enabling its themes
+never sets the code-enabled flag, grants permissions, or runs activation events.
+Disabling the package disables its theme contributions as well as its code.
+
+A later exclusive data-only manifest variant can remove the no-op entrypoint.
+It must reject `main`, activation events, permissions, companions, providers,
+commands, and every non-theme contribution. Update canonical validation,
+semantic admission, package inspection, catalog policy, manager behavior, and
+compatibility tests together. The public catalog must explicitly recognize
+this inert variant while retaining browser-only admission for executable packs.
+A theme-only exception must not admit Node or an executable mixed package.
+
+## Host registry and persistence
+
+A host registry reads only installed, immutable package versions through the
+existing package-store path boundary. Verify real paths, file kinds, byte caps,
+and package ownership. Preserve the validated source version and content hash.
+No plugin RPC can register, apply, or replace global palette data.
+
+A committed selection references plugin ID, theme ID, variant, package version,
+and validated theme hash. Store per-variant selections and a monotonic commit
+revision through the settings/persistence layer. Do not persist plugin CSS or
+turn this into implicit KV/cloud synchronization. Preserve legacy built-in theme
+IDs and existing user settings when no plugin theme is selected.
+
+Theme availability records and applied preferences are user state, separate
+from runtime KV and function permissions. Define retained missing-selection
+metadata and uninstall behavior explicitly. Missing code or theme files must
+not trigger downloads, runtime activation, or new grants.
+
+## Preview, apply, cancel, and reset
+
+A single appearance resolver feeds existing chrome/terminal effects. Do not add
+a second root effect that races `useAppThemeStyle`, `useThemeRuntime`, or active
+terminal chrome selection.
+
+| Host action | Required behavior |
+| --- | --- |
+| Preview | Create a host-owned token bound to window, preview owner, selected immutable theme, and current committed revision. Render locally without storage writes, sync events, runtime activation, or other-window changes |
+| Apply | Verify owner, token, version/hash, availability, and expected commit revision. Commit the selected theme and explicitly chosen terminal linkage as one settings action. A stale preview produces a conflict, not an overwrite |
+| Cancel or close | Clear only the matching local preview token. Render the latest committed state. Never restore a captured old settings snapshot over a newer commit |
+| Reset | Clear the selected variant's plugin reference using the same revision check and apply the host default. Preserve font, accent, per-host terminal, and accessibility preferences |
+| Another window applies | Advance the shared commit revision. End the old preview or mark it stale; later cancel cannot alter the new selection |
+| Disable/uninstall/update | Invalidate matching previews and registry entries. Immediately resolve affected selections to a safe built-in variant, retain a bounded missing-reference notice, and never silently adopt unreviewed replacement bytes |
+| Application exit or window destruction | Release local preview ownership. Only committed preferences survive startup |
+
+The preview UI always identifies plugin source/version and has host-controlled
+Apply, Cancel, and Restore default controls. Those controls live inside the
+security appearance boundary. Theme data cannot control their labels, order,
+visibility, click behavior, or layout.
+
+Applying a theme changes only the selected palette and explicit terminal linkage.
+It does not overwrite user font family/size, accent override, host terminal
+override, reduced-motion choice, or OS accessibility preferences.
+
+## Appearance precedence and terminal behavior
+
+Resolve appearance in this order:
+
+1. Host security surfaces and OS accessibility requirements.
+2. Explicit user font, size, accent, and per-host/per-terminal overrides.
+3. The selected and validated theme pack.
+4. Built-in defaults.
+
+Define one effective accent using the current host rule. Reject impossible
+contrast combinations, including a user accent override against the effective
+surface, or show an explicit host correction before apply. Do not report an
+ignored author field as a successful override.
+
+Follow App may use the pack's static terminal palette. Manual terminal choices
+and per-host overrides retain precedence. Reuse the existing active-chrome
+selection rather than resetting app appearance on tab changes. Test Vault,
+SFTP, terminal, editor, Notes, logs, split panes, and detached windows.
+
+High-contrast flags in plugin environments are not proof that the host already
+has complete high-contrast themes. Missing HC variants require a host-owned HC
+fallback. Do not downgrade a forced-colors/high-contrast preference to an
+ordinary light/dark theme. Respect reduced motion and font scaling.
+
+## Security appearance and contrast gates
+
+Native Electron permission dialogs already sit outside renderer CSS. React
+security surfaces need a new explicit boundary before a theme pack ships.
+Cover AppLock, host-key trust, credential selection, grant/revoke management,
+dangerous confirmations, and theme preview/apply controls. Use host-controlled
+colors, font, icons, and layout there. Package colors never style those surfaces.
+The existing code has no verified shared boundary covering all of them.
+
+Color validation checks complete resolved/composited pairs, not only body text:
+foreground/background, card text/card, popover text/popover, secondary/muted
+text, accent/button text, destructive/button text, focus rings, borders, inputs,
+and selected/disabled states. Ordinary text needs 4.5:1, large text 3:1, and
+required non-text indicators 3:1 against adjacent surfaces. Reject a failing
+palette with a named pair and ratio, or show an explicit host correction.
+Tests must prove the effective UI, not only a helper's arithmetic.
+
+These gates follow [WCAG text contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
+and [non-text contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
+Theme screenshot review supplements contract, lifecycle, and accessibility
+checks. It does not establish safe ownership, persistence, or revocation.
+
+## Delivery stages and acceptance
+
+Current batch A grants and SDK consistency reaches review/CI first. Complete
+the controlled native interaction/context work as planned; theme work remains
+a separate small stage from marketplace card/layout changes.
+
+| Stage | Implementation and evidence |
+| --- | --- |
+| Contract and pure validation | Canonical schema/generated SDK, feature/revision negotiation, strict color parser, derived-accent semantics, static terminal palette, bounds, named contrast diagnostics, old manifest compatibility |
+| Registry and security boundary | Immutable package ownership, static registration without runtime, independent theme/code enablement, fixed security appearance, same-variant/HC fallback, unavailable/tampered version behavior |
+| Product workflow | Appearance grouping/source, local preview ownership, revision-safe apply/cancel/reset, safe defaults, system theme changes, terminal linkage and overrides, persistence and window synchronization |
+| Samples and final acceptance | Light/dark no-op-browser sample, normal settings import without advanced mode, no runtime/grants on theme apply, later data-only admission only if fully validated, exact-SHA tests/build/package/CI, Codex review/fix/review, parent-owned native recording |
+
+Boundary tests include unknown fields/feature, invalid or excessive JSON,
+unsupported variant/base, non-package and changed paths, unreadable colors,
+preview cancellation and window close, two-window apply/cancel ordering,
+update/disable/uninstall/failure fallback, startup restoration, host and accent
+overrides, forced colors, reduced motion, Chinese fonts/fallback, and every
+protected security surface. A pending gate keeps the theme row unfinished.
+
+Later controlled candidates are known-font recommendations, radius/density
+presets after component support exists, declarative file/folder icons, and
+package-local static backgrounds on fixed surfaces with contrast limits. They
+need separate contracts and acceptance. Global CSS, free layout, remote fonts,
+HTML/video backgrounds, and security-UI customization remain excluded.
+
+## Baseline source references
+
+- `infrastructure/config/uiThemes.ts`: token fields and built-in registry.
+- `application/state/settingsStateDefaults.ts`: accent derivation and built-in ID checks.
+- `application/state/appearanceSync.ts`, `appearanceChromeStore.ts`, and
+  `useSettingsState.ts`: persistence and cross-window behavior.
+- `application/app/useAppThemeStyle.ts`, `activeChromeTheme.ts`,
+  `application/state/useThemeRuntime.ts`, and `domain/terminalAppearance.ts`:
+  effective UI and terminal precedence.
+- `packages/plugin-sdk/src/index.ts`: existing terminal theme/background types.
+- `electron/plugins/pluginProtocol.cjs`: isolated view CSS/font/network CSP.
+- `lib/customCss.ts`: personal user CSS, excluded from plugin authority.
+- `domain/pluginRuntimePolicy.cjs` and the canonical manifest schema: executable admission.
+- `electron/plugins/nativePermissionDecision.cjs`: native permission prompts.

domain/pluginPermissionDescriptions.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+// Presentation only. Admission and grants remain owned by the canonical schema
+// and permission engine. Tests require exact coverage of its permission enum.
+const PERMISSION_DESCRIPTIONS = {
+  storage: [false, "Plugin storage", "Save and read this plugin's local data.", "插件存储", "保存和读取此插件自己的本地数据。"],
+  "runtime.advanced": [true, "Full device access", "Run Node code with filesystem and network access outside broker restrictions. Developer mode only.", "完整设备访问", "运行 Node 代码，可直接访问文件系统和网络，不受代理权限限制。仅限开发者模式。"],
+  "settings.read": [false, "Read plugin settings", "Read this plugin's configured preferences.", "读取插件设置", "读取此插件自己的设置。"],
+  "settings.write": [false, "Change plugin settings", "Update this plugin's preferences.", "修改插件设置", "修改此插件自己的设置。"],
+  commands: [false, "Plugin commands", "Register and run this plugin's own commands.", "插件命令", "注册和执行此插件自己的命令。"],
+  menus: [false, "Menu entries", "Add this plugin's actions to host menus.", "菜单入口", "将此插件的操作加入应用菜单。"],
+  views: [false, "Plugin panels", "Display plugin-owned panels inside the app.", "插件面板", "在应用中显示插件自己的面板。"],
+  "clipboard.read": [true, "Read clipboard", "Read copied text, which may contain passwords or other sensitive data.", "读取剪贴板", "读取复制的文本，其中可能包含密码或其他敏感数据。"],
+  "clipboard.write": [true, "Write clipboard", "Replace clipboard content that you may paste elsewhere.", "写入剪贴板", "替换剪贴板内容，可能影响你随后粘贴的数据。"],
+  "terminal.metadata": [true, "Terminal metadata", "Read terminal/session details that may identify hosts and activity.", "终端元数据", "读取终端和会话信息，可能暴露主机及操作活动。"],
+  "terminal.output": [true, "Read terminal output", "Receive terminal output through supported providers; it may contain credentials or private data.", "读取终端输出", "通过支持的提供器接收终端输出，其中可能包含凭据或隐私信息。"],
+  "terminal.input": [true, "Send terminal input", "Send input to a terminal; input may execute commands or change a remote host.", "发送终端输入", "向终端发送输入，可能执行命令或更改远程主机。"],
+  "terminal.decorate": [false, "Terminal presentation", "Provide annotations and visual changes to terminal content.", "终端展示", "为终端内容提供标注和视觉效果。"],
+  "terminal.complete": [true, "Terminal completion", "Receive completion context and suggest terminal input.", "终端补全", "接收补全上下文并建议终端输入。"],
+  "terminal.intercept.input": [true, "Rewrite terminal input", "Inspect and modify input before delivery. Not every secret/no-echo input can be detected. Developer mode only.", "改写终端输入", "检查并修改发送前的输入。无法识别所有秘密或无回显输入。仅限开发者模式。"],
+  "terminal.intercept.output": [true, "Rewrite terminal output", "Inspect and modify output, including information shown as command results. Developer mode only.", "改写终端输出", "检查并修改输出，包括呈现为命令结果的信息。仅限开发者模式。"],
+  "vault.metadata": [true, "Host inventory", "Read host metadata that can reveal infrastructure details.", "主机清单", "读取主机元数据，可能暴露基础设施信息。"],
+  "vault.write": [true, "Change host inventory", "Request changes to stored host records.", "修改主机清单", "请求更改保存的主机记录。"],
+  "vault.credentials": [true, "Use host credentials", "Use approved host credential references through operation-bound leases; this can authenticate to hosts.", "使用主机凭据", "通过绑定操作的租约使用已批准的主机凭据引用，可能用于向主机认证。"],
+  "sftp.read": [true, "Read remote files", "Read remote file content through supported host APIs.", "读取远程文件", "通过支持的宿主 API 读取远程文件内容。"],
+  "sftp.write": [true, "Change remote files", "Write or change remote files through supported host APIs.", "修改远程文件", "通过支持的宿主 API 写入或修改远程文件。"],
+  network: [true, "Network requests", "Contact approved origins. Data sent to them leaves this device.", "网络请求", "访问已批准的网络来源。发送的数据会离开此设备。"],
+  "filesystem.read": [true, "Read local files", "Read approved local paths, which may contain sensitive files.", "读取本地文件", "读取已批准的本地路径，其中可能包含敏感文件。"],
+  "filesystem.write": [true, "Change local files", "Write to approved local paths; existing content may be changed.", "修改本地文件", "写入已批准的本地路径，可能改变现有文件内容。"],
+  secrets: [true, "Plugin secrets", "Store and use this plugin's secrets through OS-backed storage and controlled leases.", "插件秘密", "通过系统密钥存储与受控租约保存和使用此插件的秘密。"],
+  "companion.execute": [true, "Run native programs", "Launch digest-verified companion executables with device authority. Developer mode only.", "运行本机程序", "启动经过摘要校验的辅助可执行程序，拥有设备权限。仅限开发者模式。"],
+  "provider.terminal": [true, "Terminal providers", "Provide terminal features; separate permissions govern access to terminal data.", "终端提供器", "提供终端扩展功能；终端数据访问由额外权限控制。"],
+  "provider.connection": [true, "Connection provider", "Implement a connection backend and handle its session data.", "连接提供器", "实现连接后端并处理对应会话数据。"],
+  "provider.authentication": [true, "Authentication provider", "Participate in login challenges using approved credential leases.", "认证提供器", "使用已批准的凭据租约参与登录验证。"],
+  "provider.sync": [true, "Encrypted sync storage", "Store encrypted sync objects; this permission does not provide the master key or plaintext vault.", "加密同步存储", "存储加密同步对象；此权限不提供主密钥或明文凭据库。"],
+  "provider.importer": [true, "Import provider", "Parse user-selected files into drafts for host review; input files may be sensitive.", "导入提供器", "解析用户选择的文件并生成供宿主确认的草稿；输入文件可能包含敏感数据。"],
+};
+function describePluginPermission(permission, locale = "en") {
+  const entry = Object.hasOwn(PERMISSION_DESCRIPTIONS, permission) ? PERMISSION_DESCRIPTIONS[permission] : null;
+  const chinese = locale.startsWith("zh");
+  if (!entry) return { known: false, sensitive: true, label: chinese ? "无法识别的权限" : "Unrecognized permission", description: chinese ? "此版本无法识别该权限，拒绝授权。" : "This version does not recognize this permission. Access is denied." };
+  return { known: true, sensitive: entry[0], label: entry[chinese ? 3 : 1], description: entry[chinese ? 4 : 2] };
+}
+module.exports = { PERMISSION_DESCRIPTIONS, describePluginPermission };

domain/pluginPermissionDescriptions.test.cjs

@@ -0,0 +1,15 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const schema = require('../packages/plugin-contract/schema/plugin-contract.schema.json');
+const { PERMISSION_DESCRIPTIONS, describePluginPermission } = require('./pluginPermissionDescriptions.cjs');
+test('permission explanation coverage cannot drift from the canonical permission catalog', () => {
+  assert.deepEqual(Object.keys(PERMISSION_DESCRIPTIONS).sort(), [...schema.$defs.PluginPermission.enum].sort());
+  for (const id of schema.$defs.PluginPermission.enum) {
+    for (const locale of ['en', 'zh-CN']) {
+      const description = describePluginPermission(id, locale);
+      assert.equal(description.known, true); assert.ok(description.description.length > 5);
+    }
+  }
+  assert.equal(describePluginPermission('unknown.permission').sensitive, true);
+  assert.equal(describePluginPermission('unknown.permission').known, false);
+});

domain/pluginRuntimePolicy.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+// Shared by host placement, release admission, and the installed-package UI.
+// A Node entrypoint does not change default placement, but is not admitted to
+// the normal browser-only product path.
+function describePluginRuntime(manifest) {
+  const providers = manifest?.contributes?.providers ?? [];
+  const permissions = [...(manifest?.permissions?.required ?? []), ...(manifest?.permissions?.optional ?? [])];
+  const permissionIds = permissions.map((entry) => typeof entry === "string" ? entry : entry.permission);
+  const hasCompanions = Boolean(manifest?.companionExecutables?.length);
+  const hasInterceptors = providers.some((provider) => (
+    provider.kind === "terminal.interceptor.input" || provider.kind === "terminal.interceptor.output"
+  ));
+  const declaresAdvanced = permissionIds.some((permission) => [
+    "runtime.advanced", "companion.execute", "terminal.intercept.input", "terminal.intercept.output",
+  ].includes(permission));
+  const hasBrowser = Boolean(manifest?.main?.browser);
+  const hasNode = Boolean(manifest?.main?.node);
+  const defaultRuntimeKind = hasBrowser && !hasCompanions && !hasInterceptors ? "browser" : "utility";
+  return {
+    defaultRuntimeKind,
+    hasNode,
+    declaresAdvanced,
+    browserOnly: hasBrowser && !hasNode && !hasCompanions && !hasInterceptors && !declaresAdvanced,
+  };
+}
+
+function assertBrowserOnlyPlugin(manifest) {
+  if (!describePluginRuntime(manifest).browserOnly) {
+    const error = new Error("This package requires advanced developer mode; normal plugin management accepts browser-only packages");
+    error.code = "PLUGIN_UNSUPPORTED_RUNTIME";
+    throw error;
+  }
+}
+
+module.exports = { describePluginRuntime, assertBrowserOnlyPlugin };

domain/pluginRuntimePolicy.test.cjs

@@ -0,0 +1,21 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const { describePluginRuntime, assertBrowserOnlyPlugin } = require('./pluginRuntimePolicy.cjs');
+
+test('dual entrypoints retain browser default placement but require developer admission', () => {
+  const manifest = { main: { browser: 'browser.js', node: 'node.js' } };
+  assert.equal(describePluginRuntime(manifest).defaultRuntimeKind, 'browser');
+  assert.equal(describePluginRuntime(manifest).hasNode, true);
+  assert.throws(() => assertBrowserOnlyPlugin(manifest), /developer mode/);
+});
+test('normal release admission rejects advanced declarations and privileged providers', () => {
+  assert.doesNotThrow(() => assertBrowserOnlyPlugin({ main: { browser: 'index.js' }, permissions: { required: ['settings.read', 'commands'] } }));
+  for (const permission of ['runtime.advanced', 'companion.execute', 'terminal.intercept.input', 'terminal.intercept.output']) {
+    for (const kind of ['required', 'optional']) {
+      assert.throws(() => assertBrowserOnlyPlugin({ main: { browser: 'index.js' }, permissions: { [kind]: [permission] } }), /developer mode/);
+    }
+  }
+  const manifest = { main: { browser: 'index.js', node: 'node.js' }, contributes: { providers: [{ kind: 'terminal.interceptor.input' }] } };
+  assert.equal(describePluginRuntime(manifest).defaultRuntimeKind, 'utility');
+  assert.throws(() => assertBrowserOnlyPlugin(manifest), /developer mode/);
+});

domain/singleChannelSshBanner.shared.cjs

@@ -16,9 +16,6 @@
 // CloudLinker — issue #3592: the vendor identifies a single-channel gateway
 // and proposes this distinctive banner. Older "Go" banners cannot identify it
 // safely; this compatibility entry requires the vendor banner change.
-// russh — issue #3973: russh returns CHANNEL_FAILURE for wantReply=false env
-// requests, desynchronizing ssh2's callback FIFO so pty-req/shell appear to
-// fail. Skip env via the single-channel path. No chunked-write evidence.
 // JumpServer KoKo advertises Version "JumpServer" and multiplexes. Omit it.
 
 const SINGLE_CHANNEL_SOFTWARE_TOKENS = Object.freeze([
@@ -26,7 +23,6 @@ const SINGLE_CHANNEL_SOFTWARE_TOKENS = Object.freeze([
   "TERM-SSHD",
   "CLOUDBILITY",
   "CLOUDLINKER",
-  "russh",
 ]);
 
 // #3146 also drops multi-character writes. That evidence is only for these

domain/singleChannelSshBanner.shared.mjs

@@ -16,9 +16,6 @@
 // CloudLinker — issue #3592: the vendor identifies a single-channel gateway
 // and proposes this distinctive banner. Older "Go" banners cannot identify it
 // safely; this compatibility entry requires the vendor banner change.
-// russh — issue #3973: russh returns CHANNEL_FAILURE for wantReply=false env
-// requests, desynchronizing ssh2's callback FIFO so pty-req/shell appear to
-// fail. Skip env via the single-channel path. No chunked-write evidence.
 // JumpServer KoKo advertises Version "JumpServer" and multiplexes. Omit it.
 
 const SINGLE_CHANNEL_SOFTWARE_TOKENS = Object.freeze([
@@ -26,7 +23,6 @@ const SINGLE_CHANNEL_SOFTWARE_TOKENS = Object.freeze([
   "TERM-SSHD",
   "CLOUDBILITY",
   "CLOUDLINKER",
-  "russh",
 ]);
 
 // #3146 also drops multi-character writes. That evidence is only for these

domain/singleChannelSshBanner.shared.test.cjs

@@ -20,10 +20,6 @@ test("single-channel banners match only the supported software tokens", () => {
     "CloudLinker",
     "SSH-2.0-CloudLinker",
     "cloudlinker-1.0",
-    "russh",
-    "SSH-2.0-russh",
-    "SSH-2.0-russh_0.45.0",
-    "RuSSH",
   ]) {
     assert.equal(remoteSoftwareRequiresSingleChannel(version), true, version);
   }
@@ -53,12 +49,6 @@ test("single-channel banner match ignores OpenSSH, JumpServer, and lookalike tok
     "SSH-2.0-Go",
     "notcloudlinker",
     "CloudLinkerProxy",
-    "russhd",
-    "myrussh",
-    "prerussh",
-    "russhserver",
-    "SSH-2.0-russhd",
-    "notRussh",
   ]) {
     assert.equal(remoteSoftwareRequiresSingleChannel(version), false, String(version));
   }
@@ -69,8 +59,6 @@ test("chunked-write limit stays on BHostSSH and TERM-SSHD", () => {
   assert.equal(remoteDisallowsChunkedChannelWrite("SSH-2.0-TERM-SSHD"), true);
   assert.equal(remoteDisallowsChunkedChannelWrite("CLOUDBILITY-4.14"), false);
   assert.equal(remoteDisallowsChunkedChannelWrite("SSH-2.0-CloudLinker"), false);
-  assert.equal(remoteDisallowsChunkedChannelWrite("SSH-2.0-russh"), false);
-  assert.equal(remoteDisallowsChunkedChannelWrite("SSH-2.0-russh_0.45.0"), false);
   assert.equal(remoteDisallowsChunkedChannelWrite("OpenSSH_9.6"), false);
   assert.equal(remoteDisallowsChunkedChannelWrite("superterm-sshd"), false);
 });
@@ -94,7 +82,7 @@ test("CommonJS and renderer modules agree on SSH banner behavior", async () => {
   const browserModule = await import("./singleChannelSshBanner.shared.mjs");
   const nodeModule = require("./singleChannelSshBanner.shared.cjs");
   for (const version of [
-    "BHostSSH_7.0", "TERM-SSHD", "CLOUDBILITY-4.14", "CloudLinker", "SSH-2.0-russh_0.45.0", "SSH-2.0-Go", "OpenSSH_9.6", "JumpServer", "",
+    "BHostSSH_7.0", "TERM-SSHD", "CLOUDBILITY-4.14", "CloudLinker", "SSH-2.0-Go", "OpenSSH_9.6", "JumpServer", "",
   ]) {
     assert.equal(browserModule.remoteSoftwareRequiresSingleChannel(version), nodeModule.remoteSoftwareRequiresSingleChannel(version));
     assert.equal(browserModule.remoteDisallowsChunkedChannelWrite(version), nodeModule.remoteDisallowsChunkedChannelWrite(version));

electron-builder.config.cjs

@@ -68,6 +68,8 @@ module.exports = {
         // Renderer and Mosh's main-process bootstrap share the same
         // fail-closed prompt classifier at runtime.
         'domain/terminalPromptSecurity.shared.cjs',
+        'domain/pluginRuntimePolicy.cjs',
+        'domain/pluginPermissionDescriptions.cjs',
         // Main-process SSH, SFTP, and port-forward bridges share this matcher.
         // TypeScript under domain/ is excluded below, so the .cjs must be listed.
         'domain/systemManager/containerRuntime.shared.cjs',

electron/bridges/ai/ptyExecHelpers.cjs

@@ -68,8 +68,7 @@ const PROMPT_SUFFIX_WINDOW_PER_PROMPT_CHAR = 8;
 
 function hasExpectedPromptSuffix(text, expectedPrompt) {
   if (!expectedPrompt) return false;
-  const ansiFreePrompt = stripAnsi(String(expectedPrompt || ""));
-  const normalizedPrompt = ansiFreePrompt.replace(/\r/g, "");
+  const normalizedPrompt = stripAnsi(String(expectedPrompt || "")).replace(/\r/g, "");
   if (!normalizedPrompt) return false;
   const fullText = String(text || "");
   const windowChars = Math.max(
@@ -77,17 +76,7 @@ function hasExpectedPromptSuffix(text, expectedPrompt) {
     String(expectedPrompt).length * PROMPT_SUFFIX_WINDOW_PER_PROMPT_CHAR,
   );
   const tail = fullText.length > windowChars ? fullText.slice(-windowChars) : fullText;
-  const strippedTail = stripAnsi(tail);
-  // Drop CR so a redraw inside one line (`root@host:~\r# `) still matches
-  // the cached prompt. That collapses a two-line PS1's `\r\r\n` to a single
-  // LF, which no longer ends with the cache (`user@host: /root\n\n\n$ `).
-  if (strippedTail.replace(/\r/g, "").endsWith(normalizedPrompt)) return true;
-  // The idle-prompt cache turns those CRs into LFs and keeps the blank
-  // lines. Compare that form too, only when the cache itself spans lines,
-  // so a bare `$`/`#` is unchanged.
-  if (!ansiFreePrompt.includes("\n")) return false;
-  const crAsLfPrompt = ansiFreePrompt.replace(/\r/g, "\n");
-  return strippedTail.replace(/\r/g, "\n").endsWith(crAsLfPrompt);
+  return stripAnsi(tail).replace(/\r/g, "").endsWith(normalizedPrompt);
 }
 
 function escapePosixSingleQuoted(text) {

electron/bridges/ai/ptyExecPromptSuffix.test.cjs

@@ -3,7 +3,7 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 const { hasExpectedPromptSuffix } = require("./ptyExecHelpers.cjs");
-const { extractTrailingIdlePrompt, stripAnsi } = require("./shellUtils.cjs");
+const { stripAnsi } = require("./shellUtils.cjs");
 
 // The behaviour before the tail window was introduced: normalise the whole
 // text, then compare its end.
@@ -41,38 +41,6 @@ test("prompt suffix is found after a very large flood of CRLF output", () => {
   assert.equal(hasExpectedPromptSuffix(`${flood}${COLORED_PROMPT}`, "root@3160T:~# "), true);
 });
 
-test("live PTY CR bytes match a cached two-line idle prompt", () => {
-  // Bash writes the PS1 newline as CR and ONLCR adds another, so the bytes
-  // are `\r\r\n`. The idle-prompt cache keeps those as blank lines. Suffix
-  // matching has to accept that form; stripping CR down to one LF does not.
-  const live = "user@host: /workspace\r\r\n$ ";
-  const cached = extractTrailingIdlePrompt(`welcome\r\n${live}`);
-  assert.equal(cached, "user@host: /workspace\n\n\n$ ");
-  const matchLive = hasExpectedPromptSuffix(live, cached);
-  assert.equal(matchLive, true);
-  assert.equal(hasExpectedPromptSuffix(`hostname\r\nbox\r\n${live}`, cached), true);
-  assert.equal(
-    hasExpectedPromptSuffix("\x1b[?2004huser@host: /workspace\r\r\n$ ", cached),
-    true,
-  );
-
-  const rootLive = "user@host: /root\r\r\n# ";
-  const rootCached = extractTrailingIdlePrompt(rootLive);
-  assert.equal(rootCached, "user@host: /root\n\n\n# ");
-  assert.equal(hasExpectedPromptSuffix(rootLive, rootCached), true);
-
-  // Readiness for a real LF two-line prompt still matches, and a bare
-  // `$`/`#` is neither this prompt nor a POSIX prompt on its own.
-  const lfCached = extractTrailingIdlePrompt("welcome\r\nuser@host: /workspace\n$ ");
-  assert.equal(lfCached, "user@host: /workspace\n$ ");
-  assert.equal(hasExpectedPromptSuffix("user@host: /workspace\n$ ", lfCached), true);
-  assert.equal(hasExpectedPromptSuffix("output\r\n$ ", cached), false);
-  assert.equal(hasExpectedPromptSuffix("$ ", cached), false);
-  assert.equal(hasExpectedPromptSuffix("# ", rootCached), false);
-  assert.equal(extractTrailingIdlePrompt("$ "), "");
-  assert.equal(extractTrailingIdlePrompt("# "), "");
-});
-
 test("prompt suffix check does not scan the whole buffer on every call", () => {
   // 2M characters of CRLF output used to cost seconds per call because every
   // call stripped ANSI and carriage returns over the entire text.

electron/bridges/ai/shellUtils.cjs

@@ -69,11 +69,6 @@ const CMD_PROMPT_PATTERN = /^[A-Za-z]:(?:\\[^<>"|]*)?>$/;
 //     the final `]` before `$`/`#` is the delimiter.
 const POSIX_PROMPT_PATTERN = /^(?:[^\s@]+@[^\s:]+(?::[^\n\r]*)?|\[[^\s@\]]+@[^\s\]:]+(?:\s+[^\n\r]+)?\])[#$]$/;
 
-// Host line of a two-line bash PS1 (`\u@\h: \w` then a following `$` or `#`).
-// Same user@host[:path] class as POSIX_PROMPT_PATTERN's first alternative,
-// without a prompt marker on this line. A bare `$`/`#` alone is not a prompt.
-const POSIX_PROMPT_HOST_LINE_PATTERN = /^[^\s@]+@[^\s:]+(?::[^\n\r]*)?$/;
-
 // Alpine's default ash PS1 omits the username: `\h:\w\$ ` -> `localhost:~# `.
 // Require a hostname and a home/absolute path, excluding prompt delimiters
 // within the path so partially entered commands do not count as idle prompts.
@@ -89,14 +84,7 @@ function isDefaultCmdPromptLine(line) {
 
 function isDefaultPosixPromptLine(line) {
   const normalized = String(line || "").replace(/\s+$/, "");
-  // Optional virtualenv / conda / BT-panel style env name prefix: "(name) "
-  // before the shell prompt. Recognition only; callers still return the full
-  // prompt line so suffix matching sees the visible prefix (#3947).
-  const withoutEnvPrefix = normalized.replace(/^\([^()\n\r]+\)\s+/, "");
-  return (
-    POSIX_PROMPT_PATTERN.test(withoutEnvPrefix) ||
-    ALPINE_PROMPT_PATTERN.test(withoutEnvPrefix)
-  );
+  return POSIX_PROMPT_PATTERN.test(normalized) || ALPINE_PROMPT_PATTERN.test(normalized);
 }
 
 function extractTrailingIdlePrompt(output) {
@@ -107,8 +95,7 @@ function extractTrailingIdlePrompt(output) {
   const normalized = stripAnsi(output).replace(/\r/g, "\n");
   if (!normalized || normalized.endsWith("\n")) return "";
 
-  const lines = normalized.split("\n");
-  const lastLine = lines.pop() || "";
+  const lastLine = normalized.split("\n").pop() || "";
   const rightTrimmed = lastLine.replace(/\s+$/, "");
   if (!rightTrimmed) return "";
 
@@ -124,24 +111,6 @@ function extractTrailingIdlePrompt(output) {
     return lastLine;
   }
 
-  // Two-line PS1 (`export PS1="\u@\h: \w\n$ "`). Bash emits the newline as
-  // CR and the PTY's ONLCR adds another, so the bytes are `\r\r\n`. The
-  // CR-to-LF normalize above turns that into blank lines between the host
-  // line and `$`/`#`. Keep those blanks in the cache: getFreshIdlePrompt
-  // uses the same normalize, and hasExpectedPromptSuffix compares this
-  // CR-as-LF form against live PTY bytes. A lone `$` must not satisfy endsWith.
-  if (rightTrimmed === "$" || rightTrimmed === "#") {
-    let hostIndex = lines.length - 1;
-    while (hostIndex >= 0 && lines[hostIndex].replace(/\s+$/, "") === "") {
-      hostIndex -= 1;
-    }
-    const previousLine = hostIndex >= 0 ? lines[hostIndex] : "";
-    const previousRightTrimmed = previousLine.replace(/\s+$/, "");
-    if (POSIX_PROMPT_HOST_LINE_PATTERN.test(previousRightTrimmed)) {
-      return `${lines.slice(hostIndex).join("\n")}\n${lastLine}`;
-    }
-  }
-
   return "";
 }
 
@@ -202,8 +171,7 @@ function trackSessionIdlePrompt(session, chunk) {
 // Return `session.lastIdlePrompt` only if the PTY's recent rolling tail
 // still ends with it. The cached prompt is updated only when
 // extractTrailingIdlePrompt recognizes a known shape (PowerShell, cmd.exe,
-// `user@host[:path][#$]`, two-line `user@host[:path]` + `$`/`#`,
-// RHEL `[user@host path][#$]`, or Alpine `host:path[#$]`);
+// `user@host[:path][#$]`, RHEL `[user@host path][#$]`, or Alpine `host:path[#$]`);
 // a remote shell switch into another shell, an oh-my-posh / starship / custom
 // PS1, or any unrecognized prompt would
 // otherwise leave a stale value behind, which `resolveEffectiveShellKind`

electron/bridges/ai/shellUtils.test.cjs

@@ -219,97 +219,6 @@ test("extracts a trailing RHEL-family bracketed idle prompt", () => {
   assert.equal(extractTrailingIdlePrompt("welcome\r\nroot@host ~#"), "");
 });
 
-test("extractTrailingIdlePrompt recognizes a two-line user@host then bare $/# PS1", () => {
-  // export PS1="\u@\h: \w\n$ " paints the host line, then a lone "$ ".
-  // The cached prompt must keep both lines so a lone "$" cannot satisfy endsWith.
-  assert.equal(
-    extractTrailingIdlePrompt("welcome\r\nuser@host: /home/foo\n$ "),
-    "user@host: /home/foo\n$ ",
-  );
-  assert.equal(
-    extractTrailingIdlePrompt("welcome\r\nroot@host: /root\n# "),
-    "root@host: /root\n# ",
-  );
-  // Live bash PTY: prompt CR plus ONLCR is `\r\r\n`, which this normalizer
-  // stores as blank lines. The cache must keep them so endsWith still matches.
-  assert.equal(
-    extractTrailingIdlePrompt("\x1b[?2004huser@host: /home/foo\r\r\n$ "),
-    "user@host: /home/foo\n\n\n$ ",
-  );
-  assert.equal(
-    extractTrailingIdlePrompt("\x1b[?2004hroot@host: /root\r\r\n# "),
-    "root@host: /root\n\n\n# ",
-  );
-  assert.equal(extractTrailingIdlePrompt("$ "), "");
-  assert.equal(extractTrailingIdlePrompt("# "), "");
-  assert.equal(extractTrailingIdlePrompt("welcome\r\n$ "), "");
-  assert.equal(extractTrailingIdlePrompt("not a host line\n$ "), "");
-  assert.equal(extractTrailingIdlePrompt("copied output\n# "), "");
-  assert.equal(isDefaultPosixPromptLine("$"), false);
-  assert.equal(isDefaultPosixPromptLine("#"), false);
-  assert.equal(isDefaultPosixPromptLine("$ "), false);
-  assert.equal(isDefaultPosixPromptLine("# "), false);
-});
-
-test("trackSessionIdlePrompt and getFreshIdlePrompt accept a two-line user@host PS1", () => {
-  const session = {};
-  const prompt = "user@host: /home/foo\n$ ";
-  trackSessionIdlePrompt(session, `welcome\r\n${prompt}`);
-  assert.equal(getFreshIdlePrompt(session), prompt);
-
-  const ptySession = {};
-  trackSessionIdlePrompt(ptySession, "\x1b[?2004huser@host: /home/foo\r\r\n$ ");
-  assert.equal(getFreshIdlePrompt(ptySession), "user@host: /home/foo\n\n\n$ ");
-});
-
-test("extractTrailingIdlePrompt still recognizes a classic single-line POSIX prompt", () => {
-  assert.equal(extractTrailingIdlePrompt("welcome\r\nuser@host:~$ "), "user@host:~$ ");
-});
-
-test("isDefaultPosixPromptLine accepts virtualenv, conda, and BT-panel env prefixes", () => {
-  // Python venv / conda / BT-panel prepend "(name) " before the real prompt.
-  // Recognition strips that prefix; a missing space after ")" is already
-  // accepted because the username class absorbs the parens (#3947).
-  for (const prompt of [
-    "(3.12.12) root@example:~# ",
-    "(3.12.12) root@example:~#",
-    "(venv) alice@host:~$ ",
-    "(base) [opc@host ~]$ ",
-    "(my-env) localhost:~# ",
-    "(3.12.12)root@example:~# ",
-  ]) {
-    assert.equal(isDefaultPosixPromptLine(prompt), true, prompt);
-  }
-});
-
-test("extractTrailingIdlePrompt keeps the full env-prefixed POSIX prompt", () => {
-  // Suffix matching compares the visible PTY line, so the captured prompt
-  // must still include the "(name) " prefix rather than the stripped form.
-  for (const prompt of [
-    "(3.12.12) root@example:~# ",
-    "(3.12.12) root@example:~#",
-    "(venv) alice@host:~$ ",
-    "(base) [opc@host ~]$ ",
-    "(my-env) localhost:~# ",
-  ]) {
-    assert.equal(extractTrailingIdlePrompt(`Last login\r\n${prompt}`), prompt, prompt);
-  }
-});
-
-test("env-prefixed POSIX recognition rejects incomplete prefixes and non-prompts", () => {
-  for (const line of [
-    "(3.12.12 root@example:~# ",
-    "(3.12.12) root@example:~# printf busy",
-    "(venv) not a prompt",
-    "root@host ~#",
-    "(base) [opc@host ~]$ printf busy",
-    "(my-env) localhost:~# printf busy",
-  ]) {
-    assert.equal(isDefaultPosixPromptLine(line), false, line);
-    assert.equal(extractTrailingIdlePrompt(`welcome\r\n${line}`), "", line);
-  }
-});
-
 test("isPlausibleCliVersionOutput rejects stack traces and file URLs", () => {
   assert.equal(isPlausibleCliVersionOutput("2.1.123 (Claude Code)"), true);
   assert.equal(isPlausibleCliVersionOutput("codex-cli 0.125.0"), true);

electron/bridges/sftpBridge.otpTransportReuse.test.cjs

@@ -836,105 +836,6 @@ test("sudo SFTP-page transfer reuses the elevated channel instead of dialing aga
   assert.equal(sftpClients.has("browse-sudo"), true);
 });
 
-for (const [ident, sequential] of [
-  ["OpenSSH_9.6", false],
-  ["CLOUDBILITY-4.14", true],
-  ["TERM-SSHD", true],
-]) {
-  test(`sudo transfer aliases preserve ${ident} upload concurrency`, { timeout: 15000 }, async (t) => {
-    const server = await startOtpOnlyServer({ ident });
-    pool.resetSshTransportRegistryForTests({ defaultIdleTtlMs: 0 });
-    const sftpClients = new Map();
-    sftpBridge.init({ sftpClients, sessions: new Map(), electronModule: {} });
-    transferBridge.init({ sftpClients });
-    t.after(async () => {
-      for (const sftpId of [...sftpClients.keys()].reverse()) {
-        await sftpBridge.closeSftp(null, { sftpId }).catch(() => {});
-      }
-      pool.discardAllTransports("test-end");
-      pool.resetSshTransportRegistryForTests({ defaultIdleTtlMs: 0 });
-      await server.close();
-    });
-
-    const options = { ...BASE_OPTIONS(server.port), reuseTransport: false };
-    const sender = createSender();
-    const opening = sftpBridge.openSftp({ sender }, { ...options, sessionId: "sudo-owner" });
-    opening.catch(() => {});
-    await waitFor(() => answerOtpPrompts(sender));
-    const opened = await opening;
-    const owner = sftpClients.get(opened.sftpId);
-    // Model an already-elevated channel. The real SSH/SFTP peer remains the
-    // ordinary server or bastion above; no second sudo/authentication is needed.
-    const sudoOptions = { ...BASE_OPTIONS(server.port), sudo: true };
-    const endpoint = pool.buildConnectionReuseEndpoint(sudoOptions, { sftpSudo: true });
-    owner.__netcattySudoMode = true;
-    owner.__netcattyEndpointKey = pool.buildEndpointKey(endpoint);
-    owner.__netcattyChannelAdoptionKey = pool.buildChannelAdoptionKey(endpoint);
-    const firstAlias = await sftpBridge.openSftp({ sender: createSender() }, sudoOptions);
-    const secondAlias = await sftpBridge.openSftp({ sender: createSender() }, sudoOptions);
-    for (const alias of [firstAlias, secondAlias]) {
-      const client = sftpClients.get(alias.sftpId);
-      assert.equal(client.__netcattySharedChannelAlias, true);
-      assert.equal(client.__netcattySudoMode, true);
-      assert.equal(client.sftp, owner.sftp, "both uploads must retain the elevated channel");
-    }
-
-    const root = fs.mkdtempSync(`${tempDirBridge.getTempFilePath("sudo-concurrency")}-`);
-    t.after(() => fs.rmSync(root, { recursive: true, force: true }));
-    const source = path.join(root, "source.bin");
-    const payload = Buffer.alloc(3 * 32768 + 17, 0x5a);
-    fs.writeFileSync(source, payload);
-    const firstPath = "/home/otpuser/first.bin";
-    const secondPath = "/home/otpuser/second.bin";
-    server.files.set(firstPath, Buffer.from("original file"));
-    const channel = owner.sftp;
-    const originalLstat = channel.lstat.bind(channel);
-    let firstTargetChecks = 0;
-    let promotionStarted;
-    const promotionStartedPromise = new Promise((resolve) => { promotionStarted = resolve; });
-    let releasePromotion;
-    const promotionGate = new Promise((resolve) => { releasePromotion = resolve; });
-    channel.lstat = (remotePath, ...args) => {
-      if (String(remotePath) === firstPath && ++firstTargetChecks === 2) {
-        promotionStarted();
-        void promotionGate.then(() => originalLstat(remotePath, ...args));
-        return;
-      }
-      originalLstat(remotePath, ...args);
-    };
-    const upload = (alias, targetPath) => transferBridge.startTransfer({ sender: createSender() }, {
-      transferId: `sudo-concurrency-${ident}-${path.basename(targetPath)}`,
-      sourcePath: source, targetPath,
-      sourceType: "local", targetType: "sftp", targetSftpId: alias.sftpId,
-      totalBytes: payload.length, resumable: true,
-    });
-    let firstFinished = false;
-    let secondFinished = false;
-    const first = upload(firstAlias, firstPath).then((result) => { firstFinished = true; return result; });
-    let second;
-    let results;
-    try {
-      await promotionStartedPromise;
-      second = upload(secondAlias, secondPath).then((result) => { secondFinished = true; return result; });
-      await waitFor(() => secondFinished
-        || transferBridge._getSessionFastDownloadWaiterCountForTests(channel) > 0);
-      assert.equal(firstFinished, false, "the first upload must still be held before publication");
-      assert.equal(secondFinished, !sequential,
-        sequential ? "a bastion must wait for the first promotion" : "ordinary sudo uploads must remain concurrent");
-      assert.equal(transferBridge._getSessionFastDownloadWaiterCountForTests(channel), sequential ? 1 : 0);
-    } finally {
-      releasePromotion();
-      results = await Promise.all(second ? [first, second] : [first]);
-      channel.lstat = originalLstat;
-    }
-    for (const result of results) assert.equal(result.error, undefined, result.error);
-    assert.deepEqual(server.files.get(firstPath), payload);
-    assert.deepEqual(server.files.get(secondPath), payload);
-    assert.equal(server.getConnectionCount(), 1, "sudo uploads must not open an unelevated connection");
-    assert.equal(server.getKeyboardInteractiveRounds(), 1, "uploads must not ask for another OTP");
-  });
-}
-
 test("reconnecting the soft-closed owner id does not replace it with a self-alias (#3310)", async (t) => {
   const { sftpTransferSessionLeaseStore, channelAliasLeaseId } = require("./sftpTransferSessionLease.cjs");
   pool.resetSshTransportRegistryForTests({ defaultIdleTtlMs: 0 });

electron/bridges/transferBridge.cjs

@@ -2474,68 +2474,16 @@ async function acquireSessionFastDownloadSlot(client, transfer) {
   }
 }
 
-function isSingleChannelSftpClient(client) {
-  return Boolean(
-    client?.__netcattySingleChannelSsh
-    || client?.client?.__netcattySingleChannelSsh,
-  );
-}
-
-function requiresExclusiveSftpTransferChannel(client, channel) {
-  // Aliases stay on one authenticated/elevated channel, even on ordinary SSH
-  // servers. Only the owning peer's restriction requires serial transfers.
-  const peer = client?.__netcattySharedChannelAlias
-    ? sftpClients?.get(client.__netcattySharedChannelOwnerId) || client
-    : client;
-  return isSingleChannelSftpClient(peer)
-    || getSftpTransferConcurrency(channel, DOWNLOAD_TRANSFER_CONCURRENCY) === 1;
-}
-
-/**
- * Some single-channel gateways cannot safely interleave SFTP metadata and
- * write requests from different files. Serialize the complete upload
- * transaction per raw SFTP stream while leaving independent connections free.
- */
-async function acquireExclusiveSftpTransferTransaction(client, transfer) {
-  if (isScpModeClient(client)) return null;
-  // Preserve the normal lazy SFTP-open path. Only known single-channel peers
-  // acquire the transaction slot before the upload itself opens a handle.
-  const knownChannel = client?.sftp || { _client: client?.client };
-  if (!requiresExclusiveSftpTransferChannel(client, knownChannel)) return null;
-  await requireSftpChannel(client);
-  const channel = client.sftp;
-  if (transfer?._exclusiveSftpTransactionChannel === channel) return null;
-
-  await acquireSessionFastDownloadSlot(channel, transfer);
-  transfer._exclusiveSftpTransactionChannel = channel;
-  let released = false;
-  return {
-    client,
-    channel,
-    release() {
-      if (released) return;
-      released = true;
-      if (transfer._exclusiveSftpTransactionChannel === channel) {
-        transfer._exclusiveSftpTransactionChannel = null;
-      }
-      releaseSessionFastDownloadSlot(channel);
-    },
-  };
-}
-
-// Single-channel compatibility permits only one transfer operation per raw
-// SFTP stream. A per-file request limit is insufficient because pooled aliases
-// share the physical channel, and even a tiny file's second OPEN or verification
-// read can fail. Reuse the cancelable one-slot queue keyed by stream rather
-// than wrapper client across both directions and complete verification.
+// TERM-SSHD compatibility requires one file handle per channel. Per-file request
+// concurrency is not enough: pooled SFTP aliases share that physical channel,
+// and a second body or verification OPEN would fail even for tiny files.
+// Reuse the cancelable one-slot queue, keyed by the stream rather than its
+// wrapper client, across both directions and the complete verification phase.
 async function withSequentialSftpTransferSlot(client, transfer, operation) {
   if (isScpModeClient(client)) return operation();
   await requireSftpChannel(client);
   const channel = client.sftp;
-  if (transfer?._exclusiveSftpTransactionChannel === channel) {
-    return operation();
-  }
-  if (!requiresExclusiveSftpTransferChannel(client, channel)) {
+  if (getSftpTransferConcurrency(channel, DOWNLOAD_TRANSFER_CONCURRENCY) !== 1) {
     return operation();
   }
   await acquireSessionFastDownloadSlot(channel, transfer);
@@ -6677,7 +6625,6 @@ async function startTransferNow(event, payload, onProgress) {
     });
   };
 
-  let exclusiveSftpUploadTransaction = null;
   try {
     // Explicit 0 is a valid empty-snapshot plan (e.g. download of an empty log
     // that may grow later). Do not treat it as "size unknown" and re-stat into
@@ -6805,16 +6752,6 @@ async function startTransferNow(event, payload, onProgress) {
       else await verify();
     }
 
-    // A single-channel upload holds the raw SFTP stream from directory setup
-    // through stage verification, destination safety checks, promotion, and
-    // timestamp restoration so directory children cannot interleave requests.
-    if (sourceType === "local" && targetType === "sftp" && targetClient) {
-      exclusiveSftpUploadTransaction = await acquireExclusiveSftpTransferTransaction(
-        targetClient,
-        transfer,
-      );
-    }
-
     sendProgress(transfer.checkpointBytes, fileSize, { force: true });
 
     if (sourceType === 'local' && targetType === 'sftp') {
@@ -7443,13 +7380,6 @@ async function startTransferNow(event, payload, onProgress) {
 
     return { transferId, totalBytes: fileSize, ...(transfer.warning ? { warning: transfer.warning } : {}) };
   } catch (err) {
-    if (
-      exclusiveSftpUploadTransaction
-      && err?.uncleanSftpChannel
-      && exclusiveSftpUploadTransaction.client.sftp === exclusiveSftpUploadTransaction.channel
-    ) {
-      abandonWedgedVerificationSftpChannel(exclusiveSftpUploadTransaction.client);
-    }
     const failureMessage = err?.message || String(err);
     if (
       sourceType === "local"
@@ -7535,8 +7465,6 @@ async function startTransferNow(event, payload, onProgress) {
       sendError(err);
     }
     return { transferId, error: err.message };
-  } finally {
-    exclusiveSftpUploadTransaction?.release();
   }
 }
 

electron/bridges/transferBridge.termSshd.test.cjs

@@ -233,7 +233,6 @@ async function createSequentialTransferFixture(t) {
   return {
     payload, files, sftp, handles, clients,
     rejectedOpens: () => rejectedOpens,
-    openCount: () => opens,
     async start(direction, sftpId = "first", options = {}) {
       const transferId = options.transferId || crypto.randomUUID();
       const localPath = tempDirBridge.getTempFilePath(`term-concurrent-${transferId}.bin`);
@@ -264,61 +263,6 @@ async function createSequentialTransferFixture(t) {
   };
 }
 
-test("single-channel upload waits for the prior promotion before starting the next file", { timeout: 5_000 }, async (t) => {
-  const fixture = await createSequentialTransferFixture(t);
-  const originalLstat = fixture.sftp.lstat;
-  let lstatCalls = 0;
-  let promotionStarted;
-  const promotionStartedPromise = new Promise((resolve) => { promotionStarted = resolve; });
-  let releasePromotion;
-  const promotionGate = new Promise((resolve) => { releasePromotion = resolve; });
-
-  fixture.sftp.lstat = (remotePath, callback) => {
-    lstatCalls += 1;
-    // The first two calls inspect the recovery backup and initial destination.
-    // The third is the final safety check after the .part write; hold it to
-    // prove that the next file cannot acquire the channel yet.
-    if (lstatCalls === 3) {
-      promotionStarted();
-      void promotionGate.then(() => originalLstat(remotePath, callback));
-      return;
-    }
-    originalLstat(remotePath, callback);
-  };
-
-  const first = fixture.start("upload", "first");
-  await promotionStartedPromise;
-  const openCountAtPromotion = fixture.openCount();
-  const second = fixture.start("upload", "alias");
-  let firstResult;
-  let secondResult;
-  try {
-    // start() first writes its local source. Wait until the second upload
-    // actually queues, or incorrectly starts remote work, before asserting.
-    const deadline = Date.now() + 1_000;
-    while (
-      transferBridge._getSessionFastDownloadWaiterCountForTests(fixture.sftp) === 0
-      && lstatCalls === 3
-      && fixture.openCount() === openCountAtPromotion
-      && Date.now() < deadline
-    ) {
-      await new Promise((resolve) => setImmediate(resolve));
-    }
-    assert.equal(lstatCalls, 3, "the next file must not inspect its target during prior promotion");
-    assert.equal(fixture.openCount(), openCountAtPromotion, "the next file must not open a remote handle during prior promotion");
-    assert.equal(transferBridge._getSessionFastDownloadWaiterCountForTests(fixture.sftp), 1,
-      "the second upload must be waiting for the shared channel");
-  } finally {
-    releasePromotion();
-    [firstResult, secondResult] = await Promise.all([first, second]);
-  }
-  assert.equal(firstResult.result.error, undefined);
-  assert.equal(secondResult.result.error, undefined);
-  assert.deepEqual(fixture.files.get(firstResult.targetPath), fixture.payload);
-  assert.deepEqual(fixture.files.get(secondResult.targetPath), fixture.payload);
-  assert.equal(fixture.rejectedOpens(), 0);
-});
-
 for (const secondId of ["first", "alias"]) {
   test(`TERM-SSHD small downloads serialize through body and verification (${secondId})`, async (t) => {
     const fixture = await createSequentialTransferFixture(t);

electron/bridges/zmodemHelper.cjs

@@ -138,7 +138,6 @@ function createZmodemSentry(opts) {
   let pendingTerminalSuppressionAt = 0;
   let pendingHexHeaderFragment = null;
   let pendingHexHeaderFragmentTimer = null;
-  let emittedHexHeaderPrefixBytes = 0;
   // Set when a stripped hex header's trailing XON (0x11) may arrive in the
   // next terminal-output chunk; at most one byte is then dropped.
   let suppressNextTerminalXon = false;
@@ -173,11 +172,6 @@ function createZmodemSentry(opts) {
   const HEX_HEADER_FRAGMENT_TTL_MS = Number.isFinite(opts.hexHeaderFragmentTtlMs)
     ? Math.max(1, opts.hexHeaderFragmentTtlMs)
     : 1000;
-  // A bare "*" or "**" is also ordinary shell echo (#3959). Give this
-  // ambiguous printable prefix at most one frame to complete, rather than
-  // holding every typed/pasted star for the full protocol timeout. Once
-  // ZDLE arrives, retain the longer timeout for fragmented protocol bytes.
-  const PRINTABLE_HEX_PREFIX_TTL_MS = Math.min(16, HEX_HEADER_FRAGMENT_TTL_MS);
   /**
    * Upper bound on how long a drag-drop echo suppression may stay armed.
    * The suppression hides the terminal echo of the upload command, whose echo
@@ -314,10 +308,6 @@ function createZmodemSentry(opts) {
         buf.subarray(0, prefixAt),
         buf.subarray(prefixAt + headerLength),
       ]);
-      // Printable prefix bytes may already have been shown after the short
-      // echo timeout. If they belonged to this header, do not skip bytes
-      // from the ordinary output that follows the stripped header.
-      emittedHexHeaderPrefixBytes = Math.min(emittedHexHeaderPrefixBytes, prefixAt);
       searchFrom = prefixAt;
     }
 
@@ -327,17 +317,8 @@ function createZmodemSentry(opts) {
   function flushPendingHexHeaderFragment() {
     pendingHexHeaderFragmentTimer = null;
     const buf = pendingHexHeaderFragment;
-    if (!buf?.length) return;
-    const output = buf.subarray(emittedHexHeaderPrefixBytes);
-    if (buf.every((byte) => byte === 0x2a)) {
-      // Keep at most two printable bytes as parsing context: a later ZDLE
-      // must still be recognized and stripped, without replaying the stars.
-      emittedHexHeaderPrefixBytes = buf.length;
-    } else {
-      pendingHexHeaderFragment = null;
-      emittedHexHeaderPrefixBytes = 0;
-    }
-    if (output.length) onData(output);
+    pendingHexHeaderFragment = null;
+    if (buf?.length) onData(buf);
   }
 
   /**
@@ -431,27 +412,19 @@ function createZmodemSentry(opts) {
     const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
 
     const fragmentAt = findTrailingHexHeaderFragment(buf);
-    const alreadyEmitted = emittedHexHeaderPrefixBytes;
-    emittedHexHeaderPrefixBytes = fragmentAt === -1
-      ? 0
-      : Math.max(0, alreadyEmitted - fragmentAt);
-    if (fragmentAt === -1) return buf.subarray(alreadyEmitted);
+    if (fragmentAt === -1) return buf;
 
     if (fragmentAt < buf.length) {
       pendingHexHeaderFragment = Buffer.from(buf.subarray(fragmentAt));
-      if (!pendingHexHeaderFragmentTimer
-        && pendingHexHeaderFragment.length > emittedHexHeaderPrefixBytes) {
-        const ttl = pendingHexHeaderFragment.every((byte) => byte === 0x2a)
-          ? PRINTABLE_HEX_PREFIX_TTL_MS
-          : HEX_HEADER_FRAGMENT_TTL_MS;
+      if (!pendingHexHeaderFragmentTimer) {
         pendingHexHeaderFragmentTimer = setTimeout(
           flushPendingHexHeaderFragment,
-          ttl,
+          HEX_HEADER_FRAGMENT_TTL_MS,
         );
       }
     }
 
-    return buf.subarray(Math.min(alreadyEmitted, fragmentAt), fragmentAt);
+    return fragmentAt ? buf.subarray(0, fragmentAt) : Buffer.alloc(0);
   }
 
   function looksLikeResidualZmodemData(data) {

electron/bridges/zmodemHelper.test.cjs

@@ -1814,93 +1814,6 @@ function assertNoZmodemHeaderBytes(terminal, context) {
   );
 }
 
-test("ordinary star echoes wait at most one frame for a possible ZMODEM prefix", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  for (const text of ["*", "**", "ls *", "**/*.txt*"]) {
-    const { sentry, terminal } = createProbeSentry({ hexHeaderFragmentTtlMs: undefined });
-    sentry.consume(Buffer.from(text));
-    t.mock.timers.tick(16);
-    assert.equal(joinedText(terminal), text, `echo delayed: ${text}`);
-    t.mock.timers.tick(1000);
-    assert.equal(joinedText(terminal), text, "the fragment must not be emitted twice");
-  }
-});
-
-test("a following parenthesis and repeated stars preserve echo order", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const { sentry, terminal } = createProbeSentry({ hexHeaderFragmentTtlMs: undefined });
-  for (const text of ["*", "(", "*", "*", "*", "!"]) {
-    sentry.consume(Buffer.from(text));
-    t.mock.timers.tick(16);
-  }
-  assert.equal(joinedText(terminal), "*(***!");
-  t.mock.timers.tick(1000);
-  assert.equal(joinedText(terminal), "*(***!");
-});
-
-test("expired printable prefixes preserve ordinary bytes across chunk boundaries", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const input = Buffer.from("a***(b)**/*.txt *\x18X **\x18Bxy more *\uFF0A");
-  for (const gap of [0, 16, 200]) {
-    for (let chunkSize = 1; chunkSize <= input.length; chunkSize += 1) {
-      const { sentry, terminal } = createProbeSentry({ hexHeaderFragmentTtlMs: undefined });
-      for (let i = 0; i < input.length; i += chunkSize) {
-        sentry.consume(input.subarray(i, i + chunkSize));
-        t.mock.timers.tick(gap);
-      }
-      t.mock.timers.tick(1000);
-      assert.deepEqual(Buffer.concat(terminal), input, `chunkSize=${chunkSize}, gap=${gap}`);
-    }
-  }
-});
-
-test("a prefix containing ZDLE keeps the full fragmented-header timeout", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const { sentry, terminal } = createProbeSentry({ hexHeaderFragmentTtlMs: undefined });
-  const header = buildHexHeaderBytes("ZRQINIT");
-  sentry.consume(header.subarray(0, 3));
-  t.mock.timers.tick(200);
-  assert.equal(joinedText(terminal), "");
-  sentry.consume(header.subarray(3));
-  t.mock.timers.tick(1000);
-  assert.equal(joinedText(terminal), "");
-  assertNoZmodemHeaderBytes(terminal, "delayed ZDLE prefix");
-});
-
-test("a slow split header after printable-prefix expiry still detects and hides control bytes", async (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  for (const prefixLength of [1, 2]) {
-    let detected = false;
-    const { sentry, terminal } = createProbeSentry({
-      hexHeaderFragmentTtlMs: undefined,
-      selectDownloadDirectory: async () => { detected = true; return { canceled: true }; },
-    });
-    const header = buildHexHeaderBytes("ZRQINIT");
-    sentry.consume(header.subarray(0, prefixLength));
-    t.mock.timers.tick(200);
-    assert.equal(joinedText(terminal), "*".repeat(prefixLength));
-    sentry.consume(header.subarray(prefixLength, 3));
-    t.mock.timers.tick(200);
-    sentry.consume(header.subarray(3));
-    await Promise.resolve();
-    assert.equal(detected, true, "the printable echo timeout must not reset protocol detection");
-    assert.equal(joinedText(terminal), "*".repeat(prefixLength));
-    assertNoZmodemHeaderBytes(terminal, "slow split after printable prefix");
-  }
-});
-
-test("stripping a slow header does not skip ordinary output after it", (t) => {
-  t.mock.timers.enable({ apis: ["setTimeout"] });
-  const { sentry, terminal } = createProbeSentry({ hexHeaderFragmentTtlMs: undefined });
-  const header = buildHexHeaderBytes("ZRQINIT");
-  sentry.consume(header.subarray(0, 2));
-  t.mock.timers.tick(200);
-  sentry.consume(Buffer.concat([header.subarray(2), Buffer.from("* next prompt")]));
-  t.mock.timers.tick(1000);
-  assert.equal(joinedText(terminal), "*** next prompt");
-  assertNoZmodemHeaderBytes(terminal, "ordinary output after slow header");
-});
-
 test("fragmented sz ZRQINIT preamble never reaches the terminal", () => {
   const { sentry, terminal } = createProbeSentry();
   const stream = Buffer.concat([

electron/main/registerBridges.cjs

@@ -148,8 +148,8 @@ function createBridgeRegistrar(context) {
     } = require("../plugins/pluginBridge.cjs");
     let terminalWorkerManager = null;
     const { toElectronAccelerator } = require("../plugins/keybindings.cjs");
-    const { startDevelopmentPluginHost } = require("../plugins/hostBootstrap.cjs");
-    const pluginHostService = startDevelopmentPluginHost({
+    const { startPluginHost } = require("../plugins/hostBootstrap.cjs");
+    const pluginHostService = startPluginHost({
       env: process.env,
       createService: () => {
         const { createPluginHostService } = require("../plugins/hostService.cjs");
@@ -166,8 +166,15 @@ function createBridgeRegistrar(context) {
           electron: electronModule,
           safeStorage,
           requestPermissionDecision: createNativePermissionDecisionProvider({
+            getLocale: () => getWindowManager().getCurrentLanguage?.() ?? "en",
             dialog: electronModule.dialog,
             window: win,
+            getWindow: () => {
+              const settingsWindow = getWindowManager().getSettingsWindow?.();
+              return settingsWindow && !settingsWindow.isDestroyed() && settingsWindow.isFocused()
+                ? settingsWindow
+                : win;
+            },
           }),
           getLocale: () => getWindowManager().getCurrentLanguage?.() ?? "en",
           requestTerminalInterceptorSelection: async ({ direction, providers }) => {
@@ -210,6 +217,9 @@ function createBridgeRegistrar(context) {
     });
     registerPluginBridge(ipcMain, {
       manager: pluginHostService?.manager,
+      permissionEngine: pluginHostService?.permissionEngine,
+      database: pluginHostService?.database,
+      catalogService: pluginHostService?.catalogService,
       contributionService: pluginHostService?.contributionService,
       terminalProviderService: pluginHostService?.terminalProviderService,
       terminalDataPipelineService: pluginHostService?.terminalDataPipelineService,
@@ -227,6 +237,7 @@ function createBridgeRegistrar(context) {
         });
         return result.canceled ? null : result.filePaths[0] ?? null;
       },
+      resolveBrandIcon: (pluginId) => pluginHostService?.contributionIconService?.resolveBrand(pluginId),
       resolveContributionIcon: (payload) => pluginHostService?.contributionIconService?.resolve(payload),
       viewHost: pluginHostService?.viewHost,
       env: process.env,

electron/pluginRuntime.test.cjs

@@ -23,3 +23,9 @@ require("./plugins/runtimeSupervisor.test.cjs");
 require("./plugins/shutdownCoordinator.test.cjs");
 require("./plugins/streamRouter.test.cjs");
 require("./plugins/utilityPluginRuntime.test.cjs");
+
+require('./plugins/brandIconService.test.cjs');
+
+require('./plugins/settingsViewFixture.test.cjs');
+
+require('./plugins/registryCatalogService.test.cjs');

electron/plugins/brandIconService.test.cjs

@@ -0,0 +1,38 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { PluginContributionIconService } = require('./contributionIconService.cjs');
+async function fixture(t, rasterize) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'brand-icon-'));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  await fs.copyFile(path.join(__dirname, '../..', 'examples/plugins/starter-netcatty/assets/logo-light.png'), path.join(root, 'logo.png'));
+  let plugin = { id: 'com.test.brand', activeVersion: '1.0.0', archiveSha256: 'a', enabled: false, runtime: {}, manifest: { icon: { kind: 'package', light: 'logo.png' } } };
+  const service = new PluginContributionIconService({ database: { getActivePlugin: () => plugin }, packageStore: { preparePackageRoot: async () => root }, rasterizeIcon: rasterize ?? (async () => {
+    const output = Buffer.alloc(24); Buffer.from([137,80,78,71,13,10,26,10]).copy(output); output.write('IHDR', 12); output.writeUInt32BE(32, 16); output.writeUInt32BE(32, 20); return output;
+  }) });
+  return { service, plugin, setPlugin: (value) => { plugin = value; } };
+}
+test('disabled installed branding is readable without runtime activation or changing contribution admission', async (t) => {
+  const { service, plugin } = await fixture(t);
+  assert.match((await service.resolveBrand(plugin.id)).light, /^data:image\/png;base64,/);
+  await assert.rejects(service.resolve({ pluginId: plugin.id, icon: plugin.manifest.icon }), /not declared/);
+  plugin.manifest.contributes = { views: [{ icon: plugin.manifest.icon }] };
+  await assert.rejects(service.resolve({ pluginId: plugin.id, icon: plugin.manifest.icon }), /unavailable/);
+  plugin.runtime.quarantinedAt = 1;
+  assert.equal(await service.resolveBrand(plugin.id), null);
+});
+test('brand results cannot survive uninstall or a changed package hash during decoding', async (t) => {
+  for (const change of ['uninstall', 'hash']) {
+    let release; let entered;
+    const started = new Promise((resolve) => { entered = resolve; });
+    const gate = new Promise((resolve) => { release = resolve; });
+    const f = await fixture(t, async () => { entered(); await gate; const b = Buffer.alloc(24); Buffer.from([137,80,78,71,13,10,26,10]).copy(b); b.write('IHDR',12); b.writeUInt32BE(32,16); b.writeUInt32BE(32,20); return b; });
+    const pending = f.service.resolveBrand(f.plugin.id);
+    await started;
+    if (change === 'uninstall') f.setPlugin(null); else f.plugin.archiveSha256 = 'b';
+    release();
+    await assert.rejects(pending, /ownership changed/);
+  }
+});

electron/plugins/catalog.json

@@ -0,0 +1,195 @@
+[
+  {
+    "id": "com.netcatty.starter",
+    "version": "0.1.2",
+    "name": "Plugin Starter",
+    "description": "First-party greeting panel, local settings and commands, without terminal or secret access.",
+    "author": "Netcatty",
+    "repository": "binaricat/Netcatty",
+    "commit": "f4a6b205adca486d4e9cda0270e13a9ff0afd7be",
+    "license": "GPL-3.0-or-later",
+    "readme": "examples/plugins/starter-netcatty/README.md",
+    "manifest": {
+      "manifestVersion": 1,
+      "id": "com.netcatty.starter",
+      "name": "starter-netcatty",
+      "displayName": {
+        "en": "Plugin Starter",
+        "zh-CN": "插件入门"
+      },
+      "description": "First-party settings and command example. No terminal, network, filesystem or secret access.",
+      "version": "0.1.2",
+      "publisher": "netcatty",
+      "license": "GPL-3.0-or-later",
+      "engines": {
+        "netcatty": ">=0.0.0",
+        "api": ">=0.1.0-internal.1 <0.2.0"
+      },
+      "main": {
+        "browser": "dist/index.js"
+      },
+      "activationEvents": [
+        "onCommand:com.netcatty.starter.greet",
+        "onView:com.netcatty.starter.panel"
+      ],
+      "permissions": {
+        "required": [
+          "commands",
+          "settings.read",
+          "menus",
+          "views"
+        ],
+        "optional": []
+      },
+      "contributes": {
+        "settings": [
+          {
+            "id": "com.netcatty.starter.greeting",
+            "label": {
+              "en": "Greeting",
+              "zh-CN": "问候语"
+            },
+            "description": "A local preference for the example command.",
+            "control": "text",
+            "scope": "application",
+            "default": "Hello, synthetic world!"
+          }
+        ],
+        "commands": [
+          {
+            "id": "com.netcatty.starter.greet",
+            "title": {
+              "en": "Starter: Read Greeting",
+              "zh-CN": "入门：读取问候语"
+            }
+          }
+        ],
+        "menus": [
+          {
+            "command": "com.netcatty.starter.greet",
+            "location": "commandPalette",
+            "group": "examples"
+          }
+        ],
+        "views": [
+          {
+            "id": "com.netcatty.starter.panel",
+            "title": {
+              "en": "Starter: Greeting Panel",
+              "zh-CN": "入门：问候面板"
+            },
+            "location": "modal",
+            "entry": "panel.html"
+          }
+        ]
+      },
+      "features": {
+        "required": [
+          "metadata.brand-icon"
+        ]
+      },
+      "icon": {
+        "kind": "package",
+        "light": "assets/logo-light.png",
+        "dark": "assets/logo-dark.png"
+      }
+    }
+  },
+  {
+    "id": "com.netcatty.hello",
+    "version": "0.1.0",
+    "name": "Hello Netcatty",
+    "description": "First-party example: greeting settings, commands and terminal providers. Build locally and import.",
+    "author": "Netcatty",
+    "repository": "binaricat/Netcatty",
+    "commit": "4336f8fd53a05a48d6bbc9ad3ce0ca88b121862f",
+    "license": "GPL-3.0-or-later",
+    "readme": "examples/plugins/hello-netcatty/README.md",
+    "manifest": {
+      "$schema": "../../../packages/plugin-contract/schema/plugin-contract.schema.json",
+      "manifestVersion": 1,
+      "id": "com.netcatty.hello",
+      "name": "hello-netcatty",
+      "displayName": {
+        "en": "Hello Netcatty",
+        "zh-CN": "你好，Netcatty"
+      },
+      "description": "Minimal plugin contract and SDK example.",
+      "version": "0.1.0",
+      "publisher": "netcatty",
+      "license": "GPL-3.0-or-later",
+      "engines": {
+        "netcatty": ">=0.0.0",
+        "api": ">=0.1.0-internal <0.2.0"
+      },
+      "main": {
+        "browser": "dist/index.js"
+      },
+      "activationEvents": [
+        "onCommand:com.netcatty.hello.sayHello",
+        "onProvider:com.netcatty.hello.completion",
+        "onProvider:com.netcatty.hello.decoration",
+        "onProvider:com.netcatty.hello.theme"
+      ],
+      "permissions": {
+        "required": [
+          "commands",
+          "settings.read",
+          "menus",
+          "provider.terminal",
+          "terminal.complete",
+          "terminal.output",
+          "terminal.decorate"
+        ],
+        "optional": []
+      },
+      "contributes": {
+        "settings": [
+          {
+            "id": "com.netcatty.hello.greeting",
+            "label": "Greeting",
+            "description": "Text used by the example command.",
+            "control": "text",
+            "scope": "application",
+            "default": "Hello from Netcatty"
+          }
+        ],
+        "commands": [
+          {
+            "id": "com.netcatty.hello.sayHello",
+            "title": "Say Hello",
+            "category": "Examples"
+          }
+        ],
+        "menus": [
+          {
+            "command": "com.netcatty.hello.sayHello",
+            "location": "commandPalette",
+            "group": "examples",
+            "order": 10
+          }
+        ],
+        "providers": [
+          {
+            "id": "com.netcatty.hello.completion",
+            "label": "Hello completion",
+            "description": "Suggests the example hello command.",
+            "kind": "terminal.completion"
+          },
+          {
+            "id": "com.netcatty.hello.decoration",
+            "label": "Hello decoration",
+            "description": "Highlights the example greeting in terminal output.",
+            "kind": "terminal.decoration"
+          },
+          {
+            "id": "com.netcatty.hello.theme",
+            "label": "Hello theme",
+            "description": "Adds a subtle cursor color to the example terminal theme.",
+            "kind": "terminal.theme"
+          }
+        ]
+      }
+    }
+  }
+]

electron/plugins/catalogPolicy.cjs

@@ -0,0 +1,13 @@
+"use strict";
+
+const { assertBrowserOnlyPlugin } = require("../../domain/pluginRuntimePolicy.cjs");
+
+function assertCatalogManifest(manifest, expected) {
+  if (manifest.id !== expected.id || manifest.version !== expected.version) {
+    throw new Error("Catalog package identity/version mismatch");
+  }
+  assertBrowserOnlyPlugin(manifest);
+  if (!manifest.license || manifest.license !== expected.license) throw new Error("Catalog package license mismatch");
+}
+
+module.exports = { assertCatalogManifest };

electron/plugins/catalogService.cjs

@@ -0,0 +1,130 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const catalog = require("./catalog.json");
+const { getTempFilePath } = require("../bridges/tempDirBridge.cjs");
+const { createDefinitionValidator, formatValidationErrors } = require("./contractValidator.cjs");
+const validateManifest = createDefinitionValidator("PluginManifest");
+const { assertCatalogManifest } = require("./catalogPolicy.cjs");
+const { assertPluginJsonValue } = require("./jsonBoundary.cjs");
+const MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+const CATALOG_FIELDS = new Set(["id", "version", "name", "description", "author", "repository", "commit", "license", "readme", "manifest", "artifact"]);
+
+const DOWNLOAD_HOSTS = new Set(["github.com", "raw.githubusercontent.com", "release-assets.githubusercontent.com", "objects.githubusercontent.com"]);
+function assertDownloadUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || url.port || !DOWNLOAD_HOSTS.has(url.hostname)) {
+    throw new Error("Catalog download URL is not an approved HTTPS GitHub source");
+  }
+  return url.href;
+}
+function pinnedReadmeUrl(entry) {
+  if (typeof entry.readme !== "string" || /[\u0000-\u001f\u007f\\%?#]/u.test(entry.readme)
+    || entry.readme.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error("Invalid or unpinned README path");
+  }
+  const prefix = `/${entry.repository}/${entry.commit}/`;
+  const url = new URL(`https://raw.githubusercontent.com${prefix}${entry.readme.split("/").map(encodeURIComponent).join("/")}`);
+  if (!url.pathname.startsWith(prefix)) throw new Error("README URL escapes the pinned commit");
+  return url.href;
+}
+function validateCatalog(entries) {
+  assertPluginJsonValue(entries, { maxBytes: MAX_CATALOG_BYTES });
+  if (!Array.isArray(entries) || entries.length > 1000) throw new Error("Invalid plugin catalog");
+  const ids = new Set();
+  for (const entry of entries) {
+    if (!entry || Object.keys(entry).some((key) => !CATALOG_FIELDS.has(key)) || ["id", "version", "name", "description", "author", "repository", "commit", "license", "readme"].some((key) => typeof entry[key] !== "string" || entry[key].length > 4096) || !/^[a-z0-9][a-z0-9.-]+$/u.test(entry.id) || ids.has(entry.id)
+      || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(entry.repository)
+      || !/^[a-f0-9]{40}$/u.test(entry.commit)
+      || !entry.license || !entry.author || !entry.name
+      || typeof entry.readme !== "string" || !entry.readme.endsWith(".md")
+      || entry.readme.split("/").some((p) => !p || p === "." || p === "..") || /[\\%?#\0]/u.test(entry.readme)) {
+      throw new Error("Invalid or unpinned plugin catalog entry");
+    }
+    pinnedReadmeUrl(entry);
+    if (!validateManifest(entry.manifest)) throw new Error(`Catalog manifest is invalid: ${formatValidationErrors(validateManifest.errors)}`);
+    assertCatalogManifest(entry.manifest, entry);
+    ids.add(entry.id);
+    if (Object.hasOwn(entry, "artifact")) {
+      if (!entry.artifact || typeof entry.artifact !== "object" || Array.isArray(entry.artifact)
+        || Object.keys(entry.artifact).some((key) => key !== "url" && key !== "sha256")
+        || typeof entry.artifact.url !== "string" || typeof entry.artifact.sha256 !== "string") {
+        throw new Error("Invalid catalog artifact metadata");
+      }
+      assertDownloadUrl(entry.artifact.url);
+      if (!/^[a-f0-9]{64}$/u.test(entry.artifact.sha256)) throw new Error("Catalog artifact requires SHA-256");
+    }
+  }
+  return entries;
+}
+async function fetchBounded(url, limit, fetchImpl = fetch, maxRedirects = 4) {
+  const signal = AbortSignal.timeout(30_000);
+  for (let redirects = 0; redirects <= maxRedirects; redirects++) {
+    const response = await fetchImpl(assertDownloadUrl(url), { redirect: "manual", signal, credentials: "omit", referrerPolicy: "no-referrer" });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      await response.body?.cancel();
+      url = new URL(response.headers.get("location"), url).href;
+      continue;
+    }
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`Catalog download failed (${response.status})`); }
+    if (Number(response.headers.get("content-length")) > limit) {
+      await response.body?.cancel(); throw new Error("Catalog download exceeds size limit");
+    }
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("Catalog download has no body");
+    const chunks = [];
+    let size = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > limit) throw new Error("Catalog download exceeds size limit");
+        chunks.push(Buffer.from(value));
+      }
+      return Buffer.concat(chunks, size);
+    } finally { await reader.cancel(); }
+  }
+  throw new Error("Too many catalog redirects");
+}
+class PluginCatalogService {
+  constructor(options) {
+    this.entries = structuredClone(validateCatalog(options.entries ?? catalog));
+    this.fetch = options.fetch ?? fetch;
+    this.getTempFilePath = options.getTempFilePath ?? getTempFilePath;
+    this.manager = options.manager;
+    this.installing = false;
+  }
+  list() { return structuredClone(this.entries); }
+  get(id) {
+    const entry = this.entries.find((item) => item.id === id);
+    if (!entry) throw new Error("Plugin is not in the curated catalog");
+    return entry;
+  }
+  async readme(id) {
+    const entry = this.get(id);
+    const url = pinnedReadmeUrl(entry);
+    return (await fetchBounded(url, 256 * 1024, this.fetch, 0)).toString("utf8");
+  }
+  async install(id) {
+    const entry = this.get(id);
+    if (!entry.artifact) throw new Error("This source example has no published package; build and import locally");
+    if (this.installing) throw new Error("A catalog installation is already in progress");
+    this.installing = true;
+    let directory;
+    try {
+      const bytes = await fetchBounded(entry.artifact.url, 32 * 1024 * 1024, this.fetch);
+      if (createHash("sha256").update(bytes).digest("hex") !== entry.artifact.sha256) throw new Error("Catalog package SHA-256 mismatch");
+      directory = await fs.mkdtemp(this.getTempFilePath("plugin-catalog-"));
+      const archive = path.join(directory, "package.ncpkg");
+      await fs.writeFile(archive, bytes, { mode: 0o600, flag: "wx" });
+      return await this.manager.install(archive, { enable: false, catalog: entry });
+    } finally {
+      this.installing = false;
+      if (directory) await fs.rm(directory, { recursive: true, force: true });
+    }
+  }
+}
+module.exports = { PluginCatalogService, assertDownloadUrl, fetchBounded, validateCatalog, pinnedReadmeUrl, MAX_CATALOG_BYTES };

electron/plugins/catalogService.test.cjs

@@ -0,0 +1,74 @@
+"use strict";
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { createHash } = require("node:crypto");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { PluginCatalogService, validateCatalog, fetchBounded } = require("./catalogService.cjs");
+const { assertCatalogManifest } = require("./catalogPolicy.cjs");
+const entries = require("./catalog.json");
+
+test("curated catalog uses pinned public first-party source and rejects advanced manifests", () => {
+  assert.equal(validateCatalog(entries).length, 2);
+  for (const main of [{ node: "index.js" }, { browser: "index.js", node: "node.js" }]) {
+    const entry = structuredClone(entries[0]); entry.manifest.main = main;
+    assert.throws(() => validateCatalog([entry]), /browser-only packages/);
+  }
+  const entry = structuredClone(entries[0]);
+  entry.manifest.permissions.optional.push("runtime.advanced");
+  assert.throws(() => assertCatalogManifest(entry.manifest, entry), /advanced developer mode/);
+  for (const readme of ["../README.md", "a/%2e%2e/README.md", "a\\README.md"]) {
+    assert.throws(() => validateCatalog([{ ...entries[0], readme }]), /unpinned/);
+  }
+  assert.throws(() => validateCatalog([{ ...entries[0], commit: "main" }]), /unpinned/);
+});
+
+test("README retrieval is bounded and pinned, never follows a redirect to latest", async () => {
+  const requested = [];
+  const service = new PluginCatalogService({ entries, fetch: async (url) => {
+    requested.push(url); return new Response("# First-party example");
+  } });
+  assert.equal(await service.readme(entries[0].id), "# First-party example");
+  assert.equal(requested[0], `https://raw.githubusercontent.com/${entries[0].repository}/${entries[0].commit}/${entries[0].readme}`);
+  service.fetch = async () => new Response(null, { status: 302, headers: { location: "https://raw.githubusercontent.com/a/b/main/README.md" } });
+  await assert.rejects(service.readme(entries[0].id), /redirects/);
+  await assert.rejects(fetchBounded("https://raw.githubusercontent.com/a/b/c", 3, async () => new Response("1234")), /size limit/);
+  await assert.rejects(fetchBounded("https://127.0.0.1/a", 10), /approved HTTPS/);
+  await assert.rejects(fetchBounded("https://github.com/a", 10, async () => new Response(null, { status: 302, headers: { location: "http://localhost/secret" } })), /approved HTTPS/);
+});
+
+test("catalog install verifies the digest, shares manager installation, and never auto-enables", async (context) => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "netcatty-catalog-test-"));
+  context.after(() => fs.rm(root, { recursive: true, force: true }));
+  const bytes = Buffer.from("synthetic bytes: package validation belongs to PackageStore");
+  const entry = { ...structuredClone(entries[0]), artifact: { url: "https://github.com/example/repo/releases/download/v1/plugin.ncpkg", sha256: createHash("sha256").update(bytes).digest("hex") } };
+  let installs = 0;
+  const service = new PluginCatalogService({ entries: [entry], getTempFilePath: (name) => {
+    assert.equal(name, "plugin-catalog-");
+    return path.join(root, name);
+  }, fetch: async () => new Response(bytes), manager: {
+    async install(archive, options) {
+      installs++;
+      assert.equal(path.dirname(path.dirname(archive)), root);
+      assert.equal((await fs.stat(path.dirname(archive))).mode & 0o777, 0o700);
+      assert.deepEqual(await fs.readFile(archive), bytes);
+      assert.equal(options.enable, false);
+      assert.equal(options.catalog.artifact.sha256, entry.artifact.sha256);
+      return { id: entry.id };
+    },
+  } });
+  await service.install(entry.id);
+  assert.equal(installs, 1);
+  assert.deepEqual(await fs.readdir(root), []);
+  service.fetch = async () => new Response("changed");
+  await assert.rejects(service.install(entry.id), /SHA-256 mismatch/);
+  assert.equal(installs, 1);
+  await assert.rejects(service.install("unknown"), /curated catalog/);
+});
+
+test("catalog rejects unknown permissions instead of presenting an unimplemented grant", () => {
+  const entry = structuredClone(entries[0]);
+  entry.manifest.permissions.optional.push("future.unknown");
+  assert.throws(() => validateCatalog([entry]), /manifest is invalid/);
+});

electron/plugins/constants.cjs

@@ -2,7 +2,7 @@
 
 const PLUGIN_DEV_ENV = "NETCATTY_PLUGIN_DEV";
 const PLUGIN_PROTOCOL_SCHEME = "netcatty-plugin";
-const PLUGIN_API_VERSION = "0.1.0-internal";
+const PLUGIN_API_VERSION = "0.1.0-internal.1";
 const PLUGIN_ACTIVATION_TIMEOUT_MS = 5_000;
 const PLUGIN_DEACTIVATION_TIMEOUT_MS = 2_000;
 const PLUGIN_UTILITY_TERMINATION_GRACE_MS = 500;

electron/plugins/contributionIconService.cjs

@@ -231,12 +231,42 @@ class PluginContributionIconService {
     return result;
   }
 
-  async #readIcon(packageRoot, packagePath) {
+  // Branding is inert installed metadata. It does not share the enabled-only
+  // contribution admission path, and accepts no renderer-provided resource path.
+  async resolveBrand(pluginId) {
+    if (typeof pluginId !== "string" || pluginId.length > 256) throw new TypeError("Invalid plugin ID");
+    const plugin = this.database.getActivePlugin(pluginId);
+    if (!plugin?.activeVersion || plugin.runtime?.quarantinedAt != null) return null;
+    const icon = plugin.manifest?.icon;
+    if (icon?.kind !== "package") return null;
+    const identity = JSON.stringify([plugin.activeVersion, plugin.archiveSha256, icon]);
+    const key = JSON.stringify(["brand", pluginId, identity]);
+    if (this.cache.has(key)) return this.cache.get(key);
+    if (this.pending.has(key)) return this.pending.get(key);
+    const pending = (async () => {
+      const root = await this.packageStore.preparePackageRoot(plugin);
+      const result = { light: await this.#readIcon(root, icon.light, true),
+        ...(icon.dark ? { dark: await this.#readIcon(root, icon.dark, true) } : {}) };
+      const current = this.database.getActivePlugin(pluginId);
+      if (!current || current.runtime?.quarantinedAt != null || identity !== JSON.stringify([current.activeVersion, current.archiveSha256, current.manifest?.icon])) {
+        throw new Error("Plugin brand icon ownership changed while loading");
+      }
+      if (this.cache.size >= 256) this.cache.clear();
+      this.cache.set(key, result);
+      return result;
+    })().finally(() => this.pending.delete(key));
+    this.pending.set(key, pending);
+    return pending;
+  }
+
+  async #readIcon(packageRoot, packagePath, brand = false) {
     const segments = packagePath.split("/");
     const file = await readContainedFile(packageRoot, segments);
     if (file.body.byteLength > MAX_ICON_SOURCE_BYTES) throw new Error("Plugin contribution icon is too large");
     const extension = path.extname(file.filePath).toLowerCase();
-    const inspected = inspectContributionIconSource(file.body, extension);
+    const inspected = brand
+      ? (await import("@netcatty/plugin-contract")).inspectPluginBrandIcon(file.body, packagePath)
+      : inspectContributionIconSource(file.body, extension);
     const png = await this.rasterizeIcon({
       body: file.body,
       ...inspected,

electron/plugins/credentialCatalog.cjs

@@ -47,6 +47,10 @@ class PluginCredentialCatalog {
     }
   }
 
+  isAvailable() {
+    try { this.#assertAvailable(); return true; } catch { return false; }
+  }
+
   update(entries) {
     if (!Array.isArray(entries) || entries.length > MAX_CREDENTIAL_CATALOG_ENTRIES) {
       throw new PluginRpcError(RPC_ERRORS.invalidArgument, "Vault credential catalog is invalid or too large");

electron/plugins/credentialCatalog.test.cjs

@@ -66,3 +66,9 @@ test("Vault credential catalog fails closed when secure storage is unavailable",
     /unavailable|not found/i,
   );
 });
+
+test("availability reporting does not unlock a missing OS vault", () => {
+  const catalog = new PluginCredentialCatalog({ safeStorage: { isEncryptionAvailable: () => false } });
+  assert.equal(catalog.isAvailable(), false);
+  assert.throws(() => catalog.update([]), /OS-backed Vault/);
+});

electron/plugins/database.cjs

@@ -614,14 +614,15 @@ class PluginDatabase {
 
   listSyncSidecars(pluginId) {
     return this.db.prepare(`
-      SELECT plugin_id, kind, key, value_json, updated_at
+      SELECT plugin_id, kind, CAST(key AS BLOB) AS key_bytes, value_json, updated_at
       FROM plugin_sync_sidecars
       WHERE plugin_id = ?
       ORDER BY kind COLLATE BINARY, key COLLATE BINARY
     `).all(pluginId).map((row) => ({
       pluginId: row.plugin_id,
       kind: row.kind,
-      key: row.key,
+      // Node 22 truncates TEXT results at NUL; settings keys contain NUL separators.
+      key: Buffer.from(row.key_bytes).toString("utf8"),
       value: parseJson(row.value_json, "sync sidecar value"),
       updatedAt: Number(row.updated_at),
     }));
@@ -629,13 +630,14 @@ class PluginDatabase {
 
   listAllSyncSidecars() {
     return this.db.prepare(`
-      SELECT plugin_id, kind, key, value_json, updated_at
+      SELECT plugin_id, kind, CAST(key AS BLOB) AS key_bytes, value_json, updated_at
       FROM plugin_sync_sidecars
       ORDER BY plugin_id COLLATE BINARY, kind COLLATE BINARY, key COLLATE BINARY
     `).all().map((row) => ({
       pluginId: row.plugin_id,
       kind: row.kind,
-      key: row.key,
+      // Node 22 truncates TEXT results at NUL; settings keys contain NUL separators.
+      key: Buffer.from(row.key_bytes).toString("utf8"),
       value: parseJson(row.value_json, "sync sidecar value"),
       updatedAt: Number(row.updated_at),
     }));

electron/plugins/database.test.cjs

@@ -833,3 +833,14 @@ test("inferPluginIdForSyncProvider never guesses from credential key prefixes",
   assert.equal(database.inferPluginIdForSyncProvider("com.missing.sync"), undefined);
   database.close();
 });
+
+test("sync sidecar enumeration preserves NUL-separated setting coordinates", (context) => {
+  const database = createDatabase(context);
+  context.after(() => database.close());
+  const key = "com.example.test.theme\0application\0application";
+  database.setSyncSidecar("com.example.test", "settings", key, "dark", 10);
+  assert.equal(database.listSyncSidecars("com.example.test")[0].key, key);
+  assert.equal(database.listAllSyncSidecars()[0].key, key);
+  database.replaceAllSyncSidecars(database.listAllSyncSidecars());
+  assert.equal(database.getSyncSidecar("com.example.test", "settings", key).value, "dark");
+});

electron/plugins/generated/plugin-contract.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://netcatty.com/schemas/plugins/0.1.0-internal/plugin-contract.schema.json",
+  "$id": "https://netcatty.com/schemas/plugins/0.1.0-internal.1/plugin-contract.schema.json",
   "title": "Netcatty Plugin Contract",
   "description": "Canonical public contract for Netcatty plugin manifests and host RPC messages.",
   "$ref": "#/$defs/PluginManifest",
@@ -231,6 +231,131 @@
       },
       "additionalProperties": false
     },
+    "NetworkCredentialLeaseFeature": {
+      "const": "network.credential-lease"
+    },
+    "PluginNetworkAuthorization": {
+      "type": "object",
+      "properties": {
+        "scheme": {
+          "type": "string",
+          "enum": [
+            "Basic",
+            "Bearer"
+          ]
+        },
+        "username": {
+          "type": "string",
+          "maxLength": 8192,
+          "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "PluginNetworkRequest": {
+      "description": "Origin-authorized HTTP request. The host consumes a one-use credentialLease for network:<canonical origin>; plaintext credentials never return to the plugin.",
+      "type": "object",
+      "required": [
+        "url"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 8192
+        },
+        "method": {
+          "type": "string",
+          "enum": [
+            "GET",
+            "POST",
+            "PUT",
+            "PATCH",
+            "DELETE",
+            "HEAD"
+          ]
+        },
+        "headers": {
+          "type": "object",
+          "maxProperties": 64,
+          "additionalProperties": {
+            "type": "string",
+            "maxLength": 8192
+          }
+        },
+        "body": {
+          "type": "object",
+          "required": [
+            "encoding",
+            "data"
+          ],
+          "properties": {
+            "encoding": {
+              "enum": [
+                "utf8",
+                "base64"
+              ]
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 300000
+        },
+        "credentialLease": {
+          "$ref": "#/$defs/SecretLeaseRef"
+        },
+        "authorization": {
+          "$ref": "#/$defs/PluginNetworkAuthorization"
+        }
+      },
+      "additionalProperties": false
+    },
+    "PluginNetworkResponse": {
+      "type": "object",
+      "required": [
+        "url",
+        "status",
+        "headers",
+        "body"
+      ],
+      "properties": {
+        "url": {
+          "type": "string"
+        },
+        "status": {
+          "type": "integer"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "body": {
+          "type": "object",
+          "required": [
+            "encoding",
+            "data"
+          ],
+          "properties": {
+            "encoding": {
+              "const": "base64"
+            },
+            "data": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "SemanticVersion": {
       "type": "string",
       "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"
@@ -2949,6 +3074,9 @@
           "type": "string",
           "maxLength": 128
         },
+        "icon": {
+          "$ref": "#/$defs/IconReference"
+        },
         "homepage": {
           "type": "string",
           "format": "uri"

electron/plugins/hostBootstrap.cjs

@@ -1,9 +1,6 @@
 "use strict";
 
-const { isPluginDevelopmentEnabled } = require("./constants.cjs");
-
-function startDevelopmentPluginHost(options) {
-  if (!isPluginDevelopmentEnabled(options.env)) return null;
+function startPluginHost(options) {
   const reportFailure = (message, error) => {
     try { options.logger?.error?.(message, error); } catch {}
   };
@@ -30,4 +27,4 @@ function startDevelopmentPluginHost(options) {
   }
 }
 
-module.exports = { startDevelopmentPluginHost };
+module.exports = { startPluginHost };

electron/plugins/hostBootstrap.test.cjs

@@ -3,24 +3,24 @@
 const assert = require("node:assert/strict");
 const test = require("node:test");
 
-const { startDevelopmentPluginHost } = require("./hostBootstrap.cjs");
+const { startPluginHost } = require("./hostBootstrap.cjs");
 
-test("disabled development host does not construct plugin infrastructure", () => {
+test("normal release constructs the browser plugin host without a developer flag", async () => {
   let created = 0;
-  const service = startDevelopmentPluginHost({
+  const service = { manager: { async initialize() {}, async shutdown() {} } };
+  assert.equal(startPluginHost({
     env: {},
-    createService() { created += 1; },
+    createService() { created += 1; return service; },
     registerShutdown() {},
     logger: { error() {} },
-  });
-  assert.equal(service, null);
-  assert.equal(created, 0);
+  }), service);
+  assert.equal(created, 1);
 });
 
 test("synchronous plugin host construction failure leaves Netcatty available", () => {
   const errors = [];
   let registered = 0;
-  const service = startDevelopmentPluginHost({
+  const service = startPluginHost({
     env: { NETCATTY_PLUGIN_DEV: "1" },
     createService() { throw new Error("corrupt plugin database"); },
     registerShutdown() { registered += 1; },
@@ -41,7 +41,7 @@ test("created plugin host initializes and registers one shutdown owner", async (
       async shutdown() { shutdown += 1; },
     },
   };
-  assert.equal(startDevelopmentPluginHost({
+  assert.equal(startPluginHost({
     env: { NETCATTY_PLUGIN_DEV: "1" },
     createService: () => service,
     registerShutdown(handler) { shutdownHandler = handler; },
@@ -63,7 +63,7 @@ test("asynchronous initialization failure closes and leaves the host unavailable
       shutdown: async () => { shutdown += 1; },
     },
   };
-  assert.equal(startDevelopmentPluginHost({
+  assert.equal(startPluginHost({
     env: { NETCATTY_PLUGIN_DEV: "1" },
     createService: () => service,
     registerShutdown(handler) { shutdownHandler = handler; },
@@ -79,7 +79,7 @@ test("asynchronous initialization failure closes and leaves the host unavailable
 test("failure while registering shutdown closes the constructed host", async () => {
   let shutdown = 0;
   const errors = [];
-  const service = startDevelopmentPluginHost({
+  const service = startPluginHost({
     env: { NETCATTY_PLUGIN_DEV: "1" },
     createService: () => ({
       manager: {

electron/plugins/hostService.cjs

@@ -1,8 +1,10 @@
 "use strict";
 
 const path = require("node:path");
+const NETWORK_CREDENTIAL_LEASE_FEATURE = require("./generated/plugin-contract.schema.json").$defs.NetworkCredentialLeaseFeature.const;
 
-const { PLUGIN_API_VERSION } = require("./constants.cjs");
+const { assertBrowserOnlyPlugin } = require("../../domain/pluginRuntimePolicy.cjs");
+const { isPluginDevelopmentEnabled, PLUGIN_API_VERSION } = require("./constants.cjs");
 const { PluginDatabase } = require("./database.cjs");
 const { PluginCompanionSupervisor } = require("./companionSupervisor.cjs");
 const { PluginCredentialBroker, assertLeaseParams } = require("./credentialBroker.cjs");
@@ -16,6 +18,7 @@ const {
   createUtilityModuleMappings,
   normalizePluginModuleResources,
 } = require("./moduleResources.cjs");
+const { RegistryCatalogService } = require("./registryCatalogService.cjs");
 const { PackageStore } = require("./packageStore.cjs");
 const { createPluginPaths } = require("./paths.cjs");
 const { PluginManager } = require("./pluginManager.cjs");
@@ -78,17 +81,19 @@ function collectInstalledSyncProviderCatalog(database) {
 }
 
 function createPluginHostService(options) {
+  const allowAdvancedPlugins = isPluginDevelopmentEnabled(options.env ?? process.env);
   const paths = createPluginPaths(options.app.getPath("userData"));
   const appRoot = options.appRoot ?? options.app.getAppPath();
   const runtimeDirectory = options.runtimeDirectory ?? path.join(__dirname, "runtime");
   const database = new PluginDatabase(paths.database);
   try {
     const packageStore = new PackageStore({
+      allowAdvancedPlugins,
       paths,
       database,
       netcattyVersion: options.app.getVersion(),
       apiVersion: PLUGIN_API_VERSION,
-      supportedFeatures: options.supportedFeatures ?? [],
+      supportedFeatures: [...new Set(["metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, ...(options.supportedFeatures ?? [])])],
     });
     const contributionIconService = new PluginContributionIconService({
       database,
@@ -178,11 +183,13 @@ function createPluginHostService(options) {
     }
     const requestedRuntimeResolver = options.resolveRuntimeKind ?? resolveDefaultRuntimeKind;
     const resolveRuntimeKind = async (context) => {
+      if (!allowAdvancedPlugins) assertBrowserOnlyPlugin(context.plugin.manifest);
       const kind = await requestedRuntimeResolver(context);
       if (
         (kind !== "browser" && kind !== "utility")
         || !context.availableKinds.includes(kind)
       ) throw new Error(`Plugin runtime selection is unavailable: ${String(kind)}`);
+      if (!allowAdvancedPlugins && kind !== "browser") throw new Error("Advanced plugin runtime requires developer mode");
       await permissionEngine.authorizeRequired(context.plugin, {
         securityPrincipal: context.securityPrincipal,
         signal: context.signal,
@@ -217,7 +224,7 @@ function createPluginHostService(options) {
       paths,
       netcattyVersion: options.app.getVersion(),
       apiVersion: PLUGIN_API_VERSION,
-      supportedFeatures: options.supportedFeatures ?? [],
+      supportedFeatures: [...new Set(["metadata.brand-icon", NETWORK_CREDENTIAL_LEASE_FEATURE, ...(options.supportedFeatures ?? [])])],
       runtimeDirectory,
       appRoot,
       rpcRegistry,
@@ -347,6 +354,7 @@ function createPluginHostService(options) {
         })
       : null;
     const manager = new PluginManager({
+      permissionEngine,
       database,
       packageStore,
       runtimeSupervisor,
@@ -363,6 +371,7 @@ function createPluginHostService(options) {
       },
     });
     return {
+      catalogService: new RegistryCatalogService({ manager, fetch: options.electron.net?.fetch?.bind(options.electron.net) }),
       companionSupervisor,
       contributionIconService,
       contributionService,

electron/plugins/hostService.test.cjs

@@ -16,6 +16,7 @@ function createOptions(root, configureRpcRegistry) {
       getPath: () => root,
       getVersion: () => "0.0.0",
     },
+    env: { NETCATTY_PLUGIN_DEV: "1" },
     electron: {},
     configureRpcRegistry,
   };
@@ -386,3 +387,17 @@ test("custom host methods without an explicit authorization classification are d
     /no authorization policy/,
   );
 });
+
+test("normal release blocks a custom utility placement before permission prompts", async (context) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-normal-mode-"));
+  context.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  let prompts = 0;
+  const service = createPluginHostService({ ...createOptions(root), env: {}, resolveRuntimeKind: () => "utility", requestPermissionDecision: () => { prompts++; } });
+  context.after(() => service.database.close());
+  await assert.rejects(service.runtimeSupervisor.resolveRuntimeKind({
+    plugin: { id: "com.example.safe", manifest: { main: { browser: "index.js" } } },
+    availableKinds: ["browser", "utility"],
+    signal: new AbortController().signal,
+  }), /requires developer mode/);
+  assert.equal(prompts, 0);
+});

electron/plugins/leaseHttpExample.test.cjs

@@ -0,0 +1,47 @@
+"use strict";
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { MessageChannel } = require("node:worker_threads");
+const { PluginRpcRouter } = require("./rpcRouter.cjs");
+
+test("browser lease example negotiates its feature and forwards only an opaque lease", async () => {
+  const { startPluginRuntime } = await import("./runtime/runtimePeer.mjs");
+  const fixture = await import("../../examples/plugins/lease-http/browser.js");
+  const calls = [];
+  const secret = { kind: "secret", id: "s".repeat(32), key: "synthetic-token" };
+  const lease = { kind: "secret-lease", id: "l".repeat(32), operationId: "network:https://example.invalid", expiresAt: Date.now() + 30_000 };
+  const { port1, port2 } = new MessageChannel();
+  const host = new PluginRpcRouter({
+    pluginId: "com.netcatty.lease-http",
+    send: (message) => port1.postMessage(message),
+    handlers: {
+      "secrets.set": async (params) => { calls.push("secret"); assert.equal(params.key, secret.key); return { secret }; },
+      "credentials.createLease": async (params) => {
+        calls.push("lease"); assert.deepEqual(params.secret, secret); assert.equal(params.operationId, lease.operationId); return lease;
+      },
+      "network.request": async (params) => {
+        calls.push("network");
+        assert.deepEqual(params, { url: "https://example.invalid/synthetic", credentialLease: lease, authorization: { scheme: "Bearer" } });
+        assert.equal(JSON.stringify(params).includes("synthetic-acceptance-token"), false);
+        return { status: 200, url: params.url, headers: {}, body: { encoding: "base64", data: "" } };
+      },
+    },
+  });
+  port1.on("message", (message) => { void host.accept(message); });
+  const peer = await startPluginRuntime({
+    port: port2,
+    config: { pluginId: "com.netcatty.lease-http", pluginVersion: "0.1.0", netcattyVersion: "0.0.0", apiVersion: "0.1.0-internal.1", enabledFeatures: ["network.credential-lease"] },
+    loadPlugin: async () => fixture,
+  });
+  try {
+    const initialized = await host.request("plugin.initialize", { netcattyVersion: "0.0.0", apiVersion: "0.1.0-internal.1", supportedFeatures: ["network.credential-lease"] });
+    assert.deepEqual(initialized.enabledFeatures, ["network.credential-lease"]);
+    await host.request("plugin.activate", {});
+    assert.deepEqual(await host.request("plugin.command.execute", { command: "com.netcatty.lease-http.request", invocation: { source: "palette" } }), { status: 200 });
+    assert.deepEqual(calls, ["secret", "lease", "network"]);
+  } finally {
+    await peer.dispose();
+    host.close();
+    port1.close();
+  }
+});

electron/plugins/nativePermissionDecision.cjs

@@ -1,5 +1,7 @@
 "use strict";
 
+const { describePluginPermission } = require("../../domain/pluginPermissionDescriptions.cjs");
+
 const MAX_VISIBLE_RESOURCES = 20;
 const MAX_VISIBLE_FIELD_LENGTH = 1_024;
 const UNSAFE_DISPLAY_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/gu;
@@ -14,7 +16,8 @@ function escapePermissionText(value, maxLength = MAX_VISIBLE_FIELD_LENGTH) {
   });
 }
 
-function describePermissionRequest(request) {
+function describePermissionRequest(request, locale = "en") {
+  const permission = describePluginPermission(request.permission, locale);
   const identity = request.pluginName
     ? `${escapePermissionText(request.pluginName)} (${escapePermissionText(request.pluginId)})`
     : escapePermissionText(request.pluginId);
@@ -31,6 +34,7 @@ function describePermissionRequest(request) {
     `Plugin: ${identity}`,
     ...(request.publisher ? [`Publisher: ${escapePermissionText(request.publisher)}`] : []),
     `Permission: ${escapePermissionText(request.permission)}`,
+    `${permission.label}: ${permission.description}`,
     `Reason: ${escapePermissionText(request.reason)}`,
     ...(visibleResources.length ? ["Resources:", ...visibleResources] : []),
   ].join("\n");
@@ -41,9 +45,9 @@ function createNativePermissionDecisionProvider(options) {
     throw new TypeError("Native plugin permission decisions require an Electron dialog");
   }
   const dialog = options.dialog;
-  const window = options.window;
   return async (request, context = {}) => {
     context.signal?.throwIfAborted();
+    if (!describePluginPermission(request.permission).known) return Object.freeze({ requestId: request.requestId, decision: "deny" });
     const allowedScopes = Array.isArray(request.allowedScopes)
       ? new Set(request.allowedScopes)
       : null;
@@ -65,13 +69,16 @@ function createNativePermissionDecisionProvider(options) {
       type: "warning",
       title: "Plugin permission request",
       message: `${escapePermissionText(request.pluginName ?? request.pluginId)} requests ${escapePermissionText(request.permission)}`,
-      detail: describePermissionRequest(request),
+      detail: describePermissionRequest(request, options.getLocale?.() ?? "en"),
       buttons: choices.map(({ label }) => label),
       defaultId: 0,
       cancelId: 0,
       noLink: true,
       ...(context.signal ? { signal: context.signal } : {}),
     };
+    // Choose a host-owned parent when the prompt opens, not once at bootstrap.
+    const candidate = options.getWindow?.() ?? options.window;
+    const window = candidate?.isDestroyed?.() ? undefined : candidate;
     const result = window
       ? await dialog.showMessageBox(window, messageBoxOptions)
       : await dialog.showMessageBox(messageBoxOptions);

electron/plugins/nativePermissionDecision.test.cjs

@@ -131,3 +131,36 @@ test("native permission dialogs visibly escape control and bidi characters", asy
   assert.equal(captured.detail.split("\n").filter((line) => line.startsWith("Permission:")).length, 1);
   assert.equal(escapePermissionText("x".repeat(MAX_VISIBLE_FIELD_LENGTH + 20)).length, MAX_VISIBLE_FIELD_LENGTH);
 });
+
+test("native prompts share human-readable permission explanations and deny unknown permission IDs", async () => {
+  assert.match(describePermissionRequest(permissionRequest({ permission: "terminal.output" }), "zh-CN"), /读取终端输出/);
+  assert.match(describePermissionRequest(permissionRequest({ permission: "terminal.output" })), /credentials or private data/);
+  let prompts = 0;
+  const provider = createNativePermissionDecisionProvider({ dialog: { showMessageBox: async () => { prompts++; return { response: 1 }; } } });
+  assert.deepEqual(await provider(permissionRequest({ permission: "unknown.permission" })), { requestId: "request-1", decision: "deny" });
+  assert.equal(prompts, 0);
+});
+
+
+test("permission parent is resolved at prompt time without forcing focus", async () => {
+  const main = { name: "main" };
+  const settings = { name: "settings", isDestroyed: () => false };
+  let active = main;
+  const parents = [];
+  const provider = createNativePermissionDecisionProvider({
+    window: main,
+    getWindow: () => active,
+    dialog: { async showMessageBox(...args) {
+      parents.push(args.length === 2 ? args[0] : null);
+      return { response: 0 };
+    } },
+  });
+  await provider(permissionRequest());
+  active = settings;
+  await provider(permissionRequest());
+  active = { isDestroyed: () => true };
+  await provider(permissionRequest());
+  active = null;
+  await provider(permissionRequest());
+  assert.deepEqual(parents, [main, settings, null, main]);
+});

electron/plugins/networkBroker.cjs

@@ -1,5 +1,9 @@
 "use strict";
 
+const { createDefinitionValidator } = require("./contractValidator.cjs");
+const validateLease = createDefinitionValidator("SecretLeaseRef");
+const validateAuthorization = createDefinitionValidator("PluginNetworkAuthorization");
+
 const { PluginRpcError, RPC_ERRORS } = require("./rpcRouter.cjs");
 const { PLUGIN_RPC_MAX_RAW_BYTES } = require("./constants.cjs");
 const { canonicalizeNetworkOrigin } = require("./permissionResources.cjs");
@@ -180,15 +184,7 @@ class PluginNetworkBroker {
     // network.request lease injection would become dead code.
     if (params?.credentialLease !== undefined) {
       const lease = params.credentialLease;
-      if (
-        !lease
-        || typeof lease !== "object"
-        || Array.isArray(lease)
-        || lease.kind !== "secret-lease"
-        || typeof lease.id !== "string"
-        || typeof lease.operationId !== "string"
-        || !Number.isFinite(lease.expiresAt)
-      ) {
+      if (!validateLease(lease)) {
         throw invalidArgument("Plugin network credential lease is invalid");
       }
       validated.credentialLease = Object.freeze({
@@ -200,7 +196,7 @@ class PluginNetworkBroker {
     }
     if (params?.authorization !== undefined) {
       const authorization = params.authorization;
-      if (!authorization || typeof authorization !== "object" || Array.isArray(authorization)) {
+      if (!validateAuthorization(authorization)) {
         throw invalidArgument("Plugin network authorization is invalid");
       }
       const scheme = authorization.scheme === "Basic" ? "Basic" : "Bearer";

electron/plugins/networkBroker.test.cjs

@@ -157,7 +157,10 @@ test("network response streaming stops above the byte cap", async () => {
   );
 });
 
-test("network broker reports its own timeout as a stable deadline error", async () => {
+test("network broker reports its own timeout as a stable deadline error", async (context) => {
+  // A real request owns a socket; this pending fake must also keep the loop alive.
+  const keepAlive = setInterval(() => {}, 1_000);
+  context.after(() => clearInterval(keepAlive));
   const broker = new PluginNetworkBroker({
     fetch: async (_url, options) => new Promise((_resolve, reject) => {
       options.signal.addEventListener("abort", () => reject(options.signal.reason), { once: true });
@@ -169,3 +172,14 @@ test("network broker reports its own timeout as a stable deadline error", async
     (error) => error.code === RPC_ERRORS.deadlineExceeded,
   );
 });
+
+test("credential field validation follows the canonical contract and keeps Bearer default", () => {
+  const broker = new PluginNetworkBroker({ permissionEngine: {} });
+  const lease = { kind: "secret-lease", id: "l".repeat(32), operationId: "network:https://example.invalid", expiresAt: 1000 };
+  const request = { url: "https://example.invalid", credentialLease: lease, authorization: {} };
+  assert.deepEqual(broker.validate(request).authorization, { scheme: "Bearer" });
+  for (const authorization of [{ scheme: "Digest" }, { scheme: "Basic", username: "name\n" }, { password: "synthetic" }]) {
+    assert.throws(() => broker.validate({ ...request, authorization }), /authorization is invalid/);
+  }
+  assert.throws(() => broker.validate({ ...request, credentialLease: { ...lease, id: "short" } }), /lease is invalid/);
+});

electron/plugins/packageStore.cjs

@@ -21,6 +21,9 @@ const {
   resolveInstalledVersionDirectory,
 } = require("./paths.cjs");
 
+const { assertBrowserOnlyPlugin } = require("../../domain/pluginRuntimePolicy.cjs");
+const { assertCatalogManifest } = require("./catalogPolicy.cjs");
+
 const INSTALL_METADATA_FILE = "install.json";
 const ARCHIVE_SNAPSHOT_FILE = "package.ncpkg";
 const PACKAGE_DIRECTORY = "package";
@@ -136,6 +139,7 @@ function validateRemovalMetadata(value) {
 
 class PackageStore {
   constructor(options) {
+    this.allowAdvancedPlugins = options.allowAdvancedPlugins !== false;
     this.paths = options.paths;
     this.database = options.database;
     this.netcattyVersion = options.netcattyVersion;
@@ -151,6 +155,41 @@ class PackageStore {
       .filter((value) => typeof value === "string" && value !== this.paths.database)
       .map((directory) => mkdir(directory, { recursive: true, mode: 0o700 })));
     await this.recover();
+    // Reconcile every installed manifest before lazy contributions are exposed.
+    // An application/API upgrade must not leave incompatible providers enabled.
+    for (const plugin of this.database.listPlugins()) {
+      if (!plugin.enabled) continue;
+      await this.assertCompatible(plugin).catch((error) => {
+        if (!["PLUGIN_INCOMPATIBLE", "PLUGIN_UNSUPPORTED_RUNTIME"].includes(error.code)) throw error;
+      });
+    }
+  }
+
+  async assertCompatible(plugin) {
+    const pluginCli = await loadPluginCli();
+    const result = pluginCli.checkPluginCompatibility(plugin.manifest, {
+      netcattyVersion: this.netcattyVersion,
+      apiVersion: this.apiVersion,
+      features: this.supportedFeatures,
+    });
+    let error;
+    if (!this.allowAdvancedPlugins) {
+      try { assertBrowserOnlyPlugin(plugin.manifest); } catch (cause) { error = cause; }
+    }
+    if (!error && result.compatible) return result;
+    if (!error) {
+      error = new Error(`Plugin is incompatible: ${result.errors.join("; ")}`);
+      error.code = "PLUGIN_INCOMPATIBLE";
+    }
+    const current = this.database.getActivePlugin(plugin.id);
+    if (current?.activeVersion === plugin.activeVersion) {
+      this.database.setEnabled(plugin.id, false);
+      this.database.setRuntimeState(plugin.id, "error", {
+        pluginVersion: plugin.activeVersion,
+        error: error.message,
+      });
+    }
+    throw error;
   }
 
   async install(archivePath, options = {}) {
@@ -175,6 +214,7 @@ class PackageStore {
       const validation = await pluginCli.extractPluginPackage(archiveSnapshot, extractedDirectory);
       await syncDirectoryTree(extractedDirectory);
       const manifest = validation.manifest;
+      if (!this.allowAdvancedPlugins) assertBrowserOnlyPlugin(manifest);
       const compatibility = pluginCli.checkPluginCompatibility(manifest, {
         netcattyVersion: this.netcattyVersion,
         apiVersion: this.apiVersion,
@@ -187,7 +227,16 @@ class PackageStore {
       const version = assertPluginStorageSegment(manifest.version, "version");
       const targetDirectory = resolveInstalledVersionDirectory(this.paths, pluginId, version);
       const previousPlugin = this.database.getActivePlugin(pluginId);
-      const enableAfterActivation = options.enable === true || previousPlugin?.enabled === true;
+      if (options.catalog) {
+        if (snapshot.sha256 !== options.catalog.artifact.sha256) throw new Error("Catalog package SHA-256 mismatch");
+        assertCatalogManifest(manifest, options.catalog);
+        // Detail-page permissions and engine ranges must describe these exact bytes.
+        const { isDeepStrictEqual } = require("node:util");
+        if (!isDeepStrictEqual(manifest, options.catalog.manifest)) throw new Error("Catalog manifest does not match package");
+      }
+      const enableAfterActivation = options.enable === false
+        ? false
+        : options.enable === true || previousPlugin?.enabled === true;
       let activationPrepared = false;
       const prepareActivation = async (reason) => {
         if (activationPrepared) return;
@@ -214,7 +263,7 @@ class PackageStore {
           await rm(targetDirectory, { recursive: true, force: true });
         }
         if (existingValidation) {
-          if (previousPlugin?.activeVersion !== version) await prepareActivation("switch-active-version");
+          if (previousPlugin?.activeVersion !== version || options.enable === false) await prepareActivation("switch-active-version");
           const existingPackage = path.join(targetDirectory, PACKAGE_DIRECTORY);
           this.database.installVersion({
             pluginId,
@@ -222,7 +271,7 @@ class PackageStore {
             manifest: existingValidation.manifest,
             archiveSha256: existing.archiveSha256,
             packageRelativePath: path.relative(this.paths.packages, existingPackage),
-          }, { enable: enableAfterActivation });
+          }, { enable: enableAfterActivation, forceDisabled: options.enable === false });
           return this.database.getActivePlugin(pluginId);
         }
       }
@@ -241,7 +290,7 @@ class PackageStore {
       await writeDurableMetadata(path.join(stagingDirectory, INSTALL_METADATA_FILE), metadata);
       await this.syncDirectory(stagingDirectory);
       await mkdir(path.dirname(targetDirectory), { recursive: true, mode: 0o700 });
-      if (previousPlugin?.activeVersion !== version) await prepareActivation("switch-active-version");
+      if (previousPlugin?.activeVersion !== version || options.enable === false) await prepareActivation("switch-active-version");
       await rename(stagingDirectory, targetDirectory);
       await this.syncDirectory(path.dirname(targetDirectory));
       const packageRelativePath = path.relative(
@@ -255,7 +304,7 @@ class PackageStore {
           manifest,
           archiveSha256: snapshot.sha256,
           packageRelativePath,
-        }, { enable: enableAfterActivation });
+        }, { enable: enableAfterActivation, forceDisabled: options.enable === false });
       } catch (error) {
         this.verifiedArchives.delete(this.#versionKey(pluginId, version));
         await rm(targetDirectory, { recursive: true, force: true });

electron/plugins/packageStore.test.cjs

@@ -370,3 +370,89 @@ test("failed package validation removes every extracted staging file", async (co
   assert.deepEqual(await fs.promises.readdir(fixture.paths.staging), []);
   assert.deepEqual(fixture.database.listPlugins(), []);
 });
+
+test("host upgrade disables incompatible lazy plugins before contributions and retains data", async (context) => {
+  const fixture = createStore(context);
+  await fixture.store.initialize();
+  const archive = await createPackage(fixture.root, {
+    manifest: { engines: { netcatty: "<1.0.0", api: ">=0.1.0-internal <0.2.0" } },
+  });
+  const installed = await fixture.store.install(archive.archive, { enable: true });
+  fixture.database.setValue(installed.id, "synthetic", { retained: true });
+  fixture.store.netcattyVersion = "1.0.0";
+  await fixture.store.initialize();
+  const disabled = fixture.database.getActivePlugin(installed.id);
+  assert.equal(disabled.enabled, false);
+  assert.match(disabled.runtime.lastError, /incompatible.*Netcatty/);
+  assert.equal(disabled.activeVersion, installed.activeVersion);
+  assert.deepEqual(fixture.database.getValue(installed.id, "synthetic"), { retained: true });
+  assert.equal(fs.existsSync(fixture.store.resolvePackageRoot(disabled)), true);
+  await assert.rejects(fixture.store.assertCompatible(disabled), { code: "PLUGIN_INCOMPATIBLE" });
+  fixture.store.netcattyVersion = "0.0.0";
+  await fixture.store.initialize();
+  assert.equal(fixture.database.getActivePlugin(installed.id).enabled, false,
+    "returning to a compatible host must not silently re-enable code");
+});
+
+for (const target of [
+  { apiVersion: "0.2.0" },
+  { supportedFeatures: [] },
+]) {
+  test(`startup checks API and required feature compatibility: ${JSON.stringify(target)}`, async (context) => {
+    const fixture = createStore(context, { supportedFeatures: ["example.feature"] });
+    await fixture.store.initialize();
+    const archive = await createPackage(fixture.root, {
+      manifest: { features: { required: ["example.feature"] } },
+    });
+    const installed = await fixture.store.install(archive.archive, { enable: true });
+    Object.assign(fixture.store, target);
+    await fixture.store.initialize();
+    assert.equal(fixture.database.getActivePlugin(installed.id).enabled, false);
+  });
+}
+
+test("explicit disabled import never auto-enables an update of an enabled plugin", async (context) => {
+  const fixture = createStore(context);
+  await fixture.store.initialize();
+  const first = await createPackage(fixture.root);
+  await fixture.store.install(first.archive, { enable: true });
+  const update = await createPackage(fixture.root, { manifest: { version: "1.1.0" } });
+  const installed = await fixture.store.install(update.archive, { enable: false });
+  assert.equal(installed.activeVersion, "1.1.0");
+  assert.equal(installed.enabled, false);
+});
+
+test("catalog installation verifies actual package manifest and rejects Node before activation", async (context) => {
+  const fixture = createStore(context);
+  await fixture.store.initialize();
+  const archive = await createPackage(fixture.root, { manifest: { license: "MIT" } });
+  const sha256 = createHash("sha256").update(await fs.promises.readFile(archive.archive)).digest("hex");
+  const entry = { id: archive.manifest.id, version: archive.manifest.version, license: "MIT", manifest: archive.manifest, artifact: { sha256 } };
+  await assert.rejects(fixture.store.install(archive.archive, { catalog: { ...entry, version: "9.0.0" } }), /identity\/version/);
+  await assert.rejects(fixture.store.install(archive.archive, { catalog: { ...entry, artifact: { sha256: "0".repeat(64) } } }), /SHA-256/);
+  await assert.rejects(fixture.store.install(archive.archive, { catalog: { ...entry, manifest: { ...archive.manifest, description: "different" } } }), /manifest does not match/);
+  assert.equal(fixture.database.listPlugins().length, 0);
+  assert.equal((await fixture.store.install(archive.archive, { enable: false, catalog: entry })).enabled, false);
+  const advanced = await createPackage(fixture.root, { manifest: { version: "2.0.0", license: "MIT", main: { node: "dist/index.js" }, permissions: { required: ["runtime.advanced"] } } });
+  const advancedEntry = { ...entry, version: "2.0.0", manifest: advanced.manifest, artifact: { sha256: createHash("sha256").update(await fs.promises.readFile(advanced.archive)).digest("hex") } };
+  await assert.rejects(fixture.store.install(advanced.archive, { catalog: advancedEntry }), /browser-only packages/);
+  assert.equal(fixture.database.getActivePlugin(entry.id).activeVersion, "1.0.0");
+});
+
+test("normal release refuses advanced local imports and disables previously installed lazy packages", async (context) => {
+  const fixture = createStore(context);
+  await fixture.store.initialize();
+  const archive = await createPackage(fixture.root, { manifest: {
+    main: { browser: "dist/index.js", node: "dist/index.js" },
+    permissions: { optional: ["runtime.advanced"] },
+  } });
+  const installed = await fixture.store.install(archive.archive, { enable: true });
+  fixture.database.setValue(installed.id, "synthetic", 42);
+  fixture.store.allowAdvancedPlugins = false;
+  await fixture.store.initialize();
+  assert.equal(fixture.database.getActivePlugin(installed.id).enabled, false);
+  assert.match(fixture.database.getActivePlugin(installed.id).runtime.lastError, /developer mode/);
+  assert.equal(fixture.database.getValue(installed.id, "synthetic"), 42);
+  await assert.rejects(fixture.store.install(archive.archive), /browser-only packages/);
+  await assert.rejects(fixture.store.assertCompatible(installed), /browser-only packages/);
+});

electron/plugins/packaging.test.cjs

@@ -12,13 +12,17 @@ test("packaged application declares every plugin host runtime dependency and res
     "@netcatty/plugin-contract",
     "@netcatty/plugin-sdk",
   ]) {
-    assert.equal(packageJson.dependencies[dependency], "0.1.0-internal");
+    const workspace = JSON.parse(fs.readFileSync(path.join(__dirname, "../../packages", dependency.split("/")[1], "package.json"), "utf8"));
+    assert.equal(packageJson.dependencies[dependency], workspace.version);
+    assert.equal(workspace.version, require("./constants.cjs").PLUGIN_API_VERSION);
   }
   const builderSource = fs.readFileSync(path.join(__dirname, "../../electron-builder.config.cjs"), "utf8");
   assert.match(builderSource, /node_modules\/@netcatty\/plugin-cli\/\*\*\/\*/);
   assert.match(builderSource, /node_modules\/@netcatty\/plugin-contract\/\*\*\/\*/);
   assert.match(builderSource, /node_modules\/@netcatty\/plugin-sdk\/\*\*\/\*/);
   assert.match(builderSource, /electron\/plugins\/runtime\/\*\*\/\*/);
+  assert.match(builderSource, /domain\/pluginRuntimePolicy\.cjs/);
+  assert.match(builderSource, /domain\/pluginPermissionDescriptions\.cjs/);
   assert.match(builderSource, /!electron\/plugins\/fixtures\/\*\*\/\*/);
 });
 
@@ -35,7 +39,6 @@ test("clean-checkout test entrypoints build plugin runtime workspaces first", ()
     packageJson.scripts.pretest,
     /^npm run build:plugin-runtime-deps(?: && npm run check:codebuddy-sdk-contract)?$/,
   );
-  for (const lifecycle of ["pretest:plugin-runtime", "pretest:plugin-runtime:electron"]) {
-    assert.equal(packageJson.scripts[lifecycle], "npm run build:plugin-runtime-deps");
-  }
+  assert.equal(packageJson.scripts["pretest:plugin-runtime"], "npm run build:plugin-runtime-deps && npm run build --workspace @netcatty/example-starter-plugin");
+  assert.equal(packageJson.scripts["pretest:plugin-runtime:electron"], "npm run build:plugin-runtime-deps");
 });

electron/plugins/pluginBridge.cjs

@@ -3,7 +3,9 @@
 const fs = require("node:fs/promises");
 const { randomUUID } = require("node:crypto");
 
-const { isPluginDevelopmentEnabled } = require("./constants.cjs");
+const { createDefinitionValidator } = require("./contractValidator.cjs");
+const validateManagedPluginId = createDefinitionValidator("PluginId");
+
 const { raceWithAbort } = require("./rpcRouter.cjs");
 const {
   INLINE_SYNC_OBJECT_SAFE_BYTES,
@@ -15,11 +17,17 @@ const { assertSecretKey } = require("./secretStore.cjs");
 const CHANNELS = Object.freeze({
   status: "netcatty:plugins:status",
   list: "netcatty:plugins:list",
+  permissions: "netcatty:plugins:permissions",
+  revokePermissions: "netcatty:plugins:revoke-permissions",
+  catalog: "netcatty:plugins:catalog",
+  catalogReadme: "netcatty:plugins:catalog-readme",
+  catalogInstall: "netcatty:plugins:catalog-install",
   install: "netcatty:plugins:install",
   setEnabled: "netcatty:plugins:set-enabled",
   restart: "netcatty:plugins:restart",
   uninstall: "netcatty:plugins:uninstall",
   contributions: "netcatty:plugins:contributions",
+  brandIcon: "netcatty:plugins:brand-icon",
   contributionIcon: "netcatty:plugins:contribution-icon",
   contributionsChanged: "netcatty:plugins:contributions-changed",
   executeCommand: "netcatty:plugins:execute-command",
@@ -209,7 +217,6 @@ function registerPluginBridge(ipcMain, options) {
   const getTerminalWorkerManager = options.getTerminalWorkerManager ?? (() => null);
   const selectImporterFile = options.selectImporterFile;
   const viewHost = options.viewHost;
-  const env = options.env ?? process.env;
   const isTrustedSender = options.isTrustedSender;
   const defaultScopeCatalog = normalizePluginScopeCatalog({ device: [{ id: "device", label: "This device" }] });
   const scopeCatalogs = new Map();
@@ -251,15 +258,14 @@ function registerPluginBridge(ipcMain, options) {
       if (scopeCatalogs.delete(key)) publishScopeCatalog();
     });
   };
-  const configured = isPluginDevelopmentEnabled(env)
-    && Boolean(manager)
+  const configured = Boolean(manager)
     && typeof manager.initialize === "function";
   const resolveManager = async () => {
-    if (!configured) throw new Error("Plugin development runtime is disabled or unavailable");
+    if (!configured) throw new Error("Plugin runtime is disabled or unavailable");
     try {
       await manager.initialize();
     } catch (cause) {
-      throw new Error("Plugin development runtime is disabled or unavailable", { cause });
+      throw new Error("Plugin runtime is disabled or unavailable", { cause });
     }
     return manager;
   };
@@ -641,12 +647,54 @@ function registerPluginBridge(ipcMain, options) {
       await resolveManager();
       available = true;
     } catch {}
-    return { available, experimental: true };
+    return { available, experimental: true,
+      ...(typeof credentialResolver?.isAvailable === "function"
+        ? { credentialStorageAvailable: credentialResolver.isAvailable() } : {}),
+    };
+  });
+  handle(CHANNELS.catalog, async () => options.catalogService?.list() ?? { entries: [], source: "builtin", error: "Plugin catalog unavailable" });
+  handle(CHANNELS.catalogReadme, async (_manager, payload) => {
+    if (!options.catalogService) throw new Error("Plugin catalog unavailable");
+    return options.catalogService.readme(payload?.id, payload?.selectionToken);
+  });
+  handle(CHANNELS.catalogInstall, async (_manager, payload) => {
+    if (!options.catalogService) throw new Error("Plugin catalog unavailable");
+    return options.catalogService.install(payload?.id, payload?.selectionToken);
   });
   handle(CHANNELS.list, async (activeManager) => activeManager.list());
+  const assertManagedPluginId = (payload) => {
+    const id = payload?.pluginId;
+    if (!validateManagedPluginId(id)) {
+      throw new TypeError("Plugin ID is invalid");
+    }
+    return id;
+  };
+  handle(CHANNELS.permissions, async (_manager, payload) => {
+    const pluginId = assertManagedPluginId(payload);
+    if (!options.permissionEngine || !options.database) throw new Error("Plugin permissions are unavailable");
+    const groups = options.permissionEngine.listGrants(pluginId);
+    // Host-only summaries: never return arbitrary audit details, reasons,
+    // operation IDs, credentials, terminal content or future database columns.
+    const grants = ["always", "application", "session"].flatMap((scope) => (
+      (groups[scope] ?? []).map((grant) => ({
+        permission: grant.permission, resource: grant.resource,
+        resourceKind: grant.resourceKind, scope,
+        sessionId: grant.sessionId ?? null, grantedAt: grant.grantedAt,
+      }))
+    ));
+    const audit = options.database.listSecurityAudit(pluginId, 100).map((entry) => ({
+      event: entry.event, createdAt: entry.createdAt,
+      ...(typeof entry.details?.permission === "string" ? { permission: entry.details.permission } : {}),
+      ...(typeof entry.details?.scope === "string" ? { scope: entry.details.scope } : {}),
+    }));
+    return { grants, audit };
+  });
+  handle(CHANNELS.revokePermissions, async (activeManager, payload) => (
+    activeManager.revokePermissions(assertManagedPluginId(payload))
+  ));
   handle(CHANNELS.install, async (activeManager, payload) => activeManager.install(
     payload?.archivePath,
-    { enable: payload?.enable === true },
+    { enable: typeof payload?.enable === "boolean" ? payload.enable : undefined },
   ));
   handle(CHANNELS.setEnabled, async (activeManager, payload) => activeManager.setEnabled(
     payload?.pluginId,
@@ -658,6 +706,10 @@ function registerPluginBridge(ipcMain, options) {
     if (!contributionService) throw new Error("Plugin contributions are unavailable");
     return contributionService.snapshot(payload ?? {});
   });
+  handle(CHANNELS.brandIcon, async (_activeManager, payload) => {
+    if (!options.resolveBrandIcon) throw new Error("Plugin brand icons are unavailable");
+    return options.resolveBrandIcon(payload?.pluginId);
+  });
   handle(CHANNELS.contributionIcon, async (_activeManager, payload) => {
     if (!options.resolveContributionIcon) throw new Error("Plugin contribution icons are unavailable");
     return options.resolveContributionIcon(payload);

electron/plugins/pluginBridge.test.cjs

@@ -1599,3 +1599,71 @@ test("syncDeleteSecrets uses retained provider binding when contribution is miss
   assert.deepEqual(deleted, [["com.example", "prefix:sync-credential"]]);
   assert.deepEqual(unbound, [["com.example", "com.example.sync"]]);
 });
+
+test("missing OS vault does not block curated browsing and status exposes the limitation", async () => {
+  const ipcMain = createIpcMain();
+  let selected;
+  registerPluginBridge(ipcMain, {
+    manager: { async initialize() {} },
+    env: { NETCATTY_PLUGIN_DEV: "1" },
+    isTrustedSender: (event) => event.trusted === true,
+    credentialResolver: { isAvailable: () => false },
+    catalogService: {
+      list: () => [{ id: "com.example.synthetic" }],
+      install: async (id) => { selected = id; return { id }; },
+    },
+  });
+  const event = { trusted: true };
+  assert.deepEqual(await ipcMain.handlers.get(CHANNELS.status)(event), {
+    available: true, experimental: true, credentialStorageAvailable: false,
+  });
+  assert.equal((await ipcMain.handlers.get(CHANNELS.catalog)(event)).length, 1);
+  await assert.rejects(ipcMain.handlers.get(CHANNELS.catalog)({ trusted: false }), /Untrusted/);
+  await ipcMain.handlers.get(CHANNELS.catalogInstall)(event, { id: "com.example.synthetic", url: "https://attacker.invalid", enable: true });
+  assert.equal(selected, "com.example.synthetic");
+});
+
+test('brand metadata bridge accepts only trusted UI and forwards only the plugin ID', async () => {
+  const ipcMain = createIpcMain(); const seen = [];
+  registerPluginBridge(ipcMain, {
+    manager: { initialize: async () => {} },
+    isTrustedSender: (event) => event.trusted === true,
+    resolveBrandIcon: async (...args) => { seen.push(args); return { light: 'data:image/png;base64,fixture' }; },
+  });
+  await assert.rejects(ipcMain.handlers.get(CHANNELS.brandIcon)({ trusted: false }, { pluginId: 'com.test.brand' }), /Untrusted/);
+  assert.equal(seen.length, 0);
+  await ipcMain.handlers.get(CHANNELS.brandIcon)({ trusted: true }, { pluginId: 'com.test.brand', path: '/secret', url: 'https://attacker.invalid/' });
+  assert.deepEqual(seen, [['com.test.brand']]);
+});
+
+test("permission management is trusted-host-only and projects bounded audit summaries", async () => {
+  const ipcMain = createIpcMain();
+  let reads = 0;
+  const revoked = [];
+  registerPluginBridge(ipcMain, {
+    manager: { async initialize() {}, async revokePermissions(id) { revoked.push(id); return { enabled: false }; } },
+    isTrustedSender: (event) => event?.trusted === true,
+    permissionEngine: { listGrants(id) {
+      reads++;
+      assert.equal(id, "com.example.synthetic");
+      return { always: [{ permission: "network", resource: "https://example.invalid", resourceKind: "exact", grantedAt: 12, declarationHash: "private" }], application: [], session: [] };
+    } },
+    database: { listSecurityAudit(id, limit) {
+      assert.equal(id, "com.example.synthetic");
+      assert.equal(limit, 100);
+      return [{ event: "permission.used", createdAt: 13, details: { permission: "network", scope: "always", operationId: "hidden", secret: "synthetic-private" } }];
+    } },
+  });
+  const payload = { pluginId: "com.example.synthetic" };
+  for (const channel of [CHANNELS.permissions, CHANNELS.revokePermissions]) {
+    await assert.rejects(ipcMain.handlers.get(channel)({}, payload), /Untrusted/);
+    await assert.rejects(ipcMain.handlers.get(channel)({ trusted: true }, { pluginId: "../invalid" }), /Plugin ID/);
+  }
+  assert.equal(reads, 0);
+  assert.deepEqual(await ipcMain.handlers.get(CHANNELS.permissions)({ trusted: true }, payload), {
+    grants: [{ permission: "network", resource: "https://example.invalid", resourceKind: "exact", scope: "always", sessionId: null, grantedAt: 12 }],
+    audit: [{ event: "permission.used", createdAt: 13, permission: "network", scope: "always" }],
+  });
+  assert.deepEqual(await ipcMain.handlers.get(CHANNELS.revokePermissions)({ trusted: true }, payload), { enabled: false });
+  assert.deepEqual(revoked, [payload.pluginId]);
+});

electron/plugins/pluginManager.cjs

@@ -11,6 +11,7 @@ class PluginManager {
       onPluginEnabled: (pluginId) => this.runtimeSupervisor.start(pluginId),
     };
     this.beforeClose = options.beforeClose ?? null;
+    this.permissionEngine = options.permissionEngine ?? null;
     this.initialized = false;
     this.initializePromise = null;
     this.mutationTail = Promise.resolve();
@@ -52,7 +53,8 @@ class PluginManager {
       let plugin;
       try {
         plugin = await this.packageStore.install(archivePath, {
-          enable: options?.enable === true,
+          enable: options?.enable,
+          catalog: options?.catalog,
           beforeActivate: async ({ pluginId, previousPlugin }) => {
             if (!previousPlugin?.enabled) return;
             this.database.setEnabled(pluginId, false);
@@ -107,6 +109,7 @@ class PluginManager {
       await this.#ready();
       if (enabled) {
         const plugin = this.database.getActivePlugin(pluginId);
+        if (plugin) await this.packageStore.assertCompatible?.(plugin);
         if (plugin?.runtime?.quarantinedAt != null) {
           this.database.clearQuarantine(pluginId, plugin.activeVersion);
         }
@@ -126,6 +129,21 @@ class PluginManager {
     });
   }
 
+  revokePermissions(pluginId) {
+    return this.#mutate(async () => {
+      await this.#ready();
+      if (!this.permissionEngine) throw new Error("Plugin permissions are unavailable");
+      if (!this.database.getActivePlugin(pluginId)) throw new Error("Plugin is not installed");
+      // Disable before revoking. Lazy activation cannot re-create authority while
+      // runtime shutdown cancels pending RPC, streams, leases and provider work.
+      this.database.setEnabled(pluginId, false);
+      this.permissionEngine.revokeAll(pluginId);
+      this.contributionService.onPluginDisabled(pluginId);
+      await this.runtimeSupervisor.stop(pluginId);
+      return this.database.getActivePlugin(pluginId);
+    });
+  }
+
   restart(pluginId) {
     return this.#mutate(async () => {
       await this.#ready();

electron/plugins/pluginManager.test.cjs

@@ -488,3 +488,71 @@ test("shutdown cancels an in-flight runtime mutation before waiting for its queu
     "database:close",
   ]);
 });
+
+test("explicit enable checks compatibility before clearing quarantine or exposing lazy contributions", async () => {
+  const calls = [];
+  const plugin = { id: "com.example.incompatible", enabled: false, runtime: { quarantinedAt: 1 } };
+  const manager = new PluginManager({
+    database: {
+      getActivePlugin: () => plugin,
+      clearQuarantine: () => calls.push("clear"),
+      setEnabled: () => calls.push("enable"),
+    },
+    packageStore: {
+      async initialize() {},
+      async assertCompatible() { throw new Error("Plugin is incompatible"); },
+    },
+    runtimeSupervisor: {},
+    contributionService: {
+      async initialize() {},
+      onPluginEnabled: () => calls.push("contribute"),
+    },
+  });
+  await assert.rejects(manager.setEnabled(plugin.id, true), /incompatible/);
+  assert.deepEqual(calls, []);
+});
+
+test("permission revocation disables before clearing grants and waits for runtime cleanup", async () => {
+  const calls = [];
+  let releaseStop;
+  const stopped = new Promise((resolve) => { releaseStop = resolve; });
+  let enabled = true;
+  const manager = new PluginManager({
+    database: {
+      getActivePlugin: (id) => ({ id, enabled }),
+      setEnabled(_id, value) { enabled = value; calls.push("disable"); },
+    },
+    packageStore: { async initialize() {} },
+    contributionService: {
+      async initialize() {},
+      onPluginDisabled() { calls.push("contributions"); },
+    },
+    permissionEngine: { revokeAll() { assert.equal(enabled, false); calls.push("revoke"); } },
+    runtimeSupervisor: { async stop() { calls.push("stop"); await stopped; calls.push("clean"); } },
+  });
+  let complete = false;
+  const revoke = manager.revokePermissions("com.example.revoke").then((value) => { complete = true; return value; });
+  const enable = manager.setEnabled("com.example.revoke", false);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepEqual(calls, ["disable", "revoke", "contributions", "stop"]);
+  assert.equal(complete, false);
+  releaseStop();
+  assert.equal((await revoke).enabled, false);
+  await enable;
+  assert.deepEqual(calls.slice(4), ["clean", "disable", "contributions", "stop", "clean"]);
+});
+
+test("failed runtime containment leaves the revoked plugin disabled and reports failure", async () => {
+  let enabled = true;
+  let revoked = false;
+  const manager = new PluginManager({
+    database: { getActivePlugin: () => ({ enabled }), setEnabled(_id, value) { enabled = value; } },
+    packageStore: { async initialize() {} },
+    contributionService: { async initialize() {}, onPluginDisabled() {} },
+    permissionEngine: { revokeAll() { revoked = true; } },
+    runtimeSupervisor: { async stop() { throw new Error("containment failed"); } },
+  });
+  await assert.rejects(manager.revokePermissions("com.example.revoke"), /containment failed/);
+  assert.equal(enabled, false);
+  assert.equal(revoked, true);
+});

electron/plugins/registryCatalogService.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+const { PluginCatalogService, fetchBounded, validateCatalog, MAX_CATALOG_BYTES } = require("./catalogService.cjs");
+const REGISTRY_URL = "https://raw.githubusercontent.com/binaricat/netcatty-plugins/main/catalog.json";
+const tokenFor = (entry) => createHash("sha256").update(JSON.stringify(entry)).digest("hex");
+
+function prepareSnapshot(value) {
+  const entries = structuredClone(validateCatalog(value));
+  const publicEntries = structuredClone(entries).map((entry) => ({ ...entry, selectionToken: tokenFor(entry) }));
+  return { entries, publicEntries };
+}
+
+class RegistryCatalogService extends PluginCatalogService {
+  constructor(options) {
+    super(options);
+    this.publicEntries = prepareSnapshot(this.entries).publicEntries;
+    this.source = "builtin";
+    this.error = null;
+    this.refreshing = null;
+  }
+  async refresh() {
+    if (this.refreshing) return this.refreshing;
+    this.refreshing = (async () => {
+      try {
+        // No redirects: only this exact registry endpoint can replace the catalog.
+        const bytes = await fetchBounded(REGISTRY_URL, MAX_CATALOG_BYTES, this.fetch, 0);
+        const next = prepareSnapshot(JSON.parse(bytes.toString("utf8")));
+        // Publish only after full validation, clones and every token succeeded.
+        this.entries = next.entries;
+        this.publicEntries = next.publicEntries;
+        this.source = "registry";
+        this.error = null;
+        return true;
+      } catch (error) {
+        if (this.source === "registry") this.source = "cached";
+        this.error = String(error.message ?? error).slice(0, 1024);
+        return false;
+      }
+    })();
+    try { return await this.refreshing; } finally { this.refreshing = null; }
+  }
+  async list() {
+    await this.refresh();
+    return {
+      entries: structuredClone(this.publicEntries),
+      source: this.source,
+      error: this.error,
+    };
+  }
+  selected(id, token) {
+    const entry = this.get(id);
+    if (typeof token !== "string" || token !== tokenFor(entry)) {
+      throw new Error("Catalog entry changed. Refresh and review this version before continuing.");
+    }
+    return entry;
+  }
+  async readme(id, token) {
+    this.selected(id, token);
+    // Base method captures the pinned entry synchronously before its first await.
+    return super.readme(id);
+  }
+  async install(id, token) {
+    this.selected(id, token);
+    if (!await this.refresh()) throw new Error("Registry refresh failed. Cached catalogs are browse-only; retry when online.");
+    this.selected(id, token);
+    return super.install(id);
+  }
+}
+module.exports = { RegistryCatalogService, REGISTRY_URL, MAX_CATALOG_BYTES };