@hs-x/cli 0.2.7 → 0.3.6

package/dist/commands/deploy.js

@@ -1,34 +1,38 @@
 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 { cloudflareResourceName, generateHubSpotRuntimeProject, generateProjectArtifacts, planPortalSchemaManagement, renderAlchemyProgram, renderCloudflareWorkerEntrypoint, } from '@hs-x/codegen';
-import { loadCreateControlPlane } from '../control-plane-loader.js';
-import { HttpClientRequest, Schema, schemas } from '@hs-x/types';
-import { validateProject } from '@hs-x/validator';
 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 { validateProject } from '@hs-x/validator';
 import { Effect, Option } from 'effect';
+import { isLinked } from '../account-store.js';
 import { exitWith } from '../cli-error.js';
-import { readProjectBinding, writeProjectBinding } from '../project-binding.js';
 import { accountIdOption, controlPlaneUrlOption, cwdOption, deployIdOption, forceOption, jsonOption, projectIdOption, runHandler, runQuarantined, userIdOption, yesOption, } from '../cli/kit.js';
-import { Cwd } from '../services/cwd.js';
-import { isLinked } from '../account-store.js';
 import { resolveCloudflareCredentials } from '../cloudflare-kv.js';
+import { loadCloudflarePointer } from '../cloudflare-pointer.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 { captureDeployRevision } from '../deploy-revision-capture.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 { cachePath } from '../paths.js';
-import { isInteractive, promptConfirm, promptMultiSelect, promptSelect, promptText, } from '../prompt.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 { ensureTenantStateStore, preflightTenantStateCredentials, } from '../tenant-state.js';
+import { defaultTokenKeyCustodyAdapter, escrowTokenKey, resolveEscrowedTokenKey, tokenKeyCustodyIdFor, } from '../token-key-custody.js';
 import { deployPromoteCommand, requestControlPlaneDeployPromotion } from './deploy-promote.js';
 async function hostedHttp(input) {
     const headers = { ...(input.headers ?? {}) };
@@ -41,17 +45,27 @@ async function hostedHttp(input) {
 }
 async function resolveAccountIdOrPrompt(input) {
     const binding = input.root ? await readProjectBinding(input.root) : undefined;
-    const fromFlag = resolveFlag(input.argv, '--account-id') ?? process.env.HSX_ACCOUNT_ID;
-    if (fromFlag && fromFlag.length > 0) {
-        return {
-            accountId: fromFlag,
-            fromPrompt: false,
-            ...(binding && binding.accountId !== fromFlag ? { overrodeBinding: binding.accountId } : {}),
-        };
-    }
     const { loadStore } = await import('../account-store.js');
     const store = await loadStore();
     const ids = Object.keys(store.accounts);
+    const explicitFlag = resolveFlag(input.argv, '--account-id');
+    const fromFlag = explicitFlag ?? process.env.HSX_ACCOUNT_ID;
+    if (fromFlag && fromFlag.length > 0) {
+        // An explicit --account-id is always honored (it errors clearly downstream
+        // if unknown — the user asked for it). A stale HSX_ACCOUNT_ID from the
+        // ambient env, however, must not override a valid binding with a phantom
+        // account: if it names no known account, ignore it and fall through to the
+        // binding/default rather than dead-ending at "Account not found".
+        if (explicitFlag !== undefined || ids.includes(fromFlag)) {
+            return {
+                accountId: fromFlag,
+                fromPrompt: false,
+                ...(binding && binding.accountId !== fromFlag
+                    ? { overrodeBinding: binding.accountId }
+                    : {}),
+            };
+        }
+    }
     // A recorded binding wins over the global default (you may work across
     // projects bound to different accounts). Fall through if it's gone stale.
     if (binding && ids.includes(binding.accountId)) {
@@ -60,14 +74,18 @@ async function resolveAccountIdOrPrompt(input) {
     if (ids.length === 0)
         return { fromPrompt: false };
     const defaultId = store.defaultAccountId;
-    // Non-interactive, --json, or --yes: accept the configured default rather than
-    // silently degrading to "no account picked" — that path led deploy to exit 0
-    // after building artifacts only, looking like success.
-    const yes = input.argv.includes('--yes') || input.argv.includes('-y');
-    if (input.json || !isInteractive() || yes) {
-        if (defaultId && ids.includes(defaultId)) {
-            return { accountId: defaultId, fromPrompt: false };
-        }
+    // A configured default — or a single account — is an answer, not a question:
+    // use it silently, exactly like non-interactive runs. `--account-id` and
+    // `hs-x accounts switch` override; the picker remains only for the genuinely
+    // ambiguous case (multiple accounts, no default).
+    if (defaultId && ids.includes(defaultId)) {
+        return { accountId: defaultId, fromPrompt: false };
+    }
+    const soleAccount = ids.length === 1 ? ids[0] : undefined;
+    if (soleAccount) {
+        return { accountId: soleAccount, fromPrompt: false };
+    }
+    if (input.json || !isInteractive()) {
         return { fromPrompt: false };
     }
     const picked = await promptSelect({
@@ -101,8 +119,14 @@ function missingAccountIdError(input) {
         }, null, 2)}\n`);
     }
     else {
-        const reporter = createReporter({ command: input.command, argv: input.argv });
-        reporter.error(code, message, { hint, docs_url: `https://hs-x.dev/errors/${code}` });
+        const reporter = createReporter({
+            command: input.command,
+            argv: input.argv,
+        });
+        reporter.error(code, message, {
+            hint,
+            docs_url: `https://hs-x.dev/errors/${code}`,
+        });
         reporter.done(undefined, 10);
     }
     return { exitCode: 10 };
@@ -117,35 +141,91 @@ async function promptMissingText(message, current, validate) {
     return answer === undefined ? undefined : answer;
 }
 /**
- * Unlinked OAuth installs need the HubSpot app's client id + client secret so
- * the deployed Worker's `/oauth-start` can complete the token exchange. Linked
- * deploys read these from the control plane; unlinked supplies them via
- * flag/env. When interactive, PROMPT for anything missing (only on the first
- * worker, to avoid contending for stdin across the concurrent worker deploys)
- * and persist answers to the environment so sibling workers reuse them — rather
- * than the human having to know to pre-set the env vars, then silently shipping
- * a Worker that 500s on /oauth-start (the run-006 papercut).
+ * Resolve the HubSpot credentials required by the runtime. OAuth installs need
+ * the client id + secret for `/oauth-start`; every card backend needs the
+ * client secret to verify HubSpot's v3 request signature, regardless of whether
+ * the app uses OAuth or static auth. When interactive, prompt for anything
+ * required and missing (only on the first worker, to avoid contending for stdin
+ * across concurrent worker deploys), then persist answers to the process env so
+ * sibling workers reuse them.
  *
- * We deliberately do NOT hard-fail on missing creds: the client secret is
- * grabbed from the app's Auth page, which only exists once the first deploy has
- * uploaded the app, so a bootstrap deploy legitimately has no secret yet. The
- * post-deploy output points the user at that Auth URL to finish and re-deploy.
+ * 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.
  */
-async function resolveUnlinkedOAuthCredentials(input) {
-    // Only an interactive, unlinked OAuth, non-dry-run deploy prompts: linked
-    // reads the secret from the control plane, non-OAuth apps need none, a dry run
-    // never deploys, and non-interactive runs must supply creds via flag/env.
-    if (input.auth !== 'oauth' || input.linked || input.dryRun || !input.allowPrompt) {
-        return { clientId: input.hubSpotClientId, clientSecret: input.hubSpotClientSecret };
-    }
-    const clientId = await promptMissingText('HubSpot app client id (HSX_HUBSPOT_CLIENT_ID)', input.hubSpotClientId);
-    const clientSecret = await promptMissingText('HubSpot app client secret — copy it from the app’s Auth tab (it is not exposed via API)', input.hubSpotClientSecret);
+/** @internal Exported for the deploy credential-gate regression suite. */
+export async function resolveHubSpotRuntimeCredentials(input) {
+    if (input.dryRun) {
+        return {
+            clientId: input.hubSpotClientId,
+            clientSecret: input.hubSpotClientSecret,
+        };
+    }
+    const clientId = input.auth === 'oauth' && input.allowPrompt
+        ? await promptMissingText('HubSpot app client id (HSX_HUBSPOT_CLIENT_ID)', input.hubSpotClientId)
+        : input.hubSpotClientId;
+    const clientSecret = (input.auth === 'oauth' || input.requiresCardSignatureSecret) && input.allowPrompt
+        ? (input.hubSpotClientSecret ??
+            (await promptPassword({
+                message: `HubSpot app client secret — copy it from the app’s Auth tab (HSX_HUBSPOT_CLIENT_SECRET)${input.authUrl ? `\n${input.authUrl}` : ''}`,
+            })))
+        : input.hubSpotClientSecret;
     if (clientId)
         process.env.HSX_HUBSPOT_CLIENT_ID = clientId;
     if (clientSecret)
         process.env.HSX_HUBSPOT_CLIENT_SECRET = clientSecret;
+    if (input.requiresCardSignatureSecret && !clientSecret) {
+        throw new Error(`A HubSpot client secret is required to deploy card backends: HubSpot v3 signatures cannot be verified without it. Copy the secret from the app Auth tab${input.authUrl ? ` (${input.authUrl})` : ''}, then redeploy with --hubspot-client-secret or HSX_HUBSPOT_CLIENT_SECRET (linked projects may store it with \`hs-x secrets hubspot-oauth set\`).`);
+    }
     return { clientId, clientSecret };
 }
+/** @internal Exported for the deploy credential-gate regression suite. */
+export function requireHubSpotCardAppId(hubSpotAppId, authUrl) {
+    if (hubSpotAppId)
+        return hubSpotAppId;
+    throw new Error(`A HubSpot app ID is required to deploy card backends. Upload the HubSpot project first so HubSpot can create the app, or pass --hubspot-app-id / HSX_HUBSPOT_APP_ID.${authUrl ? ` App credentials: ${authUrl}` : ''}`);
+}
+/**
+ * HubSpot cannot reveal an app secret after creation, but its token endpoint
+ * authenticates the client before rejecting a deliberately invalid auth code.
+ * Use that distinction to catch a copied secret from the wrong app before a
+ * Worker ships and turns every card request into a signature 401.
+ *
+ * No credential or response body is logged. `invalid_grant` (the expected
+ * dummy-code response) proves the client pair was accepted; `invalid_client`
+ * / BAD_CLIENT_* proves it was not.
+ *
+ * @internal Exported for the deploy credential-gate regression suite.
+ */
+export async function validateHubSpotClientCredentials(input) {
+    if (!input.clientId || !input.clientSecret)
+        return;
+    const request = input.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await request('https://api.hubapi.com/oauth/2026-03/token', {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'authorization_code',
+                client_id: input.clientId,
+                client_secret: input.clientSecret,
+                redirect_uri: 'https://hs-x.dev/hubspot-credential-preflight',
+                code: 'hsx-invalid-code-preflight',
+            }),
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not validate the HubSpot app credentials, so the card-backend deploy was stopped. Check your network and retry.${input.authUrl ? ` App credentials: ${input.authUrl}` : ''}`, { cause: error });
+    }
+    const body = (await response.json().catch(() => undefined));
+    const error = isRecord(body) && typeof body.error === 'string' ? body.error : undefined;
+    const status = isRecord(body) && typeof body.status === 'string' ? body.status : undefined;
+    if (error === 'invalid_client' || status === 'BAD_CLIENT_SECRET' || status === 'BAD_CLIENT_ID') {
+        throw new Error(`The stored HubSpot client ID and secret do not match this app. Copy the client secret from the app Auth tab and store it again before deploying.${input.authUrl ? ` ${input.authUrl}` : ''}`);
+    }
+}
 function missingProjectIdError(input) {
     const code = 'HSX_E_INPUT_MISSING_PROJECT_ID';
     const message = 'Missing --project-id.';
@@ -159,8 +239,14 @@ function missingProjectIdError(input) {
         }, null, 2)}\n`);
     }
     else {
-        const reporter = createReporter({ command: input.command, argv: input.argv });
-        reporter.error(code, message, { hint, docs_url: `https://hs-x.dev/errors/${code}` });
+        const reporter = createReporter({
+            command: input.command,
+            argv: input.argv,
+        });
+        reporter.error(code, message, {
+            hint,
+            docs_url: `https://hs-x.dev/errors/${code}`,
+        });
         reporter.done(undefined, 10);
     }
     return { exitCode: 10 };
@@ -180,7 +266,10 @@ function inputValidationError(input) {
         }, null, 2)}\n`);
     }
     else {
-        const reporter = createReporter({ command: input.command, argv: input.argv });
+        const reporter = createReporter({
+            command: input.command,
+            argv: input.argv,
+        });
         reporter.error(input.code, input.message, {
             hint: input.hint,
             docs_url: `https://hs-x.dev/errors/${input.code}`,
@@ -240,8 +329,9 @@ async function promptMissingCloudflareCredentials(input) {
     const reporter = createReporter({ command: 'deploy', argv: input.argv });
     if (!initial.apiToken) {
         const { CLOUDFLARE_TOKEN_TEMPLATE_URL, CloudflareAuthError, verifyCloudflareToken } = await import('../cloudflare-auth.js');
-        reporter.info('A Cloudflare API token is needed to deploy this Worker.');
-        reporter.info(`Create one (HS-X template): ${CLOUDFLARE_TOKEN_TEMPLATE_URL}`);
+        reporter.info('A Cloudflare credential is needed to deploy this Worker.');
+        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({
                 message: 'Paste your Cloudflare API token',
@@ -263,7 +353,10 @@ async function promptMissingCloudflareCredentials(input) {
             catch (error) {
                 if (error instanceof CloudflareAuthError) {
                     reporter.warn(error.code, error.message);
-                    const retry = await promptConfirm({ message: 'Try again?', default: true });
+                    const retry = await promptConfirm({
+                        message: 'Try again?',
+                        default: true,
+                    });
                     if (retry === undefined || !retry)
                         return false;
                     continue;
@@ -284,6 +377,72 @@ async function promptMissingCloudflareCredentials(input) {
     }
     return true;
 }
+/**
+ * Bridge `hs-x connect cloudflare` to `hs-x deploy`. `connect` stores an OAuth
+ * refresh token (`cloudflare-oauth.json`) keyed by Cloudflare account id, but
+ * the deploy credential resolvers only read env/flags — so a newcomer who ran
+ * the documented "easiest" path (`connect cloudflare`) and then `deploy` was
+ * told to paste an API token that `connect` itself says doesn't exist
+ * (cold-stranger run 2026-07-22-001, finding #1). When no API token is present
+ * but a stored OAuth connection exists for the account, mint a short-lived
+ * access token from it and export it to the env every downstream consumer reads
+ * (preflight, tenant-state KV, Alchemy, wrangler). Best-effort: on any failure
+ * (no connection, expired refresh token, OAuth not configured) we return false
+ * and fall through to the existing prompt / fail-fast preflight.
+ */
+async function hydrateCloudflareTokenFromStoredOAuth(input) {
+    if (resolveCloudflareCredentials(input.argv).apiToken)
+        return false;
+    const { getCloudflareOAuthCredential, listCloudflareOAuthAccountIds } = await import('../cloudflare-oauth-store.js');
+    let cloudflareAccountId = resolveCloudflareCredentials(input.argv).accountId ??
+        (await loadCloudflarePointer(input.root))?.cloudflareAccountId;
+    if (!cloudflareAccountId) {
+        // First deploy: no pointer and no env account id yet. If the user has
+        // connected exactly one Cloudflare account, that's unambiguously the one.
+        const connected = await listCloudflareOAuthAccountIds();
+        if (connected.length === 1)
+            cloudflareAccountId = connected[0];
+    }
+    if (!cloudflareAccountId)
+        return false;
+    const applyToken = (token) => {
+        process.env.CLOUDFLARE_API_TOKEN = token;
+        if (!resolveCloudflareCredentials(input.argv).accountId) {
+            process.env.CLOUDFLARE_ACCOUNT_ID = cloudflareAccountId;
+        }
+        return true;
+    };
+    try {
+        const credential = await getCloudflareOAuthCredential(cloudflareAccountId);
+        if (!credential)
+            return false;
+        // Cloudflare OAuth issues no refresh token, so the stored access token is
+        // normally the only credential. Use it directly while it's still valid
+        // (60s safety margin); a lapsed token falls through so the deploy's
+        // fail-fast points the user back at `hs-x connect cloudflare`.
+        if (credential.accessToken) {
+            const stillValid = !credential.accessTokenExpiresAt ||
+                new Date(credential.accessTokenExpiresAt).getTime() > Date.now() + 60_000;
+            if (stillValid)
+                return applyToken(credential.accessToken);
+        }
+        if (credential.refreshToken) {
+            const { loadCloudflareOAuthConfig, refreshTokens } = await import('../cloudflare-oauth.js');
+            const config = await loadCloudflareOAuthConfig({
+                controlPlaneUrl: resolveControlPlaneUrl(input.argv),
+            });
+            const tokens = await refreshTokens({
+                config,
+                refreshToken: credential.refreshToken,
+            });
+            return applyToken(tokens.accessToken);
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
 async function waitForHealthyControlPlaneDrift({ controlPlaneUrl, projectId, deployId, userId, timeoutMs, workerUrl, }) {
     const startedAt = Date.now();
     let lastState = 'unknown';
@@ -323,18 +482,95 @@ async function waitForHealthyControlPlaneDrift({ controlPlaneUrl, projectId, dep
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
+/** First line of an error message — the right size for a step-failure detail. */
+function firstErrorLine(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split('\n')[0] ?? message;
+}
+function elapsedSince(startedAt) {
+    const ms = Date.now() - startedAt;
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+function createDeployProgress(input) {
+    const reporter = createReporter({
+        command: 'deploy',
+        argv: input.argv,
+        startedAt: input.startedAt,
+    });
+    const tally = { ok: 0, warn: 0, fail: 0 };
+    return {
+        reporter,
+        step(label) {
+            const handle = reporter.step(label);
+            return {
+                ok: (detail) => {
+                    tally.ok += 1;
+                    handle.ok(detail);
+                },
+                fail: (detail) => {
+                    tally.fail += 1;
+                    handle.fail(detail);
+                },
+                warn: (detail) => {
+                    tally.warn += 1;
+                    handle.warn(detail);
+                },
+            };
+        },
+        counts: () => ({ ...tally }),
+    };
+}
+/** ADR-007 source summaries for the human transcript (`Sources: …`). */
+function workerSourceSummaries(workers) {
+    return workers.flatMap((worker) => worker.capabilities.flatMap((capability) => capability.kind === 'sync' && capability.source
+        ? [
+            `${capability.source.name} (${capability.source.kind}${capability.source.kind === 'push'
+                ? `, ${capability.source.webhookPath}`
+                : `, ${capability.schedule ?? 'manual'}`})`,
+        ]
+        : []));
+}
+/** Per-sync manageSchema modes for the human transcript. */
+function workerSyncSchemaModes(workers) {
+    return workers.flatMap((worker) => worker.capabilities.flatMap((capability) => capability.kind === 'sync' ? [`${capability.id}: ${capability.manageSchema ?? false}`] : []));
+}
 export async function deployCommand({ argv, root, json, }) {
     // Stamp the whole invocation up front: the human summary reporter is created
     // late (render time), so without this "Deployed … in 1ms" measured only the
     // summary step rather than the deploy itself.
     const commandStartedAt = Date.now();
     if (argv[1] === 'promote') {
-        return deployPromoteCommand({ argv, json });
+        return deployPromoteCommand({ argv, json, root });
+    }
+    if (!json && isInteractive()) {
+        try {
+            const selected = await resolveLocalProject({
+                root,
+                allowPrompt: true,
+                message: 'Which local project should be deployed?',
+                prompts: { select: promptSelect },
+            });
+            if (selected && selected.root !== root) {
+                return await deployCommand({ argv, root: selected.root, json });
+            }
+        }
+        catch (error) {
+            if (error instanceof LocalProjectPickerCancelled)
+                return cancelledResult(argv, 'deploy');
+            throw error;
+        }
     }
     // bun only auto-loads .env/.env.local from the CWD; when deploying from a
     // nested app dir, pull in a repo-root .env.local (CLOUDFLARE_ACCOUNT_ID, etc.)
     // so the deploy doesn't fail for vars that are set at the root.
     hydrateAncestorEnv(root);
+    // One shared streaming reporter for the whole run (human/plain/ndjson).
+    // `echo` additionally gates the inline info/warn stream to human/plain: the
+    // ndjson stream keeps emitting those lines from the final summary (its
+    // pre-existing event order), so wiring steps stays purely additive there.
+    const progress = json ? undefined : createDeployProgress({ argv, startedAt: commandStartedAt });
+    const echo = progress && progress.reporter.mode !== 'ndjson' ? progress.reporter : undefined;
+    progress?.reporter.header(basename(root));
     const planOnly = argv.includes('--plan') || argv.includes('--dry-run');
     const buildOnly = argv.includes('--build-only');
     const hubspotOnly = argv.includes('--hubspot-only');
@@ -365,11 +601,14 @@ export async function deployCommand({ argv, root, json, }) {
     });
     const accountId = resolvedAcct.accountId;
     if (accountId) {
+        // Normalize the ambient env to the RESOLVED account so downstream helpers
+        // that independently read `HSX_ACCOUNT_ID` (the HubSpot/Cloudflare credential
+        // leases, tenant-state writes) don't fall back to a stale/phantom value and
+        // 404. Mirrors how this command normalizes HSX_HUBSPOT_CLIENT_ID below.
+        process.env.HSX_ACCOUNT_ID = accountId;
         if (resolvedAcct.overrodeBinding) {
             // One-off --account-id override: warn but leave the recorded binding intact.
-            if (!json) {
-                createReporter({ command: 'deploy', argv }).warn('HSX_W_DEPLOY_ACCOUNT_OVERRIDE', `This project is bound to ${resolvedAcct.overrodeBinding}; deploying under ${accountId} for this run only (binding unchanged).`);
-            }
+            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.
@@ -378,17 +617,48 @@ export async function deployCommand({ argv, root, json, }) {
     }
     const explicitProjectId = resolveFlag(argv, '--project-id') ?? process.env.HSX_PROJECT_ID;
     let projectId = explicitProjectId;
+    const validateStep = progress?.step('Validating project');
     const validation = await validateProject({ root });
     const workers = await discoverWorkerManifests(root, { noManageSchema });
     const app = await readHsxAppConfig(root);
     const configHeartbeat = await readHsxConfigHeartbeat(root);
+    if (validateStep) {
+        const capCount = workers.reduce((count, worker) => count + worker.capabilities.length, 0);
+        if (validation.ok) {
+            validateStep.ok(`${workers.length} workers, ${capCount} capabilities`);
+        }
+        else {
+            validateStep.fail(`${validation.diagnostics.length} diagnostic${validation.diagnostics.length === 1 ? '' : 's'}`);
+        }
+    }
+    if (echo) {
+        for (const diagnostic of validation.diagnostics)
+            echo.info(formatDiagnostic(diagnostic));
+        const sources = workerSourceSummaries(workers);
+        if (sources.length > 0)
+            echo.info(`Sources: ${sources.join(', ')}`);
+        const syncSchemaModes = workerSyncSchemaModes(workers);
+        if (syncSchemaModes.length > 0) {
+            echo.info(`Portal schema management: ${syncSchemaModes.join(', ')}`);
+        }
+    }
     if (!projectId) {
         projectId = await readHsxConfigProjectId(root);
     }
     const needsRuntime = workers.some((worker) => worker.capabilities.some((capability) => capability.runtimeNeeds.some((need) => need !== 'hubspot-only')));
+    const needsHubSpotBundle = needsRuntime || app.mcpServers.length > 0;
     const cloudflareDeployRequested = !buildOnly &&
         (explicitCloudflareDeployRequested || (!planOnly && needsRuntime && !explicitHubspotUpload));
     const hubspotUploadRequested = !buildOnly && (explicitHubspotUpload || (!planOnly && !cloudflareDryRun && Boolean(projectId)));
+    if (echo) {
+        echo.info(`Runtime: ${needsRuntime ? 'Cloudflare Worker required' : 'HubSpot-only compatible'}`);
+        if (hubspotOnly && needsRuntime) {
+            echo.warn('HSX_W_DEPLOY_HUBSPOT_ONLY_INCOMPATIBLE', 'Cannot use --hubspot-only because at least one capability has a runtime handler.');
+        }
+        if (hubspotUploadRequested && !hubspotOnly && !cloudflareDeployRequested) {
+            echo.warn('HSX_W_DEPLOY_HUBSPOT_UPLOAD_WITHOUT_RUNTIME_DEPLOY', 'HubSpot upload requested without --cloudflare-deploy; runtime endpoints may still point at an older Worker.');
+        }
+    }
     // Hosted control-plane deploys record by default: shipping code without
     // recording the revision guarantees `unknown_code` drift on the next
     // attestation (the worker attests a deploy id the control plane has no
@@ -403,10 +673,38 @@ export async function deployCommand({ argv, root, json, }) {
             !cloudflareDryRun &&
             Boolean(controlPlaneUrl) &&
             (cloudflareDeployRequested || hubspotUploadRequested));
-    const portalSchemaRead = await readPortalSchema(argv, workers);
+    const portalSchemaRequested = Boolean(resolveFlag(argv, '--portal-schema-fixture')) ||
+        argv.includes('--portal-schema-live') ||
+        argv.includes('--local-hubspot-schema');
+    const portalSchemaStep = portalSchemaRequested
+        ? progress?.step('Reading portal schema')
+        : undefined;
+    let portalSchemaRead;
+    try {
+        portalSchemaRead = await readPortalSchema(argv, workers);
+    }
+    catch (error) {
+        portalSchemaStep?.fail(firstErrorLine(error));
+        throw error;
+    }
     const portalSchemaPlan = portalSchemaRead
-        ? planPortalSchemaManagement({ workers, observed: portalSchemaRead.observed })
+        ? planPortalSchemaManagement({
+            workers,
+            observed: portalSchemaRead.observed,
+        })
         : undefined;
+    if (portalSchemaStep) {
+        if (portalSchemaRead) {
+            const objectCount = portalSchemaRead.observed.objects.length;
+            portalSchemaStep.ok(`${objectCount} object type${objectCount === 1 ? '' : 's'} (${portalSchemaRead.source})`);
+        }
+        else {
+            portalSchemaStep.ok('skipped');
+        }
+    }
+    if (echo && portalSchemaPlan) {
+        echo.info(renderPortalSchemaPlan(portalSchemaPlan).trimEnd());
+    }
     const willChangeAnything = !planOnly &&
         (applySchema ||
             shouldRecordControlPlane ||
@@ -445,9 +743,7 @@ export async function deployCommand({ argv, root, json, }) {
             shouldRecordControlPlane,
             promoteWhenHealthy,
         });
-        const reporter = createReporter({ command: 'deploy', argv });
-        reporter.header(basename(root));
-        reporter.block(summary);
+        progress?.reporter.block(summary);
         const confirm = await promptConfirm({
             message: 'Apply this plan?',
             default: false,
@@ -456,12 +752,21 @@ export async function deployCommand({ argv, root, json, }) {
             return cancelledResult(argv, 'deploy');
         }
     }
+    // `--apply-schema` writes property definitions to the live portal, but
+    // `--plan`/`--dry-run` promise to change nothing. Honoring both would let a
+    // "dry run" mutate production (cold-stranger run 2026-07-22-001, finding #2):
+    // the confirm prompt above is already suppressed under `planOnly`, so without
+    // this guard the apply ran silently. Skip the apply and say so.
+    if (applySchema && planOnly && echo) {
+        echo.warn('HSX_W_DEPLOY_APPLY_SCHEMA_DRY_RUN', '--apply-schema ignored because --plan/--dry-run was passed; no portal changes were made.');
+    }
     // The schema apply is the first phase that touches the portal. A failure here
     // used to throw a raw HubSpot error out of the command — no HSX_E code, no
     // phase/PLAN output (cold-stranger run #3, finding A). Render the curated
     // failure WITH the plan that was being applied instead.
     let portalSchemaApply;
-    if (applySchema) {
+    if (applySchema && !planOnly) {
+        const applyStep = progress?.step('Applying portal schema');
         try {
             portalSchemaApply = await applyPortalSchemaPlan({
                 argv,
@@ -470,6 +775,7 @@ export async function deployCommand({ argv, root, json, }) {
             });
         }
         catch (error) {
+            applyStep?.fail(error instanceof PortalSchemaApplyError ? error.action : firstErrorLine(error));
             return portalSchemaApplyFailure({
                 argv,
                 json,
@@ -478,16 +784,29 @@ export async function deployCommand({ argv, root, json, }) {
                 workers,
                 portalSchemaPlan,
                 error,
+                ...(progress ? { progress } : {}),
             });
         }
+        applyStep?.ok(`${portalSchemaApply.applied.length} applied${portalSchemaApply.skipped.length > 0 ? `, ${portalSchemaApply.skipped.length} skipped` : ''}`);
+        if (echo)
+            echo.info(renderPortalSchemaApply(portalSchemaApply).trimEnd());
     }
-    const manifest = await generateProjectArtifacts({
-        root,
-        workers,
-        appObjects: app.appObjects,
-        appObjectAssociations: app.appObjectAssociations,
-        appEvents: app.appEvents,
-    });
+    const artifactsStep = progress?.step('Generating project artifacts');
+    let manifest;
+    try {
+        manifest = await generateProjectArtifacts({
+            root,
+            workers,
+            appObjects: app.appObjects,
+            appObjectAssociations: app.appObjectAssociations,
+            appEvents: app.appEvents,
+        });
+    }
+    catch (error) {
+        artifactsStep?.fail(firstErrorLine(error));
+        throw error;
+    }
+    artifactsStep?.ok('.hs-x/manifest.json + refs stubs');
     const shouldCreateControlPlaneRequest = !hubspotOnly && Boolean(accountId);
     let controlPlaneRequest;
     let resolvedProjectId = projectId;
@@ -511,6 +830,7 @@ export async function deployCommand({ argv, root, json, }) {
                 projectId: resolvedProjectId,
                 manifest,
                 ...(app.billing ? { billing: app.billing } : {}),
+                ...(app.alerts ? { alerts: app.alerts } : {}),
             });
         }
         catch (error) {
@@ -526,24 +846,53 @@ export async function deployCommand({ argv, root, json, }) {
             });
         }
     }
-    const controlPlanePlan = localControlPlane && controlPlaneRequest
-        ? await requestLocalControlPlaneDeployPlan(controlPlaneRequest)
-        : controlPlaneUrl && controlPlaneRequest
-            ? await requestHostedControlPlaneDeployPlan({
-                request: controlPlaneRequest,
-                controlPlaneUrl,
-                userId,
-            })
-            : !buildOnly && !hubspotOnly && projectId
-                ? createUnlinkedDeployPlan({
-                    projectId,
-                    machineId,
-                    manifest,
-                    workers,
-                })
-                : undefined;
+    if (echo && controlPlaneRequest) {
+        echo.info(`Control plane: ready to POST /v1/deploys/plan for ${controlPlaneRequest.projectId}`);
+    }
+    const controlPlanePlanStep = controlPlaneRequest && (localControlPlane || controlPlaneUrl)
+        ? progress?.step(localControlPlane
+            ? 'Planning deploy (local control plane)'
+            : 'Planning deploy (control plane)')
+        : undefined;
+    let controlPlanePlan;
+    try {
+        controlPlanePlan =
+            localControlPlane && controlPlaneRequest
+                ? await requestLocalControlPlaneDeployPlan(controlPlaneRequest)
+                : controlPlaneUrl && controlPlaneRequest
+                    ? await requestHostedControlPlaneDeployPlan({
+                        request: controlPlaneRequest,
+                        controlPlaneUrl,
+                        userId,
+                    })
+                    : !buildOnly && !hubspotOnly && projectId
+                        ? createUnlinkedDeployPlan({
+                            projectId,
+                            machineId,
+                            manifest,
+                            workers,
+                        })
+                        : undefined;
+    }
+    catch (error) {
+        controlPlanePlanStep?.fail(firstErrorLine(error));
+        throw error;
+    }
     const controlPlaneBackedPlan = Boolean(controlPlanePlan && controlPlaneRequest && (localControlPlane || controlPlaneUrl));
     const unlinkedDeployPlan = Boolean(controlPlanePlan && !controlPlaneBackedPlan);
+    if (controlPlanePlan) {
+        controlPlanePlanStep?.ok(controlPlanePlan.deployId);
+        if (echo) {
+            if (unlinkedDeployPlan)
+                echo.info(`Unlinked deploy id: ${controlPlanePlan.deployId}`);
+            if (controlPlanePlan.sharedCloudflareQuota) {
+                echo.info(`Shared Cloudflare quota: ${controlPlanePlan.sharedCloudflareQuota.visibleSiblingAccountIds.join(', ')}`);
+            }
+            if (controlPlanePlan.leases.length > 0) {
+                echo.info(`Cloudflare credential leases issued by the control plane: ${controlPlanePlan.leases.length}`);
+            }
+        }
+    }
     if (controlPlanePlan) {
         await writeFile(join(root, '.hs-x', 'alchemy.run.ts'), renderAlchemyProgram({
             hsXAccountId: controlPlanePlan.accountId,
@@ -552,6 +901,20 @@ export async function deployCommand({ argv, root, json, }) {
             workers,
         }));
     }
+    // Bridge a prior `hs-x connect cloudflare` to this deploy: if there's no API
+    // token in env/flags but a stored OAuth connection exists, mint a token from
+    // it now so BOTH the interactive prompt below and the non-interactive
+    // (`--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,
+        });
+        if (hydrated && echo) {
+            echo.info('Using the Cloudflare connection from `hs-x connect cloudflare`.');
+        }
+    }
     // Missing Cloudflare credentials on a real CF deploy: in a TTY, prompt for
     // the token (and account id) now — first deploy on a fresh machine is the
     // common case. Non-TTY / --json / --yes keep the fail-fast preflight error.
@@ -567,74 +930,243 @@ export async function deployCommand({ argv, root, json, }) {
         if (!proceed)
             return cancelledResult(argv, 'deploy');
     }
-    const cloudflareDeployResult = cloudflareDeployRequested && !planOnly && validation.ok && controlPlanePlan
-        ? await executeCloudflareDeploy({
+    // Upload-first (fixes the first-deploy chicken-and-egg): the HubSpot app id
+    // does not exist until the upload creates it, so a plain deploy binds no
+    // HSX_APP_ID and the install + card v3 verification fail until a manual
+    // second deploy. When this is that first deploy (no app id known yet) and the
+    // 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 uploadFirstOrigin = cloudflareDeployRequested &&
+        !cloudflareDryRun &&
+        !planOnly &&
+        hubspotUploadRequested &&
+        validation.ok &&
+        controlPlanePlan &&
+        needsRuntime &&
+        !hubspotOnly &&
+        !appIdKnownBeforeDeploy
+        ? await resolveUploadFirstRuntimeOrigin({ argv, root, controlPlanePlan })
+        : undefined;
+    let hubspotUploadResult;
+    // One step per HubSpot upload, wherever it runs in the ordering (upload-first
+    // vs deploy-then-upload). A FAILED build resolves the step as a failure so
+    // the failing phase is visible in the transcript, not just the exit code.
+    const runHubSpotUploadPhase = async () => {
+        const uploadStartedAt = Date.now();
+        const uploadStep = progress?.step('Uploading to HubSpot');
+        let result;
+        try {
+            result = await executeHubSpotOnlyUpload({
+                argv,
+                root,
+                local: localHubspotUpload,
+                uploadOnly: hubspotUploadOnly,
+            });
+        }
+        catch (error) {
+            uploadStep?.fail(firstErrorLine(error));
+            throw error;
+        }
+        const buildState = readStatus(result.buildStatus) ?? 'UNKNOWN';
+        const detail = `build #${result.buildId} ${buildState} (${elapsedSince(uploadStartedAt)})`;
+        if (buildState === 'SUCCESS') {
+            uploadStep?.ok(detail);
+        }
+        else {
+            uploadStep?.fail(detail);
+        }
+        if (echo)
+            streamHubSpotUploadOutcome(echo, result);
+        return result;
+    };
+    if (uploadFirstOrigin && controlPlanePlan) {
+        const bundleStep = progress?.step('Generating HubSpot bundle');
+        try {
+            await ensureHubSpotRuntimeProjectArtifacts({
+                argv,
+                root,
+                app,
+                workers,
+                cloudflareDeployResult: undefined,
+                needsRuntime,
+                runtimeOrigin: uploadFirstOrigin,
+                ...(controlPlanePlan ? { controlPlanePlan } : {}),
+            });
+        }
+        catch (error) {
+            bundleStep?.fail(firstErrorLine(error));
+            throw error;
+        }
+        bundleStep?.ok(uploadFirstOrigin);
+        hubspotUploadResult = await runHubSpotUploadPhase();
+    }
+    const willDeployCloudflare = cloudflareDeployRequested && !planOnly && validation.ok && Boolean(controlPlanePlan);
+    const cloudflareStep = willDeployCloudflare
+        ? progress?.step(cloudflareDryRun ? 'Deploying to Cloudflare (dry-run)' : 'Deploying to Cloudflare')
+        : undefined;
+    const cloudflareStartedAt = Date.now();
+    let cloudflareDeployResult;
+    try {
+        cloudflareDeployResult =
+            willDeployCloudflare && controlPlanePlan
+                ? await executeCloudflareDeploy({
+                    argv,
+                    root,
+                    workers,
+                    controlPlanePlan,
+                    userId,
+                    machineId,
+                    heartbeatEnabled: noHeartbeat
+                        ? false
+                        : controlPlaneBackedPlan
+                            ? configHeartbeat !== false
+                            : heartbeatFlag || configHeartbeat === true,
+                    ...(controlPlaneBackedPlan && controlPlaneUrl ? { controlPlaneUrl } : {}),
+                    dryRun: cloudflareDryRun,
+                    ...(progress ? { note: (line) => progress.reporter.rawErr(line) } : {}),
+                })
+                : undefined;
+    }
+    catch (error) {
+        cloudflareStep?.fail(firstErrorLine(error));
+        throw error;
+    }
+    if (cloudflareDeployResult && cloudflareStep) {
+        const firstUrl = cloudflareDeployResult.workers.find((worker) => worker.url)?.url;
+        const workerCount = cloudflareDeployResult.workers.length;
+        cloudflareStep.ok(`${workerCount} worker${workerCount === 1 ? '' : 's'}${firstUrl ? ` at ${firstUrl}` : ''} (${elapsedSince(cloudflareStartedAt)})`);
+    }
+    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).`);
+            }
+        }
+    }
+    // ADR-021 R03: after the Worker is live, read back Cloudflare's confirmed
+    // active deployment and capture the real version identity (verbatim id +
+    // binding fingerprint) to attach to the deploy record. This runs BEFORE the
+    // control-plane record below, so the control plane never stores a revision
+    // Cloudflare has not confirmed. Best-effort + pure read: a read-back failure
+    // records without a revision, and a retry re-reads the same active
+    // deployment, so it converges to the same version id with no duplicate.
+    const willCaptureRevision = shouldRecordControlPlane &&
+        Boolean(controlPlanePlan) &&
+        Boolean(cloudflareDeployResult) &&
+        !cloudflareDryRun;
+    const revisionStep = willCaptureRevision
+        ? progress?.step('Capturing Worker revision')
+        : undefined;
+    const capturedRevision = willCaptureRevision && controlPlanePlan
+        ? await captureDeployRevisionForDeploy({
             argv,
             root,
-            workers,
             controlPlanePlan,
-            userId,
-            machineId,
-            heartbeatEnabled: noHeartbeat
-                ? false
-                : controlPlaneBackedPlan
-                    ? configHeartbeat !== false
-                    : heartbeatFlag || configHeartbeat === true,
-            ...(controlPlaneBackedPlan && controlPlaneUrl ? { controlPlaneUrl } : {}),
-            dryRun: cloudflareDryRun,
+            json,
+            ...(progress ? { reporter: progress.reporter } : {}),
         })
         : undefined;
-    const localRecordResult = shouldRecordControlPlane && controlPlaneRequest && controlPlanePlan
-        ? localControlPlane
-            ? await requestLocalControlPlaneDeployRecordAndMaybePromote({
-                request: controlPlaneRequest,
-                plan: controlPlanePlan,
-                promoteWhenHealthy,
-            })
-            : controlPlaneUrl
-                ? await requestHostedControlPlaneDeployRecordAndMaybePromote({
-                    request: controlPlaneRequest,
-                    plan: controlPlanePlan,
-                    controlPlaneUrl,
-                    userId,
-                    promoteWhenHealthy,
-                    promotionTimeoutMs: Number(resolveFlag(argv, '--promotion-timeout-ms') ?? '60000'),
-                    ...(() => {
-                        const deployedWorkerUrl = cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
-                        return deployedWorkerUrl ? { workerUrl: deployedWorkerUrl } : {};
-                    })(),
-                })
-                : undefined
+    if (revisionStep) {
+        if (capturedRevision) {
+            revisionStep.ok(`version ${capturedRevision.versionId}`);
+        }
+        else {
+            revisionStep.warn('recorded without a rollback-capable revision');
+        }
+    }
+    const willRecordControlPlane = shouldRecordControlPlane &&
+        Boolean(controlPlaneRequest) &&
+        Boolean(controlPlanePlan) &&
+        (localControlPlane || Boolean(controlPlaneUrl));
+    const recordStep = willRecordControlPlane
+        ? progress?.step(promoteWhenHealthy ? 'Recording deploy + promoting when healthy' : 'Recording deploy')
         : undefined;
+    const recordStartedAt = Date.now();
+    let localRecordResult;
+    try {
+        localRecordResult =
+            shouldRecordControlPlane && controlPlaneRequest && controlPlanePlan
+                ? localControlPlane
+                    ? await requestLocalControlPlaneDeployRecordAndMaybePromote({
+                        request: controlPlaneRequest,
+                        plan: controlPlanePlan,
+                        promoteWhenHealthy,
+                        ...(capturedRevision ? { revision: capturedRevision } : {}),
+                    })
+                    : controlPlaneUrl
+                        ? await requestHostedControlPlaneDeployRecordAndMaybePromote({
+                            request: controlPlaneRequest,
+                            plan: controlPlanePlan,
+                            controlPlaneUrl,
+                            userId,
+                            promoteWhenHealthy,
+                            promotionTimeoutMs: Number(resolveFlag(argv, '--promotion-timeout-ms') ?? '60000'),
+                            ...(capturedRevision ? { revision: capturedRevision } : {}),
+                            ...(() => {
+                                const deployedWorkerUrl = cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
+                                return deployedWorkerUrl ? { workerUrl: deployedWorkerUrl } : {};
+                            })(),
+                        })
+                        : undefined
+                : undefined;
+    }
+    catch (error) {
+        recordStep?.fail(firstErrorLine(error));
+        throw error;
+    }
+    if (recordStep) {
+        if (localRecordResult) {
+            recordStep.ok(`${localRecordResult.record.status}${localRecordResult.promotion
+                ? ` · promoted ${localRecordResult.promotion.promoted.deployId}`
+                : ''} (${elapsedSince(recordStartedAt)})`);
+        }
+        else {
+            recordStep.warn('skipped');
+        }
+    }
     const controlPlaneRecord = localRecordResult?.record;
     const controlPlaneDrift = localRecordResult?.drift;
     const controlPlanePromotion = localRecordResult?.promotion;
-    if (hubspotUploadRequested && validation.ok) {
-        await ensureHubSpotRuntimeProjectArtifacts({
-            argv,
-            root,
-            app,
-            workers,
-            cloudflareDeployResult,
-            needsRuntime,
-            ...(controlPlanePlan ? { controlPlanePlan } : {}),
-        });
+    if (echo && controlPlaneRecord?.configDrift) {
+        const configDrift = controlPlaneRecord.configDrift;
+        echo.warn('HSX_W_DEPLOY_CONFIG_DRIFT', `Worker binding/config changed since the previously recorded deploy (${configDrift.previousDeployId}): fingerprint ${configDrift.previousFingerprint} -> ${configDrift.currentFingerprint}. This is expected if you intentionally changed bindings; investigate if you did not.`);
+    }
+    // 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 = needsHubSpotBundle ? progress?.step('Generating HubSpot bundle') : undefined;
+        try {
+            await ensureHubSpotRuntimeProjectArtifacts({
+                argv,
+                root,
+                app,
+                workers,
+                cloudflareDeployResult,
+                needsRuntime,
+                ...(controlPlanePlan ? { controlPlanePlan } : {}),
+            });
+        }
+        catch (error) {
+            bundleStep?.fail(firstErrorLine(error));
+            throw error;
+        }
+        bundleStep?.ok();
+    }
+    if (!uploadFirstOrigin) {
+        hubspotUploadResult =
+            hubspotUploadRequested &&
+                !planOnly &&
+                validation.ok &&
+                !(hubspotOnly && needsRuntime) &&
+                (!needsRuntime ||
+                    hubspotOnly ||
+                    cloudflareDeployRequested ||
+                    resolveFlag(argv, '--runtime-origin'))
+                ? await runHubSpotUploadPhase()
+                : undefined;
     }
-    const hubspotUploadResult = hubspotUploadRequested &&
-        !planOnly &&
-        validation.ok &&
-        !(hubspotOnly && needsRuntime) &&
-        (!needsRuntime ||
-            hubspotOnly ||
-            cloudflareDeployRequested ||
-            resolveFlag(argv, '--runtime-origin'))
-        ? await executeHubSpotOnlyUpload({
-            argv,
-            root,
-            local: localHubspotUpload,
-            uploadOnly: hubspotUploadOnly,
-        })
-        : undefined;
     // Everything that gates a healthy deploy *except* the HubSpot upload, so we
     // can tell a total failure apart from "the Cloudflare worker is live but the
     // HubSpot upload failed". The CF deploy runs first and stands on its own, so
@@ -697,10 +1229,10 @@ export async function deployCommand({ argv, root, json, }) {
     if (json) {
         write(`${JSON.stringify(plan, null, 2)}\n`);
     }
-    else {
+    else if (progress) {
         renderDeployHuman({
-            argv,
-            startedAt: commandStartedAt,
+            reporter: progress.reporter,
+            counts: progress.counts(),
             plan,
             root,
             planOnly,
@@ -816,7 +1348,10 @@ async function emitAnonymousDeployEvent(input) {
         await fetch(endpoint, {
             method: 'POST',
             signal: controller.signal,
-            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
             body: JSON.stringify({
                 schema_version: 1,
                 event: 'deploy.succeeded',
@@ -872,28 +1407,168 @@ async function recordTenantDeployState(input) {
         updatedAt: now,
     }));
 }
-function renderDeployHuman(input) {
-    const reporter = createReporter({
-        command: 'deploy',
-        argv: input.argv,
-        startedAt: input.startedAt,
-    });
-    const subject = basename(input.root);
-    reporter.header(subject);
-    const capCount = input.workers.reduce((c, w) => c + w.capabilities.length, 0);
-    reporter
-        .step('Validating project')
-        .ok(`${input.workers.length} workers, ${capCount} capabilities`);
-    const sources = input.workers.flatMap((worker) => worker.capabilities.flatMap((capability) => capability.kind === 'sync' && capability.source
-        ? [
-            `${capability.source.name} (${capability.source.kind}${capability.source.kind === 'push'
-                ? `, ${capability.source.webhookPath}`
-                : `, ${capability.schedule ?? 'manual'}`})`,
-        ]
-        : []));
+/**
+ * Final render for the streaming deploy transcript. The phases themselves were
+ * already narrated as steps while they ran; human/plain mode closes with a
+ * railed key/value fact summary + the done footer, while ndjson keeps emitting
+ * the full legacy info/warn event block (its consumers see the same events as
+ * before, with the step events purely additive).
+ */
+function renderDeployHuman(input) {
+    if (input.reporter.mode === 'ndjson') {
+        renderDeployNdjsonSummary(input);
+        return;
+    }
+    const reporter = input.reporter;
+    reporter.rows(buildDeploySummaryRows(input));
+    const firstWorkerUrl = input.cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
+    if (input.plan.partial) {
+        // The worker deployed; only the HubSpot upload failed. Say so loudly so the
+        // live worker isn't mistaken for a total failure despite the non-zero exit.
+        reporter.warn('HSX_W_DEPLOY_PARTIAL', `Cloudflare worker is live${firstWorkerUrl ? ` at ${firstWorkerUrl}` : ''}, but the HubSpot upload failed (see above). Exit code 20.`);
+    }
+    reporter.done(deployDoneMessage(input, firstWorkerUrl), input.plan.ok ? 0 : input.plan.partial ? 20 : 1, input.counts);
+}
+function deployDoneMessage(input, firstWorkerUrl) {
+    return input.planOnly
+        ? 'Planned'
+        : input.plan.partial
+            ? `Deployed to Cloudflare${firstWorkerUrl ? ` (${firstWorkerUrl})` : ''}; HubSpot upload failed`
+            : input.cloudflareDeployResult
+                ? input.linked
+                    ? `Deployed${firstWorkerUrl ? ` to ${firstWorkerUrl}` : ''}`
+                    : `Deployed (unlinked)${firstWorkerUrl ? ` to ${firstWorkerUrl}` : ''}; machine_id ${input.machineId}. Run \`hs-x link\` to claim this history.`
+                : input.hubspotUploadResult
+                    ? input.linked
+                        ? 'Deployed to HubSpot'
+                        : `Deployed (unlinked); machine_id ${input.machineId}. Run \`hs-x link\` to claim this history.`
+                    : 'Built artifacts';
+}
+/** The railed key/value facts of what this deploy produced (human/plain). */
+function buildDeploySummaryRows(input) {
+    const rows = [];
+    if (input.controlPlanePlan) {
+        rows.push({
+            key: 'deploy',
+            value: input.controlPlanePlan.deployId,
+            status: 'ok',
+            detail: input.unlinkedDeployPlan ? 'unlinked' : 'control plane',
+        });
+    }
+    for (const worker of input.cloudflareDeployResult?.workers ?? []) {
+        rows.push({
+            key: 'worker',
+            value: worker.workerName,
+            ...(worker.dryRun
+                ? { detail: 'dry-run' }
+                : {
+                    status: 'ok',
+                    ...(worker.url ? { detail: worker.url } : {}),
+                }),
+        });
+    }
+    if (input.controlPlaneRecord) {
+        rows.push({
+            key: 'record',
+            value: input.controlPlaneRecord.status,
+            status: 'ok',
+        });
+    }
+    if (input.controlPlanePromotion) {
+        rows.push({
+            key: 'promoted',
+            value: input.controlPlanePromotion.promoted.deployId,
+            status: 'ok',
+        });
+    }
+    if (input.hubspotUploadResult) {
+        const upload = input.hubspotUploadResult;
+        const buildState = readStatus(upload.buildStatus) ?? 'UNKNOWN';
+        rows.push({
+            key: 'hubspot build',
+            value: `#${upload.buildId} ${buildState}`,
+            status: buildState === 'SUCCESS' ? 'ok' : 'fail',
+        });
+        if (upload.deployId !== undefined) {
+            rows.push({
+                key: 'hubspot deploy',
+                value: `#${upload.deployId}`,
+                status: 'ok',
+            });
+        }
+        else if (buildState === 'SUCCESS' &&
+            upload.deploySkipped &&
+            upload.deployStatus !== undefined) {
+            const autoStatus = readStatus(upload.deployStatus) ?? 'UNKNOWN';
+            rows.push({
+                key: 'hubspot deploy',
+                value: `auto-deploy ${autoStatus}`,
+                status: autoStatus === 'SUCCESS' ? 'ok' : 'warn',
+                detail: `build #${upload.buildId}`,
+            });
+        }
+        else if (buildState === 'SUCCESS' && upload.deploySkipped) {
+            rows.push({
+                key: 'hubspot deploy',
+                value: 'skipped',
+                detail: 'upload-only or auto-deploy handles it',
+            });
+        }
+        const authUrl = hubSpotAppAuthUrl(upload);
+        if (!input.linked && authUrl) {
+            rows.push({
+                key: 'app auth',
+                value: authUrl,
+                hint: 'grab the client secret / configure install OAuth here',
+            });
+        }
+    }
+    if (!input.linked && input.cloudflareDeployResult) {
+        rows.push({ key: 'history', value: machineDashboardUrl(input.machineId) });
+    }
+    return rows;
+}
+/**
+ * Streamed right after the HubSpot upload step resolves (human/plain): the
+ * per-component build results and the auto-deploy verdict, so a failed build is
+ * diagnosable from the terminal, not the HubSpot UI (run-008 build #2 failed
+ * silently here).
+ */
+function streamHubSpotUploadOutcome(reporter, upload) {
+    for (const subbuild of readSubbuildStatuses(upload.buildStatus)) {
+        if (subbuild.status === 'SUCCESS') {
+            reporter.info(`  [ok] ${subbuild.name}${subbuild.type ? ` (${subbuild.type})` : ''}`);
+        }
+        else {
+            reporter.error('HSX_E_DEPLOY_HUBSPOT_BUILD_COMPONENT', `${subbuild.name}${subbuild.type ? ` (${subbuild.type})` : ''}: ${subbuild.errorMessage ?? subbuild.status}`);
+        }
+    }
+    const buildState = readStatus(upload.buildStatus) ?? 'UNKNOWN';
+    if (upload.deployId === undefined &&
+        buildState === 'SUCCESS' &&
+        upload.deploySkipped &&
+        upload.deployStatus !== undefined) {
+        const autoStatus = readStatus(upload.deployStatus) ?? 'UNKNOWN';
+        if (autoStatus !== 'SUCCESS') {
+            reporter.warn('HSX_W_DEPLOY_HUBSPOT_AUTODEPLOY_FAILED', `HubSpot auto-deploy finished ${autoStatus} — the build is green but the app did NOT ship. Check the deploy log in the HubSpot UI (project ${upload.projectName}).`);
+            for (const subbuild of readSubbuildStatuses(upload.deployStatus)) {
+                if (subbuild.status !== 'SUCCESS') {
+                    reporter.info(`  [x] ${subbuild.name}: ${subbuild.errorMessage ?? subbuild.status}`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Legacy single-shot summary for --json-stream: the same info/warn event block
+ * the pre-streaming renderer emitted (steps stream additively alongside it).
+ */
+function renderDeployNdjsonSummary(input) {
+    const reporter = input.reporter;
+    const sources = workerSourceSummaries(input.workers);
     if (sources.length > 0)
         reporter.info(`Sources: ${sources.join(', ')}`);
-    const syncSchemaModes = input.workers.flatMap((worker) => worker.capabilities.flatMap((capability) => capability.kind === 'sync' ? [`${capability.id}: ${capability.manageSchema ?? false}`] : []));
+    const syncSchemaModes = workerSyncSchemaModes(input.workers);
     if (syncSchemaModes.length > 0) {
         reporter.info(`Portal schema management: ${syncSchemaModes.join(', ')}`);
     }
@@ -934,6 +1609,10 @@ function renderDeployHuman(input) {
     }
     if (input.controlPlaneRecord) {
         reporter.info(`Local control plane record status: ${input.controlPlaneRecord.status}`);
+        const configDrift = input.controlPlaneRecord.configDrift;
+        if (configDrift) {
+            reporter.warn('HSX_W_DEPLOY_CONFIG_DRIFT', `Worker binding/config changed since the previously recorded deploy (${configDrift.previousDeployId}): fingerprint ${configDrift.previousFingerprint} -> ${configDrift.currentFingerprint}. This is expected if you intentionally changed bindings; investigate if you did not.`);
+        }
     }
     if (input.controlPlanePromotion) {
         reporter.info(`Promoted deploy: ${input.controlPlanePromotion.promoted.deployId}`);
@@ -977,7 +1656,7 @@ function renderDeployHuman(input) {
                 reporter.info(`HubSpot deploy: auto-deploy SUCCESS (build #${upload.buildId})`);
             }
             else {
-                reporter.warn('HSX_W_DEPLOY_HUBSPOT_AUTODEPLOY_FAILED', `HubSpot auto-deploy finished ${autoStatus} — the build is green but the app did NOT ship. Check the deploy log in the HubSpot UI (project ${upload.projectName}).`);
+                reporter.warn('HSX_W_DEPLOY_HUBSPOT_AUTODEPLOY_FAILED', `HubSpot auto-deploy finished ${autoStatus} — the build is green but the app did NOT ship (project ${upload.projectName}). Run \`hs-x logs --source hubspot\` for HubSpot's side of the story.`);
                 for (const subbuild of readSubbuildStatuses(upload.deployStatus)) {
                     if (subbuild.status !== 'SUCCESS') {
                         reporter.info(`  [x] ${subbuild.name}: ${subbuild.errorMessage ?? subbuild.status}`);
@@ -996,24 +1675,9 @@ function renderDeployHuman(input) {
     reporter.info('Generated .hs-x/manifest.json and refs stubs.');
     const firstWorkerUrl = input.cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
     if (input.plan.partial) {
-        // The worker deployed; only the HubSpot upload failed. Say so loudly so the
-        // live worker isn't mistaken for a total failure despite the non-zero exit.
         reporter.warn('HSX_W_DEPLOY_PARTIAL', `Cloudflare worker is live${firstWorkerUrl ? ` at ${firstWorkerUrl}` : ''}, but the HubSpot upload failed (see above). Exit code 20.`);
     }
-    const doneMessage = input.planOnly
-        ? 'Planned'
-        : input.plan.partial
-            ? `Deployed to Cloudflare${firstWorkerUrl ? ` (${firstWorkerUrl})` : ''}; HubSpot upload failed`
-            : input.cloudflareDeployResult
-                ? input.linked
-                    ? `Deployed${firstWorkerUrl ? ` to ${firstWorkerUrl}` : ''}`
-                    : `Deployed (unlinked)${firstWorkerUrl ? ` to ${firstWorkerUrl}` : ''}; machine_id ${input.machineId}. Run \`hs-x link\` to claim this history.`
-                : input.hubspotUploadResult
-                    ? input.linked
-                        ? 'Deployed to HubSpot'
-                        : `Deployed (unlinked); machine_id ${input.machineId}. Run \`hs-x link\` to claim this history.`
-                    : 'Built artifacts';
-    reporter.done(doneMessage, input.plan.ok ? 0 : input.plan.partial ? 20 : 1);
+    reporter.done(deployDoneMessage(input, firstWorkerUrl), input.plan.ok ? 0 : input.plan.partial ? 20 : 1);
 }
 function machineDashboardUrl(machineId) {
     const base = process.env.HSX_DASHBOARD_URL ?? 'https://app.hs-x.dev';
@@ -1026,10 +1690,17 @@ function machineDashboardUrl(machineId) {
  * returns undefined when either is unknown (e.g. a control-plane lease deploy).
  */
 function hubSpotAppAuthUrl(result) {
-    if (!result.developerAccountId || !result.appUid)
+    return buildHubSpotAppAuthUrl({
+        developerAccountId: result.developerAccountId,
+        projectName: result.projectName,
+        appUid: result.appUid,
+    });
+}
+function buildHubSpotAppAuthUrl(input) {
+    if (!input.developerAccountId || !input.appUid)
         return undefined;
     const base = process.env.HSX_HUBSPOT_APP_BASE_URL ?? 'https://app.hubspot.com';
-    return `${base.replace(/\/$/, '')}/developer-projects/${encodeURIComponent(result.developerAccountId)}/project/${encodeURIComponent(result.projectName)}/component/${encodeURIComponent(result.appUid)}/auth`;
+    return `${base.replace(/\/$/, '')}/developer-projects/${encodeURIComponent(input.developerAccountId)}/project/${encodeURIComponent(input.projectName)}/component/${encodeURIComponent(input.appUid)}/auth`;
 }
 function formatDiagnostic(d) {
     if (d && typeof d === 'object') {
@@ -1050,7 +1721,10 @@ async function readPortalSchema(argv, workers) {
         if (!isRecord(value) || !Array.isArray(value.objects)) {
             throw new Error('--portal-schema-fixture must point to JSON with an objects array.');
         }
-        return { observed: value, source: 'fixture' };
+        return {
+            observed: value,
+            source: 'fixture',
+        };
     }
     if (!live && !local) {
         return undefined;
@@ -1075,7 +1749,9 @@ async function readLivePortalSchema(argv, workers, options) {
     const objects = [];
     for (const objectType of targets) {
         try {
-            const properties = await client.schemaManagement.listProperties({ objectType });
+            const properties = await client.schemaManagement.listProperties({
+                objectType,
+            });
             objects.push({
                 name: objectType,
                 properties: properties.results.map(toObservedPortalProperty),
@@ -1143,7 +1819,12 @@ async function applyPortalSchemaPlan({ argv, plan, source, }) {
             await run();
         }
         catch (cause) {
-            throw new PortalSchemaApplyError({ action: label, objectType, applied: [...applied], cause });
+            throw new PortalSchemaApplyError({
+                action: label,
+                objectType,
+                applied: [...applied],
+                cause,
+            });
         }
         applied.push(label);
     };
@@ -1356,26 +2037,44 @@ function portalSchemaApplyFailure(input) {
         }, null, 2)}\n`);
         return { exitCode };
     }
-    const reporter = createReporter({ command: 'deploy', argv: input.argv, startedAt: input.startedAt });
-    reporter.header(basename(input.root));
-    const capCount = input.workers.reduce((count, worker) => count + worker.capabilities.length, 0);
-    reporter
-        .step('Validating project')
-        .ok(`${input.workers.length} workers, ${capCount} capabilities`);
-    if (input.portalSchemaPlan) {
+    const reporter = input.progress?.reporter ??
+        createReporter({
+            command: 'deploy',
+            argv: input.argv,
+            startedAt: input.startedAt,
+        });
+    if (!input.progress) {
+        // Standalone render (no streamed transcript preceded this failure):
+        // reconstruct the header + validation context around the error.
+        reporter.header(basename(input.root));
+        const capCount = input.workers.reduce((count, worker) => count + worker.capabilities.length, 0);
+        reporter
+            .step('Validating project')
+            .ok(`${input.workers.length} workers, ${capCount} capabilities`);
+        if (input.portalSchemaPlan) {
+            reporter.info(renderPortalSchemaPlan(input.portalSchemaPlan).trimEnd());
+        }
+    }
+    else if (reporter.mode === 'ndjson' && input.portalSchemaPlan) {
+        // The streamed transcript gates the plan info to human/plain; keep the
+        // ndjson event stream carrying it on the failure path.
         reporter.info(renderPortalSchemaPlan(input.portalSchemaPlan).trimEnd());
     }
     if (applyError && applyError.applied.length > 0) {
         for (const done of applyError.applied)
             reporter.info(`APPLIED  ${done}`);
     }
-    reporter.step('Applying portal schema').fail(applyError?.action);
+    // With a streamed transcript the caller already resolved the phase step with
+    // `.fail(...)`; only the standalone render reconstructs it here.
+    if (!input.progress) {
+        reporter.step('Applying portal schema').fail(applyError?.action);
+    }
     reporter.error(code, message, {
         hint,
         cause: hubSpotDetail,
         docs_url: `https://hs-x.dev/errors/${code}`,
     });
-    reporter.done(undefined, exitCode);
+    reporter.done(undefined, exitCode, input.progress?.counts());
     return { exitCode };
 }
 function renderPortalSchemaPlan(plan) {
@@ -1430,13 +2129,48 @@ function defaultHubSpotFieldType(type) {
             return 'text';
     }
 }
-async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan, controlPlaneUrl, userId, machineId, heartbeatEnabled, dryRun, }) {
+async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan, controlPlaneUrl, userId, machineId, 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.
     if (!controlPlaneUrl && !dryRun) {
         await preflightTenantStateCredentials({ argv, root });
     }
+    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 stored = controlPlaneUrl
+            ? await readDeployHubSpotOAuthSecret({
+                controlPlaneUrl,
+                userId,
+                accountId: controlPlanePlan.accountId,
+                projectId: controlPlanePlan.projectId,
+                environment,
+                hubSpotAppId: hubspotAppId,
+            })
+            : undefined;
+        const credentials = await resolveHubSpotRuntimeCredentials({
+            auth: appConfig.auth,
+            requiresCardSignatureSecret: true,
+            dryRun: false,
+            allowPrompt: !argv.includes('--json') && !argv.includes('--yes') && isInteractive(),
+            hubSpotClientId: resolveFlag(argv, '--hubspot-client-id') ??
+                stored?.clientId ??
+                process.env.HSX_HUBSPOT_CLIENT_ID,
+            hubSpotClientSecret: resolveFlag(argv, '--hubspot-client-secret') ??
+                stored?.clientSecret ??
+                process.env.HSX_HUBSPOT_CLIENT_SECRET,
+            ...(authUrl ? { authUrl } : {}),
+        });
+        await validateHubSpotClientCredentials({
+            clientId: credentials.clientId,
+            clientSecret: credentials.clientSecret,
+            ...(authUrl ? { authUrl } : {}),
+        });
+    }
     const sourcePaths = await discoverWorkerSourcePaths(root);
     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({
@@ -1444,6 +2178,7 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         root,
         worker,
         index,
+        allowCredentialPrompt: !hasCardBackends && index === 0,
         sourcePaths,
         controlPlanePlan,
         userId,
@@ -1451,13 +2186,18 @@ async function executeCloudflareDeploy({ argv, root, workers, controlPlanePlan,
         heartbeatEnabled,
         dryRun,
         ...(controlPlaneUrl ? { controlPlaneUrl } : {}),
+        ...(note ? { note } : {}),
     })), { concurrency }));
     return {
         deployId: controlPlanePlan.deployId,
         workers: results,
     };
 }
-async function executeCloudflareWorkerDeploy({ argv, root, worker, index, sourcePaths, controlPlanePlan, controlPlaneUrl, userId, machineId, heartbeatEnabled, dryRun, }) {
+async function executeCloudflareWorkerDeploy({ argv, root, worker, index, allowCredentialPrompt, sourcePaths, controlPlanePlan, controlPlaneUrl, userId, machineId, heartbeatEnabled, dryRun, note, }) {
+    const emitNote = note ??
+        ((line) => {
+            process.stderr.write(line);
+        });
     const workerSourcePath = sourcePaths.get(worker.name);
     if (!workerSourcePath) {
         throw new Error(`Could not find source file for worker ${worker.name}.`);
@@ -1468,12 +2208,24 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
     }
     const entrypointPath = join(root, '.hs-x', 'cloudflare', `${fileSlug(worker.name)}.entry.ts`);
     await mkdir(dirname(entrypointPath), { recursive: true });
+    // ADR-023 S04: translate this worker's declared sync schedules into a
+    // deduplicated Cloudflare cron-trigger plan. The same plan feeds both the
+    // wrangler `[triggers] crons` list and the generated `scheduled` handler's
+    // baked dispatch map, so the fired `event.cron` always matches a sync.
+    const cronPlan = planWorkerCronTriggers(worker);
     const appConfig = await readHsxAppConfig(root);
     const environment = resolveFlag(argv, '--env') ?? resolveFlag(argv, '--environment') ?? 'production';
     const deployCliConfig = loadCliConfig(argv);
     const runtimeControlPlaneUrl = formatConfigUrl(deployCliConfig.runtimeControlPlaneUrl ?? new URL(DEFAULT_CONTROL_PLANE_URL));
     await writeFile(entrypointPath, renderCloudflareWorkerEntrypoint({
         workerImportPath: relativeImportPath(dirname(entrypointPath), workerSourcePath),
+        requireActiveCardInstall: appConfig.auth === 'oauth',
+        ...(cronPlan.dispatch.length > 0 ? { syncCron: cronPlan } : {}),
+        ...(appConfig.appEventBatching !== undefined
+            ? { appEventBatching: appConfig.appEventBatching }
+            : {}),
+        ...(appConfig.rateLimits !== undefined ? { rateLimits: appConfig.rateLimits } : {}),
+        ...(appConfig.redaction !== undefined ? { redaction: appConfig.redaction } : {}),
         ...(controlPlaneUrl && appConfig.billing
             ? {
                 billing: {
@@ -1514,7 +2266,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
     // Resolution: flag → env → the binding persisted by the last successful
     // upload (.hs-x/hubspot.json). Users should never have to replay an app id
     // the CLI already learned (owner directive, run-008).
-    const hubspotAppId = readOptionalHubSpotAppId(resolveFlag(argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID) ?? (await readPersistedHubSpotAppId(root));
+    const hubspotAppId = readOptionalHubSpotAppId(resolveFlag(argv, '--hubspot-app-id') ?? process.env.HSX_HUBSPOT_APP_ID) ?? (await readPersistedHubSpotAppId(root, await resolveHubSpotProjectName(argv, root)));
     const installRuntimeBinding = hubspotAppId
         ? controlPlaneUrl
             ? await ensureDeployInstallRuntimeBinding({
@@ -1553,6 +2305,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
             install: installRuntimeBinding,
             controlPlaneUrl,
             userId,
+            ...(note ? { note } : {}),
         })
         : undefined;
     const hubSpotOAuthSecret = hubspotAppId && controlPlaneUrl
@@ -1565,25 +2318,45 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
             hubSpotAppId: hubspotAppId,
         })
         : undefined;
-    const hubSpotClientId = hubSpotOAuthSecret?.clientId ??
-        resolveFlag(argv, '--hubspot-client-id') ??
+    const hubSpotClientId = resolveFlag(argv, '--hubspot-client-id') ??
+        hubSpotOAuthSecret?.clientId ??
         process.env.HSX_HUBSPOT_CLIENT_ID;
     // The client secret comes from the control plane when linked; unlinked it can
     // be supplied directly so the deployed Worker can complete the install OAuth
     // token exchange (otherwise /oauth-start 500s with "missing HSX_HUBSPOT_CLIENT_ID").
-    const hubSpotClientSecret = hubSpotOAuthSecret?.clientSecret ??
-        resolveFlag(argv, '--hubspot-client-secret') ??
+    const hubSpotClientSecret = resolveFlag(argv, '--hubspot-client-secret') ??
+        hubSpotOAuthSecret?.clientSecret ??
         process.env.HSX_HUBSPOT_CLIENT_SECRET;
-    // Interactively fill the unlinked OAuth client id/secret the deployed Worker
-    // needs for /oauth-start, instead of silently shipping a Worker that 500s.
-    const { clientId: resolvedHubSpotClientId, clientSecret: resolvedHubSpotClientSecret } = await resolveUnlinkedOAuthCredentials({
+    const hasCardBackends = worker.capabilities.some((capability) => capability.kind === 'card-backend');
+    // Interactively fill credentials required by OAuth and card backends. A card
+    // backend is never deployed without the v3-signature HMAC key.
+    const { clientId: resolvedHubSpotClientId, clientSecret: resolvedHubSpotClientSecret } = await resolveHubSpotRuntimeCredentials({
         auth: appConfig.auth,
-        linked: Boolean(controlPlaneUrl),
+        requiresCardSignatureSecret: hasCardBackends,
         dryRun,
-        allowPrompt: index === 0,
+        allowPrompt: allowCredentialPrompt,
         hubSpotClientId,
         hubSpotClientSecret,
     });
+    // Surface the OAuth client id + where it came from. This binding is the HMAC
+    // key for card v3-signature verification; a wrong one fails silently at
+    // runtime (401 invalid_hubspot_signature) hours later, so make it visible at
+    // deploy time — if it looks wrong, `hs-x secrets hubspot-oauth set` corrects
+    // the control-plane copy. Once per deploy (index 0), stderr to keep --json clean.
+    if ((appConfig.auth === 'oauth' || hasCardBackends) &&
+        (resolvedHubSpotClientId || resolvedHubSpotClientSecret) &&
+        index === 0 &&
+        !dryRun) {
+        const source = resolveFlag(argv, '--hubspot-client-secret') || resolveFlag(argv, '--hubspot-client-id')
+            ? 'flag'
+            : hubSpotOAuthSecret
+                ? 'control plane'
+                : process.env.HSX_HUBSPOT_CLIENT_SECRET || process.env.HSX_HUBSPOT_CLIENT_ID
+                    ? 'env/prompt'
+                    : 'missing';
+        emitNote(`  [hubspot auth]${resolvedHubSpotClientId ? ` client id ${resolvedHubSpotClientId};` : ''} client secret ${resolvedHubSpotClientSecret ? 'configured' : 'missing'} (source: ${source})` +
+            `${resolvedHubSpotClientSecret ? '' : ' — no client secret; card verification will fail closed'}\n`);
+    }
     const hubSpotScopesForRuntime = await readHsxAppScopesForDeploy(root);
     const billingRuntimeToken = controlPlaneUrl && appConfig.billing && !dryRun
         ? await requestDeployBillingRuntimeToken({
@@ -1599,6 +2372,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
         workerName,
         entrypointPath: relativeImportPath(dirname(configPath), entrypointPath),
         compatibilityDate,
+        ...(cronPlan.crons.length > 0 ? { crons: cronPlan.crons } : {}),
         ...(installRuntimeBinding
             ? { installKvNamespaceId: installRuntimeBinding.installKvNamespaceId }
             : {}),
@@ -1633,7 +2407,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
         .then((entry) => entry.isDirectory())
         .catch(() => false);
     if (tenantDataPlane?.tenantD1DatabaseName && !dryRun && !migrationsDirExists) {
-        process.stderr.write('warning: @hs-x/runtime did not ship its tenant migrations (pre-0.2.4 package) — tenant D1 tables were NOT applied; upgrade @hs-x/runtime.\n');
+        emitNote('warning: @hs-x/runtime did not ship its tenant migrations (pre-0.2.4 package) — tenant D1 tables were NOT applied; upgrade @hs-x/runtime.\n');
     }
     if (tenantDataPlane?.tenantD1DatabaseName && !dryRun && migrationsDirExists) {
         try {
@@ -1776,7 +2550,7 @@ async function executeCloudflareWorkerDeploy({ argv, root, worker, index, source
             });
         }
         catch (error) {
-            process.stderr.write(`warning: could not register the tenant Worker URL with the control plane: ${error instanceof Error ? error.message : String(error)}\n`);
+            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
@@ -1835,14 +2609,37 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
         hubSpotAppId: input.hubSpotAppId,
     });
     if (existing) {
+        // ADR-022 fail-closed check: the binding claims an escrowed key, so the
+        // key must resolve AND open the sealed canary before we touch anything.
+        // Nothing has been mutated at this point — a custody failure aborts the
+        // deploy with an actionable error and zero writes.
+        if (existing.tokenKeyCustody.kind === 'escrowed' && !input.dryRun) {
+            await resolveEscrowedTokenKey({ custody: existing.tokenKeyCustody });
+        }
         return {
             installKvNamespaceId: existing.installKvNamespaceId,
             installKvNamespaceName: existing.installKvNamespaceName,
             tokenKeySecretName: existing.tokenKeySecretName,
+            tokenKeyCustody: existing.tokenKeyCustody,
         };
     }
     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,
+            projectId: input.projectId,
+            environment: input.environment,
+            hubSpotAppId: input.hubSpotAppId,
+        }),
+        tokenKeySecretValue,
+    });
     const installKvNamespaceName = installKvNamespaceNameFor({
         accountId: input.ownerId,
         projectId: input.projectId,
@@ -1867,8 +2664,8 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
     if (!installKvNamespaceId) {
         throw new Error('Could not read Cloudflare KV namespace id from wrangler output.');
     }
-    const tokenKeySecretName = 'HSX_TOKEN_KEY';
     await stateStore.putBinding(Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)({
+        schemaVersion: 2,
         ownerId: pointer.ownerId,
         projectId: input.projectId,
         hubSpotAppId: input.hubSpotAppId,
@@ -1876,18 +2673,22 @@ async function ensureTenantDeployInstallRuntimeBinding(input) {
         installKvNamespaceId,
         installKvNamespaceName,
         tokenKeySecretName,
+        tokenKeyCustody,
         updatedAt: new Date().toISOString(),
     }));
     return {
         installKvNamespaceId,
         installKvNamespaceName,
         tokenKeySecretName,
-        tokenKeySecretValue: randomBytes(32).toString('base64url'),
+        tokenKeySecretValue,
+        tokenKeyCustody,
     };
 }
 async function ensureDeployInstallRuntimeBinding(input) {
     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,
@@ -1897,6 +2698,20 @@ async function ensureDeployInstallRuntimeBinding(input) {
     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,
+            projectId: input.projectId,
+            environment: input.environment,
+            hubSpotAppId: input.hubSpotAppId,
+        }),
+        tokenKeySecretValue,
+    });
     const installKvNamespaceName = installKvNamespaceNameFor({
         accountId: input.accountId,
         projectId: input.projectId,
@@ -1932,7 +2747,8 @@ async function ensureDeployInstallRuntimeBinding(input) {
         installKvNamespaceId,
         installKvNamespaceName,
         tokenKeySecretName,
-        tokenKeySecretValue: randomBytes(32).toString('base64url'),
+        tokenKeySecretValue,
+        tokenKeyCustody,
     };
 }
 async function readDeployInstallRuntimeBinding(input) {
@@ -2062,8 +2878,23 @@ async function ensureTenantDataPlane(input) {
     const tenantD1DatabaseName = existing?.tenantD1DatabaseName ?? tenantD1DatabaseNameFor(input);
     let tenantD1DatabaseId = existing?.tenantD1DatabaseId;
     if (!tenantD1DatabaseId) {
-        const output = await runCloudflareCommand(['bun', 'x', 'wrangler', 'd1', 'create', tenantD1DatabaseName], { cwd: input.root, env });
-        tenantD1DatabaseId = extractD1DatabaseId(`${output.stdout}\n${output.stderr}`);
+        // 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.');
         }
@@ -2071,8 +2902,35 @@ async function ensureTenantDataPlane(input) {
     const flagsKvNamespaceName = existing?.flagsKvNamespaceName ?? flagsKvNamespaceNameFor(input);
     let flagsKvNamespaceId = existing?.flagsKvNamespaceId;
     if (!flagsKvNamespaceId) {
-        const output = await runCloudflareCommand(['bun', 'x', 'wrangler', 'kv', 'namespace', 'create', flagsKvNamespaceName, '--binding', 'FLAGS_KV'], { cwd: input.root, env });
-        flagsKvNamespaceId = extractKvNamespaceId(`${output.stdout}\n${output.stderr}`);
+        // 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;
+            }
+            catch {
+                flagsKvNamespaceId = undefined;
+            }
+        }
         if (!flagsKvNamespaceId) {
             throw new Error('Could not read flags KV namespace id from wrangler output.');
         }
@@ -2081,6 +2939,7 @@ async function ensureTenantDataPlane(input) {
     const reusedSecret = existing?.syncGrantSecretValue;
     const syncGrantSecretValue = reusedSecret ?? randomBytes(32).toString('base64url');
     await stateStore.putBinding(Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)({
+        schemaVersion: 2,
         ownerId: pointer.ownerId,
         tenantScopeAccountId: input.accountId,
         projectId: input.projectId,
@@ -2089,6 +2948,15 @@ async function ensureTenantDataPlane(input) {
         installKvNamespaceId: input.install.installKvNamespaceId,
         installKvNamespaceName: input.install.installKvNamespaceName,
         tokenKeySecretName: input.install.tokenKeySecretName,
+        // ADR-022: carry custody through the rewrite. A binding re-hydrated
+        // from the control plane on a machine that never held the key is
+        // honestly recorded as worker-secret-only (the link preflight fails
+        // closed on that shape).
+        // A custody freshly minted this deploy (install.tokenKeyCustody) wins
+        // over whatever a previous binding recorded — the Worker secret is
+        // being set to the NEW key in this same deploy.
+        tokenKeyCustody: input.install.tokenKeyCustody ??
+            existing?.tokenKeyCustody ?? { kind: 'worker-secret-only' },
         tenantD1DatabaseId,
         tenantD1DatabaseName,
         flagsKvNamespaceId,
@@ -2113,7 +2981,13 @@ async function ensureTenantDataPlane(input) {
             });
         }
         catch (error) {
-            process.stderr.write(`warning: could not register the sync grant secret with the control plane: ${error instanceof Error ? error.message : String(error)}\n`);
+            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 {
@@ -2187,6 +3061,12 @@ export function renderWranglerConfig(input) {
             lines.push(`migrations_dir = "${tomlString(input.tenantMigrationsDir)}"`);
         }
     }
+    // ADR-023 S04: cron triggers generated from declared sync schedules. One
+    // entry per distinct cadence (syncs sharing a schedule collapse into it);
+    // the generated `scheduled` handler fans each fire out to its syncs.
+    if (input.crons && input.crons.length > 0) {
+        lines.push('', '[triggers]', `crons = [ ${input.crons.map((cron) => `"${tomlString(cron)}"`).join(', ')} ]`);
+    }
     return `${lines.join('\n')}\n`;
 }
 function tomlString(value) {
@@ -2212,11 +3092,195 @@ async function readDeployHubSpotOAuthSecret(input) {
 function extractWorkerUrl(output) {
     return /https:\/\/[a-zA-Z0-9.-]+\.workers\.dev\b/.exec(output)?.[0];
 }
-export async function ensureHubSpotRuntimeProjectArtifacts({ argv, root, app, workers, cloudflareDeployResult, needsRuntime, controlPlanePlan, }) {
-    if (!needsRuntime) {
+/**
+ * Resolve the Worker origin BEFORE deploying, for the upload-first path. An
+ * explicit `--runtime-origin` wins; otherwise compute
+ * `<workerName>.<subdomain>.workers.dev` from the planned worker name and the
+ * account's workers.dev subdomain. Returns undefined (→ fall back to the
+ * deploy-then-upload order) when the subdomain cannot be resolved, so a first
+ * deploy that can't compute the origin behaves exactly as before.
+ */
+async function resolveUploadFirstRuntimeOrigin(input) {
+    const flag = resolveFlag(input.argv, '--runtime-origin');
+    if (flag)
+        return flag;
+    const workerName = input.controlPlanePlan.resources.workerNames[0];
+    const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+    const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+    if (!workerName || !accountId || !apiToken)
+        return undefined;
+    const base = (process.env.HSX_CLOUDFLARE_API_BASE_URL ?? 'https://api.cloudflare.com/client/v4').replace(/\/$/, '');
+    try {
+        const response = await fetch(`${base}/accounts/${encodeURIComponent(accountId)}/workers/subdomain`, { headers: { authorization: `Bearer ${apiToken}` } });
+        const body = (await response.json().catch(() => undefined));
+        const subdomain = body?.result?.subdomain;
+        if (!response.ok || !subdomain)
+            return undefined;
+        return `https://${workerName}.${subdomain}.workers.dev`;
+    }
+    catch {
+        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, }) {
+    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 = resolveFlag(argv, '--runtime-origin') ??
+    const runtimeBaseUrl = runtimeOrigin ??
+        resolveFlag(argv, '--runtime-origin') ??
         cloudflareDeployResult?.workers.find((worker) => worker.url)?.url;
     if (!runtimeBaseUrl) {
         throw new Error('Runtime HubSpot metadata requires a Worker URL. Pass --runtime-origin or run a non-dry-run Cloudflare deploy that reports a workers.dev URL.');
@@ -2225,24 +3289,20 @@ 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));
     }
 }
 async function readHsxAppScopesForDeploy(root) {
@@ -2254,9 +3314,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
@@ -2272,9 +3342,16 @@ async function readHsxAppConfig(root) {
         appObjects: discoverAppObjectDeclarations(raw),
         appObjectAssociations: discoverAppObjectAssociationDeclarations(raw),
         appEvents: discoverAppEventDeclarations(raw),
-        // Cards are only recoverable from the loaded module (the literal parser
-        // can't evaluate `card(...)` calls); an unloadable config yields none.
+        ...(loaded?.appEvents?.batching !== undefined
+            ? { appEventBatching: loaded.appEvents.batching }
+            : {}),
+        ...(loaded?.rateLimits !== undefined ? { rateLimits: loaded.rateLimits } : {}),
+        ...(loaded?.alerts !== undefined ? { alerts: loaded.alerts } : {}),
+        ...(loaded?.redaction !== undefined ? { redaction: loaded.redaction } : {}),
+        // 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 } : {}),
     };
 }
@@ -2375,13 +3452,19 @@ function discoverAppObjectDeclarations(source) {
                 }
                 : {}),
             ...(readStringArrayProperty(body, 'requiredProperties').length
-                ? { requiredProperties: readStringArrayProperty(body, 'requiredProperties') }
+                ? {
+                    requiredProperties: readStringArrayProperty(body, 'requiredProperties'),
+                }
                 : {}),
             ...(readStringArrayProperty(body, 'searchableProperties').length
-                ? { searchableProperties: readStringArrayProperty(body, 'searchableProperties') }
+                ? {
+                    searchableProperties: readStringArrayProperty(body, 'searchableProperties'),
+                }
                 : {}),
             ...(readStringArrayProperty(body, 'defaultCreateFormFields').length
-                ? { defaultCreateFormFields: readStringArrayProperty(body, 'defaultCreateFormFields') }
+                ? {
+                    defaultCreateFormFields: readStringArrayProperty(body, 'defaultCreateFormFields'),
+                }
                 : {}),
             properties,
         };
@@ -2414,7 +3497,9 @@ function discoverAppEventDeclarations(source) {
         objectType: stringPropertyValue(body, 'objectType') ?? 'CONTACT',
         ...(booleanPropertyValue(body, 'supportsCustomObject') === undefined
             ? {}
-            : { supportsCustomObject: booleanPropertyValue(body, 'supportsCustomObject') }),
+            : {
+                supportsCustomObject: booleanPropertyValue(body, 'supportsCustomObject'),
+            }),
         ...(stringPropertyValue(body, 'headerTemplate')
             ? { headerTemplate: stringPropertyValue(body, 'headerTemplate') }
             : {}),
@@ -2434,7 +3519,10 @@ function declarationBodies(source, functionName) {
         const end = findMatching(source, start, '{', '}');
         if (end === -1)
             continue;
-        declarations.push({ id: match[1] ?? 'unknown', body: source.slice(start + 1, end) });
+        declarations.push({
+            id: match[1] ?? 'unknown',
+            body: source.slice(start + 1, end),
+        });
     }
     return declarations;
 }
@@ -2482,7 +3570,10 @@ function topLevelObjectEntries(source) {
                 if (braceStart !== -1 && source.slice(valueStart, braceStart).trim() === '') {
                     const braceEnd = findMatching(source, braceStart, '{', '}');
                     if (braceEnd !== -1) {
-                        entries.push({ name, body: source.slice(braceStart + 1, braceEnd) });
+                        entries.push({
+                            name,
+                            body: source.slice(braceStart + 1, braceEnd),
+                        });
                         index = braceEnd + 1;
                         continue;
                     }
@@ -2569,16 +3660,12 @@ function runCloudflareCommand(command, options) {
     })));
 }
 async function executeHubSpotOnlyUpload({ argv, root, local, uploadOnly, }) {
-    const hsprojectConfig = await readHubSpotProjectConfig(root);
-    const configuredProjectName = typeof hsprojectConfig.name === 'string' && hsprojectConfig.name.length > 0
-        ? hsprojectConfig.name
-        : undefined;
     // The HubSpot project name must match the name baked into the generated
     // bundle (hsproject.json + app-hsmeta uid), not the on-disk directory name.
     // Using basename(root) breaks when the project lives in a generic dir (e.g.
     // `app/`): the upload targets a project named "app" while the bundle declares
     // the real project id, and HubSpot rejects the mismatch with an opaque 400.
-    const projectName = resolveFlag(argv, '--hubspot-project-name') ?? configuredProjectName ?? basename(root);
+    const projectName = await resolveHubSpotProjectName(argv, root);
     const intermediateRepresentation = await readHubSpotProjectIntermediateRepresentation(root);
     const appUid = readAppUidFromIntermediateRepresentation(intermediateRepresentation) ??
         (await readAppUidFromProjectSource(root));
@@ -2596,11 +3683,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({
@@ -2616,7 +3705,11 @@ async function executeHubSpotOnlyUpload({ argv, root, local, uploadOnly, }) {
             ? await optionalHubSpotAppId(client, projectName, appUid)
             : 0;
         if (appId)
-            await persistHubSpotAppBinding(root, { appId, projectName, developerAccountId });
+            await persistHubSpotAppBinding(root, {
+                appId,
+                projectName,
+                developerAccountId,
+            });
         // Build SUCCESS does NOT mean the app shipped: HubSpot's auto-deploy can
         // still fail (found live: "Apps are not allowed to have 0 redirect URLs"
         // failed deploy #4 while the CLI reported green). Verify the deploy too.
@@ -2652,7 +3745,11 @@ async function executeHubSpotOnlyUpload({ argv, root, local, uploadOnly, }) {
             deployId,
         });
     const appId = await optionalHubSpotAppId(client, projectName, appUid);
-    await persistHubSpotAppBinding(root, { appId, projectName, developerAccountId });
+    await persistHubSpotAppBinding(root, {
+        appId,
+        projectName,
+        developerAccountId,
+    });
     return {
         projectName,
         archivePath,
@@ -2869,7 +3966,7 @@ async function collectHubSpotMetaFiles(root) {
 }
 function runZip(root, archivePath) {
     return new Promise((resolve, reject) => {
-        const child = spawn('zip', ['-qr', archivePath, '.', '-x', 'node_modules/*', '.hs-x/*'], {
+        const child = spawn('zip', ['-qr', archivePath, '.', '-x', 'node_modules/*', '*/node_modules/*', '.hs-x/*'], {
             cwd: root,
             stdio: ['ignore', 'ignore', 'pipe'],
         });
@@ -2906,25 +4003,59 @@ async function persistHubSpotAppBinding(root, binding) {
         await writeFile(join(dir, HUBSPOT_APP_BINDING_FILE[1]), `${JSON.stringify({
             appId: binding.appId,
             projectName: binding.projectName,
-            ...(binding.developerAccountId
-                ? { developerAccountId: binding.developerAccountId }
-                : {}),
+            ...(binding.developerAccountId ? { developerAccountId: binding.developerAccountId } : {}),
         }, null, 2)}\n`);
     }
     catch {
         // Advisory persistence — never fail a deploy over it.
     }
 }
-async function readPersistedHubSpotAppId(root) {
+async function resolveHubSpotProjectName(argv, root) {
+    const hsprojectConfig = await readHubSpotProjectConfig(root);
+    const configuredProjectName = typeof hsprojectConfig.name === 'string' && hsprojectConfig.name.length > 0
+        ? hsprojectConfig.name
+        : undefined;
+    return resolveFlag(argv, '--hubspot-project-name') ?? configuredProjectName ?? basename(root);
+}
+async function readPersistedHubSpotAppBinding(root, expectedProjectName) {
     try {
         const raw = await readFile(join(root, ...HUBSPOT_APP_BINDING_FILE), 'utf8');
         const parsed = JSON.parse(raw);
-        return readOptionalHubSpotAppId(typeof parsed.appId === 'number' ? String(parsed.appId) : undefined);
+        // The numeric app id is only meaningful for the HubSpot project that
+        // produced it. A renamed/re-generated project must upload first and mint
+        // its own app id; reusing the prior project's id also binds the prior
+        // client secret and makes every card v3 signature fail at runtime.
+        if (parsed.projectName !== expectedProjectName)
+            return undefined;
+        const appId = readOptionalHubSpotAppId(typeof parsed.appId === 'number' ? String(parsed.appId) : undefined);
+        if (!appId)
+            return undefined;
+        return {
+            appId,
+            projectName: expectedProjectName,
+            ...(typeof parsed.developerAccountId === 'string' && parsed.developerAccountId.length > 0
+                ? { developerAccountId: parsed.developerAccountId }
+                : {}),
+        };
     }
     catch {
         return undefined;
     }
 }
+async function readPersistedHubSpotAppId(root, expectedProjectName) {
+    return (await readPersistedHubSpotAppBinding(root, expectedProjectName))?.appId;
+}
+async function resolveHubSpotAppAuthUrl(argv, root) {
+    const projectName = await resolveHubSpotProjectName(argv, root);
+    const persisted = await readPersistedHubSpotAppBinding(root, projectName);
+    const intermediateRepresentation = await readHubSpotProjectIntermediateRepresentation(root);
+    const appUid = readAppUidFromIntermediateRepresentation(intermediateRepresentation) ??
+        (await readAppUidFromProjectSource(root));
+    const developerAccountId = resolveFlag(argv, '--developer-account-id') ??
+        process.env.HSX_HUBSPOT_DEVELOPER_ACCOUNT_ID ??
+        persisted?.developerAccountId;
+    return buildHubSpotAppAuthUrl({ developerAccountId, projectName, appUid });
+}
 function readStatus(value) {
     return isRecord(value) && typeof value.status === 'string' ? value.status : undefined;
 }
@@ -2957,8 +4088,41 @@ function readOptionalHubSpotAppId(value) {
     const parsed = readPositiveInteger(value, '--hubspot-app-id');
     return Schema.decodeSync(schemas.HubSpotAppId)(parsed);
 }
-function deployBundleKey(input) {
-    return Schema.decodeSync(schemas.BundleKey)(`r2://bundles/${input.projectId}/${input.deployId}.tar.gz`);
+/**
+ * ADR-021 R03 deploy-time capture. Reads back Cloudflare's confirmed active
+ * deployment for the primary Worker and returns its verifiable revision, or
+ * `undefined` (with a warning) when credentials are missing or the read-back
+ * fails. Best-effort: never fabricates an id and never fails the deploy —
+ * capture is a pure read, so a retry re-reads the same version id.
+ */
+async function captureDeployRevisionForDeploy(input) {
+    // Worker/script names are authoritative and never renamed (T03); the first
+    // planned Worker is the project's primary runtime Worker.
+    const scriptName = input.controlPlanePlan.resources.workerNames[0];
+    if (!scriptName)
+        return undefined;
+    const warn = (message) => {
+        if (!input.json) {
+            (input.reporter ?? createReporter({ command: 'deploy', argv: input.argv })).warn('HSX_W_DEPLOY_REVISION_CAPTURE', message);
+        }
+    };
+    const creds = resolveCloudflareCredentials(input.argv);
+    const cloudflareAccountId = creds.accountId ?? (await loadCloudflarePointer(input.root))?.cloudflareAccountId;
+    if (!creds.apiToken || !cloudflareAccountId) {
+        warn('Skipped Cloudflare version capture: no Cloudflare API token / account id available. This deploy is recorded without a rollback-capable revision.');
+        return undefined;
+    }
+    try {
+        return await captureDeployRevision({
+            cloudflareAccountId,
+            scriptName,
+            apiToken: creds.apiToken,
+        });
+    }
+    catch (error) {
+        warn(`Could not read back the Cloudflare Worker version for "${scriptName}" (${error instanceof Error ? error.message : String(error)}); recorded without a rollback-capable revision.`);
+        return undefined;
+    }
 }
 async function requestLocalControlPlaneDeployPlan(request) {
     const controlPlane = (await loadCreateControlPlane())({
@@ -2997,7 +4161,7 @@ async function requestHostedControlPlaneDeployPlan({ request, controlPlaneUrl, u
     }
     return Schema.decodeUnknownSync(schemas.DeployPlanResponse)(body);
 }
-async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, plan, promoteWhenHealthy, }) {
+async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, plan, promoteWhenHealthy, revision, }) {
     const controlPlane = (await loadCreateControlPlane())({
         now: () => new Date('2026-05-18T14:00:00.000Z'),
     });
@@ -3020,7 +4184,10 @@ async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, pl
             manifestHash: plan.manifestHash,
             signedManifest: request.manifest,
             signature: `sig_${plan.deployId}`,
-            bundleKey: deployBundleKey({ projectId: request.projectId, deployId: plan.deployId }),
+            // 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.
+            ...(revision ? { revision } : {}),
         }),
     }));
     const body = await response.json();
@@ -3061,7 +4228,10 @@ async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, pl
     const promotionResponse = await controlPlane.fetch(new Request(`https://api.hs-x.dev/v1/deploys/${plan.deployId}/promote`, {
         method: 'POST',
         headers,
-        body: JSON.stringify({ accountId: request.accountId, projectId: request.projectId }),
+        body: JSON.stringify({
+            accountId: request.accountId,
+            projectId: request.projectId,
+        }),
     }));
     const promotionBody = await promotionResponse.json();
     if (!promotionResponse.ok) {
@@ -3075,7 +4245,7 @@ async function requestLocalControlPlaneDeployRecordAndMaybePromote({ request, pl
         promotion: Schema.decodeUnknownSync(schemas.DeployPromotionResult)(promotionBody),
     };
 }
-async function requestHostedControlPlaneDeployRecordAndMaybePromote({ request, plan, controlPlaneUrl, userId, promoteWhenHealthy, promotionTimeoutMs, workerUrl, }) {
+async function requestHostedControlPlaneDeployRecordAndMaybePromote({ request, plan, controlPlaneUrl, userId, promoteWhenHealthy, promotionTimeoutMs, workerUrl, revision, }) {
     const response = await hostedHttp({
         url: new URL(`/v1/deploys/${encodeURIComponent(plan.deployId)}/record`, controlPlaneUrl),
         method: 'POST',
@@ -3086,7 +4256,10 @@ async function requestHostedControlPlaneDeployRecordAndMaybePromote({ request, p
             manifestHash: plan.manifestHash,
             signedManifest: request.manifest,
             signature: `sig_${plan.deployId}`,
-            bundleKey: deployBundleKey({ projectId: request.projectId, deployId: plan.deployId }),
+            // 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.
+            ...(revision ? { revision } : {}),
             ...(await collectDeployProvenance(userId)),
         },
     });
@@ -3157,6 +4330,18 @@ async function discoverWorkerManifests(root, options = {}) {
         if (!workerName) {
             continue;
         }
+        // Prefer the runtime manifest (the source of truth `worker.manifest()`
+        // produces): load the worker module and read its capabilities directly.
+        // This handles loops, shared field-map consts, computed ids, and full field
+        // fidelity (supportedValueTypes / isRequired / descriptions) that source
+        // regex cannot — and keeps deploy in agreement with the runtime + dev/invoke
+        // (which already call `.manifest()`). Falls back to regex parsing when the
+        // module can't be imported. See checkpoint FINDINGS #14.
+        const loadedManifest = await loadWorkerManifestModule(file).catch(() => undefined);
+        if (loadedManifest) {
+            workers.push(applyNoManageSchemaOverride(loadedManifest, options));
+            continue;
+        }
         const toolCapabilities = [
             ...source.matchAll(/(?:worker\.)?(?:tool|action)\s*\(\s*["'`]([^"'`]+)["'`]\s*,\s*\{([\s\S]*?)(?:async\s+)?handler\s*(?:[:(])/g),
         ].map((match) => ({
@@ -3174,6 +4359,8 @@ async function discoverWorkerManifests(root, options = {}) {
             kind: 'card-backend',
             id: match[1] ?? 'unknown',
             label: /label\s*:\s*["'`]([^"'`]+)["'`]/.exec(match[2] ?? '')?.[1] ?? match[1] ?? 'unknown',
+            ...objectFieldsProperty(match[2] ?? '', 'input'),
+            ...objectFieldsProperty(match[2] ?? '', 'output'),
             runtimeNeeds: ['worker'],
         }));
         const sourceDefinitions = discoverSourceDefinitions(source);
@@ -3221,6 +4408,41 @@ async function discoverWorkerManifests(root, options = {}) {
     }
     return workers;
 }
+/**
+ * Load a worker module and return its `worker.manifest()` — the runtime source
+ * of truth. Mirrors `loadHsxAppConfigModule`: a cache-busted dynamic import of
+ * the user's TypeScript. Returns undefined (so the caller falls back to regex
+ * parsing) when the file has no default WorkerDefinition or can't be imported.
+ */
+async function loadWorkerManifestModule(file) {
+    const url = pathToFileURL(file);
+    url.searchParams.set('hsxWorkerLoad', String(Date.now()));
+    const mod = (await import(url.href));
+    const def = mod.default;
+    if (def &&
+        typeof def === 'object' &&
+        typeof def.manifest === 'function') {
+        const manifest = def.manifest();
+        if (manifest && Array.isArray(manifest.capabilities)) {
+            return manifest;
+        }
+    }
+    return undefined;
+}
+/**
+ * `--no-manage-schema` is a deploy-time flag, not part of the worker's own
+ * declaration, so apply it to sync capabilities of a loaded manifest (the regex
+ * path applies it inline).
+ */
+function applyNoManageSchemaOverride(manifest, options) {
+    if (!options.noManageSchema) {
+        return manifest;
+    }
+    return {
+        ...manifest,
+        capabilities: manifest.capabilities.map((capability) => capability.kind === 'sync' ? { ...capability, manageSchema: false } : capability),
+    };
+}
 function stringProperty(source, propertyName) {
     const match = new RegExp(`${propertyName}\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(source)?.[1];
     return match ? { [propertyName]: match } : {};
@@ -3270,7 +4492,10 @@ function schemaProperty(source) {
             const inner = body.slice(valueStart + 1, end);
             const type = /type\s*:\s*["'`]([^"'`]+)["'`]/.exec(inner)?.[1];
             const property = /property\s*:\s*["'`]([^"'`]+)["'`]/.exec(inner)?.[1];
-            schema[name] = { ...(type ? { type } : {}), ...(property ? { property } : {}) };
+            schema[name] = {
+                ...(type ? { type } : {}),
+                ...(property ? { property } : {}),
+            };
             index = end + 1;
         }
         else {
@@ -3289,9 +4514,9 @@ function objectFieldsProperty(source, propertyName) {
         return {};
     }
     const fields = {};
-    for (const match of body.matchAll(/([A-Za-z_$][\w$]*)\s*:\s*\{([\s\S]*?)\}\s*,?/g)) {
-        const fieldName = match[1];
-        const definition = match[2] ?? '';
+    for (const match of body.matchAll(/(?:([A-Za-z_$][\w$]*)|["']([^"']+)["'])\s*:\s*\{([\s\S]*?)\}\s*,?/g)) {
+        const fieldName = match[1] ?? match[2];
+        const definition = match[3] ?? '';
         if (!fieldName) {
             continue;
         }
@@ -3299,6 +4524,8 @@ function objectFieldsProperty(source, propertyName) {
             ...stringProperty(definition, 'type'),
             ...stringProperty(definition, 'label'),
             ...literalProperty(definition, 'default'),
+            ...literalProperty(definition, 'required'),
+            ...literalProperty(definition, 'isRequired'),
         };
     }
     return Object.keys(fields).length > 0 ? { [propertyName]: fields } : {};
@@ -3488,6 +4715,10 @@ const deployOptions = {
     applySchema: Options.boolean('apply-schema').pipe(Options.withDefault(false)), // --apply-schema
     heartbeat: Options.boolean('heartbeat').pipe(Options.withDefault(false)), // --heartbeat
     noHeartbeat: Options.boolean('no-heartbeat').pipe(Options.withDefault(false)), // --no-heartbeat
+    // Declared explicitly: without it @effect/cli treats `--no-record` as the
+    // negation of an undeclared `record` boolean and fails routing with a
+    // confusing root-level "Invalid subcommand" error (the flag is documented).
+    noRecord: Options.boolean('no-record').pipe(Options.withDefault(false)), // --no-record
     portalSchemaLive: Options.boolean('portal-schema-live').pipe(Options.withDefault(false)), // --portal-schema-live
     localHubspotSchema: Options.boolean('local-hubspot-schema').pipe(Options.withDefault(false)), // --local-hubspot-schema
     force: Options.boolean('force').pipe(Options.withDefault(false)), // --force
@@ -3543,13 +4774,14 @@ const deployBaseCmd = Command.make('deploy', deployOptions, (opts) => runHandler
     flag('--apply-schema', opts.applySchema);
     flag('--heartbeat', opts.heartbeat);
     flag('--no-heartbeat', opts.noHeartbeat);
+    flag('--no-record', opts.noRecord);
     flag('--portal-schema-live', opts.portalSchemaLive);
     flag('--local-hubspot-schema', opts.localHubspotSchema);
     flag('--force', opts.force);
     flag('--yes', opts.yes);
     if (opts.json)
         argv.push('--json');
-    yield* runQuarantined(opts.json, () => deployCommand({ argv, root, json: opts.json }));
+    yield* runQuarantined('deploy', opts.json, () => deployCommand({ argv, root, json: opts.json }));
 })));
 // `hs-x deploy promote` — preserved as a subcommand that delegates to the legacy
 // `deployCommand` promote branch (argv[1] === 'promote'), byte-for-byte. The
@@ -3583,7 +4815,7 @@ const deployPromoteSubCmd = Command.make('promote', {
         argv.push('--yes');
     if (opts.json)
         argv.push('--json');
-    yield* runQuarantined(opts.json, () => deployCommand({ argv, root, json: opts.json }));
+    yield* runQuarantined('deploy', opts.json, () => deployCommand({ argv, root, json: opts.json }));
 })));
 export const deployCmd = deployBaseCmd.pipe(Command.withSubcommands([deployPromoteSubCmd]));
 /**
@@ -3594,7 +4826,11 @@ export const deployCmd = deployBaseCmd.pipe(Command.withSubcommands([deployPromo
 async function collectDeployProvenance(userId) {
     const git = async (args) => {
         try {
-            const proc = Bun.spawn({ cmd: ['git', ...args], stdout: 'pipe', stderr: 'ignore' });
+            const proc = Bun.spawn({
+                cmd: ['git', ...args],
+                stdout: 'pipe',
+                stderr: 'ignore',
+            });
             const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
             const trimmed = out.trim();
             return code === 0 && trimmed ? trimmed : undefined;