fix: enforce Cloud-enabled features on every managed stack (#16953)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Cloud sets managed feature values for each tenant stack.
> - Staging lets admins change experimental features.
> - The staging exception also let old tenant false values override
Cloud true values.
> - This could disable required features such as isolated workspaces.
> - This pull request keeps every Cloud-enabled feature on and rejects
attempts to disable it.
> - The same rule applies to staging, production, and managed stacks
without a hostname.

## Linked Issues or Issue Description

Refs: #16876

**What happened?**

The staging override added in #16876 treats managed true values as
editable defaults. A stored tenant false value can disable a feature
that Cloud enables. Settings writes also accept attempts to disable
Cloud-enabled features.

**Expected behavior**

If Cloud sets a feature to true, the tenant reads true and cannot turn
it off. This applies to every managed stack. Staging can still change
allowed experiments that Cloud has not enabled.

**Steps to reproduce**

1. Set a managed staging primary hostname and enable isolated workspaces
in `PAPERCLIP_MANAGED_CONFIG`.
2. Start with `enableIsolatedWorkspaces: false` in the tenant settings
row.
3. Read `/api/instance/settings/experimental`. Before this fix, staging
returns false.
4. Try to PATCH that flag to false. After this fix, the API returns 403
without saving, and reads return true with managed control metadata.

**Paperclip version or commit**

Reproduced against master at `cde944ed75648adfb569e86133adc8b118b55dd6`.

## What Changed

- Keep managed true values in the staging read overlay. They override
old tenant values and lock the existing UI controls.
- Reject attempts to set any Cloud-enabled feature to false before
writing settings.
- Cover every managed feature in service tests across staging,
production, and an absent hostname. Add real-service HTTP tests for
isolation on staging and production.
- Update operator documentation and the feature and access maps.

## Verification

- Confirmed the new service regression fails before the fix: staging
returns stored false, and writes can attempt to disable enabled flags.
- Passed all six focused settings suites: 168 tests. Passed the final
route and overlay suites after adding the HTTP regression: 109 tests.
- Passed existing experimental settings UI tests: 54 tests. These cover
the existing managed-control behavior.
- Passed `node scripts/check-maps.mjs` and `git diff --check`.
- Passed `pnpm -r typecheck` and `pnpm build`. The first typecheck used
an install that did not honor locked versions and hit an unrelated
`@pierre/diffs` API mismatch. Reinstalling from the lockfile resolved
it; no lockfile changes are included.
- Full CI passed on `f43136812a92ec838a24f0c423270e4fbd997c28`: 55
successful checks, one neutral review check, and two expected skips.
This includes typecheck, build, general and serialized tests, runner
checks, and E2E shards. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/39411907756).
- The duplicate local `pnpm test:run` was stopped after the complete CI
matrix passed. It is not counted as a completed local full-suite pass.
- Greptile reviewed `f43136812a92ec838a24f0c423270e4fbd997c28`: 5/5 with
no outstanding findings. The only finding on the first review was the
repository rule against new code comments; those comments were removed.

## Risks

- Staging users can no longer disable a feature that Cloud enables. This
is the intended behavior.
- Clients that send a stale full settings form containing false for a
Cloud-enabled feature receive 403 and must reload.
- No database migration is needed. Stored false values remain in the
database, but cannot override an active Cloud true value.
- Cloud-disabled staging experiments remain editable. Production
restrictions and self-hosted settings remain unchanged.

## Model Used

- OpenAI Codex, `gpt-6.1-sol`, with reasoning, repository tools, and
test execution. The context window size is not exposed in this session.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

docs/guides/board-operator/experimental-features.md

@@ -23,8 +23,11 @@ controls they manage; empty developer and legacy sections are omitted. Hidden
 controls retain their configured values.
 
 On Paperclip Cloud staging (`*.staging.paperclip.app`), instance admins can
-view and change experimental settings. Cloud-managed feature values act as
-defaults until changed, and saved choices survive reloads. Production Cloud
+view and change experimental settings that Cloud has not enabled. A feature
+enabled by Cloud stays on for every managed stack, including staging, even when
+an older saved tenant value is false. Its control is locked, and attempts to
+disable it through the settings API return `403`. Cloud-disabled experiments
+can still be changed on staging, and saved choices survive reloads. Production Cloud
 keeps its managed values and hosting restrictions. Staging only permits changes
 to an explicit list of feature controls. Cloud access and execution policies,
 including managed-sandbox-only execution, remain managed on staging.

maps/agent-access-map/instance-operations.md

@@ -88,7 +88,10 @@ actor without receiving other instance-admin powers. This uses the current
 stack role on each request; company membership alone does not grant it.
 Members, Support users, agents, and ordinary self-hosted sessions remain denied.
 Cloud staging exposes experimental controls to instance admins and stack Admins.
-It permits saved overrides of Cloud feature defaults. This exception requires a managed instance
+It permits saved overrides of Cloud-disabled experimental defaults. Cloud-enabled
+features remain true on every managed stack, including staging, and the settings
+service rejects attempts to disable them with 403 before saving.
+This exception requires a managed instance
 and a provisioner-supplied `*.staging.paperclip.app` primary hostname; request
 headers do not establish staging. Ordinary board members and agents still cannot
 mutate instance settings. Only an explicit feature allowlist is editable on staging. Cloud

maps/feature-map/instance-operations.md

@@ -61,7 +61,11 @@ Automated: [experimental settings](../../ui/src/pages/InstanceExperimentalSettin
 Manual: Change a harmless experimental setting, reload, and confirm the affected route honors it. Back up a disposable instance, inspect the reported file and metadata, and restore using the documented procedure into a second isolated target. Verify a known record after restoration.
 
 Cloud staging: On a managed `*.staging.paperclip.app` instance, verify experiments
-are visible and editable by a Cloud stack Admin or instance admin, and changes survive reload.
+are visible, Cloud-enabled controls are locked on, and other experiments are
+editable by a Cloud stack Admin or instance admin with changes surviving reload.
+With an old stored false value and a Cloud true value, verify the effective
+setting is true and an API attempt to disable it returns 403 without saving.
+Repeat the enabled-feature check on production and managed stacks without a hostname.
 As a stack Admin, verify a harmless experiment saves while general instance
 settings and task-drain operations remain denied. Demote that user to Member
 and verify the next experimental write is denied.

server/src/__tests__/instance-settings-managed-overlay.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { Db } from "@paperclipai/db";
+import { INSTANCE_FEATURE_CATALOG } from "@paperclipai/shared";
 import {
   applyManagedExperimentalOverlay,
   instanceSettingsService,
@@ -83,6 +84,40 @@ describe("applyManagedExperimentalOverlay", () => {
 });
 
 describe("instanceSettingsService managed overlay", () => {
+  it.each(["team.staging.paperclip.app", "team.paperclip.app", undefined])(
+    "enforces every Cloud-enabled flag over old tenant values on %s",
+    async (primaryHost) => {
+      const features = Object.fromEntries(Object.entries(INSTANCE_FEATURE_CATALOG)
+        .filter(([, entry]) => entry.tier === "managed")
+        .map(([key]) => [key, true]));
+      const stored = Object.fromEntries(Object.keys(features).map((key) => [key, false]));
+      const { db, persistedSets } = stubDb(settingsRow(stored));
+      const runtimeEnv = {
+        PAPERCLIP_PRIMARY_HOST: primaryHost,
+        ...managedEnv(JSON.stringify({
+          v: 1, mode: "cloud", catalogVersion: "test",
+          features, plugins: { autoInstall: [] },
+        })),
+      };
+      const service = instanceSettingsService(db, { runtimeEnv });
+      expect(await service.getExperimental()).toMatchObject(features);
+      expect((await service.get()).experimental).toMatchObject(features);
+      expect((await service.getExperimental()).managedKeys).toMatchObject(
+        Object.fromEntries(Object.keys(features)
+          .filter((key) => key !== "enableApps" && key !== "enableMcpAggregators")
+          .map((key) => [key, { managed: true, managedBy: "paperclip-cloud" }])),
+      );
+      for (const key of Object.keys(features)) {
+        await expect(service.updateExperimental({ [key]: false })).rejects.toMatchObject({
+          status: 403,
+          details: { code: "settings_operator_managed" },
+        });
+      }
+      expect(persistedSets).toHaveLength(0);
+      expect(await instanceSettingsService(db, { runtimeEnv }).getExperimental()).toMatchObject(features);
+    },
+  );
+
   it("keeps sandbox policy enforced on staging after a tenant tries to disable it", async () => {
     const row = settingsRow({ enableManagedSandboxOnly: false });
     const { db, persistedSets } = stubDb(row);
@@ -94,10 +129,10 @@ describe("instanceSettingsService managed overlay", () => {
       })),
     };
     const service = instanceSettingsService(db, { runtimeEnv });
-    const updated = await service.updateExperimental({ enableManagedSandboxOnly: false });
-    Object.assign(row, persistedSets.at(-1));
+    await expect(service.updateExperimental({ enableManagedSandboxOnly: false })).rejects.toMatchObject({ status: 403 });
+    expect(persistedSets).toHaveLength(0);
     const restored = await instanceSettingsService(db, { runtimeEnv }).getExperimental();
-    for (const experimental of [updated.experimental, restored]) {
+    for (const experimental of [await service.getExperimental(), restored]) {
       expect(experimental).toMatchObject({
         enableManagedSandboxOnly: true,
         managedKeys: { enableManagedSandboxOnly: { managed: true, managedBy: "paperclip-cloud" } },
@@ -109,7 +144,7 @@ describe("instanceSettingsService managed overlay", () => {
     }
   });
 
-  it("lets staging override managed defaults, persists toggles, and preserves other defaults", async () => {
+  it("lets staging override disabled defaults while keeping Cloud-enabled features managed", async () => {
     const row = settingsRow({});
     const { db, persistedSets } = stubDb(row);
     const runtimeEnv = {
@@ -121,16 +156,20 @@ describe("instanceSettingsService managed overlay", () => {
       PAPERCLIP_PRIMARY_HOST: "team.staging.paperclip.app",
     };
     const service = instanceSettingsService(db, { runtimeEnv });
+    const managedKeys = {
+      enableStatusCards: { managed: true, managedBy: "paperclip-cloud" },
+      enableNativeRunner: { managed: true, managedBy: "paperclip-cloud" },
+    };
     expect(await service.getExperimental()).toMatchObject({
-      enableStatusCards: true, enableChatConnectors: false, enableNativeRunner: true, managedKeys: {},
+      enableStatusCards: true, enableChatConnectors: false, enableNativeRunner: true, managedKeys,
     });
     expect(persistedSets).toHaveLength(0);
 
     for (const enabled of [true, false]) {
-      const updated = await service.updateExperimental({ enableChatConnectors: enabled, enableNativeRunner: enabled });
+      const updated = await service.updateExperimental({ enableChatConnectors: enabled });
       Object.assign(row, persistedSets.at(-1));
       const expected = {
-        enableStatusCards: true, enableChatConnectors: enabled, enableNativeRunner: enabled, managedKeys: {},
+        enableStatusCards: true, enableChatConnectors: enabled, enableNativeRunner: true, managedKeys,
       };
       expect(updated.experimental).toMatchObject(expected);
       const restored = instanceSettingsService(db, { runtimeEnv });
@@ -139,6 +178,7 @@ describe("instanceSettingsService managed overlay", () => {
       expect(row.experimental).not.toHaveProperty("managedKeys");
       expect(row.experimental).not.toHaveProperty("enableStatusCards");
     }
+    expect((await service.updateExperimental({ enableNativeRunner: true })).experimental.enableNativeRunner).toBe(true);
 
     const changedDefaults = instanceSettingsService(db, { runtimeEnv: {
       ...runtimeEnv,
@@ -149,7 +189,7 @@ describe("instanceSettingsService managed overlay", () => {
       }),
     } });
     expect(await changedDefaults.getExperimental()).toMatchObject({
-      enableStatusCards: false, enableChatConnectors: false, enableNativeRunner: false,
+      enableStatusCards: false, enableChatConnectors: true, enableNativeRunner: true,
     });
 
     const production = instanceSettingsService(db, { runtimeEnv: { ...runtimeEnv, PAPERCLIP_PRIMARY_HOST: "team.paperclip.app" } });
@@ -172,7 +212,7 @@ describe("instanceSettingsService managed overlay", () => {
       enableOwnerInstanceAdmin: true,
       managedKeys: { enableOwnerInstanceAdmin: { managed: true, managedBy: "paperclip-cloud" } },
     });
-    expect((await service.updateExperimental({ enableOwnerInstanceAdmin: false })).experimental.enableOwnerInstanceAdmin).toBe(true);
+    await expect(service.updateExperimental({ enableOwnerInstanceAdmin: false })).rejects.toMatchObject({ status: 403 });
   });
 
   it.each([{}, { enableMcpAggregators: false }])("keeps aggregators on with legacy stored and managed values: %j", async (stored) => {

server/src/__tests__/instance-settings-routes.test.ts

@@ -912,6 +912,46 @@ describe("instance settings routes", () => {
   });
 
   describe("Cloud staging experiments", () => {
+    it.each(["team.staging.paperclip.app", "team.paperclip.app"])(
+      "reads Cloud-enabled isolation and rejects disabling it through the real service on %s",
+      async (primaryHost) => {
+        const { instanceSettingsService } = await vi.importActual<typeof import("../services/instance-settings.js")>(
+          "../services/instance-settings.js",
+        );
+        const update = vi.fn();
+        const db = {
+          select: () => ({ from: () => ({ where: async () => [{
+            id: "settings-1",
+            experimental: { enableIsolatedWorkspaces: false },
+          }] }) }),
+          update,
+        } as unknown as Parameters<typeof instanceSettingsService>[0];
+        const service = instanceSettingsService(db, { runtimeEnv: {
+          PAPERCLIP_PRIMARY_HOST: primaryHost,
+          PAPERCLIP_MANAGED_CONFIG: JSON.stringify({
+            v: 1, mode: "cloud", catalogVersion: "test",
+            features: { enableIsolatedWorkspaces: true }, plugins: { autoInstall: [] },
+          }),
+        } });
+        mockInstanceSettingsService.getExperimental.mockImplementation(service.getExperimental);
+        mockInstanceSettingsService.updateExperimental.mockImplementation(service.updateExperimental);
+        const app = createApp({
+          type: "board", userId: "stack-admin-1", source: "cloud_tenant",
+          companyIds: ["company-1"], isInstanceAdmin: false, canManageExperimentalSettings: true,
+        });
+        const current = await request(app).get("/api/instance/settings/experimental").expect(200);
+        expect(current.body).toMatchObject({
+          enableIsolatedWorkspaces: true,
+          managedKeys: { enableIsolatedWorkspaces: { managed: true } },
+        });
+        const denied = await request(app).patch("/api/instance/settings/experimental")
+          .send({ enableIsolatedWorkspaces: false }).expect(403);
+        expect(denied.body.details).toMatchObject({ code: "settings_operator_managed" });
+        expect(update).not.toHaveBeenCalled();
+        expect(mockLogActivity).not.toHaveBeenCalled();
+      },
+    );
+
     afterEach(() => vi.unstubAllEnvs());
 
     it.each(["instance.experimental", "instance.experimental.*"])(

server/src/services/instance-settings.ts

@@ -36,6 +36,7 @@ import { eq } from "drizzle-orm";
 import { getManagedInstanceConfig, type ManagedInstanceConfig } from "./managed-config.js";
 import { getOperatorSettingDefaults } from "./setting-defaults.js";
 import { isCloudStagingExperimentalSetting, isCloudStagingInstance } from "./cloud-instance.js";
+import { forbidden } from "../errors.js";
 
 const DEFAULT_SINGLETON_KEY = "default";
 const instanceGeneralSettingsStorageSchema = instanceGeneralSettingsSchema.strip();
@@ -440,7 +441,8 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
   const enforcedManagedConfig = staging && managedConfig
     ? {
       ...managedConfig,
-      features: Object.fromEntries(Object.entries(managedConfig.features).filter(([key]) => !isCloudStagingExperimentalSetting(key))),
+      features: Object.fromEntries(Object.entries(managedConfig.features)
+        .filter(([key, enabled]) => enabled || !isCloudStagingExperimentalSetting(key))),
     }
     : managedConfig;
   // Same posture for PAPERCLIP_SETTING_DEFAULTS: parsed once, applied per
@@ -575,6 +577,13 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
     },
 
     updateExperimental: async (patch: PatchInstanceExperimentalSettings): Promise<InstanceSettings> => {
+      for (const [key, enabled] of Object.entries(managedConfig?.features ?? {})) {
+        if (enabled && patch[key as ManagedExperimentalFeatureKey] === false) {
+          throw forbidden(`${key} is enabled by Paperclip Cloud and cannot be disabled on this instance`, {
+            code: "settings_operator_managed",
+          });
+        }
+      }
       const current = await getOrCreateRow();
       // Guarded Cloud flags stay absent from the row unless chosen, so the
       // read-time catalog default keeps applying (see stripCloudCatalogDefaultEchoes).