@hs-x/cli 0.3.0 → 0.3.7

package/dist/commands/deploy.js

@@ -1,14 +1,14 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
-import { cp, mkdir, mkdtemp, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rmdir, stat, unlink, writeFile, } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import * as Command from '@effect/cli/Command';
 import * as Options from '@effect/cli/Options';
 import { cloudflareResourceName, generateHubSpotRuntimeProject, generateProjectArtifacts, planPortalSchemaManagement, planWorkerCronTriggers, renderAlchemyProgram, renderCloudflareWorkerEntrypoint, stampMigratedRunServerlessShimOrigin, } from '@hs-x/codegen';
-import { HttpClientRequest, Schema, schemas } from '@hs-x/types';
+import { HttpClientRequest, Schema, schemas, signDeploymentAttestationGrant } from '@hs-x/types';
 import { validateProject } from '@hs-x/validator';
 import { Effect, Option } from 'effect';
 import { isLinked } from '../account-store.js';
@@ -16,24 +16,30 @@ import { exitWith } from '../cli-error.js';
 import { accountIdOption, controlPlaneUrlOption, cwdOption, deployIdOption, forceOption, jsonOption, projectIdOption, runHandler, runQuarantined, userIdOption, yesOption, } from '../cli/kit.js';
 import { resolveCloudflareCredentials } from '../cloudflare-kv.js';
 import { loadCloudflarePointer } from '../cloudflare-pointer.js';
+import { resolveOrProvisionCloudflareScopedResource } from '../cloudflare-scoped-resource.js';
 import { DEFAULT_CONTROL_PLANE_URL, formatConfigUrl, loadCliConfig, resolveControlPlaneUrl, } from '../config.js';
 import { CLI_VERSION } from '../constants.js';
 import { controlPlaneAuthHeaders } from '../control-plane-fetch.js';
 import { loadCreateControlPlane } from '../control-plane-loader.js';
+import { createControlPlaneTenantProvisioningAuthority, } from '../control-plane-tenant-provisioning.js';
 import { captureDeployRevision } from '../deploy-revision-capture.js';
+import { resolveDeployTargets } from '../deploy-targets.js';
 import { executeCliHttp } from '../effect-http.js';
 import { createDeployHubSpotDeveloperClient } from '../hubspot-developer-client.js';
 import { hydrateAncestorEnv } from '../load-env.js';
 import { LocalProjectPickerCancelled, resolveLocalProject } from '../local-project-picker.js';
-import { getMachineId } from '../machine-id.js';
+import { getMachineId, getMachineSecret, previewMachineId } from '../machine-id.js';
+import { requestMutationConsent } from '../mutation-consent.js';
 import { cachePath } from '../paths.js';
 import { readProjectBinding, writeProjectBinding } from '../project-binding.js';
 import { isInteractive, promptConfirm, promptMultiSelect, promptPassword, promptSelect, promptText, } from '../prompt.js';
 import { createReporter } from '../reporter/index.js';
 import { Cwd } from '../services/cwd.js';
+import { createTenantDataPlaneProvisioningCoordinator, } from '../tenant-data-plane-provisioning.js';
 import { ensureTenantStateStore, preflightTenantStateCredentials, } from '../tenant-state.js';
 import { defaultTokenKeyCustodyAdapter, escrowTokenKey, resolveEscrowedTokenKey, tokenKeyCustodyIdFor, } from '../token-key-custody.js';
 import { deployPromoteCommand, requestControlPlaneDeployPromotion } from './deploy-promote.js';
+import { withTransientDeployRetry } from './deploy-retry.js';
 async function hostedHttp(input) {
     const headers = { ...(input.headers ?? {}) };
     let request = HttpClientRequest.make(input.method ?? 'GET')(input.url).pipe(HttpClientRequest.setHeaders(headers));
@@ -149,10 +155,11 @@ async function promptMissingText(message, current, validate) {
  * across concurrent worker deploys), then persist answers to the process env so
  * sibling workers reuse them.
  *
- * OAuth-only bootstrap deploys retain the historical warning-only behavior
- * because the Auth page may not exist until after upload. Card backends fail
- * closed before the Worker deploy: shipping one without the HMAC key guarantees
- * that every live `hubspot.fetch` returns 401.
+ * OAuth-only bootstrap deploys may proceed with a warning because the Auth page
+ * may not exist until after upload, but every HubSpot-authored runtime route
+ * returns 503 until the secret is configured and the Worker is redeployed.
+ * Card backends fail earlier, at deploy time, because they cannot be useful in
+ * that bootstrap state.
  */
 /** @internal Exported for the deploy credential-gate regression suite. */
 export async function resolveHubSpotRuntimeCredentials(input) {
@@ -333,7 +340,7 @@ async function promptMissingCloudflareCredentials(input) {
         reporter.info('Easiest: `hs-x connect cloudflare` signs in via your browser and stores it for every future deploy.');
         reporter.info(`Or paste an API token (HS-X template): ${CLOUDFLARE_TOKEN_TEMPLATE_URL}`);
         for (;;) {
-            const token = await promptText({
+            const token = await promptPassword({
                 message: 'Paste your Cloudflare API token',
                 validate: (v) => (v.length >= 30 ? undefined : 'Token looks too short.'),
             });
@@ -591,7 +598,6 @@ export async function deployCommand({ argv, root, json, }) {
     const explicitControlPlaneUrl = resolveFlag(argv, '--control-plane-url');
     const controlPlaneUrl = explicitControlPlaneUrl ?? (planOnly ? undefined : process.env.HSX_CONTROL_PLANE_URL);
     const linked = await isLinked();
-    const machineId = await getMachineId();
     const userId = resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user';
     const resolvedAcct = await resolveAccountIdOrPrompt({
         argv,
@@ -610,10 +616,6 @@ export async function deployCommand({ argv, root, json, }) {
             // One-off --account-id override: warn but leave the recorded binding intact.
             progress?.reporter.warn('HSX_W_DEPLOY_ACCOUNT_OVERRIDE', `This project is bound to ${resolvedAcct.overrodeBinding}; deploying under ${accountId} for this run only (binding unchanged).`);
         }
-        else {
-            // Sticky binding: remember which HS-X account this project deploys under.
-            await writeProjectBinding(root, accountId).catch(() => { });
-        }
     }
     const explicitProjectId = resolveFlag(argv, '--project-id') ?? process.env.HSX_PROJECT_ID;
     let projectId = explicitProjectId;
@@ -646,9 +648,17 @@ export async function deployCommand({ argv, root, json, }) {
         projectId = await readHsxConfigProjectId(root);
     }
     const needsRuntime = workers.some((worker) => worker.capabilities.some((capability) => capability.runtimeNeeds.some((need) => need !== 'hubspot-only')));
-    const cloudflareDeployRequested = !buildOnly &&
-        (explicitCloudflareDeployRequested || (!planOnly && needsRuntime && !explicitHubspotUpload));
-    const hubspotUploadRequested = !buildOnly && (explicitHubspotUpload || (!planOnly && !cloudflareDryRun && Boolean(projectId)));
+    const needsHubSpotBundle = needsRuntime || app.mcpServers.length > 0;
+    const { deploymentMode, cloudflareDeployRequested, hubspotUploadRequested } = resolveDeployTargets({
+        buildOnly,
+        planOnly,
+        needsRuntime,
+        hasProjectId: Boolean(projectId),
+        hubspotOnly,
+        explicitHubspotUpload,
+        explicitCloudflareDeploy: explicitCloudflareDeployRequested,
+        cloudflareDryRun,
+    });
     if (echo) {
         echo.info(`Runtime: ${needsRuntime ? 'Cloudflare Worker required' : 'HubSpot-only compatible'}`);
         if (hubspotOnly && needsRuntime) {
@@ -723,15 +733,11 @@ export async function deployCommand({ argv, root, json, }) {
             projectId = answer;
         }
     }
-    if (projectId && accountId && !resolvedAcct.overrodeBinding) {
-        // Sticky binding, project half: project-scoped reads (status/logs/routes/
-        // drift) resolve their project id from here when no flag is passed.
-        await writeProjectBinding(root, accountId, projectId).catch(() => { });
-    }
-    if (!json && willChangeAnything && !flagYes && isInteractive()) {
+    if (willChangeAnything) {
         const summary = buildDeployPlanSummary({
             accountId,
             projectId,
+            deploymentMode,
             workers,
             portalSchemaPlan,
             applySchema,
@@ -742,14 +748,37 @@ export async function deployCommand({ argv, root, json, }) {
             shouldRecordControlPlane,
             promoteWhenHealthy,
         });
-        progress?.reporter.block(summary);
-        const confirm = await promptConfirm({
+        const machineOutput = json || progress?.reporter.mode === 'ndjson';
+        if (!machineOutput && !flagYes)
+            progress?.reporter.block(summary);
+        const consent = await requestMutationConsent({
+            yes: flagYes,
+            machineOutput,
+            interactive: isInteractive(),
             message: 'Apply this plan?',
-            default: false,
+            confirm: promptConfirm,
         });
-        if (confirm === undefined || confirm === false) {
-            return cancelledResult(argv, 'deploy');
+        if (consent === 'require-yes') {
+            return inputValidationError({
+                argv,
+                command: 'deploy',
+                json,
+                code: 'HSX_E_INPUT_INVALID',
+                message: 'Deploy requires explicit consent in machine or non-interactive mode.',
+                hint: 'Review with `hs-x deploy --plan`, then re-run the mutating command with --yes.',
+                detail: summary,
+            });
         }
+        if (consent === 'cancelled')
+            return cancelledResult(argv, 'deploy');
+    }
+    // Consent is the boundary for durable command state too. A declined deploy,
+    // JSON/non-TTY invocation without --yes, or --plan must not create a machine
+    // id or rewrite the project's sticky account/project binding.
+    const machineId = willChangeAnything ? await getMachineId() : await previewMachineId();
+    const machineSecret = willChangeAnything && !linked ? await getMachineSecret() : undefined;
+    if (willChangeAnything && accountId && !resolvedAcct.overrodeBinding) {
+        await writeProjectBinding(root, accountId, projectId).catch(() => { });
     }
     // `--apply-schema` writes property definitions to the live portal, but
     // `--plan`/`--dry-run` promise to change nothing. Honoring both would let a
@@ -1017,6 +1046,7 @@ export async function deployCommand({ argv, root, json, }) {
                     controlPlanePlan,
                     userId,
                     machineId,
+                    ...(machineSecret ? { machineSecret } : {}),
                     heartbeatEnabled: noHeartbeat
                         ? false
                         : controlPlaneBackedPlan
@@ -1039,8 +1069,8 @@ export async function deployCommand({ argv, root, json, }) {
     }
     if (echo && cloudflareDeployResult) {
         for (const worker of cloudflareDeployResult.workers) {
-            if (worker.unauthenticatedInvoke) {
-                echo.warn('HSX_W_DEPLOY_UNAUTHENTICATED_INVOKE', `${worker.workerName}: workflow-action invoke endpoints accept unsigned requests until the app's OAuth client secret is configured (redeploy with HSX_HUBSPOT_CLIENT_SECRET / --hubspot-client-secret after the OAuth install).`);
+            if (worker.signatureVerificationUnavailable) {
+                echo.warn('HSX_W_DEPLOY_SIGNATURE_UNAVAILABLE', `${worker.workerName}: HubSpot workflow-action and trigger requests will fail closed until the app's OAuth client secret is configured (redeploy with HSX_HUBSPOT_CLIENT_SECRET / --hubspot-client-secret after the OAuth install).`);
             }
         }
     }
@@ -1135,7 +1165,7 @@ export async function deployCommand({ argv, root, json, }) {
     // Default order (skipped when we already uploaded first above): generate the
     // HubSpot bundle from the deployed Worker URL, then upload.
     if (!uploadFirstOrigin && hubspotUploadRequested && validation.ok) {
-        const bundleStep = needsRuntime ? progress?.step('Generating HubSpot bundle') : undefined;
+        const bundleStep = needsHubSpotBundle ? progress?.step('Generating HubSpot bundle') : undefined;
         try {
             await ensureHubSpotRuntimeProjectArtifacts({
                 argv,
@@ -1208,6 +1238,16 @@ export async function deployCommand({ argv, root, json, }) {
                             : planOnly
                                 ? 'plan'
                                 : 'local-artifacts',
+        deploymentMode,
+        targets: {
+            cloudflare: {
+                requested: cloudflareDeployRequested,
+                dryRun: cloudflareDryRun,
+            },
+            hubspot: {
+                uploadRequested: hubspotUploadRequested,
+            },
+        },
         root,
         hubspotOnly,
         needsRuntime,
@@ -1253,6 +1293,7 @@ export async function deployCommand({ argv, root, json, }) {
             hubspotUploadResult,
             linked,
             machineId,
+            machineSecret,
         });
     }
     // Record tenant state + emit the deploy event whenever the worker is actually
@@ -1267,14 +1308,17 @@ export async function deployCommand({ argv, root, json, }) {
             plan: controlPlanePlan,
             environment: resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production',
         });
-        await emitAnonymousDeployEvent({
-            argv,
-            machineId,
-            projectId: controlPlanePlan?.projectId ?? projectId,
-            deployId: cloudflareDeployResult.deployId,
-            workerUrl: cloudflareDeployResult.workers.find((worker) => worker.url)?.url,
-            environment: resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production',
-        });
+        if (machineSecret) {
+            await emitAnonymousDeployEvent({
+                argv,
+                machineId,
+                machineSecret,
+                projectId: controlPlanePlan?.projectId ?? projectId,
+                deployId: cloudflareDeployResult.deployId,
+                workerUrl: cloudflareDeployResult.workers.find((worker) => worker.url)?.url,
+                environment: resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production',
+            });
+        }
     }
     // 0 = clean, 20 = partial (worker live, HubSpot upload failed — distinct so
     // automation doesn't treat a serving worker as a total failure), 1 = failure.
@@ -1287,6 +1331,7 @@ function buildDeployPlanSummary(input) {
         lines.push(`  account:        ${input.accountId}`);
     if (input.projectId)
         lines.push(`  project:        ${input.projectId}`);
+    lines.push(`  deploy mode:    ${input.deploymentMode}`);
     lines.push(`  workers:        ${input.workers.length} (${capCount} capabilities)`);
     if (input.applySchema && input.portalSchemaPlan) {
         const adds = input.portalSchemaPlan.actions.filter((item) => item.kind === 'will-create-object' || item.kind === 'will-create-property').length;
@@ -1305,8 +1350,7 @@ function buildDeployPlanSummary(input) {
     if (input.cloudflareDeployRequested) {
         lines.push(`  cloudflare:     ${input.cloudflareDryRun ? 'dry-run' : 'deploy'}`);
     }
-    if (input.hubspotUpload)
-        lines.push('  hubspot upload: yes');
+    lines.push(`  hubspot upload: ${input.hubspotUpload ? 'yes' : 'no'}`);
     return lines.join('\n');
 }
 function createUnlinkedDeployPlan(input) {
@@ -1350,6 +1394,7 @@ async function emitAnonymousDeployEvent(input) {
             headers: {
                 'content-type': 'application/json',
                 accept: 'application/json',
+                authorization: `Bearer ${input.machineSecret}`,
             },
             body: JSON.stringify({
                 schema_version: 1,
@@ -1445,7 +1490,12 @@ function deployDoneMessage(input, firstWorkerUrl) {
 }
 /** The railed key/value facts of what this deploy produced (human/plain). */
 function buildDeploySummaryRows(input) {
-    const rows = [];
+    const rows = [
+        {
+            key: 'deploy mode',
+            value: input.plan.deploymentMode,
+        },
+    ];
     if (input.controlPlanePlan) {
         rows.push({
             key: 'deploy',
@@ -1523,7 +1573,10 @@ function buildDeploySummaryRows(input) {
         }
     }
     if (!input.linked && input.cloudflareDeployResult) {
-        rows.push({ key: 'history', value: machineDashboardUrl(input.machineId) });
+        rows.push({
+            key: 'history',
+            value: machineDashboardUrl(input.machineId, input.machineSecret),
+        });
     }
     return rows;
 }
@@ -1622,13 +1675,13 @@ function renderDeployNdjsonSummary(input) {
             .join(', ');
         reporter.info(`Cloudflare deploy: ${deployed}`);
         for (const worker of input.cloudflareDeployResult.workers) {
-            if (worker.unauthenticatedInvoke) {
-                reporter.warn('HSX_W_DEPLOY_UNAUTHENTICATED_INVOKE', `${worker.workerName}: workflow-action invoke endpoints accept unsigned requests until the app's OAuth client secret is configured (redeploy with HSX_HUBSPOT_CLIENT_SECRET / --hubspot-client-secret after the OAuth install).`);
+            if (worker.signatureVerificationUnavailable) {
+                reporter.warn('HSX_W_DEPLOY_SIGNATURE_UNAVAILABLE', `${worker.workerName}: HubSpot workflow-action and trigger requests will fail closed until the app's OAuth client secret is configured (redeploy with HSX_HUBSPOT_CLIENT_SECRET / --hubspot-client-secret after the OAuth install).`);
             }
         }
     }
     if (!input.linked && input.cloudflareDeployResult) {
-        reporter.info(`Deploy history for this machine: ${machineDashboardUrl(input.machineId)}`);
+        reporter.info(`Deploy history for this machine: ${machineDashboardUrl(input.machineId, input.machineSecret)}`);
     }
     if (input.hubspotUploadResult) {
         const upload = input.hubspotUploadResult;
@@ -1678,9 +1731,12 @@ function renderDeployNdjsonSummary(input) {
     }
     reporter.done(deployDoneMessage(input, firstWorkerUrl), input.plan.ok ? 0 : input.plan.partial ? 20 : 1);
 }
-function machineDashboardUrl(machineId) {
+function machineDashboardUrl(machineId, machineSecret) {
     const base = process.env.HSX_DASHBOARD_URL ?? 'https://app.hs-x.dev';
-    return `${base.replace(/\/$/, '')}/m/${encodeURIComponent(machineId)}`;
+    const url = new URL(`/m/${encodeURIComponent(machineId)}`, `${base.replace(/\/$/, '')}/`);
+    if (machineSecret)
+        url.hash = new URLSearchParams({ access: machineSecret }).toString();
+    return url.toString();
 }
 /**
  * The HubSpot developer-console URL for an uploaded app's auth tab, where a
@@ -2128,7 +2184,7 @@ function defaultHubSpotFieldType(type) {
             return 'text';
     }
 }
-async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan, controlPlaneUrl, userId, machineId, heartbeatEnabled, dryRun, note, }) {
+async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan, controlPlaneUrl, userId, machineId, machineSecret, heartbeatEnabled, dryRun, note, }) {
     // Fail fast on missing Cloudflare credentials BEFORE deploying any Worker, so
     // an unlinked deploy can't leave a Worker live and then error on the
     // tenant-state write for a missing account id.
@@ -2171,6 +2227,17 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         });
     }
     const sourcePaths = await discoverWorkerSourcePaths(root);
+    // Provision once per tenant trust domain, then let every Worker continue its
+    // deploy in parallel with the exact same resources and verifier secret.
+    const tenantDataPlaneProvisioning = createTenantDataPlaneProvisioningCoordinator(controlPlaneUrl && !dryRun
+        ? {
+            authority: createControlPlaneTenantProvisioningAuthority({
+                controlPlaneUrl,
+                authorizationHeaders: () => controlPlaneAuthHeaders(userId),
+                http: hostedHttp,
+            }),
+        }
+        : {});
     const concurrency = Math.max(1, Math.min(4, workers.length));
     const results = await Effect.runPromise(Effect.forEach(workers.map((worker, index) => ({ worker, index })), ({ worker, index }) => Effect.promise(() => executeCloudflareWorkerDeploy({
         argv,
@@ -2182,8 +2249,10 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         controlPlanePlan,
         userId,
         machineId,
+        ...(machineSecret ? { machineSecret } : {}),
         heartbeatEnabled,
         dryRun,
+        tenantDataPlaneProvisioning,
         ...(controlPlaneUrl ? { controlPlaneUrl } : {}),
         ...(note ? { note } : {}),
     })), { concurrency }));
@@ -2192,7 +2261,7 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         workers: results,
     };
 }
-async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowCredentialPrompt, sourcePaths, controlPlanePlan, controlPlaneUrl, userId, machineId, heartbeatEnabled, dryRun, note, }) {
+async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowCredentialPrompt, sourcePaths, controlPlanePlan, controlPlaneUrl, userId, machineId, machineSecret, heartbeatEnabled, dryRun, tenantDataPlaneProvisioning, note, }) {
     const emitNote = note ??
         ((line) => {
             process.stderr.write(line);
@@ -2216,10 +2285,24 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
     const environment = resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production';
     const deployCliConfig = loadCliConfig(argv);
     const runtimeControlPlaneUrl = formatConfigUrl(deployCliConfig.runtimeControlPlaneUrl ?? new URL(DEFAULT_CONTROL_PLANE_URL));
+    const exactTenantScope = {
+        accountId: controlPlanePlan.accountId,
+        projectId: controlPlanePlan.projectId,
+        environment,
+    };
     await writeFile(entrypointPath, renderCloudflareWorkerEntrypoint({
         workerImportPath: relativeImportPath(dirname(entrypointPath), workerSourcePath),
         requireActiveCardInstall: appConfig.auth === 'oauth',
-        ...(cronPlan.dispatch.length > 0 ? { syncCron: cronPlan } : {}),
+        // Tenant D1/KV and the grant secret are shared across the linked app's
+        // Workers. Wire the matching routes on every linked Worker even though
+        // revision-bound heartbeat/attestation remains primary-only below.
+        ...(controlPlaneUrl ? { tenantDataPlaneScope: exactTenantScope } : {}),
+        ...(cronPlan.dispatch.length > 0
+            ? {
+                syncCron: cronPlan,
+                syncRunScope: exactTenantScope,
+            }
+            : {}),
         ...(appConfig.appEventBatching !== undefined
             ? { appEventBatching: appConfig.appEventBatching }
             : {}),
@@ -2235,7 +2318,10 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
                 },
             }
             : {}),
-        ...(heartbeatEnabled
+        // A linked deploy records the primary Worker's Cloudflare revision on
+        // the deploy record, so only that Worker may attest against it. Anonymous
+        // telemetry remains per Worker because it has no revision trust binding.
+        ...(heartbeatEnabled && (!controlPlaneUrl || index === 0)
             ? {
                 heartbeat: controlPlaneUrl
                     ? {
@@ -2253,6 +2339,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
                         controlPlaneUrl: formatConfigUrl(loadCliConfig(argv).runtimeControlPlaneUrl ??
                             new URL(DEFAULT_CONTROL_PLANE_URL)),
                         machineId,
+                        machineSecretBinding: 'HSX_MACHINE_SECRET',
                         projectId: controlPlanePlan.projectId,
                         deployId: controlPlanePlan.deployId,
                         environment,
@@ -2294,7 +2381,12 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
     // flags KV + grant secret, persisting the scope + secret to local state so the
     // leaveable `hs-x flags` CLI can sign without the control plane.
     const tenantDataPlane = installRuntimeBinding && controlPlaneUrl && hubspotAppId && !dryRun
-        ? await ensureTenantDataPlane({
+        ? await tenantDataPlaneProvisioning.resolve({
+            accountId: controlPlanePlan.accountId,
+            projectId: controlPlanePlan.projectId,
+            environment,
+            hubSpotAppId: hubspotAppId,
+        }, (claim) => ensureTenantDataPlane({
             argv,
             root,
             accountId: controlPlanePlan.accountId,
@@ -2302,9 +2394,14 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             environment,
             hubSpotAppId: hubspotAppId,
             install: installRuntimeBinding,
-            controlPlaneUrl,
-            userId,
-            ...(note ? { note } : {}),
+            ...(claim ? { canonicalSyncGrantSecretValue: claim.syncGrantSecretValue } : {}),
+        }), async () => {
+            const { stateStore } = await ensureTenantStateStore({ argv, root });
+            return (await stateStore.getBinding({
+                projectId: controlPlanePlan.projectId,
+                environment,
+                hubSpotAppId: hubspotAppId,
+            }))?.syncGrantSecretValue;
         })
         : undefined;
     const hubSpotOAuthSecret = hubspotAppId && controlPlaneUrl
@@ -2376,6 +2473,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             ? { installKvNamespaceId: installRuntimeBinding.installKvNamespaceId }
             : {}),
         ...(controlPlaneUrl ? { checkpointDataset: 'hsx_checkpoint', observability: true } : {}),
+        ...(controlPlaneUrl ? { versionMetadataBinding: 'CF_VERSION_METADATA' } : {}),
         ...(tenantDataPlane
             ? {
                 flagsKvNamespaceId: tenantDataPlane.flagsKvNamespaceId,
@@ -2451,10 +2549,10 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
         ...(dryRun ? ['--dry-run'] : []),
     ];
     const deployEnv = cloudflareDeployEnv(argv);
-    const output = await runCloudflareCommand(command, {
+    const output = await withTransientDeployRetry(() => runCloudflareCommand(command, {
         cwd: root,
         env: deployEnv,
-    });
+    }));
     if (installRuntimeBinding?.tokenKeySecretValue && !dryRun) {
         await runCloudflareCommand([
             'bun',
@@ -2471,6 +2569,13 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             stdin: installRuntimeBinding.tokenKeySecretValue,
         });
     }
+    if (!controlPlaneUrl && heartbeatEnabled && machineSecret && !dryRun) {
+        await runCloudflareCommand(['bun', 'x', 'wrangler', 'secret', 'put', 'HSX_MACHINE_SECRET', '--name', workerName], {
+            cwd: root,
+            env: deployEnv,
+            stdin: machineSecret,
+        });
+    }
     if (resolvedHubSpotClientSecret && !dryRun) {
         await runCloudflareCommand([
             'bun',
@@ -2494,9 +2599,10 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             stdin: billingRuntimeToken.runtimeToken,
         });
     }
-    // ADR-015 grant-verifier secret — only set when freshly generated (a re-deploy
-    // reuses the value already on the Worker + in local state).
-    if (tenantDataPlane?.syncGrantSecretValue && !dryRun) {
+    // ADR-015 grant-verifier secret. Cloudflare Worker secrets are write-only and
+    // per Worker, so install the canonical stored value on EVERY deployed Worker
+    // (including one added after the trust domain was first provisioned).
+    if (tenantDataPlane && !dryRun) {
         await runCloudflareCommand([
             'bun',
             'x',
@@ -2552,10 +2658,10 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             emitNote(`warning: could not register the tenant Worker URL with the control plane: ${error instanceof Error ? error.message : String(error)}\n`);
         }
     }
-    // Without the client secret on the Worker, the runtime accepts UNSIGNED
-    // workflow-action invokes (HubSpot must still be able to call them pre-OAuth)
-    // — surface that as a one-line warning instead of leaving it silent.
-    const hasWorkflowActions = worker.capabilities.some((capability) => capability.kind === 'tool');
+    // Without the client secret, all HubSpot-authored request surfaces fail
+    // closed. Surface the unavailable state instead of leaving bootstrap deploys
+    // live but mysteriously non-functional.
+    const hasHubSpotAuthoredIngress = worker.capabilities.some((capability) => capability.kind === 'tool' || capability.kind === 'trigger');
     return {
         workerName,
         workerSourcePath: relative(root, workerSourcePath),
@@ -2566,8 +2672,8 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
         dryRun,
         stdout: output.stdout,
         stderr: output.stderr,
-        ...(hasWorkflowActions && !resolvedHubSpotClientSecret && !dryRun
-            ? { unauthenticatedInvoke: true }
+        ...(hasHubSpotAuthoredIngress && !resolvedHubSpotClientSecret && !dryRun
+            ? { signatureVerificationUnavailable: true }
             : {}),
     };
 }
@@ -2620,49 +2726,68 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
             installKvNamespaceName: existing.installKvNamespaceName,
             tokenKeySecretName: existing.tokenKeySecretName,
             tokenKeyCustody: existing.tokenKeyCustody,
+            ...(existing.tenantD1DatabaseId ? { tenantD1DatabaseId: existing.tenantD1DatabaseId } : {}),
+            ...(existing.tenantD1DatabaseName
+                ? { tenantD1DatabaseName: existing.tenantD1DatabaseName }
+                : {}),
+            ...(existing.flagsKvNamespaceId ? { flagsKvNamespaceId: existing.flagsKvNamespaceId } : {}),
+            ...(existing.flagsKvNamespaceName
+                ? { flagsKvNamespaceName: existing.flagsKvNamespaceName }
+                : {}),
         };
     }
     if (input.dryRun)
         return undefined;
-    // ADR-022: generate the token key and escrow it BEFORE creating any
-    // Cloudflare resource — if custody is unavailable, the deploy stops with
-    // zero mutations instead of minting a key that exists nowhere durable.
     const tokenKeySecretName = 'HSX_TOKEN_KEY';
-    const tokenKeySecretValue = randomBytes(32).toString('base64url');
-    const tokenKeyCustody = await escrowTokenKey({
-        adapter: defaultTokenKeyCustodyAdapter(),
-        custodyId: tokenKeyCustodyIdFor({
-            ownerId: pointer.ownerId,
+    const installResource = await resolveOrProvisionCloudflareScopedResource({
+        identity: {
+            accountId: input.ownerId,
             projectId: input.projectId,
             environment: input.environment,
             hubSpotAppId: input.hubSpotAppId,
-        }),
-        tokenKeySecretValue,
-    });
-    const installKvNamespaceName = installKvNamespaceNameFor({
-        accountId: input.ownerId,
-        projectId: input.projectId,
-        environment: input.environment,
-        hubSpotAppId: input.hubSpotAppId,
-    });
-    const namespaceOutput = await runCloudflareCommand([
-        'bun',
-        'x',
-        'wrangler',
-        'kv',
-        'namespace',
-        'create',
-        installKvNamespaceName,
-        '--binding',
-        'INSTALL_KV',
-    ], {
-        cwd: input.root,
-        env: cloudflareDeployEnv(input.argv),
+        },
+        kind: 'install-kv',
+        async provisionByName(installKvNamespaceName) {
+            // ADR-022: generate and escrow the token key before creating Cloudflare
+            // state, but only after long ambiguous names have already failed closed.
+            const tokenKeySecretValue = randomBytes(32).toString('base64url');
+            const tokenKeyCustody = await escrowTokenKey({
+                adapter: defaultTokenKeyCustodyAdapter(),
+                custodyId: tokenKeyCustodyIdFor({
+                    ownerId: pointer.ownerId,
+                    projectId: input.projectId,
+                    environment: input.environment,
+                    hubSpotAppId: input.hubSpotAppId,
+                }),
+                tokenKeySecretValue,
+            });
+            const namespaceOutput = await runCloudflareCommand([
+                'bun',
+                'x',
+                'wrangler',
+                'kv',
+                'namespace',
+                'create',
+                installKvNamespaceName,
+                '--binding',
+                'INSTALL_KV',
+            ], {
+                cwd: input.root,
+                env: cloudflareDeployEnv(input.argv),
+            });
+            const resourceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
+            if (!resourceId) {
+                throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
+            }
+            return { resourceId, value: { tokenKeySecretValue, tokenKeyCustody } };
+        },
     });
-    const installKvNamespaceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
-    if (!installKvNamespaceId) {
-        throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
+    if (!installResource.value) {
+        throw new Error('Install KV provisioning did not return token-key custody.');
     }
+    const installKvNamespaceId = installResource.resourceId;
+    const installKvNamespaceName = installResource.resourceName;
+    const { tokenKeySecretValue, tokenKeyCustody } = installResource.value;
     await stateStore.putBinding(Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)({
         schemaVersion: 2,
         ownerId: pointer.ownerId,
@@ -2692,49 +2817,68 @@ async function ensureDeployInstallRuntimeBinding(input) {
             installKvNamespaceId: existing.installKvNamespaceId,
             installKvNamespaceName: existing.installKvNamespaceName,
             tokenKeySecretName: existing.tokenKeySecretName,
+            ...(existing.tenantD1DatabaseId ? { tenantD1DatabaseId: existing.tenantD1DatabaseId } : {}),
+            ...(existing.tenantD1DatabaseName
+                ? { tenantD1DatabaseName: existing.tenantD1DatabaseName }
+                : {}),
+            ...(existing.flagsKvNamespaceId ? { flagsKvNamespaceId: existing.flagsKvNamespaceId } : {}),
+            ...(existing.flagsKvNamespaceName
+                ? { flagsKvNamespaceName: existing.flagsKvNamespaceName }
+                : {}),
         };
     }
     if (input.dryRun) {
         return undefined;
     }
-    // ADR-022: the linked path generates the token key at the same seam, so it
-    // gets the same escrow — before any Cloudflare mutation. Only the custody
-    // REFERENCE lands in local state; the control plane never sees key bytes.
-    const tokenKeySecretValue = randomBytes(32).toString('base64url');
-    const tokenKeyCustody = await escrowTokenKey({
-        adapter: defaultTokenKeyCustodyAdapter(),
-        custodyId: tokenKeyCustodyIdFor({
-            ownerId: input.accountId,
+    const installResource = await resolveOrProvisionCloudflareScopedResource({
+        identity: {
+            accountId: input.accountId,
             projectId: input.projectId,
             environment: input.environment,
             hubSpotAppId: input.hubSpotAppId,
-        }),
-        tokenKeySecretValue,
-    });
-    const installKvNamespaceName = installKvNamespaceNameFor({
-        accountId: input.accountId,
-        projectId: input.projectId,
-        environment: input.environment,
-        hubSpotAppId: input.hubSpotAppId,
-    });
-    const namespaceOutput = await runCloudflareCommand([
-        'bun',
-        'x',
-        'wrangler',
-        'kv',
-        'namespace',
-        'create',
-        installKvNamespaceName,
-        '--binding',
-        'INSTALL_KV',
-    ], {
-        cwd: input.root,
-        env: cloudflareDeployEnv(input.argv),
+        },
+        kind: 'install-kv',
+        async provisionByName(installKvNamespaceName) {
+            // ADR-022: escrow precedes Cloudflare mutation, while the ambiguity
+            // guard precedes both. The control plane never receives key bytes.
+            const tokenKeySecretValue = randomBytes(32).toString('base64url');
+            const tokenKeyCustody = await escrowTokenKey({
+                adapter: defaultTokenKeyCustodyAdapter(),
+                custodyId: tokenKeyCustodyIdFor({
+                    ownerId: input.accountId,
+                    projectId: input.projectId,
+                    environment: input.environment,
+                    hubSpotAppId: input.hubSpotAppId,
+                }),
+                tokenKeySecretValue,
+            });
+            const namespaceOutput = await runCloudflareCommand([
+                'bun',
+                'x',
+                'wrangler',
+                'kv',
+                'namespace',
+                'create',
+                installKvNamespaceName,
+                '--binding',
+                'INSTALL_KV',
+            ], {
+                cwd: input.root,
+                env: cloudflareDeployEnv(input.argv),
+            });
+            const resourceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
+            if (!resourceId) {
+                throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
+            }
+            return { resourceId, value: { tokenKeySecretValue, tokenKeyCustody } };
+        },
     });
-    const installKvNamespaceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
-    if (!installKvNamespaceId) {
-        throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
+    if (!installResource.value) {
+        throw new Error('Install KV provisioning did not return token-key custody.');
     }
+    const installKvNamespaceId = installResource.resourceId;
+    const installKvNamespaceName = installResource.resourceName;
+    const { tokenKeySecretValue, tokenKeyCustody } = installResource.value;
     const tokenKeySecretName = 'HSX_TOKEN_KEY';
     await putDeployInstallRuntimeBinding({
         ...input,
@@ -2819,31 +2963,11 @@ async function requestDeployBillingRuntimeToken(input) {
         binding: body.binding,
     };
 }
-function installKvNamespaceNameFor(input) {
-    return truncateCloudflareResourceName(`hsx-${cloudflareNameSlug(input.accountId)}-${cloudflareNameSlug(input.projectId)}-${cloudflareNameSlug(input.environment)}-${cloudflareNameSlug(String(input.hubSpotAppId))}-install`);
-}
-function cloudflareNameSlug(value) {
-    return (value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '') || 'x');
-}
-function truncateCloudflareResourceName(value) {
-    return value.length <= 63 ? value : value.slice(0, 63).replace(/-+$/g, '');
-}
 function extractKvNamespaceId(output) {
     return (/"id"\s*:\s*"([^"]+)"/.exec(output)?.[1] ??
         /id\s*=\s*"([^"]+)"/.exec(output)?.[1] ??
         /id[:\s]+([a-f0-9]{16,})/i.exec(output)?.[1]);
 }
-// ADR-015/ADR-014 tenant data plane: one project-scoped D1 (flag config +
-// installer PII + platform events) and one flags-snapshot KV per install.
-function tenantD1DatabaseNameFor(input) {
-    return truncateCloudflareResourceName(`hsx-${cloudflareNameSlug(input.accountId)}-${cloudflareNameSlug(input.projectId)}-${cloudflareNameSlug(input.environment)}-${cloudflareNameSlug(String(input.hubSpotAppId))}-tenant`);
-}
-function flagsKvNamespaceNameFor(input) {
-    return truncateCloudflareResourceName(`hsx-${cloudflareNameSlug(input.accountId)}-${cloudflareNameSlug(input.projectId)}-${cloudflareNameSlug(input.environment)}-${cloudflareNameSlug(String(input.hubSpotAppId))}-flags`);
-}
 function extractD1DatabaseId(output) {
     return (/"database_id"\s*:\s*"([^"]+)"/.exec(output)?.[1] ??
         /database_id\s*=\s*"([^"]+)"/.exec(output)?.[1] ??
@@ -2858,10 +2982,12 @@ function extractD1DatabaseId(output) {
  *
  * Idempotent: re-uses already-provisioned ids + an already-generated secret from
  * local state (so a re-deploy keeps the same secret the Worker already holds).
- * Returns `syncGrantSecretValue` only when freshly generated — the caller does
- * a `wrangler secret put` only then. Tenant-data-plane activation is
- * linked-only (codegen emits the options solely for heartbeat.mode==='linked'),
- * so this is never called for unlinked direct-to-HubSpot deploys.
+ * Returns the canonical `syncGrantSecretValue` on every call — including when
+ * it came from the durable binding — because a newly-added Worker does not yet
+ * have the write-only Cloudflare secret even though sibling Workers do.
+ * Tenant-data-plane activation is linked-only. Codegen receives the exact
+ * tenant scope for every linked Worker independently of primary-only heartbeat
+ * ownership, so this is never called for unlinked direct-to-HubSpot deploys.
  */
 async function ensureTenantDataPlane(input) {
     const { pointer, stateStore } = await ensureTenantStateStore({
@@ -2874,69 +3000,86 @@ async function ensureTenantDataPlane(input) {
         hubSpotAppId: input.hubSpotAppId,
     });
     const env = cloudflareDeployEnv(input.argv);
-    const tenantD1DatabaseName = existing?.tenantD1DatabaseName ?? tenantD1DatabaseNameFor(input);
-    let tenantD1DatabaseId = existing?.tenantD1DatabaseId;
-    if (!tenantD1DatabaseId) {
-        // Create, or ADOPT on a name conflict: resource names are deterministic,
-        // so a database that already exists is this project's own tenant D1 from
-        // an earlier deploy whose local state was lost — failing here would brick
-        // every redeploy while the data-holding database sits one lookup away.
-        const created = await runCloudflareCommand(['bun', 'x', 'wrangler', 'd1', 'create', tenantD1DatabaseName], { cwd: input.root, env }).catch((error) => {
-            if (!/already exists/i.test(String(error)))
-                throw error;
-            return undefined;
-        });
-        if (created) {
-            tenantD1DatabaseId = extractD1DatabaseId(`${created.stdout}\n${created.stderr}`);
-        }
-        else {
-            const info = await runCloudflareCommand(['bun', 'x', 'wrangler', 'd1', 'info', tenantD1DatabaseName, '--json'], { cwd: input.root, env });
-            tenantD1DatabaseId =
-                extractD1DatabaseId(info.stdout) ?? /"uuid"\s*:\s*"([^"]+)"/.exec(info.stdout)?.[1];
-        }
-        if (!tenantD1DatabaseId) {
-            throw new Error('Could not read tenant D1 database id from wrangler output.');
-        }
-    }
-    const flagsKvNamespaceName = existing?.flagsKvNamespaceName ?? flagsKvNamespaceNameFor(input);
-    let flagsKvNamespaceId = existing?.flagsKvNamespaceId;
-    if (!flagsKvNamespaceId) {
-        // Same create-or-adopt posture as the tenant D1 above.
-        const created = await runCloudflareCommand([
-            'bun',
-            'x',
-            'wrangler',
-            'kv',
-            'namespace',
-            'create',
-            flagsKvNamespaceName,
-            '--binding',
-            'FLAGS_KV',
-        ], { cwd: input.root, env }).catch((error) => {
-            if (!/already exists/i.test(String(error)))
-                throw error;
-            return undefined;
-        });
-        if (created) {
-            flagsKvNamespaceId = extractKvNamespaceId(`${created.stdout}\n${created.stderr}`);
-        }
-        else {
-            const listed = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'], { cwd: input.root, env });
-            try {
-                const namespaces = JSON.parse(listed.stdout);
-                flagsKvNamespaceId = namespaces.find((namespace) => namespace.title === flagsKvNamespaceName)?.id;
+    // Exact local state wins; exact control-plane refs recover a linked deploy
+    // when its tenant-state binding was lost. Name-only create/adopt remains
+    // available for short legacy-compatible names only.
+    const exactTenantD1DatabaseId = existing?.tenantD1DatabaseId ?? input.install.tenantD1DatabaseId;
+    const exactTenantD1DatabaseName = existing?.tenantD1DatabaseName ?? input.install.tenantD1DatabaseName;
+    const tenantD1 = await resolveOrProvisionCloudflareScopedResource({
+        identity: input,
+        kind: 'tenant-d1',
+        ...(exactTenantD1DatabaseId ? { exactResourceId: exactTenantD1DatabaseId } : {}),
+        ...(exactTenantD1DatabaseName ? { exactResourceName: exactTenantD1DatabaseName } : {}),
+        async provisionByName(tenantD1DatabaseName) {
+            const created = await runCloudflareCommand(['bun', 'x', 'wrangler', 'd1', 'create', tenantD1DatabaseName], { cwd: input.root, env }).catch((error) => {
+                if (!/already exists/i.test(String(error)))
+                    throw error;
+                return undefined;
+            });
+            let resourceId = created
+                ? extractD1DatabaseId(`${created.stdout}\n${created.stderr}`)
+                : undefined;
+            if (!created) {
+                const info = await runCloudflareCommand(['bun', 'x', 'wrangler', 'd1', 'info', tenantD1DatabaseName, '--json'], { cwd: input.root, env });
+                resourceId =
+                    extractD1DatabaseId(info.stdout) ?? /"uuid"\s*:\s*"([^"]+)"/.exec(info.stdout)?.[1];
             }
-            catch {
-                flagsKvNamespaceId = undefined;
+            if (!resourceId) {
+                throw new Error('Could not read tenant D1 database id from wrangler output.');
             }
-        }
-        if (!flagsKvNamespaceId) {
-            throw new Error('Could not read flags KV namespace id from wrangler output.');
-        }
-    }
+            return { resourceId };
+        },
+    });
+    const tenantD1DatabaseId = tenantD1.resourceId;
+    const tenantD1DatabaseName = tenantD1.resourceName;
+    const exactFlagsKvNamespaceId = existing?.flagsKvNamespaceId ?? input.install.flagsKvNamespaceId;
+    const exactFlagsKvNamespaceName = existing?.flagsKvNamespaceName ?? input.install.flagsKvNamespaceName;
+    const flagsKv = await resolveOrProvisionCloudflareScopedResource({
+        identity: input,
+        kind: 'flags-kv',
+        ...(exactFlagsKvNamespaceId ? { exactResourceId: exactFlagsKvNamespaceId } : {}),
+        ...(exactFlagsKvNamespaceName ? { exactResourceName: exactFlagsKvNamespaceName } : {}),
+        async provisionByName(flagsKvNamespaceName) {
+            const created = await runCloudflareCommand([
+                'bun',
+                'x',
+                'wrangler',
+                'kv',
+                'namespace',
+                'create',
+                flagsKvNamespaceName,
+                '--binding',
+                'FLAGS_KV',
+            ], { cwd: input.root, env }).catch((error) => {
+                if (!/already exists/i.test(String(error)))
+                    throw error;
+                return undefined;
+            });
+            let resourceId = created
+                ? extractKvNamespaceId(`${created.stdout}\n${created.stderr}`)
+                : undefined;
+            if (!created) {
+                const listed = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'], { cwd: input.root, env });
+                try {
+                    const namespaces = JSON.parse(listed.stdout);
+                    resourceId = namespaces.find((namespace) => namespace.title === flagsKvNamespaceName)?.id;
+                }
+                catch {
+                    resourceId = undefined;
+                }
+            }
+            if (!resourceId) {
+                throw new Error('Could not read flags KV namespace id from wrangler output.');
+            }
+            return { resourceId };
+        },
+    });
+    const flagsKvNamespaceId = flagsKv.resourceId;
+    const flagsKvNamespaceName = flagsKv.resourceName;
     const syncGrantSecretName = 'HSX_SYNC_GRANT_KEY';
-    const reusedSecret = existing?.syncGrantSecretValue;
-    const syncGrantSecretValue = reusedSecret ?? randomBytes(32).toString('base64url');
+    const syncGrantSecretValue = input.canonicalSyncGrantSecretValue ??
+        existing?.syncGrantSecretValue ??
+        randomBytes(32).toString('base64url');
     await stateStore.putBinding(Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)({
         schemaVersion: 2,
         ownerId: pointer.ownerId,
@@ -2964,58 +3107,15 @@ async function ensureTenantDataPlane(input) {
         syncGrantSecretValue,
         updatedAt: new Date().toISOString(),
     }));
-    // ADR-015 §5 "Both": register the secret control-plane-side for the (gated)
-    // dashboard/agent/sync consumers. Best-effort — the leaveable CLI-direct path
-    // reads the value from local state and needs no control plane.
-    if (input.controlPlaneUrl && input.userId) {
-        try {
-            await registerDeploySyncGrantSecret({
-                controlPlaneUrl: input.controlPlaneUrl,
-                userId: input.userId,
-                accountId: input.accountId,
-                projectId: input.projectId,
-                environment: input.environment,
-                hubSpotAppId: input.hubSpotAppId,
-                syncGrantSecret: syncGrantSecretValue,
-            });
-        }
-        catch (error) {
-            const warning = `warning: could not register the sync grant secret with the control plane: ${error instanceof Error ? error.message : String(error)}\n`;
-            if (input.note) {
-                input.note(warning);
-            }
-            else {
-                process.stderr.write(warning);
-            }
-        }
-    }
     return {
         tenantD1DatabaseId,
         tenantD1DatabaseName,
         flagsKvNamespaceId,
         flagsKvNamespaceName,
         syncGrantSecretName,
-        ...(reusedSecret ? {} : { syncGrantSecretValue }),
+        syncGrantSecretValue,
     };
 }
-async function registerDeploySyncGrantSecret(input) {
-    const response = await hostedHttp({
-        url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/hubspot-apps/${encodeURIComponent(input.hubSpotAppId)}/sync-grant-secret`, input.controlPlaneUrl),
-        method: 'PUT',
-        headers: await controlPlaneAuthHeaders(input.userId),
-        body: {
-            environment: input.environment,
-            syncGrantSecret: input.syncGrantSecret,
-        },
-    });
-    const body = await response.json();
-    if (!response.ok) {
-        const message = isRecord(body) && typeof body.message === 'string'
-            ? body.message
-            : `Control plane returned ${response.status}.`;
-        throw new Error(`Could not register the sync grant secret: ${message}`);
-    }
-}
 export function renderWranglerConfig(input) {
     const lines = [
         '# Generated by hs-x. Do not edit by hand.',
@@ -3031,12 +3131,19 @@ export function renderWranglerConfig(input) {
         // when --compatibility-date is set to an older date.
         'compatibility_flags = [ "nodejs_compat", "nodejs_compat_populate_process_env" ]',
     ];
+    if (input.versionMetadataBinding) {
+        lines.push('', '[version_metadata]', `binding = "${tomlString(input.versionMetadataBinding)}"`);
+    }
     if (input.installKvNamespaceId) {
         lines.push('', '[[kv_namespaces]]', 'binding = "INSTALL_KV"', `id = "${tomlString(input.installKvNamespaceId)}"`);
     }
     // ADR-015 flag-snapshot KV (the eval-path hot replica).
     if (input.flagsKvNamespaceId) {
         lines.push('', '[[kv_namespaces]]', 'binding = "FLAGS_KV"', `id = "${tomlString(input.flagsKvNamespaceId)}"`);
+        // Route-level abuse protection for the public flag evaluate + authoring
+        // surfaces. The request key includes deployment identity + exact route, so
+        // a namespace collision cannot merge counters between generated Workers.
+        lines.push('', '[[ratelimits]]', 'name = "HSX_FLAGS_RATE_LIMITER"', `namespace_id = "${flagsRateLimitNamespaceId(input.workerName)}"`, '', '  [ratelimits.simple]', '  limit = 120', '  period = 60');
     }
     // ADR-015/ADR-014 project-scoped tenant D1 (flag config + installer PII +
     // platform events). migrations_dir lets wrangler auto-apply the tenant
@@ -3068,6 +3175,14 @@ export function renderWranglerConfig(input) {
     }
     return `${lines.join('\n')}\n`;
 }
+function flagsRateLimitNamespaceId(workerName) {
+    let hash = 2_166_136_261;
+    for (const character of `${workerName}:HSX_FLAGS_RATE_LIMITER`) {
+        hash ^= character.codePointAt(0) ?? 0;
+        hash = Math.imul(hash, 16_777_619) >>> 0;
+    }
+    return String(hash || 1);
+}
 function tomlString(value) {
     return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
 }
@@ -3121,8 +3236,161 @@ async function resolveUploadFirstRuntimeOrigin(input) {
         return undefined;
     }
 }
+const HUBSPOT_GENERATED_LEDGER = '.hs-x/hubspot-generated-files.json';
+const USER_OWNED_GENERATED_PATHS = new Set(['src/app/cards/package.json']);
+function generatedFileHash(contents) {
+    return createHash('sha256').update(contents).digest('hex');
+}
+function isKnownGeneratedHubSpotPath(file) {
+    return (file === 'hsproject.json' ||
+        file === 'src/app/app-hsmeta.json' ||
+        file === 'src/app/cards/package.json' ||
+        file === 'src/app/cards/_hsx-backend.ts' ||
+        /^src\/app\/(?:workflow-actions|app-objects|app-object-associations|app-events|mcp-server|cards)\/[^/]+-hsmeta\.json$/.test(file));
+}
+/** Resolve a ledger path only when it is a known, normalized root-relative artifact. */
+function resolveGeneratedFilePath(root, file) {
+    if (!isKnownGeneratedHubSpotPath(file) || isAbsolute(file) || file.includes('\\')) {
+        return undefined;
+    }
+    const segments = file.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        return undefined;
+    }
+    const rootPath = resolve(root);
+    const resolved = resolve(rootPath, file);
+    return resolved.startsWith(`${rootPath}/`) ? resolved : undefined;
+}
+async function assertGeneratedPathIsContained(root, path) {
+    const rootRealPath = await realpath(root);
+    let existingAncestor = dirname(path);
+    while (true) {
+        try {
+            const ancestorRealPath = await realpath(existingAncestor);
+            const fromRoot = relative(rootRealPath, ancestorRealPath);
+            if (fromRoot.startsWith('..') || isAbsolute(fromRoot)) {
+                throw new Error(`Generated HubSpot artifact parent escapes the project root: ${path}`);
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = dirname(existingAncestor);
+            if (parent === existingAncestor)
+                throw error;
+            existingAncestor = parent;
+        }
+    }
+    const target = await lstat(path).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (target?.isSymbolicLink()) {
+        throw new Error(`Generated HubSpot artifact path must not be a symbolic link: ${path}`);
+    }
+}
+async function readGeneratedFileLedger(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, HUBSPOT_GENERATED_LEDGER), 'utf8'));
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            parsed.version !== 1 ||
+            typeof parsed.files !== 'object' ||
+            parsed.files === null) {
+            return { version: 1, files: {} };
+        }
+        const files = {};
+        for (const [file, hash] of Object.entries(parsed.files)) {
+            if (resolveGeneratedFilePath(root, file) && /^[a-f0-9]{64}$/.test(String(hash))) {
+                files[file] = String(hash);
+            }
+        }
+        return { version: 1, files };
+    }
+    catch {
+        // No heuristic cleanup for projects that predate the ledger, or for a
+        // malformed ledger. Generation can safely establish a fresh ledger.
+        return { version: 1, files: {} };
+    }
+}
+async function pruneEmptyGeneratedDirectories(root, from) {
+    const rootPath = resolve(root);
+    let directory = resolve(from);
+    while (directory !== rootPath && directory.startsWith(`${rootPath}/`)) {
+        try {
+            if ((await readdir(directory)).length > 0)
+                return;
+            await rmdir(directory);
+        }
+        catch {
+            return;
+        }
+        directory = dirname(directory);
+    }
+}
+async function reconcileHubSpotRuntimeProjectFiles(root, generatedFiles, options = {}) {
+    const previous = await readGeneratedFileLedger(root);
+    const generatedPaths = new Set(Object.keys(generatedFiles));
+    const nextFiles = {};
+    for (const [file, expectedHash] of Object.entries(previous.files)) {
+        if (generatedPaths.has(file) || USER_OWNED_GENERATED_PATHS.has(file))
+            continue;
+        if (options.preservePrevious?.(file)) {
+            nextFiles[file] = expectedHash;
+            continue;
+        }
+        const path = resolveGeneratedFilePath(root, file);
+        if (!path)
+            continue;
+        try {
+            await assertGeneratedPathIsContained(root, path);
+            const current = await readFile(path);
+            if (generatedFileHash(current) !== expectedHash)
+                continue;
+            await unlink(path);
+            await pruneEmptyGeneratedDirectories(root, dirname(path));
+        }
+        catch {
+            // Missing and non-file paths are preserved; only a byte-for-byte owned
+            // regular file is eligible for removal.
+        }
+    }
+    for (const [file, contents] of Object.entries(generatedFiles)) {
+        const path = resolveGeneratedFilePath(root, file);
+        if (!path)
+            throw new Error(`Generated HubSpot artifact has an unsafe path: ${file}`);
+        await assertGeneratedPathIsContained(root, path);
+        // HubSpot tells card authors to add dependencies here. Once created, this
+        // file is user-owned and is deliberately never entered in the ledger.
+        if (USER_OWNED_GENERATED_PATHS.has(file)) {
+            if (!(await stat(path).catch(() => undefined))) {
+                await mkdir(dirname(path), { recursive: true });
+                await writeFile(path, contents);
+            }
+            continue;
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, contents);
+        nextFiles[file] = generatedFileHash(contents);
+    }
+    const ledgerPath = join(root, HUBSPOT_GENERATED_LEDGER);
+    await assertGeneratedPathIsContained(root, ledgerPath);
+    await mkdir(dirname(ledgerPath), { recursive: true });
+    const temporaryLedgerPath = `${ledgerPath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    await writeFile(temporaryLedgerPath, `${JSON.stringify({ version: 1, files: nextFiles }, null, 2)}\n`);
+    await rename(temporaryLedgerPath, ledgerPath);
+}
 export async function ensureHubSpotRuntimeProjectArtifacts({ argv, root, app, workers, cloudflareDeployResult, needsRuntime, controlPlanePlan, runtimeOrigin, }) {
-    if (!needsRuntime) {
+    const hasMcpServers = app.mcpServers.length > 0;
+    if (!needsRuntime && !hasMcpServers) {
+        // A prior MCP-only generation may have left ledger-owned MCP files. Remove
+        // those declarations, but retain other generated metadata: a display-only
+        // card or schema declaration remains valid when its runtime worker is gone.
+        await reconcileHubSpotRuntimeProjectFiles(root, {}, {
+            preservePrevious: (file) => !file.startsWith('src/app/mcp-server/'),
+        });
         return;
     }
     const runtimeBaseUrl = runtimeOrigin ??
@@ -3135,26 +3403,17 @@ export async function ensureHubSpotRuntimeProjectArtifacts({ argv, root, app, wo
     const redirectUrls = app.auth === 'oauth' && oauthCallbackPath
         ? [`${runtimeBaseUrl.replace(/\/$/, '')}${oauthCallbackPath}`]
         : [];
+    const platformVersion = resolveFlag(argv, '--platform-version') ?? app.platformVersion;
     const generated = generateHubSpotRuntimeProject({
         ...app,
+        platformVersion,
         workers,
         runtimeBaseUrl,
         redirectUrls,
     });
-    for (const [file, contents] of Object.entries(generated.files)) {
-        const path = join(root, file);
-        // src/app/cards/package.json is user-owned once it exists: HubSpot's own
-        // build errors instruct users to add card dependencies (e.g. hs-uix) to
-        // it, and regenerating the fixed-dep version here silently dropped those
-        // deps so the card never built (cold-stranger run #2 blocker B). Keep the
-        // user's file verbatim; only generate one when absent.
-        if (file === 'src/app/cards/package.json' && (await stat(path).catch(() => undefined))) {
-            continue;
-        }
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, contents);
-    }
+    await reconcileHubSpotRuntimeProjectFiles(root, generated.files);
     const migratedShimPath = join(root, 'src', 'app', 'cards', '_hsx-migration-run-serverless.ts');
+    await assertGeneratedPathIsContained(root, migratedShimPath);
     if (await stat(migratedShimPath).catch(() => undefined)) {
         const migratedShim = await readFile(migratedShimPath, 'utf8');
         await writeFile(migratedShimPath, stampMigratedRunServerlessShimOrigin(migratedShim, runtimeBaseUrl));
@@ -3169,9 +3428,19 @@ async function readHsxAppScopesForDeploy(root) {
         return [];
     }
 }
-async function readHsxAppConfig(root) {
+export async function readHsxAppConfig(root) {
     const raw = await readFile(join(root, 'hsx.config.ts'), 'utf8');
-    const loaded = parseHsxAppConfigLiteral(raw) ?? (await loadHsxAppConfigModule(root).catch(() => undefined));
+    let loaded = parseHsxAppConfigLiteral(raw);
+    if (!loaded) {
+        try {
+            loaded = await loadHsxAppConfigModule(root);
+        }
+        catch (error) {
+            if (/\bmcpServer\s*\(|\bmcpServers\b/.test(raw)) {
+                throw new Error('Could not evaluate helper-based MCP declarations in hsx.config.ts; refusing to treat the declaration set as empty because that could remove generated MCP metadata.', { cause: error });
+            }
+        }
+    }
     return {
         appName: loaded?.name ?? /name\s*:\s*["'`]([^"'`]+)["'`]/.exec(raw)?.[1] ?? basename(root),
         // No regex fallback for description: a raw-text match could pick up a
@@ -3193,9 +3462,10 @@ async function readHsxAppConfig(root) {
         ...(loaded?.rateLimits !== undefined ? { rateLimits: loaded.rateLimits } : {}),
         ...(loaded?.alerts !== undefined ? { alerts: loaded.alerts } : {}),
         ...(loaded?.redaction !== undefined ? { redaction: loaded.redaction } : {}),
-        // Cards are only recoverable from the loaded module (the literal parser
-        // can't evaluate `card(...)` calls); an unloadable config yields none.
+        // Helper-based declarations are only recoverable from the loaded module
+        // (the literal parser cannot evaluate card(...) or mcpServer(...) calls).
         cards: loaded?.cards ?? [],
+        mcpServers: loaded?.mcpServers ?? [],
         ...(loaded?.billing ? { billing: loaded.billing } : {}),
     };
 }
@@ -3527,11 +3797,13 @@ async function executeHubSpotOnlyUpload({ argv, root, local, uploadOnly, }) {
         cwd: root,
     });
     await client.projects.ensureProject({ projectName });
+    const hsproject = await readHubSpotProjectConfig(root);
+    const configuredPlatformVersion = typeof hsproject.platformVersion === 'string' ? hsproject.platformVersion : undefined;
     const upload = await client.projects.upload({
         projectName,
         archivePath,
         message: resolveFlag(argv, '--message') ?? 'HS-X HubSpot-only deploy',
-        platformVersion: resolveFlag(argv, '--platform-version') ?? '2026.03',
+        platformVersion: resolveFlag(argv, '--platform-version') ?? configuredPlatformVersion ?? '2026.03',
         intermediateRepresentation,
     });
     const buildStatus = await waitForHubSpotBuildStatus({
@@ -3574,11 +3846,11 @@ async function executeHubSpotOnlyUpload({ argv, root, local, uploadOnly, }) {
             local,
         };
     }
-    const deploy = await client.projects.deployBuild({
+    const deploy = await withTransientDeployRetry(() => client.projects.deployBuild({
         projectName,
         buildId: upload.buildId,
         force: argv.includes('--force'),
-    });
+    }));
     const deployId = readNumericProperty(deploy, 'deployId');
     const deployStatus = deployId === undefined
         ? deploy
@@ -4004,8 +4276,28 @@ async function requestHostedControlPlaneDeployPlan({ request, controlPlaneUrl, u
     return Schema.decodeUnknownSync(schemas.DeployPlanResponse)(body);
 }
 async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, plan, promoteWhenHealthy, revision, }) {
+    const localAttestationAuth = revision
+        ? { grantSecret: randomBytes(32).toString('base64url'), hubSpotAppId: 1 }
+        : undefined;
     const controlPlane = (await loadCreateControlPlane())({
         now: () => new Date('2026-05-18T14:00:00.000Z'),
+        ...(localAttestationAuth
+            ? {
+                secretsKv: {
+                    async get() {
+                        return JSON.stringify({
+                            accountId: request.accountId,
+                            projectId: request.projectId,
+                            environment: 'dev',
+                            hubSpotAppId: localAttestationAuth.hubSpotAppId,
+                            syncGrantSecret: localAttestationAuth.grantSecret,
+                            updatedAt: '2026-05-18T14:00:00.000Z',
+                        });
+                    },
+                    async put() { },
+                },
+            }
+            : {}),
     });
     const headers = {
         'content-type': 'application/json',
@@ -4042,20 +4334,37 @@ async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, pl
     if (!promoteWhenHealthy) {
         return { record };
     }
+    if (!localAttestationAuth || !revision) {
+        throw new Error('Local promotion requires a scoped runtime grant secret, HubSpot app id, and captured Cloudflare revision.');
+    }
+    const attestationBody = JSON.stringify({
+        manifestHash: plan.manifestHash,
+        bindingFingerprint: `bindings:${plan.deployId}`,
+        sdkVersion: CLI_VERSION,
+        taggedResourceCount: Math.max(1, plan.resources.workerNames.length),
+        hsXAccountId: request.accountId,
+        projectId: request.projectId,
+        environment: 'dev',
+        hubSpotAppId: localAttestationAuth.hubSpotAppId,
+        deployId: plan.deployId,
+        revisionId: revision.versionId,
+        timestamp: '2026-05-18T14:00:00.000Z',
+    });
+    const attestationGrant = await signDeploymentAttestationGrant({
+        secret: localAttestationAuth.grantSecret,
+        body: attestationBody,
+        accountId: request.accountId,
+        projectId: request.projectId,
+        environment: 'dev',
+        hubSpotAppId: localAttestationAuth.hubSpotAppId,
+        deployId: plan.deployId,
+        revisionId: revision.versionId,
+        now: new Date('2026-05-18T14:00:00.000Z'),
+    });
     const driftResponse = await controlPlane.fetch(new Request(`https://api.hs-x.dev/v1/projects/${request.projectId}/attestation`, {
         method: 'POST',
-        headers,
-        body: JSON.stringify({
-            manifestHash: plan.manifestHash,
-            bindingFingerprint: `bindings:${plan.deployId}`,
-            sdkVersion: CLI_VERSION,
-            taggedResourceCount: Math.max(1, plan.resources.workerNames.length),
-            hsXAccountId: request.accountId,
-            projectId: request.projectId,
-            environment: 'dev',
-            deployId: plan.deployId,
-            timestamp: '2026-05-18T14:00:00.000Z',
-        }),
+        headers: { ...headers, authorization: `Bearer ${attestationGrant}` },
+        body: attestationBody,
     }));
     const driftBody = await driftResponse.json();
     if (!driftResponse.ok) {