Fix/plugin audit findings (#2031)

* fix(plugins): enforce manifest apiVersion at install and activation

* test(plugins): exercise the absent-apiVersion default

* feat(plugins): generate the core-event catalog into host-facts

* docs(plugins): explain the packing.listBags write-permission binding

* test(plugins): cover apiVersion upload refusal; tidy docblocks and generator header

* fix(plugin-sdk): validate settings options and oauth like the host

* fix(plugin-sdk): model the full manifest shape and stop dropping fields

* fix(plugin-sdk): drop non-string routeProfiles icons like the host

* docs(plugin-sdk): document host limits, oauth contract, and ignored asUserId

* feat(plugin-sdk): enforce daily budgets and meta quotas in the mock host

* feat(plugin-sdk): expose the generated core-event catalog

* feat(plugin-sdk): scaffold trek range >=3.4.0 <5.0.0 ahead of TREK 4.0

* feat(plugin-sdk): scaffold the oauth broker settings for oauth:client plugins

* chore(plugin-sdk): fix stale mirror docs and the colliding permissions export

* docs(plugin-sdk): add the rate-limit string; restore trek docblock; match host meta sizing

* feat(plugin-sdk): raise the scaffold trek floor to 4.0.0

* docs(wiki): bring the plugin pages in line with the current runtime

* docs: bring the workspace CLAUDE.md guides up to date and make them committable

* feat(plugin-sdk): roll back failed publishes, add unrelease, sync the fork, retro-sign updates

* docs(wiki): document the publish rollback, unrelease, fork sync, and retro-signing

* chore(plugin-sdk): 1.6.0

server/tests/integration/plugins/plugin-runtime.test.ts

@@ -12,7 +12,7 @@ const { testDb } = vi.hoisted(() => {
   const Database = require('better-sqlite3');
   const db = new Database(':memory:');
   db.exec(`CREATE TABLE plugins (
-    id TEXT PRIMARY KEY, status TEXT, enabled INTEGER DEFAULT 0, version TEXT, permissions TEXT DEFAULT '[]', operator_egress INTEGER DEFAULT 0, granted_permissions TEXT DEFAULT '',
+    id TEXT PRIMARY KEY, status TEXT, enabled INTEGER DEFAULT 0, version TEXT, api_version INTEGER DEFAULT 1, permissions TEXT DEFAULT '[]', operator_egress INTEGER DEFAULT 0, granted_permissions TEXT DEFAULT '',
     config TEXT DEFAULT '{}', dependencies TEXT DEFAULT '{}', capabilities TEXT DEFAULT '{}', last_error TEXT, updated_at TEXT,
     -- Activation refuses a plugin that declares no TREK range, so the fixtures default to a
     -- satisfied one: these tests are about permissions/dependencies, and every row would
@@ -722,3 +722,39 @@ describe('TREK host-version gating', () => {
     cleanup('both-wrong');
   });
 });
+
+/**
+ * The activation gate also refuses a plugin whose manifest `apiVersion` is newer than
+ * what this TREK's plugin-API surface supports (`PLUGIN_API_VERSION`) — mirrors the
+ * TREK-version gate above, just for the plugin-API surface instead of the host version.
+ */
+describe('plugin-API version gating', () => {
+  const seedApi = (id: string, apiVersion: number) => {
+    fs.mkdirSync(path.join(codeRoot, id, 'server'), { recursive: true });
+    fs.writeFileSync(path.join(codeRoot, id, 'server', 'index.js'), 'module.exports = { async onLoad() {} };');
+    testDb
+      .prepare(
+        "INSERT INTO plugins (id, status, enabled, permissions, granted_permissions, config, trek_range, api_version) VALUES (?, 'inactive', 0, '[]', '[]', '{}', '>=3.0.0', ?)",
+      )
+      .run(id, apiVersion);
+  };
+  const cleanup = (...ids: string[]) => { for (const id of ids) testDb.prepare('DELETE FROM plugins WHERE id = ?').run(id); };
+
+  it('refuses to activate a plugin whose apiVersion this TREK does not support', async () => {
+    seedApi('future-api', 2);
+    const err = await createPluginRuntime(new DatabaseService(dbConn)).activate('future-api').catch((e) => e);
+    expect(err).toBeInstanceOf(PluginDependencyError);
+    expect(err).toMatchObject({ code: 'API_VERSION_INCOMPATIBLE' });
+    expect(err.message).toBe('plugin requires plugin-API v2; this TREK supports v1');
+    cleanup('future-api');
+  });
+
+  it('activates normally when apiVersion is within what this TREK supports', async () => {
+    seedApi('current-api', 1);
+    const rt = createPluginRuntime(new DatabaseService(dbConn));
+    await rt.activate('current-api');
+    expect(rt.isActive('current-api')).toBe(true);
+    await rt.deactivate('current-api');
+    cleanup('current-api');
+  });
+});

server/tests/integration/plugins/registry.test.ts

@@ -824,6 +824,14 @@ describe('TREK-version gating on install', () => {
       const bytes = makeArtifact({ id: 'my-upload', name: 'Up', version: '1.0.0', type: 'integration', trek: undefined });
       expect(() => svc.stageUpload(bytes)).toThrow(/missing "trek"/);
     });
+
+    it('refuses an uploaded archive declaring apiVersion 2 (this TREK only speaks plugin-API v1), and writes nothing to the plugin code dir', () => {
+      // trek range is satisfiable on its own — parseManifest's apiVersion check must
+      // fire (and stop the upload) before assertHostCompatible is ever reached.
+      const bytes = makeArtifact({ id: 'my-upload', name: 'Up', version: '1.0.0', type: 'integration', apiVersion: 2 });
+      expect(() => svc.stageUpload(bytes)).toThrow('plugin requires plugin-API v2; this TREK supports v1');
+      expect(fs.existsSync(path.join(codeRoot, 'my-upload'))).toBe(false);
+    });
   });
 
   it('installWithDependencies installs the version it RESOLVED, not versions[0]', async () => {