@hs-x/cli 0.4.5 → 0.4.7

package/dist/commands/deploy.js

@@ -15,9 +15,10 @@ import { Effect, Option } from 'effect';
 import { isLinked } from '../account-store.js';
 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 { classifyCloudflareCommandFailure, preflightCloudflareAnalyticsEngine, validateCloudflareResourceForAccount, } from '../cloudflare-account-preflight.js';
+import { applyLeasedCloudflareCredentials, resolveCloudflareCredentials, } from '../cloudflare-kv.js';
 import { loadCloudflarePointer } from '../cloudflare-pointer.js';
-import { resolveOrProvisionCloudflareScopedResource } from '../cloudflare-scoped-resource.js';
+import { parseWranglerJsonArray, 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';
@@ -30,6 +31,7 @@ import { DirectHubSpotAccountResolutionError, createDeployHubSpotDeveloperClient
 import { HubSpotProjectArchiveSourceError, fingerprintHubSpotArchiveSource, writeLocalHubSpotProjectArchive, } from '../hubspot-project-archive.js';
 import { deployHubSpotProjectBuild, readHubSpotSubbuildStatuses, waitForHubSpotAutoDeploy, waitForHubSpotBuildStatus, } from '../hubspot-project-lifecycle.js';
 import { detectLocalProjectMode, readHubSpotProjectDescriptor, validateHubSpotProject, } from '../hubspot-project.js';
+import { linkMigrationJournalId, loadLinkMigrationJournal } from '../link-migration-journal.js';
 import { hydrateAncestorEnv } from '../load-env.js';
 import { LocalProjectPickerCancelled, resolveLocalProject } from '../local-project-picker.js';
 import { getMachineId, getMachineSecret, previewMachineId } from '../machine-id.js';
@@ -41,7 +43,7 @@ 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 { defaultTokenKeyCustodyAdapter, escrowTokenKey, resolveEscrowedTokenKey, sealTokenKeyCanary, tokenKeyCustodyAdapterFor, tokenKeyCustodyIdFor, } from '../token-key-custody.js';
 import { deployPromoteCommand, requestControlPlaneDeployPromotion } from './deploy-promote.js';
 import { withTransientDeployRetry } from './deploy-retry.js';
 async function hostedHttp(input) {
@@ -475,7 +477,31 @@ async function hydrateCloudflareTokenFromStoredOAuth(input) {
         return false;
     }
 }
-async function waitForHealthyControlPlaneDrift({ controlPlaneUrl, projectId, deployId, userId, timeoutMs, workerUrl, }) {
+/**
+ * Prefer the account-scoped Cloudflare connection held by the control plane.
+ * This keeps an explicit `--account-id` deploy from being redirected by a
+ * stale local `.hs-x/cloudflare.json` pointer or an unrelated stored OAuth
+ * connection on a machine that works across several HS-X accounts.
+ */
+async function hydrateCloudflareTokenFromControlPlane(input) {
+    // A command-line credential is an intentional one-run override. Ambient
+    // env credentials are not: on a multi-account machine they commonly point
+    // at a different Cloudflare account, so a linked deploy must replace them
+    // with the selected HS-X account's leased credential pair.
+    if (resolveFlag(input.argv, '--cloudflare-api-token') || resolveFlag(input.argv, '--api-token')) {
+        return false;
+    }
+    const { leaseCloudflareViaSession } = await import('../tenant-state.js');
+    const lease = await leaseCloudflareViaSession(input.argv, input.root);
+    if (!lease)
+        return false;
+    applyLeasedCloudflareCredentials({
+        apiToken: lease.apiToken,
+        accountId: lease.cloudflareAccountId,
+    });
+    return true;
+}
+async function waitForHealthyControlPlaneDrift({ controlPlaneUrl, accountId, projectId, deployId, userId, timeoutMs, workerUrl, }) {
     const startedAt = Date.now();
     let lastState = 'unknown';
     let lastReason;
@@ -485,7 +511,7 @@ async function waitForHealthyControlPlaneDrift({ controlPlaneUrl, projectId, dep
         }
         const response = await hostedHttp({
             url: new URL(`/v1/projects/${encodeURIComponent(projectId)}/drift`, controlPlaneUrl),
-            headers: await controlPlaneAuthHeaders(userId),
+            headers: await controlPlaneAuthHeaders(userId, undefined, accountId),
         });
         const body = await response.json().catch(() => undefined);
         if (response.ok) {
@@ -953,7 +979,7 @@ async function executeHubSpotDirectDeployCommand({ argv, root, json, }) {
             ? (readStatus(uploaded.deployStatus) ?? 'UNKNOWN')
             : undefined;
         const deployUnverified = uploaded.autoDeployExpected && deployState === undefined;
-        const ok = buildState === 'SUCCESS' && !deployUnverified && (!deployState || deployState === 'SUCCESS');
+        const ok = hubSpotUploadSucceeded(uploaded);
         const result = {
             schema_version: 1,
             ok,
@@ -1078,8 +1104,14 @@ export async function deployCommand({ argv, root, json, }) {
     const noHeartbeat = argv.includes('--no-heartbeat');
     const noRecord = argv.includes('--no-record');
     const explicitControlPlaneUrl = resolveFlag(argv, '--control-plane-url');
-    const controlPlaneUrl = explicitControlPlaneUrl ?? (planOnly ? undefined : process.env.HSX_CONTROL_PLANE_URL);
     const linked = await isLinked();
+    const controlPlaneUrl = resolveDeployControlPlaneUrl({
+        explicitControlPlaneUrl,
+        environmentControlPlaneUrl: process.env.HSX_CONTROL_PLANE_URL,
+        platformControlPlaneUrl: resolveControlPlaneUrl(argv),
+        linked,
+        planOnly,
+    });
     const userId = resolveFlag(argv, '--user-id') ?? process.env.HSX_USER_ID ?? 'local-cli-user';
     const resolvedAcct = await resolveAccountIdOrPrompt({
         argv,
@@ -1133,7 +1165,6 @@ export async function deployCommand({ argv, root, json, }) {
     const needsHubSpotBundle = needsRuntime || app.mcpServers.length > 0;
     const { deploymentMode, cloudflareDeployRequested, hubspotUploadRequested } = resolveDeployTargets({
         buildOnly,
-        planOnly,
         needsRuntime,
         hasProjectId: Boolean(projectId),
         hubspotOnly,
@@ -1417,10 +1448,8 @@ export async function deployCommand({ argv, root, json, }) {
     // (`--yes`) preflight succeed instead of demanding a token connect says
     // doesn't exist (cold-stranger run 2026-07-22-001, finding #1).
     if (cloudflareDeployRequested && !planOnly && !cloudflareDryRun) {
-        const hydrated = await hydrateCloudflareTokenFromStoredOAuth({
-            argv,
-            root,
-        });
+        const hydrated = (controlPlaneUrl ? await hydrateCloudflareTokenFromControlPlane({ argv, root }) : false) ||
+            (await hydrateCloudflareTokenFromStoredOAuth({ argv, root }));
         if (hydrated && echo) {
             echo.info('Using the Cloudflare connection from `hs-x connect cloudflare`.');
         }
@@ -1447,7 +1476,17 @@ export async function deployCommand({ argv, root, json, }) {
     // Worker origin is resolvable up front, upload BEFORE the Cloudflare deploy so
     // the minted app id binds in a single pass. Falls back to the original
     // deploy-then-upload order whenever the origin can't be resolved.
-    const appIdKnownBeforeDeploy = readOptionalHubSpotAppId(resolveFlag(argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID) ?? (await readPersistedHubSpotAppId(root, await resolveHubSpotProjectName(argv, root)));
+    const appIdKnownBeforeDeploy = controlPlanePlan && controlPlaneBackedPlan && controlPlaneUrl
+        ? await resolveHubSpotAppIdForDeploy({
+            argv,
+            root,
+            controlPlaneUrl,
+            userId,
+            accountId: controlPlanePlan.accountId,
+            projectId: controlPlanePlan.projectId,
+            environment: resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production',
+        })
+        : (readOptionalHubSpotAppId(resolveFlag(argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID) ?? (await readPersistedHubSpotAppId(root, await resolveHubSpotProjectName(argv, root))));
     const uploadFirstOrigin = cloudflareDeployRequested &&
         !cloudflareDryRun &&
         !planOnly &&
@@ -1596,6 +1635,10 @@ export async function deployCommand({ argv, root, json, }) {
                         plan: controlPlanePlan,
                         promoteWhenHealthy,
                         ...(capturedRevision ? { revision: capturedRevision } : {}),
+                        ...(() => {
+                            const deployedWorkerUrl = cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
+                            return deployedWorkerUrl ? { workerUrl: deployedWorkerUrl } : {};
+                        })(),
                     })
                     : controlPlaneUrl
                         ? await requestHostedControlPlaneDeployRecordAndMaybePromote({
@@ -1694,7 +1737,7 @@ export async function deployCommand({ argv, root, json, }) {
     // run-008 build #2's failure mode. Only a SUCCESS status counts.
     const hubspotUploadFailed = !planOnly &&
         hubspotUploadRequested &&
-        (!hubspotUploadResult || readStatus(hubspotUploadResult.buildStatus) !== 'SUCCESS');
+        (!hubspotUploadResult || !hubSpotUploadSucceeded(hubspotUploadResult));
     const cloudflareDeployed = !planOnly && cloudflareDeployRequested && Boolean(cloudflareDeployResult);
     // A live worker with only the HubSpot upload failing: not a clean success,
     // but distinct from total failure so callers don't tear down a good worker.
@@ -1810,6 +1853,16 @@ export async function deployCommand({ argv, root, json, }) {
     // automation doesn't treat a serving worker as a total failure), 1 = failure.
     return { exitCode: plan.ok ? 0 : plan.partial ? 20 : 1 };
 }
+/** @internal Exported for the linked-default deploy regression suite. */
+export function resolveDeployControlPlaneUrl(input) {
+    if (input.explicitControlPlaneUrl)
+        return input.explicitControlPlaneUrl;
+    if (input.planOnly)
+        return undefined;
+    if (input.linked)
+        return input.platformControlPlaneUrl;
+    return input.environmentControlPlaneUrl;
+}
 function buildDeployPlanSummary(input) {
     const lines = ['', 'Planned changes:'];
     const capCount = input.workers.reduce((c, w) => c + w.capabilities.length, 0);
@@ -2680,6 +2733,14 @@ function defaultHubSpotFieldType(type) {
             return 'text';
     }
 }
+/** @internal Exported for deterministic deploy-outcome regression tests. */
+export function hubSpotUploadSucceeded(upload) {
+    if (readStatus(upload.buildStatus) !== 'SUCCESS')
+        return false;
+    if (upload.deployStatus !== undefined)
+        return readStatus(upload.deployStatus) === 'SUCCESS';
+    return !upload.autoDeployExpected;
+}
 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
@@ -2687,12 +2748,40 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
     if (!controlPlaneUrl && !dryRun) {
         await preflightTenantStateCredentials({ argv, root });
     }
+    if (controlPlaneUrl && !dryRun) {
+        const credentials = resolveCloudflareCredentials(argv);
+        if (!credentials.accountId || !credentials.apiToken) {
+            throw new Error('Linked Cloudflare deploy requires an account id and API token from the connected credential lease.');
+        }
+        // Read-only and intentionally first: a fresh Cloudflare account otherwise
+        // fails only at Worker upload, after KV/D1 provisioning has already run.
+        await preflightCloudflareAnalyticsEngine({
+            accountId: credentials.accountId,
+            apiToken: credentials.apiToken,
+        });
+        // Tenant provisioning authorizes only registered projects. Register the
+        // plan scope before any Worker enters that authority, not after recordDeploy.
+        await ensureHostedProjectRegistration({
+            controlPlaneUrl,
+            userId,
+            accountId: controlPlanePlan.accountId,
+            projectId: controlPlanePlan.projectId,
+        });
+    }
     const hasCardBackends = workers.some((worker) => worker.capabilities.some((capability) => capability.kind === 'card-backend'));
     if (hasCardBackends && !dryRun) {
         const appConfig = await readHsxAppConfig(root);
         const environment = resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production';
         const authUrl = await resolveHubSpotAppAuthUrl(argv, root);
-        const hubspotAppId = requireHubSpotCardAppId(readOptionalHubSpotAppId(resolveFlag(argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID) ?? (await readPersistedHubSpotAppId(root, await resolveHubSpotProjectName(argv, root))), authUrl);
+        const hubspotAppId = requireHubSpotCardAppId(await resolveHubSpotAppIdForDeploy({
+            argv,
+            root,
+            ...(controlPlaneUrl ? { controlPlaneUrl } : {}),
+            userId,
+            accountId: controlPlanePlan.accountId,
+            projectId: controlPlanePlan.projectId,
+            environment,
+        }), authUrl);
         const stored = controlPlaneUrl
             ? await readDeployHubSpotOAuthSecret({
                 controlPlaneUrl,
@@ -2729,8 +2818,9 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         ? {
             authority: createControlPlaneTenantProvisioningAuthority({
                 controlPlaneUrl,
-                authorizationHeaders: () => controlPlaneAuthHeaders(userId),
+                authorizationHeaders: () => controlPlaneAuthHeaders(userId, undefined, controlPlanePlan.accountId),
                 http: hostedHttp,
+                validateCompleteResources: (resources) => validateTenantDataPlaneResourcesForActiveAccount(argv, root, resources),
             }),
         }
         : {});
@@ -2952,7 +3042,13 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowC
             `${resolvedHubSpotClientSecret ? '' : ' — no client secret; card verification will fail closed'}\n`);
     }
     const hubSpotScopesForRuntime = await readHsxAppScopesForDeploy(root);
-    const billingRuntimeToken = controlPlaneUrl && appConfig.billing && !dryRun
+    // The same scoped runtime bearer authenticates both hosted billing and the
+    // redacted install-lifecycle telemetry emitted by linked OAuth Workers.
+    // Provision it whenever either consumer is present. Gating this solely on
+    // `appConfig.billing` leaves ordinary OAuth apps with generated telemetry
+    // code but no HSX_RUNTIME_TOKEN binding, making every emit a silent no-op.
+    const needsRuntimeControlPlaneToken = appConfig.billing !== undefined || appConfig.auth === 'oauth';
+    const billingRuntimeToken = controlPlaneUrl && needsRuntimeControlPlaneToken && !dryRun
         ? await requestDeployBillingRuntimeToken({
             controlPlaneUrl,
             userId,
@@ -3246,9 +3342,15 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
             hubSpotAppId: input.hubSpotAppId,
         },
         kind: 'install-kv',
+        legacyResourceNameExists: (resourceName) => cloudflareResourceNameExists({
+            argv: input.argv,
+            root: input.root,
+            kind: 'install-kv',
+            resourceName,
+        }),
         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.
+            // state, after long-name recovery ambiguity has already been ruled out.
             const tokenKeySecretValue = randomBytes(32).toString('base64url');
             const tokenKeyCustody = await escrowTokenKey({
                 adapter: defaultTokenKeyCustodyAdapter(),
@@ -3273,8 +3375,24 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
             ], {
                 cwd: input.root,
                 env: cloudflareDeployEnv(input.argv),
+            }).catch((error) => {
+                if (!/already exists/i.test(String(error)))
+                    throw error;
+                return undefined;
             });
-            const resourceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
+            let resourceId = namespaceOutput
+                ? extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`)
+                : undefined;
+            if (!namespaceOutput) {
+                const listed = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'], { cwd: input.root, env: cloudflareDeployEnv(input.argv) });
+                try {
+                    const namespaces = parseWranglerJsonArray(listed.stdout);
+                    resourceId = namespaces.find((namespace) => namespace.title === installKvNamespaceName)?.id;
+                }
+                catch {
+                    resourceId = undefined;
+                }
+            }
             if (!resourceId) {
                 throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
             }
@@ -3308,23 +3426,38 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
     };
 }
 async function ensureDeployInstallRuntimeBinding(input) {
+    const preserved = await recoverCompletedLinkInstallRuntimeBinding(input);
+    if (preserved)
+        return preserved;
     const existing = await readDeployInstallRuntimeBinding(input);
     if (existing) {
-        // Control-plane metadata carries no key custody (and never key bytes) —
-        // on a machine that never generated the key this is worker-secret-only.
-        return {
-            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 }
-                : {}),
-        };
+        const credentials = resolveCloudflareCredentials(input.argv);
+        if (!credentials.accountId || !credentials.apiToken) {
+            throw new Error('Could not validate the stored install KV without Cloudflare credentials.');
+        }
+        const valid = await validateCloudflareResourceForDeploy({
+            argv: input.argv,
+            root: input.root,
+            kind: 'install-kv',
+            resourceId: existing.installKvNamespaceId,
+        });
+        if (valid) {
+            // Control-plane metadata carries no key custody (and never key bytes) —
+            // on a machine that never generated the key this is worker-secret-only.
+            return {
+                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;
@@ -3337,9 +3470,15 @@ async function ensureDeployInstallRuntimeBinding(input) {
             hubSpotAppId: input.hubSpotAppId,
         },
         kind: 'install-kv',
+        legacyResourceNameExists: (resourceName) => cloudflareResourceNameExists({
+            argv: input.argv,
+            root: input.root,
+            kind: 'install-kv',
+            resourceName,
+        }),
         async provisionByName(installKvNamespaceName) {
-            // ADR-022: escrow precedes Cloudflare mutation, while the ambiguity
-            // guard precedes both. The control plane never receives key bytes.
+            // ADR-022: escrow precedes Cloudflare mutation, while the legacy-name
+            // ambiguity guard precedes both. The control plane never receives key bytes.
             const tokenKeySecretValue = randomBytes(32).toString('base64url');
             const tokenKeyCustody = await escrowTokenKey({
                 adapter: defaultTokenKeyCustodyAdapter(),
@@ -3364,8 +3503,24 @@ async function ensureDeployInstallRuntimeBinding(input) {
             ], {
                 cwd: input.root,
                 env: cloudflareDeployEnv(input.argv),
+            }).catch((error) => {
+                if (!/already exists/i.test(String(error)))
+                    throw error;
+                return undefined;
             });
-            const resourceId = extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`);
+            let resourceId = namespaceOutput
+                ? extractKvNamespaceId(`${namespaceOutput.stdout}\n${namespaceOutput.stderr}`)
+                : undefined;
+            if (!namespaceOutput) {
+                const listed = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'], { cwd: input.root, env: cloudflareDeployEnv(input.argv) });
+                try {
+                    const namespaces = parseWranglerJsonArray(listed.stdout);
+                    resourceId = namespaces.find((namespace) => namespace.title === installKvNamespaceName)?.id;
+                }
+                catch {
+                    resourceId = undefined;
+                }
+            }
             if (!resourceId) {
                 throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
             }
@@ -3393,10 +3548,106 @@ async function ensureDeployInstallRuntimeBinding(input) {
         tokenKeyCustody,
     };
 }
+/**
+ * A completed ADR-022 link journal is the authoritative preserve-set for the
+ * first linked redeploy. Rehydrate its exact INSTALL_KV and re-keyed token-key
+ * custody before consulting account-scoped control-plane metadata, which may
+ * not have been backfilled yet. This prevents link from silently provisioning
+ * a replacement namespace or key.
+ */
+async function recoverCompletedLinkInstallRuntimeBinding(input) {
+    const pointer = await loadCloudflarePointer(input.root);
+    if (!pointer || !pointer.ownerId.startsWith('acct_'))
+        return undefined;
+    const journal = await loadLinkMigrationJournal(linkMigrationJournalId({
+        cloudflareAccountId: pointer.cloudflareAccountId,
+        stateKvNamespaceId: pointer.stateKvNamespaceId,
+        newOwnerId: pointer.ownerId,
+    }));
+    if (!journal || journal.status !== 'done')
+        return undefined;
+    const binding = journal.bindings.find((candidate) => candidate.projectId === input.projectId &&
+        candidate.environment === input.environment &&
+        candidate.hubSpotAppId === input.hubSpotAppId);
+    if (!binding)
+        return undefined;
+    if (input.dryRun) {
+        return {
+            installKvNamespaceId: binding.installKvNamespaceId,
+            installKvNamespaceName: binding.installKvNamespaceName,
+            tokenKeySecretName: binding.tokenKeySecretName,
+        };
+    }
+    const valid = await validateCloudflareResourceForDeploy({
+        argv: input.argv,
+        root: input.root,
+        kind: 'install-kv',
+        resourceId: binding.installKvNamespaceId,
+    });
+    if (!valid) {
+        throw new Error(`The completed link journal's preserved install KV ${binding.installKvNamespaceId} is no longer present in the connected Cloudflare account.`);
+    }
+    const custodyMechanism = Schema.decodeUnknownSync(schemas.TokenKeyCustodyMechanism)(binding.custodyMechanism);
+    const adapter = tokenKeyCustodyAdapterFor(custodyMechanism);
+    const tokenKeySecretValue = await adapter.retrieve(binding.newCustodyId);
+    if (!tokenKeySecretValue) {
+        throw new Error(`The completed link journal's re-keyed token custody ${binding.newCustodyId} is unavailable.`);
+    }
+    const tokenKeyCustody = Schema.decodeUnknownSync(schemas.EscrowedTokenKeyCustody)({
+        kind: 'escrowed',
+        mechanism: custodyMechanism,
+        custodyId: binding.newCustodyId,
+        escrowedAt: journal.updatedAt,
+        canary: await sealTokenKeyCanary(tokenKeySecretValue),
+    });
+    await putDeployInstallRuntimeBinding({
+        ...input,
+        installKvNamespaceId: binding.installKvNamespaceId,
+        installKvNamespaceName: binding.installKvNamespaceName,
+        tokenKeySecretName: binding.tokenKeySecretName,
+    });
+    const { pointer: currentPointer, stateStore } = await ensureTenantStateStore({
+        argv: input.argv,
+        root: input.root,
+    });
+    const existing = await stateStore.getBinding({
+        projectId: input.projectId,
+        environment: input.environment,
+        hubSpotAppId: input.hubSpotAppId,
+    });
+    await stateStore.putBinding(Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)({
+        ...(existing ?? {}),
+        schemaVersion: 2,
+        ownerId: currentPointer.ownerId,
+        projectId: input.projectId,
+        environment: input.environment,
+        hubSpotAppId: input.hubSpotAppId,
+        installKvNamespaceId: binding.installKvNamespaceId,
+        installKvNamespaceName: binding.installKvNamespaceName,
+        tokenKeySecretName: binding.tokenKeySecretName,
+        tokenKeyCustody,
+        updatedAt: new Date().toISOString(),
+    }));
+    return {
+        installKvNamespaceId: binding.installKvNamespaceId,
+        installKvNamespaceName: binding.installKvNamespaceName,
+        tokenKeySecretName: binding.tokenKeySecretName,
+        tokenKeySecretValue,
+        tokenKeyCustody,
+        ...(existing?.tenantD1DatabaseId ? { tenantD1DatabaseId: existing.tenantD1DatabaseId } : {}),
+        ...(existing?.tenantD1DatabaseName
+            ? { tenantD1DatabaseName: existing.tenantD1DatabaseName }
+            : {}),
+        ...(existing?.flagsKvNamespaceId ? { flagsKvNamespaceId: existing.flagsKvNamespaceId } : {}),
+        ...(existing?.flagsKvNamespaceName
+            ? { flagsKvNamespaceName: existing.flagsKvNamespaceName }
+            : {}),
+    };
+}
 async function readDeployInstallRuntimeBinding(input) {
     const response = await hostedHttp({
         url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/hubspot-apps/${encodeURIComponent(input.hubSpotAppId)}/install-runtime?environment=${encodeURIComponent(input.environment)}`, input.controlPlaneUrl),
-        headers: await controlPlaneAuthHeaders(input.userId),
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
     });
     if (response.status === 404) {
         return undefined;
@@ -3414,7 +3665,7 @@ async function putDeployInstallRuntimeBinding(input) {
     const response = await hostedHttp({
         url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/hubspot-apps/${encodeURIComponent(input.hubSpotAppId)}/install-runtime`, input.controlPlaneUrl),
         method: 'PUT',
-        headers: await controlPlaneAuthHeaders(input.userId),
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
         body: {
             environment: input.environment,
             installKvNamespaceId: input.installKvNamespaceId,
@@ -3436,11 +3687,30 @@ async function putDeployInstallRuntimeBinding(input) {
         throw new Error(`Could not store scoped install runtime binding: ${message}`);
     }
 }
+async function ensureHostedProjectRegistration(input) {
+    const response = await hostedHttp({
+        url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects`, input.controlPlaneUrl),
+        method: 'POST',
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
+        body: { projectId: input.projectId, displayName: input.projectId },
+    });
+    if (response.ok || response.status === 409)
+        return;
+    // The in-process legacy control-plane test adapter predates the extracted
+    // project router. Production exposes this route; tolerate only absence.
+    if (response.status === 404 || response.status === 405)
+        return;
+    const body = await response.json().catch(() => undefined);
+    const message = isRecord(body) && typeof body.message === 'string'
+        ? body.message
+        : `Control plane returned ${response.status}.`;
+    throw new Error(`Could not register project before tenant provisioning: ${message}`);
+}
 async function requestDeployBillingRuntimeToken(input) {
     const response = await hostedHttp({
         url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/billing/runtime-token`, input.controlPlaneUrl),
         method: 'POST',
-        headers: await controlPlaneAuthHeaders(input.userId),
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
         body: {
             environment: input.environment,
         },
@@ -3499,6 +3769,10 @@ async function ensureTenantDataPlane(input) {
         hubSpotAppId: input.hubSpotAppId,
     });
     const env = cloudflareDeployEnv(input.argv);
+    const cloudflareCredentials = resolveCloudflareCredentials(input.argv);
+    if (!cloudflareCredentials.accountId || !cloudflareCredentials.apiToken) {
+        throw new Error('Tenant data-plane provisioning requires Cloudflare credentials.');
+    }
     // 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.
@@ -3509,6 +3783,24 @@ async function ensureTenantDataPlane(input) {
         kind: 'tenant-d1',
         ...(exactTenantD1DatabaseId ? { exactResourceId: exactTenantD1DatabaseId } : {}),
         ...(exactTenantD1DatabaseName ? { exactResourceName: exactTenantD1DatabaseName } : {}),
+        legacyResourceNameExists: (resourceName) => cloudflareResourceNameExists({
+            argv: input.argv,
+            root: input.root,
+            kind: 'tenant-d1',
+            resourceName,
+        }),
+        validateExactResource: (resourceId) => {
+            const credentials = resolveCloudflareCredentials(input.argv);
+            if (!credentials.accountId || !credentials.apiToken) {
+                throw new Error('Could not validate the stored tenant D1 without Cloudflare credentials.');
+            }
+            return validateCloudflareResourceForDeploy({
+                argv: input.argv,
+                root: input.root,
+                kind: 'tenant-d1',
+                resourceId,
+            });
+        },
         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)))
@@ -3538,6 +3830,24 @@ async function ensureTenantDataPlane(input) {
         kind: 'flags-kv',
         ...(exactFlagsKvNamespaceId ? { exactResourceId: exactFlagsKvNamespaceId } : {}),
         ...(exactFlagsKvNamespaceName ? { exactResourceName: exactFlagsKvNamespaceName } : {}),
+        legacyResourceNameExists: (resourceName) => cloudflareResourceNameExists({
+            argv: input.argv,
+            root: input.root,
+            kind: 'flags-kv',
+            resourceName,
+        }),
+        validateExactResource: (resourceId) => {
+            const credentials = resolveCloudflareCredentials(input.argv);
+            if (!credentials.accountId || !credentials.apiToken) {
+                throw new Error('Could not validate the stored flags KV without Cloudflare credentials.');
+            }
+            return validateCloudflareResourceForDeploy({
+                argv: input.argv,
+                root: input.root,
+                kind: 'flags-kv',
+                resourceId,
+            });
+        },
         async provisionByName(flagsKvNamespaceName) {
             const created = await runCloudflareCommand([
                 'bun',
@@ -3560,7 +3870,7 @@ async function ensureTenantDataPlane(input) {
             if (!created) {
                 const listed = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'], { cwd: input.root, env });
                 try {
-                    const namespaces = JSON.parse(listed.stdout);
+                    const namespaces = parseWranglerJsonArray(listed.stdout);
                     resourceId = namespaces.find((namespace) => namespace.title === flagsKvNamespaceName)?.id;
                 }
                 catch {
@@ -3607,6 +3917,7 @@ async function ensureTenantDataPlane(input) {
         updatedAt: new Date().toISOString(),
     }));
     return {
+        cloudflareAccountId: cloudflareCredentials.accountId,
         tenantD1DatabaseId,
         tenantD1DatabaseName,
         flagsKvNamespaceId,
@@ -3615,6 +3926,78 @@ async function ensureTenantDataPlane(input) {
         syncGrantSecretValue,
     };
 }
+async function validateTenantDataPlaneResourcesForActiveAccount(argv, root, resources) {
+    const credentials = resolveCloudflareCredentials(argv);
+    if (!credentials.accountId || !credentials.apiToken) {
+        throw new Error('Could not validate tenant resources without Cloudflare credentials.');
+    }
+    if (resources.cloudflareAccountId && resources.cloudflareAccountId !== credentials.accountId) {
+        return false;
+    }
+    const [tenantD1Valid, flagsKvValid] = await Promise.all([
+        validateCloudflareResourceForDeploy({
+            argv,
+            root,
+            kind: 'tenant-d1',
+            resourceId: resources.tenantD1DatabaseId,
+        }),
+        validateCloudflareResourceForDeploy({
+            argv,
+            root,
+            kind: 'flags-kv',
+            resourceId: resources.flagsKvNamespaceId,
+        }),
+    ]);
+    return tenantD1Valid && flagsKvValid;
+}
+async function validateCloudflareResourceForDeploy(input) {
+    const credentials = resolveCloudflareCredentials(input.argv);
+    if (!credentials.accountId || !credentials.apiToken) {
+        throw new Error('Could not validate Cloudflare resources without connected credentials.');
+    }
+    try {
+        return await validateCloudflareResourceForAccount({
+            accountId: credentials.accountId,
+            apiToken: credentials.apiToken,
+            kind: input.kind,
+            resourceId: input.resourceId,
+        });
+    }
+    catch (error) {
+        if (!/\((?:401|403)\)/.test(String(error)))
+            throw error;
+    }
+    const command = input.kind === 'tenant-d1'
+        ? ['bun', 'x', 'wrangler', 'd1', 'list', '--json']
+        : ['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'];
+    const listed = await runCloudflareCommand(command, {
+        cwd: input.root,
+        env: cloudflareDeployEnv(input.argv),
+    });
+    try {
+        const rows = parseWranglerJsonArray(listed.stdout);
+        return rows.some((row) => row.id === input.resourceId || row.uuid === input.resourceId);
+    }
+    catch {
+        throw new Error(`HSX_E_CLOUDFLARE_RESOURCE_VALIDATION_FAILED: Wrangler returned malformed ${input.kind} list output.`);
+    }
+}
+async function cloudflareResourceNameExists(input) {
+    const command = input.kind === 'tenant-d1'
+        ? ['bun', 'x', 'wrangler', 'd1', 'list', '--json']
+        : ['bun', 'x', 'wrangler', 'kv', 'namespace', 'list'];
+    const listed = await runCloudflareCommand(command, {
+        cwd: input.root,
+        env: cloudflareDeployEnv(input.argv),
+    });
+    try {
+        const rows = parseWranglerJsonArray(listed.stdout);
+        return rows.some((row) => row.name === input.resourceName || row.title === input.resourceName);
+    }
+    catch {
+        throw new Error(`HSX_E_CLOUDFLARE_RESOURCE_VALIDATION_FAILED: Wrangler returned malformed ${input.kind} list output.`);
+    }
+}
 export function renderWranglerConfig(input) {
     const lines = [
         '# Generated by hs-x. Do not edit by hand.',
@@ -3688,7 +4071,7 @@ function tomlString(value) {
 async function readDeployHubSpotOAuthSecret(input) {
     const response = await hostedHttp({
         url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/hubspot-apps/${encodeURIComponent(input.hubSpotAppId)}/oauth-secret?environment=${encodeURIComponent(input.environment)}`, input.controlPlaneUrl),
-        headers: await controlPlaneAuthHeaders(input.userId),
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
     });
     if (response.status === 404) {
         return undefined;
@@ -4279,7 +4662,14 @@ function runCloudflareCommand(command, options) {
                 resolvePromise({ stdout, stderr });
             }
             else {
-                rejectPromise(new Error(`Cloudflare deploy failed with exit code ${code ?? 'unknown'}.\n${stderr || stdout}`));
+                rejectPromise(classifyCloudflareCommandFailure({
+                    ...(options.env.CLOUDFLARE_ACCOUNT_ID
+                        ? { accountId: options.env.CLOUDFLARE_ACCOUNT_ID }
+                        : {}),
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                }));
             }
         });
     })).pipe(Effect.withSpan('cli.deploy.cloudflare_command', {
@@ -4677,6 +5067,45 @@ async function readPersistedHubSpotAppBinding(root, expectedProjectName) {
 async function readPersistedHubSpotAppId(root, expectedProjectName) {
     return (await readPersistedHubSpotAppBinding(root, expectedProjectName))?.appId;
 }
+/**
+ * Resolve the one HubSpot app a linked project already registered. The common
+ * path remains implicit: a first combined deploy persists the app id, while a
+ * checkout missing that advisory file can recover an unambiguous binding from
+ * the control plane. Explicit ids remain the advanced override.
+ */
+async function resolveHubSpotAppIdForDeploy(input) {
+    const explicit = readOptionalHubSpotAppId(resolveFlag(input.argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID);
+    const projectName = await resolveHubSpotProjectName(input.argv, input.root);
+    const persisted = await readPersistedHubSpotAppId(input.root, projectName);
+    const selected = explicit ?? persisted;
+    if (selected || !input.controlPlaneUrl)
+        return selected;
+    const response = await hostedHttp({
+        url: new URL(`/v1/accounts/${encodeURIComponent(input.accountId)}/projects/${encodeURIComponent(input.projectId)}/runtime-bindings`, input.controlPlaneUrl),
+        headers: await controlPlaneAuthHeaders(input.userId, undefined, input.accountId),
+    });
+    if (!response.ok)
+        return undefined;
+    const body = await response.json();
+    const bindings = Schema.decodeUnknownSync(schemas.ListProjectRuntimeBindingsResponse)(body).bindings;
+    const appIds = [
+        ...new Set(bindings
+            .filter((binding) => binding.environment === input.environment)
+            .map((binding) => binding.hubSpotAppId)),
+    ];
+    if (appIds.length === 0)
+        return undefined;
+    if (appIds.length > 1) {
+        throw new Error(`Project ${input.projectId} has multiple HubSpot apps in ${input.environment} (${appIds.join(', ')}). Pass --hubspot-app-id once to choose one.`);
+    }
+    const appId = appIds[0];
+    await persistHubSpotAppBinding(input.root, {
+        appId,
+        projectName,
+        developerAccountId: undefined,
+    });
+    return appId;
+}
 async function resolveHubSpotAppAuthUrl(argv, root) {
     const projectName = await resolveHubSpotProjectName(argv, root);
     const persisted = await readPersistedHubSpotAppBinding(root, projectName);
@@ -4794,7 +5223,7 @@ async function requestHostedControlPlaneDeployPlan({ request, controlPlaneUrl, u
     const response = await hostedHttp({
         url: new URL('/v1/deploys/plan', controlPlaneUrl),
         method: 'POST',
-        headers: await controlPlaneAuthHeaders(userId),
+        headers: await controlPlaneAuthHeaders(userId, undefined, request.accountId),
         body: request,
     });
     const body = await response.json();
@@ -4805,7 +5234,7 @@ async function requestHostedControlPlaneDeployPlan({ request, controlPlaneUrl, u
     }
     return Schema.decodeUnknownSync(schemas.DeployPlanResponse)(body);
 }
-async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, plan, promoteWhenHealthy, revision, }) {
+async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, plan, promoteWhenHealthy, workerUrl, revision, }) {
     const localAttestationAuth = revision
         ? { grantSecret: randomBytes(32).toString('base64url'), hubSpotAppId: 1 }
         : undefined;
@@ -4848,6 +5277,7 @@ async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, pl
             manifestHash: plan.manifestHash,
             signedManifest: request.manifest,
             signature: `sig_${plan.deployId}`,
+            ...(workerUrl ? { workerUrl } : {}),
             // ADR-021 R03: the real Cloudflare Worker version identity captured
             // back from the confirmed active deployment. Absent only when capture
             // was skipped/failed (best-effort) — then this deploy is history-only.
@@ -4930,13 +5360,14 @@ async function requestHostedControlPlaneDeployRecordAndMaybePromote({ request, p
     const response = await hostedHttp({
         url: new URL(`/v1/deploys/${encodeURIComponent(plan.deployId)}/record`, controlPlaneUrl),
         method: 'POST',
-        headers: await controlPlaneAuthHeaders(userId),
+        headers: await controlPlaneAuthHeaders(userId, undefined, request.accountId),
         body: {
             accountId: request.accountId,
             projectId: request.projectId,
             manifestHash: plan.manifestHash,
             signedManifest: request.manifest,
             signature: `sig_${plan.deployId}`,
+            ...(workerUrl ? { workerUrl } : {}),
             // ADR-021 R03: the real Cloudflare Worker version identity captured back
             // from the confirmed active deployment. Absent only when capture was
             // skipped/failed (best-effort) — then this deploy is history-only.
@@ -4956,6 +5387,7 @@ async function requestHostedControlPlaneDeployRecordAndMaybePromote({ request, p
     }
     const drift = await waitForHealthyControlPlaneDrift({
         controlPlaneUrl,
+        accountId: request.accountId,
         projectId: request.projectId,
         deployId: plan.deployId,
         userId,
@@ -5258,7 +5690,7 @@ function discoverManageSchemaMode(definition) {
 }
 function discoverSourceDefinitions(source) {
     const definitions = new Map();
-    for (const match of source.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*defineSource(\.push)?\s*\(\s*\{([\s\S]*?)\}\s*\)/g)) {
+    for (const match of source.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*defineSource(\.push)?\s*(?:<[\s\S]*?>)?\s*\(\s*\{([\s\S]*?)\}\s*\)/g)) {
         const variableName = match[1];
         const body = match[3] ?? '';
         if (!variableName) {
@@ -5382,6 +5814,9 @@ const deployOptions = {
     message: Options.text('message').pipe(Options.withAlias('m'), Options.optional), // --message / -m
     platformVersion: Options.text('platform-version').pipe(Options.optional), // --platform-version
     hubspotProjectName: Options.text('hubspot-project-name').pipe(Options.optional), // --hubspot-project-name
+    cloudflareAccountId: Options.text('cloudflare-account-id').pipe(Options.optional), // --cloudflare-account-id
+    cloudflareApiToken: Options.text('cloudflare-api-token').pipe(Options.optional), // --cloudflare-api-token
+    apiToken: Options.text('api-token').pipe(Options.optional), // --api-token
     // ── boolean flags (argv.includes) ──
     plan: Options.boolean('plan').pipe(Options.withDefault(false)), // --plan
     dryRun: Options.boolean('dry-run').pipe(Options.withDefault(false)), // --dry-run
@@ -5448,6 +5883,9 @@ const deployBaseCmd = Command.make('deploy', deployOptions, (opts) => runHandler
     push('--message', opts.message);
     push('--platform-version', opts.platformVersion);
     push('--hubspot-project-name', opts.hubspotProjectName);
+    push('--cloudflare-account-id', opts.cloudflareAccountId);
+    push('--cloudflare-api-token', opts.cloudflareApiToken);
+    push('--api-token', opts.apiToken);
     flag('--plan', opts.plan);
     flag('--dry-run', opts.dryRun);
     flag('--build-only', opts.buildOnly);