@agent-native/dispatch 0.40.30-nightly-20261021093329 → 0.40.31

package/src/server/lib/app-creation-store.spec.ts

@@ -1,3 +1,4 @@
+import { createHmac } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -10,23 +11,44 @@ import {
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
+  archiveWorkspaceApp,
   generateWorkspaceAppDescription,
   getAppCreationSettings,
   listAvailableWorkspaceTemplates,
+  listOrganizationVisibleWorkspaceApps,
   listWorkspaceApps,
   scaffoldWorkspaceAppFromTemplate,
   setAppCreationSettings,
   startWorkspaceAppCreation,
   updateWorkspaceAppMetadata,
 } from "./app-creation-store.js";
+import {
+  orgAppsDirectoryAccessCache,
+  orgAppsDirectoryCache,
+} from "./org-apps-directory-cache.js";
 
 const originalFetch = globalThis.fetch;
 const settingsKey = "dispatch-app-creation-settings:user:dev@example.test";
 
+function verifyJwtWithSecret(
+  token: string,
+  secret: string,
+): Record<string, unknown> {
+  const [header, payload, signature] = token.split(".");
+  const expected = createHmac("sha256", secret)
+    .update(`${header}.${payload}`)
+    .digest("base64url");
+  if (signature !== expected || !payload) {
+    throw new Error("JWT signature did not match the provided secret.");
+  }
+  return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+}
+
 const mocks = vi.hoisted(() => {
   const settings = new Map<string, unknown>();
   const state = {
     orgRole: "admin" as string | null,
+    workspaceApps: [] as Record<string, unknown>[],
   };
   const executedSql: string[] = [];
   return {
@@ -48,6 +70,8 @@ const mocks = vi.hoisted(() => {
     getOrgDomain: vi.fn(async (orgId: string) =>
       orgId ? "example.test" : null,
     ),
+    getOrgA2ASecret: vi.fn(async () => null as string | null),
+    signA2AToken: vi.fn(),
     isWorkspaceAppAccessAllowed: vi.fn(
       async (): Promise<boolean | "unavailable"> => true,
     ),
@@ -62,6 +86,20 @@ const mocks = vi.hoisted(() => {
             ? statement
             : String((statement as { sql?: unknown })?.sql ?? "");
         executedSql.push(sql);
+        if (sql.includes("SELECT id, org_id, visibility, org_enabled")) {
+          const args = (statement as { args?: unknown[] }).args ?? [];
+          return {
+            rows: state.workspaceApps.filter((app) => args.includes(app.id)),
+            rowsAffected: 0,
+          };
+        }
+        if (sql.includes("SELECT id, owner_email, org_id, visibility")) {
+          const args = (statement as { args?: unknown[] }).args ?? [];
+          return {
+            rows: state.workspaceApps.filter((app) => args.includes(app.id)),
+            rowsAffected: 0,
+          };
+        }
         if (sql.includes("SELECT id FROM workspace_apps")) {
           return { rows: [], rowsAffected: 0 };
         }
@@ -71,6 +109,22 @@ const mocks = vi.hoisted(() => {
         };
       }),
     })),
+    getDb: vi.fn(() => ({
+      select: vi.fn(() => ({
+        from: vi.fn(() => ({
+          where: vi.fn(async () =>
+            state.workspaceApps
+              .filter(
+                (app) =>
+                  app.org_id === "org-123" &&
+                  app.visibility === "org" &&
+                  app.org_enabled === 1,
+              )
+              .map((app) => ({ id: String(app.id) })),
+          ),
+        })),
+      })),
+    })),
     resolveBuilderCredentialsDetailed: vi.fn(async () => ({
       privateKey: null as string | null,
       publicKey: null as string | null,
@@ -94,6 +148,23 @@ const mocks = vi.hoisted(() => {
   };
 });
 
+vi.mock("@agent-native/core/a2a", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/a2a")>();
+  mocks.signA2AToken.mockImplementation((...args: any[]) =>
+    actual.signA2AToken(...args),
+  );
+  return {
+    ...actual,
+    signA2AToken: (...args: any[]) => mocks.signA2AToken(...args),
+  };
+});
+
+vi.mock("../../db/index.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../db/index.js")>();
+  return { ...actual, getDb: mocks.getDb };
+});
+
 vi.mock("@agent-native/core/secrets", async (importOriginal) => {
   const actual =
     await importOriginal<typeof import("@agent-native/core/secrets")>();
@@ -124,6 +195,7 @@ vi.mock("@agent-native/core/org", async (importOriginal) => {
     await importOriginal<typeof import("@agent-native/core/org")>();
   return {
     ...actual,
+    getOrgA2ASecret: (...args: any[]) => mocks.getOrgA2ASecret(...args),
     getOrgDomain: (...args: any[]) => mocks.getOrgDomain(...args),
     isWorkspaceAppAccessAllowed: (...args: any[]) =>
       mocks.isWorkspaceAppAccessAllowed(...args),
@@ -176,6 +248,8 @@ afterEach(() => {
   mocks.settings.clear();
   mocks.getOrgSetting.mockReset();
   mocks.getOrgSetting.mockResolvedValue(null);
+  mocks.getOrgA2ASecret.mockReset();
+  mocks.getOrgA2ASecret.mockResolvedValue(null);
   mocks.isWorkspaceAppAccessAllowed.mockReset();
   mocks.isWorkspaceAppAccessAllowed.mockResolvedValue(true);
   mocks.mutateSetting.mockReset();
@@ -187,6 +261,9 @@ afterEach(() => {
     },
   );
   mocks.state.orgRole = "admin";
+  mocks.state.workspaceApps = [];
+  orgAppsDirectoryCache.clear();
+  orgAppsDirectoryAccessCache.clear();
   mocks.getDbExec.mockReset();
   mocks.getDbExec.mockImplementation(() => ({
     execute: vi.fn(async (statement: unknown) => {
@@ -195,6 +272,24 @@ afterEach(() => {
           ? statement
           : String((statement as { sql?: unknown })?.sql ?? "");
       mocks.executedSql.push(sql);
+      if (sql.includes("SELECT id, org_id, visibility, org_enabled")) {
+        const args = (statement as { args?: unknown[] }).args ?? [];
+        return {
+          rows: mocks.state.workspaceApps.filter((app) =>
+            args.includes(app.id),
+          ),
+          rowsAffected: 0,
+        };
+      }
+      if (sql.includes("SELECT id, owner_email, org_id, visibility")) {
+        const args = (statement as { args?: unknown[] }).args ?? [];
+        return {
+          rows: mocks.state.workspaceApps.filter((app) =>
+            args.includes(app.id),
+          ),
+          rowsAffected: 0,
+        };
+      }
       if (sql.includes("SELECT id FROM workspace_apps")) {
         return { rows: [], rowsAffected: 0 };
       }
@@ -373,6 +468,71 @@ describe("listWorkspaceApps", () => {
     ]);
   });
 
+  it("lists only ready org-visible apps for an organization principal", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "qr", name: "QR", path: "/qr" },
+      { id: "private-app", name: "Private", path: "/private-app" },
+      { id: "disabled-app", name: "Disabled", path: "/disabled-app" },
+      { id: "foreign-app", name: "Foreign", path: "/foreign-app" },
+    ]);
+    mocks.settings.set("dispatch-app-creation-settings:org:org-123", {
+      pendingApps: [pendingApp("pending-app")],
+    });
+    mocks.state.workspaceApps = [
+      {
+        id: "dispatch",
+        owner_email: "owner@example.test",
+        org_id: "org-123",
+        visibility: "org",
+        org_enabled: 1,
+      },
+      {
+        id: "qr",
+        owner_email: "owner@example.test",
+        org_id: "org-123",
+        visibility: "org",
+        org_enabled: 1,
+      },
+      {
+        id: "private-app",
+        owner_email: "dev@example.test",
+        org_id: "org-123",
+        visibility: "private",
+        org_enabled: 1,
+      },
+      {
+        id: "disabled-app",
+        owner_email: "owner@example.test",
+        org_id: "org-123",
+        visibility: "org",
+        org_enabled: 0,
+      },
+      {
+        id: "foreign-app",
+        owner_email: "owner@example.test",
+        org_id: "another-org",
+        visibility: "org",
+        org_enabled: 1,
+      },
+    ];
+
+    const apps = await runWithRequestContext({ orgId: "org-123" }, () =>
+      listOrganizationVisibleWorkspaceApps(),
+    );
+
+    expect(apps.map((app) => app.id)).toEqual(["dispatch", "qr"]);
+    expect(mocks.executedSql.some((sql) => sql.includes("INSERT INTO"))).toBe(
+      false,
+    );
+    expect(
+      mocks.executedSql.some((sql) =>
+        sql.includes("INSERT INTO workspace_apps"),
+      ),
+    ).toBe(false);
+  });
+
   it.each([401, 403])(
     "keeps a local gateway denial on the unverified fallback path (%i)",
     async (status) => {
@@ -472,6 +632,130 @@ describe("listWorkspaceApps", () => {
     expect(apps[0]?.url).toBe("https://agent-workspace.builder.io/atlas");
   });
 
+  it("signs the hosted registry request with the caller's organization secret", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify([]), {
+          headers: { "content-type": "application/json" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "dispatch-deployment-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    mocks.getOrgA2ASecret.mockResolvedValueOnce("workspace-org-secret");
+
+    await runWithRequestContext(
+      { userEmail: "dev@example.test", orgId: "org-1" },
+      () => listWorkspaceApps({ includeAgentCards: false }),
+    );
+
+    const authorization = fetchMock.mock.calls[0]?.[1]?.headers
+      ?.Authorization as string;
+    const token = authorization.slice("Bearer ".length);
+    const payload = verifyJwtWithSecret(token, "workspace-org-secret");
+    expect(payload).toMatchObject({
+      sub: "dev@example.test",
+      org_domain: "example.test",
+      aud: "https://agent-workspace.builder.io",
+    });
+    expect(() =>
+      verifyJwtWithSecret(token, "dispatch-deployment-secret"),
+    ).toThrow();
+  });
+
+  it("reports missing hosted gateway signing credentials instead of sending anonymously", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    mocks.getOrgA2ASecret.mockResolvedValueOnce(null);
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "clips", name: "Clips", path: "/clips" },
+    ]);
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-1" },
+        () => listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_a2a_secret_missing",
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("reports organization A2A secret lookup failures before using manifest apps", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "dispatch-deployment-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "clips", name: "Clips", path: "/clips" },
+    ]);
+    mocks.getOrgA2ASecret.mockRejectedValueOnce(
+      new Error("database unavailable"),
+    );
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-1" },
+        () => listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_org_a2a_secret_unavailable",
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("reports token signing failures before using manifest apps", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "dispatch-deployment-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "clips", name: "Clips", path: "/clips" },
+    ]);
+    mocks.signA2AToken.mockRejectedValueOnce(new Error("signing unavailable"));
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-1" },
+        () => listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_token_signing_failed",
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("does not hide an organization lookup failure behind manifest apps", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "clips", name: "Clips", path: "/clips" },
+    ]);
+    mocks.getOrgDomain.mockRejectedValueOnce(new Error("database unavailable"));
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-1" },
+        () => listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_org_domain_unavailable",
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("binds hosted registry tokens to the mounted Dispatch path", async () => {
     const fetchMock = vi.fn(async () => {
       return new Response(
@@ -665,6 +949,122 @@ describe("listWorkspaceApps", () => {
     expect(apps.map((app) => app.id)).toEqual(["dispatch", "clips"]);
   });
 
+  it("treats an empty hosted registry response as a successful empty list", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify([]), {
+          headers: { "content-type": "application/json" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([{ id: "dispatch", name: "Dispatch", path: "/dispatch" }]);
+
+    const apps = await runWithRequestContext(
+      { userEmail: "dev@example.test" },
+      () => listWorkspaceApps({ includeAgentCards: false }),
+    );
+
+    expect(apps).toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([206, 500, 502, 503])(
+    "surfaces hosted registry HTTP %i failures instead of using manifest apps",
+    async (status) => {
+      const fetchMock = vi.fn(
+        async () => new Response("gateway unavailable", { status }),
+      );
+      vi.stubGlobal("fetch", fetchMock);
+      vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+      vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+      stubManifest([{ id: "dispatch", name: "Dispatch", path: "/dispatch" }]);
+
+      await expect(
+        runWithRequestContext({ userEmail: "dev@example.test" }, () =>
+          listWorkspaceApps({ includeAgentCards: false }),
+        ),
+      ).rejects.toMatchObject({
+        statusCode: 503,
+        errorCode: `workspace_gateway_http_${status}`,
+      });
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it("surfaces hosted registry transport failures instead of using manifest apps", async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new TypeError("Network connection failed");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([{ id: "dispatch", name: "Dispatch", path: "/dispatch" }]);
+
+    await expect(
+      runWithRequestContext({ userEmail: "dev@example.test" }, () =>
+        listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_unavailable",
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("surfaces malformed hosted registry responses instead of using manifest apps", async () => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response("not json", {
+          headers: { "content-type": "application/json" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([{ id: "dispatch", name: "Dispatch", path: "/dispatch" }]);
+
+    await expect(
+      runWithRequestContext({ userEmail: "dev@example.test" }, () =>
+        listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_invalid_response",
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    [{ id: "dispatch", name: "Dispatch", path: "/dispatch" }, null],
+    [
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "DISPATCH", name: "Duplicate Dispatch", path: "/other" },
+    ],
+  ])("rejects incomplete hosted registry lists: %j", async (apps) => {
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify(apps), {
+          headers: { "content-type": "application/json" },
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+    vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
+    stubManifest([{ id: "dispatch", name: "Dispatch", path: "/dispatch" }]);
+
+    await expect(
+      runWithRequestContext({ userEmail: "dev@example.test" }, () =>
+        listWorkspaceApps({ includeAgentCards: false }),
+      ),
+    ).rejects.toMatchObject({
+      statusCode: 503,
+      errorCode: "workspace_gateway_invalid_response",
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
   it("passes the Vercel protection bypass to the hosted workspace registry", async () => {
     const fetchMock = vi.fn(async () => {
       return new Response(
@@ -731,10 +1131,10 @@ describe("listWorkspaceApps", () => {
     );
   });
 
-  it("does not recursively call the hosted registry action", async () => {
+  it("skips a same-origin hosted registry without credentials", async () => {
     const fetchMock = vi.fn();
     vi.stubGlobal("fetch", fetchMock);
-    vi.stubEnv("A2A_SECRET", "test-a2a-secret");
+    vi.stubEnv("A2A_SECRET", "");
     vi.stubEnv("WORKSPACE_GATEWAY_URL", "https://agent-workspace.builder.io");
 
     const apps = await runWithRequestContext(
@@ -763,9 +1163,13 @@ describe("listWorkspaceApps", () => {
         { userEmail: "dev@example.test", orgId: "org-without-domain" },
         () => listWorkspaceApps({ includeAgentCards: false }),
       ),
-    ).rejects.toThrow(
-      "Workspace apps gateway cannot authenticate without a resolved organization domain.",
-    );
+    ).rejects.toMatchObject({
+      name: "WorkspaceAppsGatewayAuthorizationError",
+      statusCode: 401,
+      errorCode: "workspace_gateway_org_domain_missing",
+      message:
+        "Workspace apps gateway cannot authenticate without a resolved organization domain.",
+    });
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
@@ -1508,6 +1912,51 @@ describe("listWorkspaceApps", () => {
     );
   });
 
+  it("keeps the curated source id on a pending app summary", async () => {
+    stubNoPendingContext();
+    stubManifest();
+    mocks.settings.set(settingsKey, {
+      pendingApps: [
+        pendingApp("community-qr", {
+          communitySourceId: "community-qr",
+        }),
+      ],
+    });
+
+    const apps = await runWithRequestContext(
+      { userEmail: "dev@example.test" },
+      () => listWorkspaceApps({ includeAgentCards: false }),
+    );
+
+    expect(apps.find((app) => app.id === "community-qr")).toMatchObject({
+      status: "pending",
+      communitySourceId: "community-qr",
+    });
+  });
+
+  it("keeps the curated source id on ready app metadata", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      { id: "dispatch", name: "Dispatch", path: "/dispatch" },
+      { id: "community-qr", name: "QR", path: "/community-qr" },
+    ]);
+    mocks.settings.set("workspace-app-metadata:user:dev@example.test", {
+      apps: {
+        "community-qr": { communitySourceId: "community-qr" },
+      },
+    });
+
+    const apps = await runWithRequestContext(
+      { userEmail: "dev@example.test" },
+      () => listWorkspaceApps({ includeAgentCards: false }),
+    );
+
+    expect(apps.find((app) => app.id === "community-qr")).toMatchObject({
+      status: "ready",
+      communitySourceId: "community-qr",
+    });
+  });
+
   it("keeps unscoped legacy pending rows visible when there is no deploy context", async () => {
     stubNoPendingContext();
     stubManifest();
@@ -1643,7 +2092,7 @@ describe("listWorkspaceApps", () => {
     expect(apps.find((app) => app.id === "mail")?.status).toBe("ready");
   });
 
-  it("lets workspace admins update app display metadata", async () => {
+  it("lets workspace admins update app profile metadata", async () => {
     stubNoPendingContext();
     stubManifest([
       { id: "dispatch", name: "Dispatch", path: "/dispatch" },
@@ -1662,24 +2111,26 @@ describe("listWorkspaceApps", () => {
           appId: "todo",
           name: "Todo Board",
           description: "Tracks team work.",
+          whenToUse: ["Create a task from a meeting note"],
         }),
     );
 
     expect(updated.name).toBe("Todo Board");
     expect(updated.description).toBe("Tracks team work.");
+    expect(updated.whenToUse).toEqual(["Create a task from a meeting note"]);
     expect(mocks.settings.get("workspace-app-metadata:org:org-123")).toEqual({
       apps: {
         todo: expect.objectContaining({
           name: "Todo Board",
           description: "Tracks team work.",
+          whenToUse: ["Create a task from a meeting note"],
           updatedBy: "dev@example.test",
         }),
       },
     });
   });
 
-  it("lets workspace members update app display metadata", async () => {
-    mocks.state.orgRole = "member";
+  it("does not overwrite app profile metadata when its settings are unreadable", async () => {
     stubNoPendingContext();
     stubManifest([
       {
@@ -1689,30 +2140,262 @@ describe("listWorkspaceApps", () => {
         path: "/todo",
       },
     ]);
+    const key = "workspace-app-metadata:org:org-123";
+    const existing = { apps: { other: { name: "Preserve me" } } };
+    mocks.settings.set(key, existing);
+    let metadataReads = 0;
+    mocks.getSetting.mockImplementation(async (settingKey: string) => {
+      if (settingKey === key && ++metadataReads === 2) {
+        throw new Error("metadata settings unavailable");
+      }
+      return mocks.settings.get(settingKey) ?? null;
+    });
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-123" },
+        () => updateWorkspaceAppMetadata({ appId: "todo", name: "Updated" }),
+      ),
+    ).rejects.toThrow("metadata settings unavailable");
+
+    expect(metadataReads).toBe(2);
+    expect(mocks.putSetting).not.toHaveBeenCalled();
+    expect(mocks.settings.get(key)).toEqual(existing);
+  });
+
+  it("does not overwrite workspace settings when archiving after a read failure", async () => {
+    const key = "dispatch-app-creation-settings:org:org-123";
+    const existing = {
+      builderProjectId: "project-123",
+      pendingCommunityReservations: ["community-qr"],
+      archivedAppIds: [],
+    };
+    mocks.settings.set(key, existing);
+    mocks.getSetting.mockRejectedValueOnce(
+      new Error("workspace settings unavailable"),
+    );
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-123" },
+        () => archiveWorkspaceApp({ appId: "todo" }),
+      ),
+    ).rejects.toThrow("workspace settings unavailable");
+
+    expect(mocks.putSetting).not.toHaveBeenCalled();
+    expect(mocks.settings.get(key)).toEqual(existing);
+  });
+
+  it("preserves generated name and description when only examples change", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      {
+        id: "todo",
+        name: "Todo",
+        description: "Manifest description",
+        path: "/todo",
+      },
+    ]);
+    mocks.settings.set("workspace-app-metadata:org:org-123", {
+      apps: {
+        todo: {
+          description: "Generated description",
+          generated: true,
+        },
+      },
+    });
 
     const updated = await runWithRequestContext(
       { userEmail: "dev@example.test", orgId: "org-123" },
       () =>
         updateWorkspaceAppMetadata({
           appId: "todo",
-          name: "Todo Board",
-          description: "Tracks team work.",
+          whenToUse: ["Create a task from a meeting note"],
         }),
     );
 
-    expect(updated).toMatchObject({
-      name: "Todo Board",
-      description: "Tracks team work.",
-    });
+    expect(updated.name).toBe("Todo");
+    expect(updated.description).toBe("Manifest description");
+    expect(updated.whenToUse).toEqual(["Create a task from a meeting note"]);
     expect(mocks.settings.get("workspace-app-metadata:org:org-123")).toEqual({
       apps: {
         todo: expect.objectContaining({
-          name: "Todo Board",
-          description: "Tracks team work.",
+          description: "Generated description",
+          generated: true,
+          whenToUse: ["Create a task from a meeting note"],
           updatedBy: "dev@example.test",
         }),
       },
     });
+    expect(
+      (mocks.settings.get("workspace-app-metadata:org:org-123") as any).apps
+        .todo,
+    ).not.toHaveProperty("name");
+  });
+
+  it("invalidates org directory discovery after a profile edit", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      { id: "todo", name: "Todo", description: "Tasks", path: "/todo" },
+    ]);
+    const load = vi.fn(async () => [
+      {
+        id: "todo",
+        name: "Old profile",
+        url: "https://todo.example.test",
+      },
+    ]);
+    await orgAppsDirectoryCache.get("org-123|organization", load);
+    const loadAccess = vi.fn(async () => new Set(["todo"]));
+    await orgAppsDirectoryAccessCache.get("org-123|organization", loadAccess);
+
+    await runWithRequestContext(
+      { userEmail: "dev@example.test", orgId: "org-123" },
+      () =>
+        updateWorkspaceAppMetadata({
+          appId: "todo",
+          description: "Updated profile",
+        }),
+    );
+
+    const refreshedLoad = vi.fn(async () => [
+      {
+        id: "todo",
+        name: "Updated profile",
+        url: "https://todo.example.test",
+      },
+    ]);
+    await expect(
+      orgAppsDirectoryCache.get("org-123|organization", refreshedLoad),
+    ).resolves.toEqual([
+      {
+        id: "todo",
+        name: "Updated profile",
+        url: "https://todo.example.test",
+      },
+    ]);
+    expect(refreshedLoad).toHaveBeenCalledOnce();
+
+    const refreshedAccess = vi.fn(async () => new Set(["todo"]));
+    await expect(
+      orgAppsDirectoryAccessCache.get("org-123|organization", refreshedAccess),
+    ).resolves.toEqual(new Set(["todo"]));
+    expect(refreshedAccess).toHaveBeenCalledOnce();
+  });
+
+  it("clears explicit null metadata and preserves an empty when-to-use list", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      {
+        id: "todo",
+        name: "Manifest name",
+        description: "Manifest description",
+        path: "/todo",
+      },
+    ]);
+    mocks.settings.set("workspace-app-metadata:org:org-123", {
+      apps: {
+        todo: {
+          name: "Override name",
+          description: "Override description",
+          whenToUse: ["Old example"],
+        },
+      },
+    });
+
+    await runWithRequestContext(
+      { userEmail: "dev@example.test", orgId: "org-123" },
+      () =>
+        updateWorkspaceAppMetadata({
+          appId: "todo",
+          name: null,
+          description: null,
+          whenToUse: [],
+        }),
+    );
+
+    expect(mocks.settings.get("workspace-app-metadata:org:org-123")).toEqual({
+      apps: {
+        todo: expect.objectContaining({ whenToUse: [] }),
+      },
+    });
+  });
+
+  it("reports owner-role lookup failures as unavailable instead of unauthorized", async () => {
+    stubNoPendingContext();
+    stubManifest([{ id: "todo", name: "Todo", path: "/todo" }]);
+    mocks.getDbExec.mockReturnValue({
+      execute: vi.fn(async () => {
+        throw new Error("database unavailable");
+      }),
+    } as any);
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-123" },
+        () => updateWorkspaceAppMetadata({ appId: "todo", name: "Updated" }),
+      ),
+    ).rejects.toMatchObject({
+      name: "AppCreationOwnerRoleUnavailableError",
+      statusCode: 503,
+    });
+    expect(mocks.settings.has("workspace-app-metadata:org:org-123")).toBe(
+      false,
+    );
+  });
+
+  it("rejects malformed profile examples before writing", async () => {
+    stubNoPendingContext();
+    stubManifest([
+      { id: "todo", name: "Todo", description: "Tasks", path: "/todo" },
+    ]);
+    const tooManyExamples = Array.from(
+      { length: 7 },
+      (_, index) => `Example ${index}`,
+    );
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-123" },
+        () =>
+          updateWorkspaceAppMetadata({
+            appId: "todo",
+            whenToUse: tooManyExamples,
+          }),
+      ),
+    ).rejects.toThrow(/up to 6 non-empty examples/);
+    expect(mocks.settings.has("workspace-app-metadata:org:org-123")).toBe(
+      false,
+    );
+  });
+
+  it("rejects workspace member updates to app profile metadata", async () => {
+    mocks.state.orgRole = "member";
+    stubNoPendingContext();
+    stubManifest([
+      {
+        id: "todo",
+        name: "Todo",
+        description: "Original description",
+        path: "/todo",
+      },
+    ]);
+
+    await expect(
+      runWithRequestContext(
+        { userEmail: "dev@example.test", orgId: "org-123" },
+        () =>
+          updateWorkspaceAppMetadata({
+            appId: "todo",
+            name: "Todo Board",
+            description: "Tracks team work.",
+            whenToUse: ["Create a task from a meeting note"],
+          }),
+      ),
+    ).rejects.toMatchObject({ statusCode: 403 });
+    expect(mocks.settings.has("workspace-app-metadata:org:org-123")).toBe(
+      false,
+    );
   });
 
   it("generates a concise seed description from an app prompt", () => {
@@ -1812,6 +2495,82 @@ describe("startWorkspaceAppCreation", () => {
     });
   });
 
+  it("persists the curated source id for local-agent app creation", async () => {
+    const result = await runWithRequestContext(
+      { userEmail: "dev@example.test", orgId: "org-123" },
+      () =>
+        startWorkspaceAppCreation({
+          prompt: "Install the curated QR template",
+          appId: "community-qr",
+          communitySourceId: "community-qr",
+          attachments: [
+            {
+              type: "upload",
+              contentType: "text/plain",
+              name: "community-qr/README.md",
+              text: "Pinned template source",
+              dataUrl: "",
+              id: "community-qr:README.md",
+            },
+          ],
+        }),
+    );
+
+    expect(result).toMatchObject({
+      mode: "local-agent",
+      attachments: [
+        {
+          type: "file",
+          contentType: "text/plain",
+          name: "community-qr/README.md",
+          text: "Pinned template source",
+        },
+      ],
+    });
+    expect(
+      mocks.settings.get("workspace-app-metadata:org:org-123"),
+    ).toMatchObject({
+      apps: {
+        "community-qr": { communitySourceId: "community-qr" },
+      },
+    });
+    expect(
+      mocks.settings.get("dispatch-app-creation-settings:org:org-123"),
+    ).toMatchObject({
+      pendingApps: [
+        expect.objectContaining({
+          id: "community-qr",
+          communitySourceId: "community-qr",
+          createdBy: "dev@example.test",
+        }),
+      ],
+    });
+  });
+
+  it("atomically reserves local community installs against duplicate requests", async () => {
+    const input = {
+      prompt: "Install the curated QR template",
+      appId: "community-qr",
+      communitySourceId: "community-qr",
+    };
+    const context = { userEmail: "dev@example.test", orgId: "org-123" };
+
+    const first = await runWithRequestContext(context, () =>
+      startWorkspaceAppCreation(input),
+    );
+    const duplicate = await runWithRequestContext(context, () =>
+      startWorkspaceAppCreation(input),
+    );
+
+    expect(first.mode).toBe("local-agent");
+    expect(duplicate).toMatchObject({
+      mode: "app-id-taken",
+      appId: "community-qr",
+      conflict: "pending",
+      owner: "dev@example.test",
+    });
+  });
+
   it("rejects a cross-member collision with an active pending app id", async () => {
     stubHostedRuntime();
     stubBuilderProjectConfigured();
@@ -1961,6 +2720,51 @@ describe("startWorkspaceAppCreation", () => {
     expect(mocks.mutateSetting).toHaveBeenCalled();
   });
 
+  it("persists the curated source id with a hosted pending reservation", async () => {
+    stubHostedRuntime();
+    stubBuilderProjectConfigured();
+    mocks.resolveBuilderCredentialsDetailed.mockResolvedValue(
+      credentials({
+        privateKey: "priv",
+        publicKey: "pub",
+        userId: "builder-user-42",
+      }),
+    );
+    mocks.runBuilderAgent.mockResolvedValue({
+      branchName: "community-qr1",
+      url: "https://builder.io/app/projects/project-1/community-qr1",
+      status: "processing",
+    });
+
+    await runWithRequestContext(
+      { userEmail: "dev@example.test", orgId: "org-123" },
+      () =>
+        startWorkspaceAppCreation({
+          prompt: "Install the curated QR template",
+          appId: "community-qr",
+          communitySourceId: "community-qr",
+        }),
+    );
+
+    expect(
+      mocks.settings.get("dispatch-app-creation-settings:org:org-123"),
+    ).toMatchObject({
+      pendingApps: [
+        expect.objectContaining({
+          id: "community-qr",
+          communitySourceId: "community-qr",
+        }),
+      ],
+    });
+    expect(
+      mocks.settings.get("workspace-app-metadata:org:org-123"),
+    ).toMatchObject({
+      apps: {
+        "community-qr": { communitySourceId: "community-qr" },
+      },
+    });
+  });
+
   it("releases the reservation when Builder handoff fails", async () => {
     stubHostedRuntime();
     stubBuilderProjectConfigured();