[codex] Add local Cloud Upstream sync (#6548)

## Thinking Path

> - Paperclip is the control plane for AI-agent companies.
> - Operators need a path to move local company state toward Paperclip
Cloud without losing local-first control.
> - The Cloud Upstream flow needs API, persistence, CLI, and board UI
surfaces that agree on the same manifest/run model.
> - The existing branch had the feature work plus UX and error-handling
follow-ups.
> - This pull request packages the remaining Cloud Upstream sync work
into one standalone branch.
> - The benefit is an inspectable local-to-cloud sync workflow with
preview, conflicts, activation, and captured UX review states.

## What Changed

- Added Cloud Upstream shared types, server routes/services, and
persisted run schema/migration.
- Added Paperclip Cloud CLI sync helpers and local connection storage.
- Added the Cloud Upstream board UI, settings entry points, query keys,
and UX lab page.
- Added preview/activation checklist behavior, redirect handling,
manifest-only preview support, friendly errors, in-flight hints, and
entity count summaries.

## Verification

- `pnpm --filter @paperclipai/plugin-sdk build`
- `NODE_ENV=test pnpm exec vitest run cli/src/__tests__/cloud.test.ts
server/src/__tests__/instance-settings-routes.test.ts
server/src/__tests__/instance-settings-service.test.ts
ui/src/pages/CloudUpstream.test.tsx
ui/src/components/CompanySettingsSidebar.test.tsx`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/cloud-upstreams.test.ts`

Worktree setup note: the isolated worktree install skipped native sqlite
build scripts, so I copied the already-built local sqlite binding from
the main checkout before running
`server/src/__tests__/cloud-upstreams.test.ts`. The test then passed.

## Risks

- Medium: this adds a database migration and a broad feature path across
CLI/server/UI.
- Merge order: this is the only PR in this split with a DB migration;
merge it before any future Cloud Upstream migration follow-up.
- Mitigation: the PR is based directly on current `origin/master`, has
targeted route/service/UI tests, and keeps the feature behind existing
experimental Cloud Sync settings.

> 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

- OpenAI GPT-5 Codex via `codex_local`, tool-enabled coding session;
exact context window not exposed by this runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, screenshot artifacts are
intentionally omitted per reviewer request
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

server/src/routes/cloud-upstreams.ts

@@ -0,0 +1,118 @@
+import { Router } from "express";
+import type { Db } from "@paperclipai/db";
+import { badRequest, notFound } from "../errors.js";
+import { assertBoardOrgAccess } from "./authz.js";
+import { cloudUpstreamService, instanceSettingsService } from "../services/index.js";
+
+export function cloudUpstreamRoutes(db: Db, options: { instanceId?: string } = {}) {
+  const router = Router();
+  const service = cloudUpstreamService(db, options);
+  const settings = instanceSettingsService(db);
+
+  async function assertEnabled() {
+    const experimental = await settings.getExperimental();
+    if (experimental.enableCloudSync !== true) {
+      throw notFound("Cloud sync is not enabled");
+    }
+  }
+
+  router.get("/cloud-upstreams", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    const companyId = stringQuery(req.query.companyId, "companyId");
+    res.json(await service.list(companyId));
+  });
+
+  router.post("/cloud-upstreams/connect/start", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    const companyId = stringBody(req.body, "companyId");
+    const remoteUrl = stringBody(req.body, "remoteUrl");
+    const redirectUri = stringBody(req.body, "redirectUri");
+    res.json(await service.startConnect({ companyId, remoteUrl, redirectUri }));
+  });
+
+  router.post("/cloud-upstreams/connect/finish", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.finishConnect({
+      pendingConnectionId: stringBody(req.body, "pendingConnectionId"),
+      code: stringBody(req.body, "code"),
+      state: stringBody(req.body, "state"),
+    }));
+  });
+
+  router.post("/cloud-upstreams/:connectionId/push-runs/preview", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.preview(req.params.connectionId, stringBody(req.body, "companyId")));
+  });
+
+  router.post("/cloud-upstreams/:connectionId/push-runs", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.createRun({
+      connectionId: req.params.connectionId,
+      companyId: stringBody(req.body, "companyId"),
+      retryOfRunId: optionalString(req.body?.retryOfRunId),
+    }));
+  });
+
+  router.get("/cloud-upstreams/:connectionId/push-runs/:runId", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.readRun(req.params.connectionId, req.params.runId, stringQuery(req.query.companyId, "companyId")));
+  });
+
+  router.post("/cloud-upstreams/:connectionId/push-runs/:runId/cancel", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.cancelRun(req.params.connectionId, req.params.runId, stringBody(req.body, "companyId")));
+  });
+
+  router.post("/cloud-upstreams/:connectionId/push-runs/:runId/activation", async (req, res) => {
+    assertBoardOrgAccess(req);
+    await assertEnabled();
+    res.json(await service.activateRunEntities({
+      connectionId: req.params.connectionId,
+      runId: req.params.runId,
+      companyId: stringBody(req.body, "companyId"),
+      entityType: activationEntityTypeBody(req.body),
+    }));
+  });
+
+  return router;
+}
+
+function stringQuery(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw badRequest(`${label} is required`);
+  }
+  return value;
+}
+
+function stringBody(body: unknown, key: string): string {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw badRequest(`${key} is required`);
+  }
+  const value = (body as Record<string, unknown>)[key];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw badRequest(`${key} is required`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function activationEntityTypeBody(body: unknown): "agents" | "routines" | "monitors" {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw badRequest("entityType is required");
+  }
+  const value = (body as Record<string, unknown>).entityType;
+  if (value !== "agents" && value !== "routines" && value !== "monitors") {
+    throw badRequest("entityType must be agents, routines, or monitors");
+  }
+  return value;
+}

server/src/routes/index.ts

@@ -19,3 +19,4 @@ export { llmRoutes } from "./llms.js";
 export { accessRoutes } from "./access.js";
 export { instanceSettingsRoutes } from "./instance-settings.js";
 export { instanceDatabaseBackupRoutes } from "./instance-database-backups.js";
+export { cloudUpstreamRoutes } from "./cloud-upstreams.js";