thinkwork-cli 0.13.2 → 1.0.0

package/dist/plugins/catalog/src/contracts.ts

@@ -210,6 +210,15 @@ export interface McpServerComponent {
   resultTransforms?: McpResultTransform[];
   /** Optional human notes about the tools the server exposes. */
   toolNotes?: string[];
+  /**
+   * THINK-623 — opt in to the long-call profile for this server's tools.
+   * Set it only when the server streams MCP progress notifications during
+   * long calls: the runtime then resets the per-attempt `callTool` wall on
+   * every notification (bounded by an absolute total ceiling) instead of
+   * killing the call at the fixed 60s wall. Servers that go quiet for
+   * longer than the per-attempt wall still time out.
+   */
+  longRunning?: boolean;
 }
 
 export interface SkillSupportingFile {
@@ -671,6 +680,12 @@ function validateMcpServerComponent(
       );
     }
   }
+  if (
+    component.longRunning !== undefined &&
+    typeof component.longRunning !== "boolean"
+  ) {
+    throw new PluginManifestError(`${prefix}.longRunning must be a boolean`);
+  }
   const auth = component.auth as Partial<McpServerAuth> | undefined;
   if (!auth || typeof auth !== "object" || Array.isArray(auth)) {
     throw new PluginManifestError(`${prefix}.auth is required`);

package/dist/plugins/catalog/src/registry/generated-first-party.ts

@@ -3,26 +3,14 @@
 //   pnpm --filter @thinkwork/plugin-catalog generate:plugins
 
 import { defineFirstPartyPluginPackage } from "../plugin-package";
-import { companyDataPluginPackage as rawCompanyDataPluginPackage } from "@thinkwork/plugin-company-data";
-import { companyEtlPluginPackage as rawCompanyEtlPluginPackage } from "@thinkwork/plugin-company-etl";
 import { emailChannelPluginPackage as rawEmailChannelPluginPackage } from "@thinkwork/plugin-email-channel";
-import { lastmilePluginPackage as rawLastmilePluginPackage } from "@thinkwork/plugin-lastmile";
 import { n8nPluginPackage as rawN8nPluginPackage } from "@thinkwork/plugin-n8n";
 import { sendgridPluginPackage as rawSendgridPluginPackage } from "@thinkwork/plugin-sendgrid";
 import { twentyPluginPackage as rawTwentyPluginPackage } from "@thinkwork/plugin-twenty";
 
-export const companyDataPluginPackage = defineFirstPartyPluginPackage(
-  rawCompanyDataPluginPackage,
-);
-export const companyEtlPluginPackage = defineFirstPartyPluginPackage(
-  rawCompanyEtlPluginPackage,
-);
 export const emailChannelPluginPackage = defineFirstPartyPluginPackage(
   rawEmailChannelPluginPackage,
 );
-export const lastmilePluginPackage = defineFirstPartyPluginPackage(
-  rawLastmilePluginPackage,
-);
 export const n8nPluginPackage = defineFirstPartyPluginPackage(
   rawN8nPluginPackage,
 );
@@ -33,19 +21,13 @@ export const twentyPluginPackage = defineFirstPartyPluginPackage(
   rawTwentyPluginPackage,
 );
 
-export const companyDataManifest = companyDataPluginPackage.manifest;
-export const companyEtlManifest = companyEtlPluginPackage.manifest;
 export const emailChannelManifest = emailChannelPluginPackage.manifest;
-export const lastmileManifest = lastmilePluginPackage.manifest;
 export const n8nManifest = n8nPluginPackage.manifest;
 export const sendgridManifest = sendgridPluginPackage.manifest;
 export const twentyManifest = twentyPluginPackage.manifest;
 
 export const firstPartyPluginPackages = [
-  companyDataPluginPackage,
-  companyEtlPluginPackage,
   emailChannelPluginPackage,
-  lastmilePluginPackage,
   n8nPluginPackage,
   sendgridPluginPackage,
   twentyPluginPackage,

package/dist/plugins/n8n/test/integrated-app-contract.test.ts

@@ -211,7 +211,7 @@ describe("n8n integrated app contract", () => {
     const docsPage = await readFile(
       fileURLToPath(
         new URL(
-          "../../../docs/src/content/docs/applications/n8n.mdx",
+          "../../../docs/reference/applications/n8n.mdx",
           import.meta.url,
         ),
       ),

package/dist/plugins/twenty/package.json

@@ -13,7 +13,8 @@
   "scripts": {
     "build": "tsc --build",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "migrate:lastmile": "tsx scripts/migrate-lastmile.ts"
   },
   "dependencies": {
     "graphql": "^16.10.0"

package/dist/plugins/twenty/scripts/LAMBDA_DEPLOY.md

@@ -0,0 +1,114 @@
+# TEI LastMile → Twenty sync — Lambda deploy runbook
+
+Deploy the nightly LastMile → Twenty delta sync as an AWS Lambda in **TEI's
+account** (the same account as `n8n.lastmile-tei.com` and the LastMile RDS), and
+invoke it nightly from n8n. The function reuses the exact code proven against
+TEI's live Twenty; a full delta run is ~90s, so it fits Lambda's 15-minute
+ceiling with wide headroom.
+
+**Properties:** idempotent (upsert by `sourceId` + deletion mirror), reads
+LastMile **read-only**, never provisions members, needs **no AWS credentials**
+of its own (the ~4 CRM attachments Twenty can't ingest are reported, not fatal).
+
+---
+
+## 1. Build the deployment zip
+
+From the repo root:
+
+```bash
+pnpm install
+bash plugins/twenty/scripts/build-lambda.sh
+# → plugins/twenty/dist/tei-lastmile-sync-lambda.zip   (handler: index.handler)
+```
+
+The zip is self-contained (pg, bcryptjs, aws-sdk all inlined) — no `npm install`
+in the account.
+
+## 2. Create the function
+
+- **Runtime:** Node.js 22.x
+- **Handler:** `index.handler`
+- **Architecture:** arm64 or x86_64 (either)
+- **Timeout:** 300s (run is ~90s; leaves headroom for a busier delta)
+- **Memory:** 512 MB
+- **Code:** upload `tei-lastmile-sync-lambda.zip`
+
+```bash
+aws lambda create-function \
+  --function-name tei-lastmile-sync \
+  --runtime nodejs22.x --handler index.handler \
+  --timeout 300 --memory-size 512 \
+  --role arn:aws:iam::<ACCOUNT_ID>:role/<lambda-exec-role> \
+  --zip-file fileb://plugins/twenty/dist/tei-lastmile-sync-lambda.zip
+# later updates: aws lambda update-function-code --function-name tei-lastmile-sync \
+#   --zip-file fileb://plugins/twenty/dist/tei-lastmile-sync-lambda.zip
+```
+
+## 3. Configuration (the three env vars)
+
+| Variable                | Value                                                |
+| ----------------------- | ---------------------------------------------------- |
+| `TWENTY_PUBLIC_URL`     | `https://crm.tei.thinkwork.ai`                       |
+| `TWENTY_API_KEY`        | Twenty workspace API key (Settings → API & Webhooks) |
+| `LASTMILE_DATABASE_URL` | read-only DSN for the `dispatch` database            |
+
+Set them directly as Lambda environment variables, or (preferred) store the two
+secrets in Secrets Manager and resolve them at start. If you use Secrets
+Manager, add `secretsmanager:GetSecretValue` to the execution role.
+
+```bash
+aws lambda update-function-configuration --function-name tei-lastmile-sync \
+  --environment "Variables={TWENTY_PUBLIC_URL=https://crm.tei.thinkwork.ai,TWENTY_API_KEY=***,LASTMILE_DATABASE_URL=***}"
+```
+
+## 4. Networking — the one thing that must be right
+
+The function must reach **both** the LastMile RDS **and** `crm.tei.thinkwork.ai`.
+Mirror wherever n8n already connects to the RDS:
+
+- **In-VPC (cleanest):** attach the Lambda to the RDS's VPC/subnets, give it a
+  security group allowed to reach the RDS on 5432, and ensure the subnets have a
+  **NAT gateway** so it can still reach `crm.tei.thinkwork.ai` over HTTPS.
+- **No-VPC (public):** the RDS is a public endpoint — the function reaches it and
+  Twenty over the internet, but the **RDS security group must admit the
+  function's egress IP** (the account's NAT/EIP). This is the same allowlisting
+  n8n already has.
+
+Execution role needs at least `AWSLambdaBasicExecutionRole` (CloudWatch Logs),
+plus `AWSLambdaVPCAccessExecutionRole` if you attach it to a VPC.
+
+## 5. Smoke test before scheduling
+
+Always dry-run first (reads + reports, writes nothing):
+
+```bash
+aws lambda invoke --function-name tei-lastmile-sync \
+  --payload '{"mode":"dry-run"}' --cli-binary-format raw-in-base64-out out.json
+cat out.json   # → {"ok":true,"failed":0,"report":{...parity...}}
+```
+
+If `report.mode` is `dry-run` and the entity counts look right, you're wired
+correctly. Then run once for real: `--payload '{"mode":"apply"}'` (or `'{}'` —
+apply is the default).
+
+## 6. Wire n8n
+
+1. **Schedule Trigger** node — cron `0 3 * * *` (03:00 America/Chicago), or your
+   preferred window.
+2. **AWS Lambda** node → _Invoke_, region `us-east-1`, function
+   `tei-lastmile-sync`, invocation type `RequestResponse`. Leave the payload
+   empty (defaults to apply) or send `{"mode":"apply"}`.
+3. (Optional) an **IF** node on `{{$json.ok}}` / `{{$json.failed}}` to post a
+   Slack/email alert when a run reports soft failures.
+
+n8n's AWS credential needs `lambda:InvokeFunction` on the function ARN.
+
+## 7. Operational invariants (human-owned)
+
+- Keep Twenty's **"Create company when adding a new person"** workflow
+  **deactivated** — the API key can't toggle it, and it mislinks new people.
+- **Rotate** the shared `TWENTY_REP_PASSWORD` once the validation window closes.
+- A **cold re-seed** (empty Twenty) creates thousands of records at Twenty's rate
+  limit and can exceed 15 min — run that from the CLI/bundle, not this Lambda.
+  Steady-state nightly deltas are the Lambda's job.

package/dist/plugins/twenty/scripts/build-lambda.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Build a self-contained AWS Lambda deployment zip for the LastMile → Twenty
+# nightly sync. The bundle inlines every dependency (pg, bcryptjs, aws-sdk),
+# so the target account needs no `npm install` — just upload the zip.
+#
+# Usage:  bash scripts/build-lambda.sh
+# Output: plugins/twenty/dist/tei-lastmile-sync-lambda.zip  (handler: index.handler)
+set -euo pipefail
+
+cd "$(dirname "$0")/.." # -> plugins/twenty
+OUT_DIR="dist/tei-lastmile-sync-lambda"
+ZIP="dist/tei-lastmile-sync-lambda.zip"
+
+rm -rf "$OUT_DIR" "$ZIP"
+mkdir -p "$OUT_DIR"
+
+# CJS + .js so Lambda's Node runtime resolves `index.handler` with no wrapper.
+npx esbuild scripts/lambda-handler.ts \
+  --bundle --platform=node --format=cjs --target=node20 \
+  --outfile="$OUT_DIR/index.js"
+
+# The repo's plugins/twenty/package.json is "type":"module", which would make
+# Node treat the CJS index.js as ESM. Ship a CommonJS marker inside the zip so
+# the handler loads correctly regardless of the deploy environment.
+printf '{\n  "type": "commonjs"\n}\n' >"$OUT_DIR/package.json"
+
+(cd "$OUT_DIR" && zip -q -r "../../$ZIP" index.js package.json)
+echo "built $(cd "$(dirname "$ZIP")" && pwd)/$(basename "$ZIP")"
+echo "  handler: index.handler   size: $(du -h "$ZIP" | cut -f1)"

package/dist/plugins/twenty/scripts/configure-product-views.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env npx tsx
+/**
+ * One-off: make the Opportunity's Products table show Product, Quantity, and
+ * Amount.
+ *
+ * Twenty gives a new custom object a default TABLE view whose columns are
+ * `name` plus the audit fields (createdAt, createdBy, updatedAt, updatedBy).
+ * So the Products section rendered a row per line with no product, no quantity,
+ * and no amount — the data was all there, just never surfaced.
+ *
+ * This sets the opportunityProduct table view to:
+ *   Product | Quantity | Amount | Line
+ * and hides the audit columns. It also orders the record-page field widget the
+ * same way.
+ *
+ * Idempotent: re-running reconciles the view to the same state.
+ *
+ * Usage:
+ *   npx tsx scripts/configure-product-views.ts          # dry-run
+ *   npx tsx scripts/configure-product-views.ts --apply
+ */
+
+import process from "node:process";
+
+import { fetchObjectMetadata } from "./lib/schema-ensure";
+import { TwentyClient, normalizeBaseUrl } from "./lib/twenty-client";
+
+/**
+ * Exactly what Eric asked for: "Each line needs to be Product Name, Quantity and
+ * Amount." `name` is the record's label identifier (it holds the product name,
+ * or "Line 2" for the 173 lines whose brand did not map), so it leads. Twenty
+ * will not let the label identifier be hidden, which is also why it stays.
+ */
+const VISIBLE_COLUMNS = ["name", "quantity", "amount"] as const;
+
+/** Noise on a line item: audit trail, internals, and the product relation whose
+ * value already reads out through `name`. */
+const HIDDEN_COLUMNS = [
+  "createdAt",
+  "createdBy",
+  "updatedAt",
+  "updatedBy",
+  "sourceId",
+  "sourceHash",
+  "isMobil",
+  "opportunity",
+  "lineNumber",
+  "product",
+] as const;
+
+interface ViewField {
+  id: string;
+  fieldMetadataId: string;
+  isVisible: boolean;
+  position: number;
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required environment variable: ${name}`);
+  return value;
+}
+
+function log(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
+async function main(): Promise<void> {
+  const apply = process.argv.slice(2).includes("--apply");
+  const client = new TwentyClient({
+    baseUrl: normalizeBaseUrl(requireEnv("TWENTY_PUBLIC_URL")),
+    authToken: requireEnv("TWENTY_API_KEY"),
+  });
+
+  const objects = await fetchObjectMetadata(client);
+  const line = objects.get("opportunityProduct");
+  if (!line) throw new Error('Twenty object "opportunityProduct" not found.');
+  const fieldIdByName = new Map(
+    [...line.fields.values()].map((field) => [field.name, field.id]),
+  );
+
+  const views = await client.requestWithRetry<{
+    getViews: Array<{ id: string; name: string; type: string }>;
+  }>(
+    "/metadata",
+    `query ConfigViews($objectMetadataId: String!) {
+      getViews(objectMetadataId: $objectMetadataId) { id name type }
+    }`,
+    { objectMetadataId: line.id },
+  );
+
+  const report: Record<string, unknown> = {
+    mode: apply ? "apply" : "dry-run",
+    views: views.getViews.map((view) => `${view.type}:${view.name}`),
+  };
+  const changes: string[] = [];
+
+  for (const view of views.getViews) {
+    const fields = await client.requestWithRetry<{
+      getViewFields: ViewField[];
+    }>(
+      "/metadata",
+      `query ConfigViewFields($viewId: String!) {
+        getViewFields(viewId: $viewId) { id fieldMetadataId isVisible position }
+      }`,
+      { viewId: view.id },
+    );
+    const existingByFieldId = new Map(
+      fields.getViewFields.map((field) => [field.fieldMetadataId, field]),
+    );
+
+    // Wanted columns, in order.
+    for (const [index, name] of VISIBLE_COLUMNS.entries()) {
+      const fieldMetadataId = fieldIdByName.get(name);
+      if (!fieldMetadataId) {
+        throw new Error(
+          `opportunityProduct.${name} not found; run restructure-products first.`,
+        );
+      }
+      const existing = existingByFieldId.get(fieldMetadataId);
+      if (existing?.isVisible && existing.position === index) continue;
+
+      changes.push(`${view.type}: show ${name} at ${index}`);
+      if (!apply) continue;
+
+      if (existing) {
+        await client.requestOnce(
+          "/metadata",
+          `mutation ConfigUpdateViewField($input: UpdateViewFieldInput!) {
+            updateViewField(input: $input) { id }
+          }`,
+          {
+            input: {
+              id: existing.id,
+              update: { isVisible: true, position: index },
+            },
+          },
+        );
+      } else {
+        await client.requestOnce(
+          "/metadata",
+          `mutation ConfigCreateViewField($input: CreateViewFieldInput!) {
+            createViewField(input: $input) { id }
+          }`,
+          {
+            input: {
+              viewId: view.id,
+              fieldMetadataId,
+              isVisible: true,
+              position: index,
+              size: 150,
+            },
+          },
+        );
+      }
+    }
+
+    // Everything else on the line is noise in a table of deal lines.
+    for (const name of HIDDEN_COLUMNS) {
+      const fieldMetadataId = fieldIdByName.get(name);
+      if (!fieldMetadataId) continue;
+      const existing = existingByFieldId.get(fieldMetadataId);
+      if (!existing || !existing.isVisible) continue;
+      changes.push(`${view.type}: hide ${name}`);
+      if (!apply) continue;
+      await client.requestOnce(
+        "/metadata",
+        `mutation ConfigHideViewField($input: UpdateViewFieldInput!) {
+          updateViewField(input: $input) { id }
+        }`,
+        { input: { id: existing.id, update: { isVisible: false } } },
+      );
+    }
+  }
+
+  // The opportunity's `products` relation is left as-is (visible chips). An
+  // earlier version hid it and/or replaced it with a denormalized text field;
+  // both were wrong. The line records (Product / Quantity / Amount) are the
+  // correct structured model. A real inline COLUMNAR table on the record page
+  // is not something stock Twenty renders for a one-to-many relation — that
+  // needs a custom Twenty-app widget, scoped separately.
+
+  report.changes =
+    changes.length > 0 ? changes : "none — views already correct";
+  if (apply && changes.length > 0)
+    log(`applied ${changes.length} view changes`);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+});

package/dist/plugins/twenty/scripts/lambda-handler.ts

@@ -0,0 +1,49 @@
+/**
+ * AWS Lambda entry point for the nightly LastMile → Twenty sync.
+ *
+ * Invoked by n8n (Schedule → AWS Lambda) in TEI's account, where the function
+ * can reach both the LastMile RDS and crm.tei.thinkwork.ai. Reads the same
+ * three env vars as the CLI and runs an APPLY (delta re-sync) by default; pass
+ * `{"mode":"dry-run"}` to read + report without writing. Returns the parity
+ * report so n8n can log it or branch on failures.
+ *
+ * The sync is idempotent (upsert by sourceId + deletion mirror), reads LastMile
+ * read-only, never provisions members, and needs no AWS credentials. Runtime is
+ * ~90s against TEI's current data — set the Lambda timeout to 300s for headroom.
+ *
+ * Build the deployment zip with scripts/build-lambda.sh; deploy per
+ * scripts/LAMBDA_DEPLOY.md. Handler string: `index.handler`.
+ */
+import { executeMigration } from "./migrate-lastmile";
+
+interface SyncEvent {
+  mode?: "apply" | "dry-run";
+}
+
+interface EntityFailures {
+  failed?: number;
+}
+
+function totalFailed(report: Record<string, unknown>): number {
+  let failed = 0;
+  for (const value of Object.values(report)) {
+    if (value && typeof value === "object" && "failed" in value) {
+      const n = (value as EntityFailures).failed;
+      if (typeof n === "number") failed += n;
+    }
+  }
+  return failed;
+}
+
+export async function handler(
+  event: SyncEvent | null,
+): Promise<{ ok: boolean; failed: number; report: Record<string, unknown> }> {
+  // Default to apply — the whole point of the scheduled invocation. A hard
+  // failure (DB unreachable, sourceId abort) throws and fails the invocation;
+  // per-record soft failures surface via `failed` so n8n can alert without the
+  // run being considered a crash.
+  const apply = event?.mode !== "dry-run";
+  const report = await executeMigration({ apply });
+  const failed = totalFailed(report);
+  return { ok: failed === 0, failed, report };
+}

package/dist/plugins/twenty/scripts/lib/__tests__/load-attachments.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { isUploadUnsupported } from "../load-attachments";
+import { TwentyGraphqlError } from "../twenty-client";
+
+describe("isUploadUnsupported", () => {
+  it("recognizes the missing Upload scalar and uploadFile mutation", () => {
+    expect(
+      isUploadUnsupported(
+        new TwentyGraphqlError("x", {
+          errors: [{ message: 'Unknown type "Upload". Did you mean "Float"?' }],
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      isUploadUnsupported(
+        new TwentyGraphqlError("x", {
+          errors: [
+            { message: 'Cannot query field "uploadFile" on type "Mutation".' },
+          ],
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not swallow a genuine upload failure", () => {
+    // A real 500 or a missing binary must still count as a failure, so the run
+    // exits non-zero and someone looks at it.
+    expect(
+      isUploadUnsupported(
+        new TwentyGraphqlError("x", {
+          errors: [{ message: "Internal server error" }],
+        }),
+      ),
+    ).toBe(false);
+    expect(isUploadUnsupported(new Error("connect ETIMEDOUT"))).toBe(false);
+  });
+});

package/dist/plugins/twenty/scripts/lib/__tests__/load-records.test.ts

@@ -3,12 +3,14 @@ import { describe, expect, it, vi } from "vitest";
 import {
   COMPANY,
   emptyCounters,
+  isMissingSourceIdFieldError,
   mirrorDeletions,
+  upsertNotes,
   upsertRecords,
 } from "../load-records";
 import { contentHash } from "../mappers";
-import type { MappedRecord } from "../mappers";
-import type { TwentyClient } from "../twenty-client";
+import type { MappedNote, MappedRecord } from "../mappers";
+import { TwentyGraphqlError, type TwentyClient } from "../twenty-client";
 
 function mapped(
   sourceId: string,
@@ -230,3 +232,144 @@ describe("mirrorDeletions (AE2 / KTD7)", () => {
     ]);
   });
 });
+
+describe("isMissingSourceIdFieldError", () => {
+  const gqlError = (message: string) =>
+    new TwentyGraphqlError("wrapped", { errors: [{ message }] });
+
+  it("recognizes a not-yet-created sourceId field", () => {
+    expect(
+      isMissingSourceIdFieldError(
+        gqlError('Object company doesn\'t have any "sourceId" field.'),
+      ),
+    ).toBe(true);
+  });
+
+  it("recognizes a not-yet-created custom object", () => {
+    expect(
+      isMissingSourceIdFieldError(
+        gqlError('Unknown type "OrganizationFilterInput".'),
+      ),
+    ).toBe(true);
+    expect(
+      isMissingSourceIdFieldError(
+        gqlError('Cannot query field "organizations" on type "Query".'),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not swallow unrelated errors", () => {
+    expect(isMissingSourceIdFieldError(gqlError("Rate limit reached"))).toBe(
+      false,
+    );
+    expect(isMissingSourceIdFieldError(new Error("boom"))).toBe(false);
+  });
+});
+
+describe("upsertNotes batches the NoteTarget existence check (perf)", () => {
+  function note(sourceId: string): MappedNote {
+    return {
+      sourceId,
+      title: sourceId,
+      bodyMarkdown: sourceId,
+      targetSourceId: "opportunity:o1",
+      targetKind: "opportunity",
+      isDeleted: false,
+      createdAt: null,
+      authorName: null,
+    };
+  }
+
+  // A note whose id appears here already has a NoteTarget in Twenty.
+  function noteClient(pairedNoteIds: string[]): {
+    client: TwentyClient;
+    lookups: number;
+    createdTargets: Array<Record<string, unknown>>;
+  } {
+    const state = {
+      lookups: 0,
+      createdTargets: [] as Record<string, unknown>[],
+    };
+    const client = {
+      requestWithRetry: vi.fn(
+        async (
+          _path: string,
+          query: string,
+          variables: { filter?: { noteId?: { in?: string[] } } },
+        ) => {
+          if (query.includes("MigrationNoteTargets")) {
+            state.lookups += 1;
+            const ids = variables.filter?.noteId?.in ?? [];
+            return {
+              noteTargets: {
+                edges: ids
+                  .filter((id) => pairedNoteIds.includes(id))
+                  .map((id) => ({ node: { noteId: id } })),
+                pageInfo: { hasNextPage: false, endCursor: null },
+              },
+            };
+          }
+          // Note sourceId existence lookups → nothing exists yet (force create).
+          return { notes: { edges: [] } };
+        },
+      ),
+      requestOnce: vi.fn(
+        async (
+          _path: string,
+          query: string,
+          variables: { data: Array<Record<string, unknown>> },
+        ) => {
+          if (query.includes("createNotes")) {
+            return {
+              createNotes: variables.data.map((row) => ({
+                id: `note-${row.sourceId as string}`,
+                sourceId: row.sourceId,
+              })),
+            };
+          }
+          if (query.includes("createNoteTargets")) {
+            state.createdTargets.push(...variables.data);
+            return {
+              createNoteTargets: variables.data.map((_, i) => ({
+                id: `nt-${i}`,
+              })),
+            };
+          }
+          return { ok: true };
+        },
+      ),
+    } as unknown as TwentyClient;
+    return { client, ...state };
+  }
+
+  it("issues one lookup for many notes and only creates the missing targets", async () => {
+    const notes = [note("task_comment:c1"), note("task_comment:c2")];
+    // c1 already has its target; c2 does not.
+    const harness = noteClient(["note-task_comment:c1"]);
+    const counters = emptyCounters();
+
+    await upsertNotes({
+      client: harness.client,
+      notes,
+      targetIdBySourceId: new Map([["opportunity:o1", "opp1"]]),
+      dryRun: false,
+      counters,
+    });
+
+    // Batched: a single noteTargets query covers both notes (was one per note).
+    const lookupCalls = (
+      harness.client.requestWithRetry as unknown as {
+        mock: { calls: unknown[] };
+      }
+    ).mock.calls.filter((c) =>
+      String((c as unknown[])[1]).includes("MigrationNoteTargets"),
+    ).length;
+    expect(lookupCalls).toBe(1);
+
+    // Only the unpaired note gets a target, and it carries the opportunity FK.
+    expect(harness.createdTargets).toEqual([
+      { noteId: "note-task_comment:c2", targetOpportunityId: "opp1" },
+    ]);
+    expect(counters.failed).toBe(0);
+  });
+});