feat(environments): fill an unset instance default with a managed plugin environment (#19551)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A managed instance gets its instance-level environments from the
`PAPERCLIP_MANAGED_CONFIG` document, which can declare plugin
environments next to the managed sandbox
> - A platform that runs managed instances wants a new instance to start
with one of those plugin environments as its default, without changing
the default of any instance that already has one
> - #19632 made boot fill the instance default only when it is unset,
local or deleted, in one locked transaction, and removed the revert, so
every existing managed instance keeps a set default
> - This pull request adds an `instanceDefault` flag to a plugin entry.
That entry fills an unset default through the same locked fill, before
the managed sandbox does
> - The fill follows the same readiness rule as an admin's default
write, so it never moves ready agents onto a plugin that has not
prepared them
> - The platform also needs a way to know whether a release understands
plugin entries, so the release now ships a small capabilities file
> - The benefit: new instances get the plugin environment as their
default, and existing instances and admin choices are never changed

## Linked Issues or Issue Description

Refs #19632 (the locked fill-if-unset rule this builds on), #19508
(plugin entries in the managed config)

**Subsystem affected**
Server environments: the managed config parser and the managed
environment bootstrap.

**Problem or motivation**
The managed config can declare plugin environments, but it can't make
one the instance default on a new instance. An external platform also
has no way to tell whether a given release supports plugin entries
before it sends one.

**Proposed solution**
- Add `instanceDefault: true` to at most one plugin entry. Right after
that entry's boot ensure succeeds, it fills the instance default through
`fillUnsetInstanceDefault`. The managed sandbox fill runs after it.
- On a new instance the plugin environment wins. On an existing instance
the default is already set, so neither fill changes it.
- The fill declines while an active agent that follows the default
hasn't been prepared by that plugin. This is the rule the
instance-settings route enforces. When the plugin fill declines, the
managed sandbox fills as usual.
- Ship `server/src/services/managed-config-capabilities.json`, which
lists `pluginEnvironments`.

**Alternatives considered**
- A recorded one-time decision with a retry worker. It needed pending
states and extra checks for many writer and trigger combinations.
Filling only an unset default, under the existing lock, needs none of
that.
- Rejecting the fill whenever agents exist. That is stricter than the
admin route and blocks harmless cases, such as agents that are paused or
already prepared.

**Roadmap alignment**
This extends existing managed-environment behaviour. It adds no UI.

## What Changed

- `server/src/services/managed-config.ts`:
- `ManagedPluginEnvironmentSpec.instanceDefault` (boolean, default
`false`).
- The parser refuses `instanceDefault` on more than one plugin entry, on
the sandbox entry (even `false`), or as a non-boolean.
- `MANAGED_CONFIG_CAPABILITIES` and
`MANAGED_CONFIG_CAPABILITIES_SCHEMA_VERSION` constants. A plugin entry
is refused unless `pluginEnvironments` is listed.
- `server/src/services/managed-config-capabilities.json`: `{
"schemaVersion": 1, "capabilities": ["pluginEnvironments"] }`. A test
pins it to the constants and to this literal contract.
- `server/src/services/managed-environments.ts`:
- New `fillPluginInstanceDefault`. It runs right after a successful boot
ensure of the flagged entry and logs a fill or a decline. Recovery after
boot never fills.
  - The managed sandbox fill now runs once, after the plugin entries.
- `server/src/services/managed-instance-default.ts`:
`fillUnsetInstanceDefault` runs `agentsNeedSetupForEnvironmentChange`
inside its locked transaction and returns `declined:
"agents_need_setup"`. A sandbox target never needs agent setup, so the
managed sandbox fill behaves as before.
- `server/src/services/plugin-environment-driver.ts`: the readiness
query is factored into `agentsNeedSetupForEnvironmentChange`.
`assertAgentsReadyForEnvironmentChange` wraps it and still throws the
same conflict.
- `doc/DEVELOPING.md`: documents `instanceDefault`, the fill order, the
readiness decline, and the capabilities file.

## Verification

- `cd server && npx vitest run
src/__tests__/managed-plugin-environments.test.ts` (embedded Postgres),
under `instanceDefault (fill only an unset default)`:
  - A new instance gets the plugin row as its default.
  - An existing sandbox default is kept, and so is an admin's choice.
- If the plugin was down at the first boot and the sandbox filled, a
later recovery and boot keep the sandbox default.
- An admin-cleared or local default is declined while a ready or
verifying agent follows the default without the plugin's setup. The
managed sandbox then fills it.
- It fills when the agents that follow the default are paused or already
prepared, or are pinned to another environment.
  - Without the flag, nothing happens.
- A new agent that follows the default gets the plugin in
`requiredPluginIds`.
- `npx vitest run src/__tests__/managed-instance-default.test.ts`
(embedded Postgres): the earlier fill, lock and overlap cases pass. A
sandbox fill also succeeds while active agents follow the default.
- `npx vitest run
src/services/managed-environments-plugin-entries.test.ts`:
  - The fill order is plugin then sandbox.
  - When the plugin is down there is no fill, and recovery never fills.
- A failed ensure gives only the sandbox fill, and a failed fill keeps
the ensure counted.
  - When the plugin fill declines, the sandbox still fills.
- `npx vitest run src/__tests__/managed-config.test.ts
src/services/managed-config-capabilities.test.ts`: parser refusals and
the capabilities contract.
- `npx vitest run src/services/managed-environments.test.ts
src/__tests__/instance-settings-routes.test.ts
src/__tests__/environment-routes.test.ts`: pass. The route still throws
the same readiness conflict.
- `pnpm --filter @paperclipai/server typecheck` passes.
- I did not run the full `pnpm test:run`, `pnpm -r typecheck` or `pnpm
build`. CI covers them.

## Risks

- An instance whose default is unset at the first boot after this
release gets the plugin environment, if its agents are ready for it.
That covers a new instance, and an instance whose admin cleared the
default or chose the local environment. This is the intended behaviour.
- The readiness check doesn't lock agent rows. If an agent becomes ready
during the boot fill, it can miss the check, which is the same race the
admin route has. Agents created after the fill are prepared for the
plugin, because setup reads the current default.
- If the plugin is down at a new instance's first boot, the instance
keeps the managed sandbox default from then on.
- No schema change.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (file edits, shell, test runs).

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

server/src/__tests__/managed-config.test.ts

@@ -428,6 +428,7 @@ describe("parseManagedConfigEnv plugin environment entries", () => {
     pluginKey: PLUGIN_KEY,
     driverKey: "tasks",
     driverConfig: {},
+    instanceDefault: true,
     ...overrides,
   });
   const sandbox = { name: "Managed Sandbox", provider: "daytona", config: { target: "us" } };
@@ -456,6 +457,7 @@ describe("parseManagedConfigEnv plugin environment entries", () => {
       pluginKey: PLUGIN_KEY,
       driverKey: "tasks",
       driverConfig: {},
+      instanceDefault: true,
     }]);
     expect(Object.isFrozen(config?.pluginEnvironments)).toBe(true);
     expect(Object.isFrozen(config?.pluginEnvironments[0])).toBe(true);
@@ -464,7 +466,7 @@ describe("parseManagedConfigEnv plugin environment entries", () => {
   it("parses a plugin entry alone, with optional fields omitted", () => {
     const config = parseManagedConfigEnv(docWith([{ name: "Remote", driver: "plugin", pluginKey: PLUGIN_KEY, driverKey: "tasks" }]));
     expect(config?.environments).toEqual([]);
-    expect(config?.pluginEnvironments[0]).toMatchObject({ driverConfig: {} });
+    expect(config?.pluginEnvironments[0]).toMatchObject({ driverConfig: {}, instanceDefault: false });
     expect(config?.pluginEnvironments[0]?.description).toBeUndefined();
   });
 
@@ -478,10 +480,27 @@ describe("parseManagedConfigEnv plugin environment entries", () => {
   });
 
   it("refuses a duplicate pluginKey and driverKey pair", () => {
-    expect(() => parseManagedConfigEnv(docWith([remoteHost(), remoteHost({ name: "Second" })])))
+    expect(() => parseManagedConfigEnv(docWith([remoteHost(), remoteHost({ name: "Second", instanceDefault: false })])))
       .toThrow(/duplicates another plugin entry's pluginKey and driverKey/);
   });
 
+  it("refuses instanceDefault on two entries", () => {
+    expect(() => parseManagedConfigEnv(docWith([remoteHost(), remoteHost({ name: "Second", driverKey: "other" })])))
+      .toThrow(/at most one entry may become the instance default/);
+  });
+
+  it("refuses instanceDefault on the sandbox entry, even false", () => {
+    expect(() => parseManagedConfigEnv(docWith([{ ...sandbox, instanceDefault: true }])))
+      .toThrow(/"environments\[0\].instanceDefault" is not allowed on the sandbox entry/);
+    expect(() => parseManagedConfigEnv(docWith([{ ...sandbox, instanceDefault: false }])))
+      .toThrow(/not allowed on the sandbox entry/);
+  });
+
+  it("refuses a non-boolean instanceDefault", () => {
+    expect(() => parseManagedConfigEnv(docWith([remoteHost({ instanceDefault: "yes" })])))
+      .toThrow(/"environments\[0\].instanceDefault" must be a boolean/);
+  });
+
   it("refuses secret-like driverConfig keys at any depth", () => {
     expect(() => parseManagedConfigEnv(docWith([remoteHost({ driverConfig: { apiToken: "t" } })])))
       .toThrow(/"environments\[0\].driverConfig" key "apiToken" looks secret-bearing/);
@@ -495,9 +514,6 @@ describe("parseManagedConfigEnv plugin environment entries", () => {
     expect(() => parseManagedConfigEnv(docWith([remoteHost({ envVars: {} })]))).toThrow(/unknown key "envVars"/);
     expect(() => parseManagedConfigEnv(docWith([remoteHost({ provider: "daytona" })]))).toThrow(/unknown key "provider"/);
     expect(() => parseManagedConfigEnv(docWith([{ ...sandbox, pluginKey: PLUGIN_KEY }]))).toThrow(/unknown key "pluginKey"/);
-    // Not supported by this build on either entry.
-    expect(() => parseManagedConfigEnv(docWith([remoteHost({ instanceDefault: true })]))).toThrow(/unknown key "instanceDefault"/);
-    expect(() => parseManagedConfigEnv(docWith([{ ...sandbox, instanceDefault: false }]))).toThrow(/unknown key "instanceDefault"/);
   });
 
   it("refuses an unknown driver and malformed plugin fields", () => {

server/src/__tests__/managed-instance-default.test.ts

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { eq } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { createDb, environments, instanceSettings, type Db } from "@paperclipai/db";
+import { agents, companies, createDb, environments, instanceSettings, type Db } from "@paperclipai/db";
 import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
 import { fillUnsetInstanceDefault } from "../services/managed-instance-default.js";
 import { applyManagedEnvironments } from "../services/managed-environments.js";
@@ -18,6 +19,8 @@ const support = await getEmbeddedPostgresTestSupport();
   }, 90_000);
   afterAll(async () => { await database?.cleanup(); });
   beforeEach(async () => {
+    await db.delete(agents);
+    await db.delete(companies);
     await db.delete(instanceSettings);
     await db.delete(environments);
     const [sandbox] = await db.insert(environments).values({
@@ -47,6 +50,13 @@ const support = await getEmbeddedPostgresTestSupport();
     expect(await instanceDefault()).toBe(sandboxId);
   });
 
+  it("fills with the managed sandbox while active agents follow the default (a sandbox needs no agent setup)", async () => {
+    const companyId = randomUUID();
+    await db.insert(companies).values({ id: companyId, name: "Managed", issuePrefix: `M${companyId.slice(0, 7)}` });
+    await db.insert(agents).values({ companyId, name: "Ready agent", adapterType: "process", defaultEnvironmentId: null });
+    expect(await fillUnsetInstanceDefault(db, sandboxId)).toEqual({ filled: true, previousDefaultEnvironmentId: null });
+  });
+
   it("fills a default that names the local environment", async () => {
     const localId = await environment("Local", "local");
     await setInstanceDefault(localId);

server/src/__tests__/managed-plugin-environments.test.ts

@@ -15,6 +15,10 @@ import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } fro
 import { environmentService } from "../services/environments.js";
 import { MANAGED_CONFIG_ENV_KEY, parseManagedConfigEnv } from "../services/managed-config.js";
 import { applyManagedEnvironments } from "../services/managed-environments.js";
+import { fillUnsetInstanceDefault } from "../services/managed-instance-default.js";
+import { createLifecycleDriver } from "../services/agent-lifecycle-driver.js";
+import { createAgentLifecycleEffects } from "../services/agent-lifecycle.js";
+import { createLifecycleStore } from "../modules/agent-lifecycle/adapters/postgres.js";
 
 const PLUGIN_KEY = "example.remote-host-plugin";
 const MARKER = `${PLUGIN_KEY}:tasks`;
@@ -86,7 +90,8 @@ const support = await getEmbeddedPostgresTestSupport();
       version: "1.0.0",
       status: "ready",
       manifestJson: {
-        capabilities: ["environment.drivers.register"],
+        agentLifecycle: true,
+        capabilities: ["agents.lifecycle.manage", "environment.drivers.register"],
         environmentDrivers: [{ driverKey: "tasks", requiresAgent: true, supportsTasks: true }],
       } as never,
     });
@@ -252,4 +257,115 @@ const support = await getEmbeddedPostgresTestSupport();
       expect((await pluginRows())[0]!.status).toBe("active");
     });
   });
+
+  describe("instanceDefault (fill only an unset default)", () => {
+    const defaultEntry = { ...remoteHostEntry, instanceDefault: true };
+    const boot = (entries: unknown[] = [defaultEntry]) =>
+      applyManagedEnvironments(db, managedConfig(entries), { env: {}, workerManager, autoInstalledPluginKeys: [PLUGIN_KEY] });
+    const instanceDefault = async () =>
+      (await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, "default")))[0]?.defaultEnvironmentId ?? null;
+    const setInstanceDefault = async (environmentId: string | null) => {
+      const [row] = await db.select().from(instanceSettings).where(eq(instanceSettings.singletonKey, "default"));
+      if (row) await db.update(instanceSettings).set({ defaultEnvironmentId: environmentId }).where(eq(instanceSettings.id, row.id));
+      else await db.insert(instanceSettings).values({ singletonKey: "default", defaultEnvironmentId: environmentId });
+    };
+    const sandboxRow = async () => {
+      const [row] = await db.insert(environments).values({
+        name: "Managed Sandbox", driver: "sandbox", status: "active", config: { provider: "daytona" },
+        metadata: { managedByPaperclip: true, managedSandboxProvider: "daytona" },
+      }).returning();
+      return row!.id;
+    };
+    const agent = async (companyId: string, defaultEnvironmentId: string | null,
+      lifecycle: Partial<Pick<typeof agents.$inferInsert, "lifecycleState" | "lifecycleRequiredPluginIds">> = {}) => {
+      const id = randomUUID();
+      await db.insert(agents).values({ id, companyId, name: `Agent ${id}`, adapterType: "process", defaultEnvironmentId, ...lifecycle });
+      return id;
+    };
+
+    it("makes the plugin row the default on a new instance (unset default)", async () => {
+      await boot();
+      const [row] = await pluginRows();
+      expect(await instanceDefault()).toBe(row!.id);
+    });
+
+    it("keeps an existing instance's default, which the managed sandbox already filled", async () => {
+      const sandboxId = await sandboxRow();
+      await setInstanceDefault(sandboxId);
+      await agent(await company(), null);
+      await boot();
+      await boot();
+      expect(await instanceDefault()).toBe(sandboxId);
+    });
+
+    it("keeps an admin's choice", async () => {
+      const [chosen] = await db.insert(environments).values({ name: "Admin choice", driver: "ssh", status: "active", config: {} }).returning();
+      await setInstanceDefault(chosen!.id);
+      await boot();
+      expect(await instanceDefault()).toBe(chosen!.id);
+    });
+
+    it("never takes over later when the plugin was down at the first boot and the sandbox filled", async () => {
+      running = false;
+      await boot();
+      expect(await instanceDefault()).toBeNull();
+      // The same boot's managed sandbox fill (under managed-sandbox-only).
+      const sandboxId = await sandboxRow();
+      await fillUnsetInstanceDefault(db, sandboxId);
+
+      // The plugin recovers mid-process, then on a later boot: no fill either way.
+      running = true;
+      for (const listener of [...readyListeners]) listener({ pluginId });
+      await vi.waitFor(async () => expect((await pluginRows())[0]?.status).toBe("active"));
+      await boot();
+      expect(await instanceDefault()).toBe(sandboxId);
+    });
+
+    it("declines an admin-cleared default while an active agent that follows it lacks the plugin's setup", async () => {
+      await setInstanceDefault(null);
+      await agent(await company(), null);
+      await boot();
+      expect(await instanceDefault()).toBeNull();
+      // The same boot's managed sandbox fill still fills it.
+      const sandboxId = await sandboxRow();
+      expect(await fillUnsetInstanceDefault(db, sandboxId)).toMatchObject({ filled: true });
+      expect(await instanceDefault()).toBe(sandboxId);
+    });
+
+    it("declines a local default the same way", async () => {
+      const [local] = await db.insert(environments).values({ name: "Local", driver: "local", status: "active", config: {} }).returning();
+      await setInstanceDefault(local!.id);
+      await agent(await company(), null, { lifecycleState: "verifying" });
+      await boot();
+      expect(await instanceDefault()).toBe(local!.id);
+    });
+
+    it("fills when no active agent following the default needs the plugin's setup", async () => {
+      const companyId = await company();
+      const sandboxId = await sandboxRow();
+      await agent(companyId, null, { lifecycleState: "paused" });
+      await agent(companyId, null, { lifecycleRequiredPluginIds: [pluginId] });
+      await agent(companyId, sandboxId);
+      await setInstanceDefault(null);
+      await boot();
+      const [row] = await pluginRows();
+      expect(await instanceDefault()).toBe(row!.id);
+    });
+
+    it("does nothing without the flag", async () => {
+      await boot([remoteHostEntry]);
+      expect(await instanceDefault()).toBeNull();
+    });
+
+    it("prepares a new agent that follows the default with the plugin, and one set to the sandbox without it", async () => {
+      await boot();
+      const sandboxId = await sandboxRow();
+      const companyId = await company();
+      const selection = async (id: string) =>
+        createLifecycleDriver(db, { call } as never)
+          .requiredPluginIds((await createLifecycleStore(db, createAgentLifecycleEffects()).get(id))!);
+      expect(await selection(await agent(companyId, null))).toEqual([pluginId]);
+      expect(await selection(await agent(companyId, sandboxId))).toEqual([]);
+    });
+  });
 });