Merge remote-tracking branch 'public-gh/master' into paperclip-subissues

* public-gh/master: (51 commits)
  Use attachment-size limit for company logos
  Address Greptile company logo feedback
  Drop lockfile from PR branch
  Use asset-backed company logos
  fix: use appType "custom" for Vite dev server so worktree branding is applied
  docs: fix documentation drift — adapters, plugins, tech stack
  docs: update documentation for accuracy after plugin system launch
  chore: ignore superset artifacts
  Dark theme for CodeMirror code blocks in MDXEditor
  Remove duplicate @paperclipai/adapter-openclaw-gateway in server/package.json
  Fix code block styles with robust prose overrides
  Add Docker setup for untrusted PR review in isolated containers
  Fix org chart canvas height to fit viewport without scrolling
  Add doc-maintenance skill for periodic documentation accuracy audits
  Fix sidebar scrollbar: hide track background when not hovering
  Restyle markdown code blocks: dark background, smaller font, compact padding
  Add archive project button and filter archived projects from selectors
  fix: address review feedback — subscription cleanup, filter nullability, stale diagram
  fix: wire plugin event subscriptions from worker to host
  fix(ui): hide scrollbar track background when sidebar is not hovered
  ...

# Conflicts:
#	packages/db/src/migrations/meta/0030_snapshot.json
#	packages/db/src/migrations/meta/_journal.json

server/src/__tests__/assets.test.ts

@@ -0,0 +1,250 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import express from "express";
+import request from "supertest";
+import { MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+import { assetRoutes } from "../routes/assets.js";
+import type { StorageService } from "../storage/types.js";
+
+const { createAssetMock, getAssetByIdMock, logActivityMock } = vi.hoisted(() => ({
+  createAssetMock: vi.fn(),
+  getAssetByIdMock: vi.fn(),
+  logActivityMock: vi.fn(),
+}));
+
+vi.mock("../services/index.js", () => ({
+  assetService: vi.fn(() => ({
+    create: createAssetMock,
+    getById: getAssetByIdMock,
+  })),
+  logActivity: logActivityMock,
+}));
+
+function createAsset() {
+  const now = new Date("2026-01-01T00:00:00.000Z");
+  return {
+    id: "asset-1",
+    companyId: "company-1",
+    provider: "local",
+    objectKey: "assets/abc",
+    contentType: "image/png",
+    byteSize: 40,
+    sha256: "sha256-sample",
+    originalFilename: "logo.png",
+    createdByAgentId: null,
+    createdByUserId: "user-1",
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function createStorageService(contentType = "image/png"): StorageService {
+  const putFile: StorageService["putFile"] = vi.fn(async (input: {
+    companyId: string;
+    namespace: string;
+    originalFilename: string | null;
+    contentType: string;
+    body: Buffer;
+  }) => {
+    return {
+      provider: "local_disk" as const,
+      objectKey: `${input.namespace}/${input.originalFilename ?? "upload"}`,
+      contentType: contentType || input.contentType,
+      byteSize: input.body.length,
+      sha256: "sha256-sample",
+      originalFilename: input.originalFilename,
+    };
+  });
+
+  return {
+    provider: "local_disk" as const,
+    putFile,
+    getObject: vi.fn(),
+    headObject: vi.fn(),
+    deleteObject: vi.fn(),
+  };
+}
+
+function createApp(storage: ReturnType<typeof createStorageService>) {
+  const app = express();
+  app.use((req, _res, next) => {
+    req.actor = {
+      type: "board",
+      source: "local_implicit",
+      userId: "user-1",
+    };
+    next();
+  });
+  app.use("/api", assetRoutes({} as any, storage));
+  return app;
+}
+
+describe("POST /api/companies/:companyId/assets/images", () => {
+  afterEach(() => {
+    createAssetMock.mockReset();
+    getAssetByIdMock.mockReset();
+    logActivityMock.mockReset();
+  });
+
+  it("accepts PNG image uploads and returns an asset path", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/assets/images")
+      .field("namespace", "goals")
+      .attach("file", Buffer.from("png"), "logo.png");
+
+    expect(res.status).toBe(201);
+    expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
+    expect(createAssetMock).toHaveBeenCalledTimes(1);
+    expect(png.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/goals",
+      originalFilename: "logo.png",
+      contentType: "image/png",
+      body: expect.any(Buffer),
+    });
+  });
+
+  it("allows supported non-image attachments outside the company logo flow", async () => {
+    const text = createStorageService("text/plain");
+    const app = createApp(text);
+
+    createAssetMock.mockResolvedValue({
+      ...createAsset(),
+      contentType: "text/plain",
+      originalFilename: "note.txt",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/company-1/assets/images")
+      .field("namespace", "issues/drafts")
+      .attach("file", Buffer.from("hello"), { filename: "note.txt", contentType: "text/plain" });
+
+    expect(res.status).toBe(201);
+    expect(text.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/issues/drafts",
+      originalFilename: "note.txt",
+      contentType: "text/plain",
+      body: expect.any(Buffer),
+    });
+  });
+});
+
+describe("POST /api/companies/:companyId/logo", () => {
+  afterEach(() => {
+    createAssetMock.mockReset();
+    getAssetByIdMock.mockReset();
+    logActivityMock.mockReset();
+  });
+
+  it("accepts PNG logo uploads and returns an asset path", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("png"), "logo.png");
+
+    expect(res.status).toBe(201);
+    expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
+    expect(createAssetMock).toHaveBeenCalledTimes(1);
+    expect(png.putFile).toHaveBeenCalledWith({
+      companyId: "company-1",
+      namespace: "assets/companies",
+      originalFilename: "logo.png",
+      contentType: "image/png",
+      body: expect.any(Buffer),
+    });
+  });
+
+  it("sanitizes SVG logo uploads before storing them", async () => {
+    const svg = createStorageService("image/svg+xml");
+    const app = createApp(svg);
+
+    createAssetMock.mockResolvedValue({
+      ...createAsset(),
+      contentType: "image/svg+xml",
+      originalFilename: "logo.svg",
+    });
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach(
+        "file",
+        Buffer.from(
+          "<svg xmlns='http://www.w3.org/2000/svg' onload='alert(1)'><script>alert(1)</script><a href='https://evil.example/'><circle cx='12' cy='12' r='10'/></a></svg>",
+        ),
+        "logo.svg",
+      );
+
+    expect(res.status).toBe(201);
+    expect(svg.putFile).toHaveBeenCalledTimes(1);
+    const stored = (svg.putFile as ReturnType<typeof vi.fn>).mock.calls[0]?.[0];
+    expect(stored.contentType).toBe("image/svg+xml");
+    expect(stored.originalFilename).toBe("logo.svg");
+    const body = stored.body.toString("utf8");
+    expect(body).toContain("<svg");
+    expect(body).toContain("<circle");
+    expect(body).not.toContain("<script");
+    expect(body).not.toContain("onload=");
+    expect(body).not.toContain("https://evil.example/");
+  });
+
+  it("allows logo uploads within the general attachment limit", async () => {
+    const png = createStorageService("image/png");
+    const app = createApp(png);
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const file = Buffer.alloc(150 * 1024, "a");
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", file, "within-limit.png");
+
+    expect(res.status).toBe(201);
+  });
+
+  it("rejects logo files larger than the general attachment limit", async () => {
+    const app = createApp(createStorageService());
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const file = Buffer.alloc(MAX_ATTACHMENT_BYTES + 1, "a");
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", file, "too-large.png");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe(`Image exceeds ${MAX_ATTACHMENT_BYTES} bytes`);
+  });
+
+  it("rejects unsupported image types", async () => {
+    const app = createApp(createStorageService("text/plain"));
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("not an image"), "note.txt");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe("Unsupported image type: text/plain");
+    expect(createAssetMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects SVG image uploads that cannot be sanitized", async () => {
+    const app = createApp(createStorageService("image/svg+xml"));
+    createAssetMock.mockResolvedValue(createAsset());
+
+    const res = await request(app)
+      .post("/api/companies/company-1/logo")
+      .attach("file", Buffer.from("not actually svg"), "logo.svg");
+
+    expect(res.status).toBe(422);
+    expect(res.body.error).toBe("SVG could not be sanitized");
+    expect(createAssetMock).not.toHaveBeenCalled();
+  });
+});

server/src/adapters/registry.ts

@@ -51,6 +51,15 @@ import {
 import {
   agentConfigurationDoc as piAgentConfigurationDoc,
 } from "@paperclipai/adapter-pi-local";
+import {
+  execute as hermesExecute,
+  testEnvironment as hermesTestEnvironment,
+  sessionCodec as hermesSessionCodec,
+} from "hermes-paperclip-adapter/server";
+import {
+  agentConfigurationDoc as hermesAgentConfigurationDoc,
+  models as hermesModels,
+} from "hermes-paperclip-adapter";
 import { processAdapter } from "./process/index.js";
 import { httpAdapter } from "./http/index.js";
 
@@ -127,6 +136,16 @@ const piLocalAdapter: ServerAdapterModule = {
   agentConfigurationDoc: piAgentConfigurationDoc,
 };
 
+const hermesLocalAdapter: ServerAdapterModule = {
+  type: "hermes_local",
+  execute: hermesExecute,
+  testEnvironment: hermesTestEnvironment,
+  sessionCodec: hermesSessionCodec,
+  models: hermesModels,
+  supportsLocalAgentJwt: true,
+  agentConfigurationDoc: hermesAgentConfigurationDoc,
+};
+
 const adaptersByType = new Map<string, ServerAdapterModule>(
   [
     claudeLocalAdapter,
@@ -136,6 +155,7 @@ const adaptersByType = new Map<string, ServerAdapterModule>(
     cursorLocalAdapter,
     geminiLocalAdapter,
     openclawGatewayAdapter,
+    hermesLocalAdapter,
     processAdapter,
     httpAdapter,
   ].map((a) => [a.type, a]),

server/src/app.ts

@@ -38,6 +38,7 @@ import { pluginLifecycleManager } from "./services/plugin-lifecycle.js";
 import { createPluginJobCoordinator } from "./services/plugin-job-coordinator.js";
 import { buildHostServices, flushPluginLogBuffer } from "./services/plugin-host-services.js";
 import { createPluginEventBus } from "./services/plugin-event-bus.js";
+import { setPluginEventBus } from "./services/activity-log.js";
 import { createPluginDevWatcher } from "./services/plugin-dev-watcher.js";
 import { createPluginHostServiceCleanup } from "./services/plugin-host-service-cleanup.js";
 import { pluginRegistryService } from "./services/plugin-registry.js";
@@ -150,6 +151,7 @@ export async function createApp(
   const workerManager = createPluginWorkerManager();
   const pluginRegistry = pluginRegistryService(db);
   const eventBus = createPluginEventBus();
+  setPluginEventBus(eventBus);
   const jobStore = pluginJobStore(db);
   const lifecycle = pluginLifecycleManager(db, { workerManager });
   const scheduler = createPluginJobScheduler({
@@ -249,7 +251,7 @@ export async function createApp(
     const { createServer: createViteServer } = await import("vite");
     const vite = await createViteServer({
       root: uiRoot,
-      appType: "spa",
+      appType: "custom",
       server: {
         middlewareMode: true,
         hmr: {

server/src/config.ts

@@ -1,5 +1,6 @@
 import { readConfigFile } from "./config-file.js";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { config as loadDotenv } from "dotenv";
 import { resolvePaperclipEnvPath } from "./paths.js";
 import {
@@ -27,6 +28,14 @@ if (existsSync(PAPERCLIP_ENV_FILE_PATH)) {
   loadDotenv({ path: PAPERCLIP_ENV_FILE_PATH, override: false, quiet: true });
 }
 
+const CWD_ENV_PATH = resolve(process.cwd(), ".env");
+const isSameFile = existsSync(CWD_ENV_PATH) && existsSync(PAPERCLIP_ENV_FILE_PATH)
+  ? realpathSync(CWD_ENV_PATH) === realpathSync(PAPERCLIP_ENV_FILE_PATH)
+  : CWD_ENV_PATH === PAPERCLIP_ENV_FILE_PATH;
+if (!isSameFile && existsSync(CWD_ENV_PATH)) {
+  loadDotenv({ path: CWD_ENV_PATH, override: false, quiet: true });
+}
+
 type DatabaseMode = "embedded-postgres" | "postgres";
 
 export interface Config {

server/src/routes/assets.ts

@@ -1,21 +1,104 @@
 import { Router, type Request, type Response } from "express";
 import multer from "multer";
+import createDOMPurify from "dompurify";
+import { JSDOM } from "jsdom";
 import type { Db } from "@paperclipai/db";
 import { createAssetImageMetadataSchema } from "@paperclipai/shared";
 import type { StorageService } from "../storage/types.js";
 import { assetService, logActivity } from "../services/index.js";
-import { assertCompanyAccess, getActorInfo } from "./authz.js";
 import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.js";
+import { assertCompanyAccess, getActorInfo } from "./authz.js";
+const SVG_CONTENT_TYPE = "image/svg+xml";
+const ALLOWED_COMPANY_LOGO_CONTENT_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/jpg",
+  "image/webp",
+  "image/gif",
+  SVG_CONTENT_TYPE,
+]);
+
+function sanitizeSvgBuffer(input: Buffer): Buffer | null {
+  const raw = input.toString("utf8").trim();
+  if (!raw) return null;
+
+  const baseDom = new JSDOM("");
+  const domPurify = createDOMPurify(
+    baseDom.window as unknown as Parameters<typeof createDOMPurify>[0],
+  );
+  domPurify.addHook("uponSanitizeAttribute", (_node, data) => {
+    const attrName = data.attrName.toLowerCase();
+    const attrValue = (data.attrValue ?? "").trim();
+
+    if (attrName.startsWith("on")) {
+      data.keepAttr = false;
+      return;
+    }
+
+    if ((attrName === "href" || attrName === "xlink:href") && attrValue && !attrValue.startsWith("#")) {
+      data.keepAttr = false;
+    }
+  });
+
+  let parsedDom: JSDOM | null = null;
+  try {
+    const sanitized = domPurify.sanitize(raw, {
+      USE_PROFILES: { svg: true, svgFilters: true, html: false },
+      FORBID_TAGS: ["script", "foreignObject"],
+      FORBID_CONTENTS: ["script", "foreignObject"],
+      RETURN_TRUSTED_TYPE: false,
+    });
+
+    parsedDom = new JSDOM(sanitized, { contentType: SVG_CONTENT_TYPE });
+    const document = parsedDom.window.document;
+    const root = document.documentElement;
+    if (!root || root.tagName.toLowerCase() !== "svg") return null;
+
+    for (const el of Array.from(root.querySelectorAll("script, foreignObject"))) {
+      el.remove();
+    }
+    for (const el of Array.from(root.querySelectorAll("*"))) {
+      for (const attr of Array.from(el.attributes)) {
+        const attrName = attr.name.toLowerCase();
+        const attrValue = attr.value.trim();
+        if (attrName.startsWith("on")) {
+          el.removeAttribute(attr.name);
+          continue;
+        }
+        if ((attrName === "href" || attrName === "xlink:href") && attrValue && !attrValue.startsWith("#")) {
+          el.removeAttribute(attr.name);
+        }
+      }
+    }
+
+    const output = root.outerHTML.trim();
+    if (!output || !/^<svg[\s>]/i.test(output)) return null;
+    return Buffer.from(output, "utf8");
+  } catch {
+    return null;
+  } finally {
+    parsedDom?.window.close();
+    baseDom.window.close();
+  }
+}
 
 export function assetRoutes(db: Db, storage: StorageService) {
   const router = Router();
   const svc = assetService(db);
-  const upload = multer({
+  const assetUpload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
+  });
+  const companyLogoUpload = multer({
     storage: multer.memoryStorage(),
     limits: { fileSize: MAX_ATTACHMENT_BYTES, files: 1 },
   });
 
-  async function runSingleFileUpload(req: Request, res: Response) {
+  async function runSingleFileUpload(
+    upload: ReturnType<typeof multer>,
+    req: Request,
+    res: Response,
+  ) {
     await new Promise<void>((resolve, reject) => {
       upload.single("file")(req, res, (err: unknown) => {
         if (err) reject(err);
@@ -29,7 +112,7 @@ export function assetRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, companyId);
 
     try {
-      await runSingleFileUpload(req, res);
+      await runSingleFileUpload(assetUpload, req, res);
     } catch (err) {
       if (err instanceof multer.MulterError) {
         if (err.code === "LIMIT_FILE_SIZE") {
@@ -48,16 +131,6 @@ export function assetRoutes(db: Db, storage: StorageService) {
       return;
     }
 
-    const contentType = (file.mimetype || "").toLowerCase();
-    if (!isAllowedContentType(contentType)) {
-      res.status(422).json({ error: `Unsupported file type: ${contentType || "unknown"}` });
-      return;
-    }
-    if (file.buffer.length <= 0) {
-      res.status(422).json({ error: "Image is empty" });
-      return;
-    }
-
     const parsedMeta = createAssetImageMetadataSchema.safeParse(req.body ?? {});
     if (!parsedMeta.success) {
       res.status(400).json({ error: "Invalid image metadata", details: parsedMeta.error.issues });
@@ -65,13 +138,32 @@ export function assetRoutes(db: Db, storage: StorageService) {
     }
 
     const namespaceSuffix = parsedMeta.data.namespace ?? "general";
+    const contentType = (file.mimetype || "").toLowerCase();
+    if (contentType !== SVG_CONTENT_TYPE && !isAllowedContentType(contentType)) {
+      res.status(422).json({ error: `Unsupported file type: ${contentType || "unknown"}` });
+      return;
+    }
+    let fileBody = file.buffer;
+    if (contentType === SVG_CONTENT_TYPE) {
+      const sanitized = sanitizeSvgBuffer(file.buffer);
+      if (!sanitized || sanitized.length <= 0) {
+        res.status(422).json({ error: "SVG could not be sanitized" });
+        return;
+      }
+      fileBody = sanitized;
+    }
+    if (fileBody.length <= 0) {
+      res.status(422).json({ error: "Image is empty" });
+      return;
+    }
+
     const actor = getActorInfo(req);
     const stored = await storage.putFile({
       companyId,
       namespace: `assets/${namespaceSuffix}`,
       originalFilename: file.originalname || null,
       contentType,
-      body: file.buffer,
+      body: fileBody,
     });
 
     const asset = await svc.create(companyId, {
@@ -118,6 +210,105 @@ export function assetRoutes(db: Db, storage: StorageService) {
     });
   });
 
+  router.post("/companies/:companyId/logo", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+
+    try {
+      await runSingleFileUpload(companyLogoUpload, req, res);
+    } catch (err) {
+      if (err instanceof multer.MulterError) {
+        if (err.code === "LIMIT_FILE_SIZE") {
+          res.status(422).json({ error: `Image exceeds ${MAX_ATTACHMENT_BYTES} bytes` });
+          return;
+        }
+        res.status(400).json({ error: err.message });
+        return;
+      }
+      throw err;
+    }
+
+    const file = (req as Request & { file?: { mimetype: string; buffer: Buffer; originalname: string } }).file;
+    if (!file) {
+      res.status(400).json({ error: "Missing file field 'file'" });
+      return;
+    }
+
+    const contentType = (file.mimetype || "").toLowerCase();
+    if (!ALLOWED_COMPANY_LOGO_CONTENT_TYPES.has(contentType)) {
+      res.status(422).json({ error: `Unsupported image type: ${contentType || "unknown"}` });
+      return;
+    }
+
+    let fileBody = file.buffer;
+    if (contentType === SVG_CONTENT_TYPE) {
+      const sanitized = sanitizeSvgBuffer(file.buffer);
+      if (!sanitized || sanitized.length <= 0) {
+        res.status(422).json({ error: "SVG could not be sanitized" });
+        return;
+      }
+      fileBody = sanitized;
+    }
+
+    if (fileBody.length <= 0) {
+      res.status(422).json({ error: "Image is empty" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    const stored = await storage.putFile({
+      companyId,
+      namespace: "assets/companies",
+      originalFilename: file.originalname || null,
+      contentType,
+      body: fileBody,
+    });
+
+    const asset = await svc.create(companyId, {
+      provider: stored.provider,
+      objectKey: stored.objectKey,
+      contentType: stored.contentType,
+      byteSize: stored.byteSize,
+      sha256: stored.sha256,
+      originalFilename: stored.originalFilename,
+      createdByAgentId: actor.agentId,
+      createdByUserId: actor.actorType === "user" ? actor.actorId : null,
+    });
+
+    await logActivity(db, {
+      companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "asset.created",
+      entityType: "asset",
+      entityId: asset.id,
+      details: {
+        originalFilename: asset.originalFilename,
+        contentType: asset.contentType,
+        byteSize: asset.byteSize,
+        namespace: "assets/companies",
+      },
+    });
+
+    res.status(201).json({
+      assetId: asset.id,
+      companyId: asset.companyId,
+      provider: asset.provider,
+      objectKey: asset.objectKey,
+      contentType: asset.contentType,
+      byteSize: asset.byteSize,
+      sha256: asset.sha256,
+      originalFilename: asset.originalFilename,
+      createdByAgentId: asset.createdByAgentId,
+      createdByUserId: asset.createdByUserId,
+      createdAt: asset.createdAt,
+      updatedAt: asset.updatedAt,
+      contentPath: `/api/assets/${asset.id}/content`,
+    });
+  });
+
   router.get("/assets/:assetId/content", async (req, res, next) => {
     const assetId = req.params.assetId as string;
     const asset = await svc.getById(assetId);
@@ -128,9 +319,14 @@ export function assetRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, asset.companyId);
 
     const object = await storage.getObject(asset.companyId, asset.objectKey);
-    res.setHeader("Content-Type", asset.contentType || object.contentType || "application/octet-stream");
+    const responseContentType = asset.contentType || object.contentType || "application/octet-stream";
+    res.setHeader("Content-Type", responseContentType);
     res.setHeader("Content-Length", String(asset.byteSize || object.contentLength || 0));
     res.setHeader("Cache-Control", "private, max-age=60");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    if (responseContentType === SVG_CONTENT_TYPE) {
+      res.setHeader("Content-Security-Policy", "sandbox; default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'");
+    }
     const filename = asset.originalFilename ?? "asset";
     res.setHeader("Content-Disposition", `inline; filename=\"${filename.replaceAll("\"", "")}\"`);
 
@@ -142,4 +338,3 @@ export function assetRoutes(db: Db, storage: StorageService) {
 
   return router;
 }
-

server/src/services/activity-log.ts

@@ -1,8 +1,25 @@
+import { randomUUID } from "node:crypto";
 import type { Db } from "@paperclipai/db";
 import { activityLog } from "@paperclipai/db";
+import { PLUGIN_EVENT_TYPES, type PluginEventType } from "@paperclipai/shared";
+import type { PluginEvent } from "@paperclipai/plugin-sdk";
 import { publishLiveEvent } from "./live-events.js";
 import { redactCurrentUserValue } from "../log-redaction.js";
 import { sanitizeRecord } from "../redaction.js";
+import { logger } from "../middleware/logger.js";
+import type { PluginEventBus } from "./plugin-event-bus.js";
+
+const PLUGIN_EVENT_SET: ReadonlySet<string> = new Set(PLUGIN_EVENT_TYPES);
+
+let _pluginEventBus: PluginEventBus | null = null;
+
+/** Wire the plugin event bus so domain events are forwarded to plugins. */
+export function setPluginEventBus(bus: PluginEventBus): void {
+  if (_pluginEventBus) {
+    logger.warn("setPluginEventBus called more than once, replacing existing bus");
+  }
+  _pluginEventBus = bus;
+}
 
 export interface LogActivityInput {
   companyId: string;
@@ -45,4 +62,27 @@ export async function logActivity(db: Db, input: LogActivityInput) {
       details: redactedDetails,
     },
   });
+
+  if (_pluginEventBus && PLUGIN_EVENT_SET.has(input.action)) {
+    const event: PluginEvent = {
+      eventId: randomUUID(),
+      eventType: input.action as PluginEventType,
+      occurredAt: new Date().toISOString(),
+      actorId: input.actorId,
+      actorType: input.actorType,
+      entityId: input.entityId,
+      entityType: input.entityType,
+      companyId: input.companyId,
+      payload: {
+        ...redactedDetails,
+        agentId: input.agentId ?? null,
+        runId: input.runId ?? null,
+      },
+    };
+    void _pluginEventBus.emit(event).then(({ errors }) => {
+      for (const { pluginId, error } of errors) {
+        logger.warn({ pluginId, eventType: event.eventType, err: error }, "plugin event handler failed");
+      }
+    }).catch(() => {});
+  }
 }

server/src/services/companies.ts

@@ -2,6 +2,8 @@ import { eq, count } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
   companies,
+  companyLogos,
+  assets,
   agents,
   agentApiKeys,
   agentRuntimeState,
@@ -23,10 +25,41 @@ import {
   principalPermissionGrants,
   companyMemberships,
 } from "@paperclipai/db";
+import { notFound, unprocessable } from "../errors.js";
 
 export function companyService(db: Db) {
   const ISSUE_PREFIX_FALLBACK = "CMP";
 
+  const companySelection = {
+    id: companies.id,
+    name: companies.name,
+    description: companies.description,
+    status: companies.status,
+    issuePrefix: companies.issuePrefix,
+    issueCounter: companies.issueCounter,
+    budgetMonthlyCents: companies.budgetMonthlyCents,
+    spentMonthlyCents: companies.spentMonthlyCents,
+    requireBoardApprovalForNewAgents: companies.requireBoardApprovalForNewAgents,
+    brandColor: companies.brandColor,
+    logoAssetId: companyLogos.assetId,
+    createdAt: companies.createdAt,
+    updatedAt: companies.updatedAt,
+  };
+
+  function enrichCompany<T extends { logoAssetId: string | null }>(company: T) {
+    return {
+      ...company,
+      logoUrl: company.logoAssetId ? `/api/assets/${company.logoAssetId}/content` : null,
+    };
+  }
+
+  function getCompanyQuery(database: Pick<Db, "select">) {
+    return database
+      .select(companySelection)
+      .from(companies)
+      .leftJoin(companyLogos, eq(companyLogos.companyId, companies.id));
+  }
+
   function deriveIssuePrefixBase(name: string) {
     const normalized = name.toUpperCase().replace(/[^A-Z]/g, "");
     return normalized.slice(0, 3) || ISSUE_PREFIX_FALLBACK;
@@ -70,32 +103,97 @@ export function companyService(db: Db) {
   }
 
   return {
-    list: () => db.select().from(companies),
+    list: () =>
+      getCompanyQuery(db).then((rows) => rows.map((row) => enrichCompany(row))),
 
     getById: (id: string) =>
-      db
-        .select()
-        .from(companies)
+      getCompanyQuery(db)
         .where(eq(companies.id, id))
-        .then((rows) => rows[0] ?? null),
+        .then((rows) => (rows[0] ? enrichCompany(rows[0]) : null)),
 
-    create: async (data: typeof companies.$inferInsert) => createCompanyWithUniquePrefix(data),
+    create: async (data: typeof companies.$inferInsert) => {
+      const created = await createCompanyWithUniquePrefix(data);
+      const row = await getCompanyQuery(db)
+        .where(eq(companies.id, created.id))
+        .then((rows) => rows[0] ?? null);
+      if (!row) throw notFound("Company not found after creation");
+      return enrichCompany(row);
+    },
 
-    update: (id: string, data: Partial<typeof companies.$inferInsert>) =>
-      db
-        .update(companies)
-        .set({ ...data, updatedAt: new Date() })
-        .where(eq(companies.id, id))
-        .returning()
-        .then((rows) => rows[0] ?? null),
+    update: (
+      id: string,
+      data: Partial<typeof companies.$inferInsert> & { logoAssetId?: string | null },
+    ) =>
+      db.transaction(async (tx) => {
+        const existing = await getCompanyQuery(tx)
+          .where(eq(companies.id, id))
+          .then((rows) => rows[0] ?? null);
+        if (!existing) return null;
+
+        const { logoAssetId, ...companyPatch } = data;
+
+        if (logoAssetId !== undefined && logoAssetId !== null) {
+          const nextLogoAsset = await tx
+            .select({ id: assets.id, companyId: assets.companyId })
+            .from(assets)
+            .where(eq(assets.id, logoAssetId))
+            .then((rows) => rows[0] ?? null);
+          if (!nextLogoAsset) throw notFound("Logo asset not found");
+          if (nextLogoAsset.companyId !== existing.id) {
+            throw unprocessable("Logo asset must belong to the same company");
+          }
+        }
+
+        const updated = await tx
+          .update(companies)
+          .set({ ...companyPatch, updatedAt: new Date() })
+          .where(eq(companies.id, id))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!updated) return null;
+
+        if (logoAssetId === null) {
+          await tx.delete(companyLogos).where(eq(companyLogos.companyId, id));
+        } else if (logoAssetId !== undefined) {
+          await tx
+            .insert(companyLogos)
+            .values({
+              companyId: id,
+              assetId: logoAssetId,
+            })
+            .onConflictDoUpdate({
+              target: companyLogos.companyId,
+              set: {
+                assetId: logoAssetId,
+                updatedAt: new Date(),
+              },
+            });
+        }
+
+        if (logoAssetId !== undefined && existing.logoAssetId && existing.logoAssetId !== logoAssetId) {
+          await tx.delete(assets).where(eq(assets.id, existing.logoAssetId));
+        }
+
+        return enrichCompany({
+          ...updated,
+          logoAssetId: logoAssetId === undefined ? existing.logoAssetId : logoAssetId,
+        });
+      }),
 
     archive: (id: string) =>
-      db
-        .update(companies)
-        .set({ status: "archived", updatedAt: new Date() })
-        .where(eq(companies.id, id))
-        .returning()
-        .then((rows) => rows[0] ?? null),
+      db.transaction(async (tx) => {
+        const updated = await tx
+          .update(companies)
+          .set({ status: "archived", updatedAt: new Date() })
+          .where(eq(companies.id, id))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!updated) return null;
+        const row = await getCompanyQuery(tx)
+          .where(eq(companies.id, id))
+          .then((rows) => rows[0] ?? null);
+        return row ? enrichCompany(row) : null;
+      }),
 
     remove: (id: string) =>
       db.transaction(async (tx) => {
@@ -116,6 +214,8 @@ export function companyService(db: Db) {
         await tx.delete(principalPermissionGrants).where(eq(principalPermissionGrants.companyId, id));
         await tx.delete(companyMemberships).where(eq(companyMemberships.companyId, id));
         await tx.delete(issues).where(eq(issues.companyId, id));
+        await tx.delete(companyLogos).where(eq(companyLogos.companyId, id));
+        await tx.delete(assets).where(eq(assets.companyId, id));
         await tx.delete(goals).where(eq(goals.companyId, id));
         await tx.delete(projects).where(eq(projects.companyId, id));
         await tx.delete(agents).where(eq(agents.companyId, id));

server/src/services/heartbeat.ts

@@ -1364,11 +1364,11 @@ export function heartbeatService(db: Db) {
     const staleThresholdMs = opts?.staleThresholdMs ?? 0;
     const now = new Date();
 
-    // Find all runs in "queued" or "running" state
+    // Find all runs stuck in "running" state (queued runs are legitimately waiting; resumeQueuedRuns handles them)
     const activeRuns = await db
       .select()
       .from(heartbeatRuns)
-      .where(inArray(heartbeatRuns.status, ["queued", "running"]));
+      .where(eq(heartbeatRuns.status, "running"));
 
     const reaped: string[] = [];
 

server/src/services/plugin-capability-validator.ts

@@ -102,6 +102,7 @@ const UI_SLOT_CAPABILITIES: Record<PluginUiSlotType, PluginCapability> = {
   detailTab: "ui.detailTab.register",
   taskDetailView: "ui.detailTab.register",
   dashboardWidget: "ui.dashboardWidget.register",
+  globalToolbarButton: "ui.action.register",
   toolbarButton: "ui.action.register",
   contextMenuItem: "ui.action.register",
   commentAnnotation: "ui.commentAnnotation.register",
@@ -124,6 +125,7 @@ const LAUNCHER_PLACEMENT_CAPABILITIES: Record<
   sidebar: "ui.sidebar.register",
   sidebarPanel: "ui.sidebar.register",
   projectSidebarItem: "ui.sidebar.register",
+  globalToolbarButton: "ui.action.register",
   toolbarButton: "ui.action.register",
   contextMenuItem: "ui.action.register",
   commentAnnotation: "ui.commentAnnotation.register",

server/src/services/plugin-config-validator.ts

@@ -34,6 +34,10 @@ export function validateInstanceConfig(
   // ajv-formats v3 default export is a FormatsPlugin object; call it as a plugin.
   const applyFormats = (addFormats as any).default ?? addFormats;
   applyFormats(ajv);
+  // Register the secret-ref format used by plugin manifests to mark fields that
+  // hold a Paperclip secret UUID rather than a raw value. The format is a UI
+  // hint only — UUID validation happens in the secrets handler at resolve time.
+  ajv.addFormat("secret-ref", { validate: () => true });
   const validate = ajv.compile(schema);
   const valid = validate(configJson);
 

server/src/services/plugin-host-services.ts

@@ -556,6 +556,18 @@ export function buildHostServices(
         }
         await scopedBus.emit(params.name, params.companyId, params.payload);
       },
+      async subscribe(params: { eventPattern: string; filter?: Record<string, unknown> | null }) {
+        const handler = async (event: import("@paperclipai/plugin-sdk").PluginEvent) => {
+          if (notifyWorker) {
+            notifyWorker("onEvent", { event });
+          }
+        };
+        if (params.filter) {
+          scopedBus.subscribe(params.eventPattern as any, params.filter as any, handler);
+        } else {
+          scopedBus.subscribe(params.eventPattern as any, handler);
+        }
+      },
     },
 
     http: {
@@ -1058,6 +1070,10 @@ export function buildHostServices(
     dispose() {
       disposed = true;
 
+      // Clear event bus subscriptions to prevent accumulation on worker restart.
+      // Without this, each crash/restart cycle adds duplicate subscriptions.
+      scopedBus.clear();
+
       // Snapshot to avoid iterator invalidation from concurrent sendMessage() calls
       const snapshot = Array.from(activeSubscriptions);
       activeSubscriptions.clear();

server/src/services/plugin-loader.ts

@@ -1302,6 +1302,7 @@ export function pluginLoader(
       const plugin = (await registry.getById(pluginId)) as {
         id: string;
         packageName: string;
+        packagePath: string | null;
         manifestJson: PaperclipPluginManifestV1;
       } | null;
       if (!plugin) throw new Error(`Plugin not found: ${pluginId}`);
@@ -1309,7 +1310,10 @@ export function pluginLoader(
       const oldManifest = plugin.manifestJson;
       const {
         packageName = plugin.packageName,
-        localPath,
+        // For local-path installs, fall back to the stored packagePath so
+        // `upgradePlugin` can re-read the manifest from disk without needing
+        // the caller to re-supply the path every time.
+        localPath = plugin.packagePath ?? undefined,
         version,
       } = upgradeOptions;