@inquir/compute-cli 0.3.0 → 0.4.1

package/dist/commands/apps.js

@@ -1,16 +1,25 @@
 import path from 'node:path';
+import { alertsSubcommand, logHistorySubcommand, metricsSubcommand, OBSERVATION_HELP, OBSERVATION_VALUE_FLAGS } from './apps-observability.js';
+import { RESOURCES_HELP, RESOURCES_VALUE_FLAGS, resourcesSubcommand } from './apps-resources.js';
+import { DESCRIBE_HELP, describeSubcommand } from './apps-describe.js';
+import { INSTANCES_HELP, instancesSubcommand, resolveReplicaAllocationId } from './apps-instances.js';
+import { followPromoteRollout } from './apps-promote.js';
 import { hasFlag, readFlagValue, readJsonFlag, readLimitFlag, readMultiFlag, readPositionalArgs, } from '../utils/args.js';
-import { listAppBackups, getAppBackup, createAppBackup, deleteAppBackup, restoreAppBackup, getAppConnectionUrl, connectApps, addApplicationDomain, archiveApplication, cancelBuild, createApplication, getBuild, listApplicationDomains, listBuilds, queueBuild, removeApplicationDomain, createRelease, redeployApplication, execInApplication, getAppLimits, getApplication, getRelease, listApplications, promoteRelease, requireAuth, resolveApplication, rollbackApplication, stopRelease, streamBuildLogs, streamReleaseLogs, updateApplication, wakeApplication, pauseApplication, verifyApplicationDomain, } from '../utils/api.js';
-import { createZipBase64, isSettledReleaseStatus, isTerminalBuildStatus } from '../sdk.js';
-import { formatBytes, formatElapsed, humanizeApiError, permanentAddress, presentRelease, } from '../utils/apps-presentation.js';
+import { listAppBackups, getAppBackup, createAppBackup, deleteAppBackup, restoreAppBackup, getAppConnectionUrl, connectApps, createApiClient, addApplicationDomain, archiveApplication, cancelBuild, createApplication, getBuild, listApplicationDomains, listBuilds, queueBuild, removeApplicationDomain, createRelease, redeployApplication, execInApplication, getAppLimits, getAppLocation, getApplication, getProject, getProductionReplacement, getRelease, listApplications, promoteRelease, isPromoteAccepted, requireAuth, resolveApplication, rollbackApplication, stopRelease, streamBuildLogs, streamReleaseLogs, updateApplication, wakeApplication, pauseApplication, verifyApplicationDomain, } from '../utils/api.js';
+import { ApiError, DEFAULT_BUILD_TIMEOUT_POLICY, getAppLogHistory, isSettledReleaseStatus, isTerminalBuildStatus } from '../sdk.js';
+import { formatBytes, formatElapsed, humanizeApiError, permanentAddress, presentRelease, replacementPhaseMeaning, } from '../utils/apps-presentation.js';
 import { buildApiOptions, runtime } from '../utils/context.js';
 import { confirm } from '../utils/prompt.js';
 import { resolveCreateProject } from '../utils/project-context.js';
-import { CliError, ExitCode, usageError } from '../utils/errors.js';
+import { CliError, ExitCode, toCliError, usageError } from '../utils/errors.js';
 import { redact, registerSecret } from '../utils/redact.js';
-import { dim, formatTable, printCommandHelp, printError, printInfo, printLine, printSuccess } from '../utils/output.js';
+import { dim, formatTable, printCommandHelp, printError, printInfo, printLine, printSuccess, printWarning } from '../utils/output.js';
+import { containerPathArgument, MSYS_PATH_HINT } from '../utils/msys-path.js';
+import { packSourceForUpload } from '../utils/source-pack.js';
 /** Value flags across every subcommand — readPositionalArgs must know them all. */
 const VALUE_FLAGS = [
+    ...OBSERVATION_VALUE_FLAGS,
+    ...RESOURCES_VALUE_FLAGS,
     '--project',
     '--template',
     '--image',
@@ -22,6 +31,7 @@ const VALUE_FLAGS = [
     '--set',
     '--memory',
     '--cpu',
+    '--drain-grace',
     '--health-path',
     '--health-command',
     '--description',
@@ -45,6 +55,8 @@ const VALUE_FLAGS = [
     '--stabilization',
     '--scale-down-stabilization',
     '--replicas',
+    '--node-selector',
+    '--location',
 ];
 export async function appsCommand(args) {
     const [subcommand, ...rest] = readPositionalArgs(args, { valueFlags: VALUE_FLAGS });
@@ -76,7 +88,21 @@ export async function appsCommand(args) {
         case 'status':
             return statusSubcommand(args, rest, apiOptions);
         case 'logs':
+            if (hasFlag(args, '--history'))
+                return logHistorySubcommand(args, rest, apiOptions);
             return logsSubcommand(args, rest, apiOptions);
+        case 'metrics':
+            return metricsSubcommand(args, rest, apiOptions);
+        case 'log-history':
+            return logHistorySubcommand(args, rest, apiOptions);
+        case 'alerts':
+            return alertsSubcommand(args, rest, apiOptions);
+        case 'resources':
+            return resourcesSubcommand(args, rest, apiOptions);
+        case 'describe':
+            return describeSubcommand(args, rest, apiOptions);
+        case 'instances':
+            return instancesSubcommand(args, rest, apiOptions);
         case 'promote':
             return promoteSubcommand(args, rest, apiOptions);
         case 'rollback':
@@ -124,12 +150,18 @@ function printAppsHelp() {
         'build <app> [--dir <path>]  Build an image from source (Dockerfile) without releasing',
         'builds <app>                List image builds',
         'status <app>                Endpoints and recent releases',
-        'logs <app|release|build>    Stream container (or build) logs',
+        'describe <app>              Why it is (not) running: conditions, placement, events',
+        'instances <app>             Replicas (like pods): name, state, runner, CPU/RAM now',
+        'logs <app|release|build>    Recent container (or build) logs, then follow (--no-follow exits)',
+        'log-history <app>          Persisted runtime or HTTP logs with time/replica filters',
+        'metrics <app>              CPU/RAM, network, disk I/O or HTTP history (--json)',
+        'alerts <app> [action]      Configure resource/deployment alerts and read incidents',
+        'resources recommend <app>   CPU/RAM right-sizing from observed usage (read-only)',
         'promote <release>           Send production traffic to a release',
         'rollback <app>              Return production to the previous release',
         'stop <release>              Stop a release that is not serving production',
-        'exec <release> -- <cmd>     Run a command inside the container',
-        'update <app>                Change env vars, ports, resources, egress',
+        'exec <app> [--replica <r>] -- <cmd>  Run a command in production (one replica: name or index)',
+        'update <app>                Change env vars, ports, resources, egress, node selector',
         'scale <app> [mode]          Set always/http/manual scaling (--replicas for always)',
         'wake <app>                  Start a sleeping application',
         'pause <app>                 Stop an http/manual app (HTTP wakes only http mode)',
@@ -137,10 +169,10 @@ function printAppsHelp() {
         'delete <app>                Archive an application (stops every release)',
         '',
         'Create/deploy flags:',
-        '--project <id|slug>         create: use this project (overrides projects use)',
+        '--project <project>         create: this project by id, slug or unique name (overrides projects use)',
         '--image <ref>               Container image, e.g. nginx:alpine (omit to build from source)',
         '--promote                   deploy: take production by itself once healthy (needs apps:promote)',
-        '--template <name>           postgres | redis: volume, stable TCP endpoint, generated password, first release',
+        '--template <name>           postgres | redis: volume, private TCP endpoint, generated password, first release',
         '--dir <path>                Source directory to build (default: current directory)',
         '--dockerfile <path>         Dockerfile relative to the context (default: Dockerfile)',
         '--context <path>            Build context inside the source tree (default: .)',
@@ -150,9 +182,14 @@ function printAppsHelp() {
         '--tcp <name:port[:public]>  Extra TCP port; endpoint port is platform-managed (repeatable)',
         '--volume <name:/path[:ro]> Persistent volume mount (repeatable)',
         '--volume-runner <id>        Pin volumes (and the container) to a worker runner',
+        '--node-selector KEY=VALUE   update: run only on servers with this node label (repeatable),',
+        '                            e.g. inquir.io/region=eu; --clear-node-selector removes it',
+        '--location <id|auto>        update (experimental): run in this location, e.g. nl or ru; auto',
+        '                            runs wherever there is capacity. Applies from the next deploy',
         '--set KEY=VALUE             Environment variable (repeatable)',
         '--memory <mb>               Memory ceiling (default 512)',
         '--cpu <vcpus>               CPU ceiling (default 0.5)',
+        '--drain-grace <seconds>     Time the old container gets after SIGTERM before it is killed (0-3600)',
         '--egress <none|full>        Outbound network policy',
         '--ingress <private|public>  Public Networking: public creates the generated domain (new apps are private)',
         '--health-path </path>       HTTP health check path',
@@ -210,6 +247,77 @@ export function parseTcpPortFlag(value) {
     }
     return spec;
 }
+/**
+ * `--location <id|auto>`: the service's location, verbatim; the server says
+ * which ids it offers. Undefined when the flag is absent.
+ */
+export function parseLocationFlag(value) {
+    if (value === undefined)
+        return undefined;
+    const location = value.trim().toLowerCase();
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/.test(location)) {
+        throw usageError(`Invalid --location value '${value}'`, 'inquir apps update <app> --location nl   (or --location auto)');
+    }
+    return location;
+}
+/**
+ * The status line of a service's location: its setting by name, what
+ * production runs with while a change waits for the next deploy, and where
+ * the replicas run. Undefined while the platform offers no location choice.
+ */
+export function describeServiceLocation(status) {
+    if (!status.enabled)
+        return undefined;
+    const name = (id) => (id === 'auto' ? 'Auto' : status.locations.find((entry) => entry.id === id)?.name ?? id);
+    const parts = [status.setting === 'auto' ? 'Auto (wherever there is capacity)' : name(status.setting)];
+    if (status.pending && status.applied !== null) {
+        parts.push(`applies on the next deploy (production runs ${status.applied === 'auto' ? 'without a location' : `in ${name(status.applied)}`})`);
+    }
+    const running = [...new Set(status.replicas.map((replica) => (replica.location ? name(replica.location) : 'a server without a location')))];
+    if (running.length > 0)
+        parts.push(`running in ${running.join(', ')}`);
+    return parts.join(' — ');
+}
+/**
+ * `--node-selector KEY=VALUE` (repeatable): the node labels a server must
+ * carry, verbatim (`inquir.io/region=eu`, `tier=fast`). The server validates
+ * keys and values and says which keys it exposes.
+ */
+export function parseNodeSelectorFlags(values) {
+    const selector = {};
+    for (const entry of values) {
+        const index = entry.indexOf('=');
+        const key = index > 0 ? entry.slice(0, index).trim() : '';
+        if (!key) {
+            throw usageError(`Invalid --node-selector value '${entry}'`, 'inquir apps update <app> --node-selector inquir.io/region=eu');
+        }
+        if (Object.hasOwn(selector, key)) {
+            throw usageError(`--node-selector repeats the key '${key}'`, 'inquir apps update <app> --node-selector inquir.io/region=eu');
+        }
+        selector[key] = entry.slice(index + 1).trim();
+    }
+    return selector;
+}
+/**
+ * The runtime defaults with `--node-selector` / `--clear-node-selector`
+ * applied over `base` (the flags' runtime, else the stored one); undefined
+ * when neither flag is given.
+ */
+export function applyNodeSelectorFlags(args, base) {
+    const values = readMultiFlag(args, '--node-selector');
+    const clear = hasFlag(args, '--clear-node-selector');
+    if (values.length === 0 && !clear)
+        return undefined;
+    if (values.length > 0 && clear) {
+        throw usageError('Use either --node-selector or --clear-node-selector', 'inquir apps update <app> --clear-node-selector');
+    }
+    if (!base) {
+        throw usageError('This application has no runtime defaults to place; set its port first', 'inquir apps update <app> --port 3000 --node-selector inquir.io/region=eu');
+    }
+    const rest = { ...base };
+    delete rest.nodeSelector;
+    return clear ? rest : { ...rest, nodeSelector: parseNodeSelectorFlags(values) };
+}
 export function parseSetFlags(values) {
     const env = {};
     for (const entry of values) {
@@ -306,6 +414,7 @@ export function buildScalingPatchFromFlags(args, positionalActivation) {
 }
 const VOLUME_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
 const MAX_APP_VOLUMES = 16;
+// eslint-disable-next-line no-control-regex -- Container mount paths must reject control characters.
 const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
 /** `--volume name:/absolute/container/path[:ro]`; host paths are never accepted. */
 export function parseVolumeFlag(value) {
@@ -314,7 +423,7 @@ export function parseVolumeFlag(value) {
     let mountPath = separator > 0 ? value.slice(separator + 1) : '';
     let readOnly = false;
     if (/^[A-Za-z]:[\\/]/.test(mountPath)) {
-        throw usageError(`Invalid --volume mount path '${mountPath}'`, 'Volume targets are absolute paths inside the Linux container, for example data:/var/lib/data');
+        throw usageError(`Invalid --volume mount path '${mountPath}'`, `Volume targets are absolute paths inside the Linux container, for example data:/var/lib/data. ${MSYS_PATH_HINT}`);
     }
     const modifierAt = mountPath.lastIndexOf(':');
     if (modifierAt >= 0) {
@@ -375,6 +484,16 @@ function mergeVolumes(base, overrides) {
     assertVolumeSet(merged);
     return merged;
 }
+/** Largest `runtimeSpec.drainGraceSeconds` the API accepts. */
+const MAX_DRAIN_GRACE_SECONDS = 3600;
+/** `--drain-grace <seconds>`: whole seconds, 0..3600, as the API's runtime schema. */
+export function parseDrainGraceFlag(value) {
+    const seconds = /^\d{1,4}$/.test(value) ? Number(value) : Number.NaN;
+    if (!(seconds <= MAX_DRAIN_GRACE_SECONDS)) {
+        throw usageError(`Invalid --drain-grace value '${value}' (whole seconds, 0-${MAX_DRAIN_GRACE_SECONDS})`, 'inquir apps deploy <app> --drain-grace 30');
+    }
+    return seconds;
+}
 /** Runtime flags patch the saved application runtime rather than replacing unrelated fields. */
 export function buildRuntimeFromFlags(args, baseRuntime) {
     const portRaw = readFlagValue(args, '--port');
@@ -382,7 +501,13 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
     const volumeValues = readMultiFlag(args, '--volume');
     const memory = readFlagValue(args, '--memory');
     const cpu = readFlagValue(args, '--cpu');
-    const healthPath = readFlagValue(args, '--health-path');
+    const drainGraceRaw = readFlagValue(args, '--drain-grace');
+    const healthPathRaw = readFlagValue(args, '--health-path');
+    const healthPathArgument = healthPathRaw !== undefined ? containerPathArgument(healthPathRaw, '--health-path') : undefined;
+    if (healthPathArgument?.recoveredFrom) {
+        printWarning(`--health-path: read '${healthPathArgument.recoveredFrom}' as ${healthPathArgument.value} (Git Bash path conversion). ${MSYS_PATH_HINT}`);
+    }
+    const healthPath = healthPathArgument?.value;
     const healthCommand = readFlagValue(args, '--health-command');
     const ports = tcpValues.map(parseTcpPortFlag);
     const volumes = volumeValues.map(parseVolumeFlag);
@@ -390,7 +515,13 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
     if (portRaw && (!Number.isInteger(port) || port < 1 || port > 65535)) {
         throw usageError(`Invalid --port value '${portRaw}'`, 'inquir apps create <name> --port 3000');
     }
-    if (!portRaw && tcpValues.length === 0 && volumeValues.length === 0 && !memory && !cpu && !healthPath && !healthCommand) {
+    // `--drain-grace` without a value reads as undefined; refuse it rather than
+    // silently deploying without the setting the caller asked for.
+    if (drainGraceRaw === undefined && hasFlag(args, '--drain-grace'))
+        parseDrainGraceFlag('');
+    const drainGraceSeconds = drainGraceRaw !== undefined ? parseDrainGraceFlag(drainGraceRaw) : undefined;
+    if (!portRaw && tcpValues.length === 0 && volumeValues.length === 0 && !memory && !cpu &&
+        drainGraceSeconds === undefined && !healthPath && !healthCommand) {
         return undefined;
     }
     const spec = {
@@ -398,6 +529,7 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
         ...(portRaw ? { port } : {}),
         ...(tcpValues.length > 0 ? { ports } : {}),
         ...(volumeValues.length > 0 ? { volumes: mergeVolumes(baseRuntime?.volumes, volumes) } : {}),
+        ...(drainGraceSeconds !== undefined ? { drainGraceSeconds } : {}),
     };
     if (memory || cpu) {
         const parsedMemory = memory ? Number(memory) : (baseRuntime?.resources?.memoryMb ?? 512);
@@ -453,7 +585,7 @@ async function createAppSubcommand(args, positionals, apiOptions) {
     if (!name)
         throw usageError('Missing application name', 'inquir apps create <name> --port 3000');
     if (positionals.length > 1)
-        throw usageError('Expected one application name', 'inquir apps create <name> --project <id|slug>');
+        throw usageError('Expected one application name', 'inquir apps create <name> --project <project>');
     await requireAuth(apiOptions);
     const template = readFlagValue(args, '--template');
     if (template && !TEMPLATE_NAMES.includes(template)) {
@@ -477,7 +609,22 @@ async function createAppSubcommand(args, positionals, apiOptions) {
         runtime: buildRuntimeFromFlags(args),
         ...(Object.keys(envVars).length > 0 ? { envVars } : {}),
         ...(networkPolicy ? { networkPolicy } : {}),
-    }, project.apiOptions);
+    }, project.apiOptions).catch((error) => {
+        // A worker runner pulls only a digest-pinned registry image, and this
+        // installation has no mirror of the template's image yet.
+        if (error instanceof ApiError && error.code === 'APP_TEMPLATE_IMAGE_NOT_MIRRORED') {
+            throw new CliError(`The ${template} template cannot run on a worker runner on this installation yet`, {
+                code: error.code,
+                exitCode: ExitCode.ERROR,
+                requestId: error.requestId,
+                details: error.payload,
+                explanation: error.message,
+                fix: 'An operator mirrors the template image into the platform registry and sets APPS_TEMPLATE_IMAGES (docs/operations/template-images.md). Until then, create the database without --volume-runner: it runs on the control-plane runner.',
+                command: `inquir apps create ${name} --template ${template}`,
+            });
+        }
+        throw error;
+    });
     const firstRelease = app.firstRelease;
     if (readJsonFlag(args)) {
         // A scripted create must answer the same question the human one does:
@@ -490,8 +637,9 @@ async function createAppSubcommand(args, positionals, apiOptions) {
     }
     printSuccess(`Created application ${app.name}`);
     printInfo(dim(`  id: ${app.id}`));
-    if (app.projectIds?.length)
-        printInfo(dim(`  project: ${app.projectIds.join(', ')}`));
+    for (const line of await landingProjectLines(app, project.projectId, project.apiOptions)) {
+        printInfo(dim(`  ${line}`));
+    }
     if (template && firstRelease) {
         printInfo(dim(`  template: ${template} — first release ${firstRelease.releaseId.slice(0, 8)} is starting`));
         const release = await waitForRelease(firstRelease.releaseId, project.apiOptions);
@@ -507,9 +655,148 @@ async function createAppSubcommand(args, positionals, apiOptions) {
     printInfo(dim(`  deploy it: inquir apps deploy ${app.name}            (builds the Dockerfile in the current directory)`));
     printInfo(dim(`         or: inquir apps deploy ${app.name} --image <ref>`));
 }
+/**
+ * Which project a new application landed in, by name. With neither --project
+ * nor a selection the server creates one named after the application, so a
+ * database and the app using it land in two projects: say so, and how to
+ * group them.
+ */
+async function landingProjectLines(app, requestedProject, apiOptions) {
+    const projectId = app.projectIds?.[0];
+    if (!projectId)
+        return [];
+    const project = await getProject(projectId, apiOptions).catch(() => null);
+    const label = project ? `${project.name} (${project.slug})` : projectId;
+    if (requestedProject)
+        return [`project: ${label}`];
+    return [
+        `project: ${label}, created for it since no project is selected here`,
+        `  group it with another application: inquir projects move <project> ${app.name}`,
+        '  put new applications in one project: inquir projects use <project>',
+    ];
+}
 const TEMPLATE_NAMES = ['postgres', 'redis'];
 /** `apps <sub> --help` answered per subcommand; the global page is the fallback. */
-const SUBCOMMAND_HELP = {
+export const SUBCOMMAND_HELP = {
+    ...OBSERVATION_HELP,
+    ...RESOURCES_HELP,
+    ...DESCRIBE_HELP,
+    ...INSTANCES_HELP,
+    logs: [
+        'Usage: inquir apps logs <app|release|build> [--tail <n>] [--no-follow] [--replica <name|index|allocation>]',
+        '  Prints the last --tail lines (default 200, at most 2000), then follows new',
+        '  ones until Ctrl-C.',
+        '  --no-follow Print the last --tail lines and exit (for scripts and agents).',
+        '  --replica   Only one replica\'s lines (see apps instances <app>).',
+        '  --history selects persisted history instead; see apps log-history --help.',
+    ],
+    exec: [
+        'Usage: inquir apps exec <app> [--replica <name|index|allocation>] [--timeout <ms>] -- <command>',
+        '  Runs one audited command in the production container. <app> is the',
+        '  application name or id; the id of its production release works too.',
+        '  --replica   One serving replica (see apps instances <app>); default: the projected one.',
+    ],
+    list: [
+        'Usage: inquir apps list [--json]',
+        '',
+        '  The workspace\'s applications with their production status.',
+    ],
+    deploy: [
+        'Usage: inquir apps deploy <app> [--image <ref> | --build <buildId> | --dir <path>] [--promote] [--no-wait]',
+        '',
+        '  Without --image or --build, packs the source directory (default: the',
+        '  current one), builds its Dockerfile and releases the image as a preview.',
+        '  The upload honours .dockerignore and .inquirignore and never contains',
+        '  .env files, private keys or literal registry tokens.',
+        '  --image <ref>        Release a container image instead of building',
+        '  --build <buildId>    Release an existing successful build',
+        '  --dir <path>         Source directory (default: current directory)',
+        '  --dockerfile, --context, --target, --build-arg KEY=VALUE  Build options',
+        '  --promote            Take production by itself once healthy (needs apps:promote)',
+        '  --no-wait            Return as soon as the release is queued',
+        '  Runtime flags (--port, --tcp, --volume, --set, --memory, --cpu, ...) as in apps --help.',
+    ],
+    status: [
+        'Usage: inquir apps status <app> [--json]',
+        '',
+        '  Production, endpoints (public URL, private address, TCP ports), volumes',
+        '  and recent releases.',
+    ],
+    rollback: [
+        'Usage: inquir apps rollback <app> [--json]',
+        '',
+        '  Returns production to the previous release: instantly while its container',
+        '  still runs, otherwise after it restarts and passes its health check.',
+    ],
+    stop: [
+        'Usage: inquir apps stop <release>',
+        '',
+        '  Stops a release that is not serving production; its container and preview',
+        '  URL go away.',
+    ],
+    build: [
+        'Usage: inquir apps build <app> [--dir <path>] [--dockerfile <path>] [--context <path>] [--target <stage>] [--build-arg KEY=VALUE]',
+        '',
+        '  Builds an image from source without releasing it (release it later with',
+        '  apps deploy <app> --build <buildId>). Uploads like apps deploy.',
+    ],
+    builds: [
+        'Usage: inquir apps builds <app> [--cancel <buildId>] [--json]',
+        '',
+        '  Lists the application\'s image builds; --cancel stops a queued or running one.',
+    ],
+    update: [
+        'Usage: inquir apps update <app> [--set KEY=VALUE] [--port <n>] [--memory <mb>] [--cpu <vcpus>] [--ingress private|public] [flags]',
+        '',
+        '  Applied now: --ingress (the generated public domain is created or removed',
+        '  at once) and --description.',
+        '  Applied by the next release (inquir apps redeploy <app>): --set, --port,',
+        '  --tcp, --volume, --memory, --cpu, --drain-grace, --health-path,',
+        '  --health-command, --egress, --location, --node-selector / --clear-node-selector.',
+    ],
+    scale: [
+        'Usage: inquir apps scale <app> <always|http|manual> [--replicas <n>] [--idle-timeout <d>] [--activation-timeout <d>] [--stabilization <d>]',
+        '',
+        '  always   Keep --replicas replicas running (1..8)',
+        '  http     Sleep after --idle-timeout without requests (minimum 5m); a request wakes it',
+        '  manual   Run until paused; only wake starts it again',
+        '  Durations: 90s, 15m, 1h30m. Takes effect now.',
+        '',
+        'Examples:',
+        '  inquir apps scale web always --replicas 2',
+        '  inquir apps scale web http --idle-timeout 15m',
+    ],
+    wake: [
+        'Usage: inquir apps wake <app> [--json]',
+        '',
+        '  Starts a sleeping (http) or paused (manual) application.',
+    ],
+    pause: [
+        'Usage: inquir apps pause <app> [--json]',
+        '',
+        '  Stops an http or manual application; an http one wakes on the next request.',
+    ],
+    domain: [
+        'Usage: inquir apps domain <app> [hostname] [--verify | --remove] [--json]',
+        '',
+        '  Without a hostname, lists the bound domains. With one, binds it and prints',
+        '  the DNS records to create; --verify checks them, --remove unbinds it.',
+    ],
+    delete: [
+        'Usage: inquir apps delete <app>',
+        '',
+        '  Archives the application and stops every release. Refused while another',
+        '  application depends on it (apps connect).',
+    ],
+    promote: [
+        'Usage: inquir apps promote <release> [--no-wait] [--json]',
+        '',
+        '  Sends production traffic to a healthy release. A multi-replica service',
+        '  may be promoted as a rolling rollout: the server starts the new replicas a',
+        '  few at a time and switches production once enough of them serve, and the',
+        '  CLI follows it until then.',
+        '  --no-wait           Return as soon as the rollout has started',
+    ],
     redeploy: [
         'Usage: inquir apps redeploy <app> [--no-promote] [--no-wait]',
         '',
@@ -525,14 +812,18 @@ const SUBCOMMAND_HELP = {
     create: [
         'Usage: inquir apps create <name> [--template postgres|redis] [flags]',
         '',
-        '  --project <id|slug>  Add to this project. Otherwise uses projects use;',
-        '                      without a selection, creates a project named after the app.',
-        '  --template <name>   postgres | redis: volume, pinned public TCP port,',
-        '                      generated password, and the first release — one command',
-        '                      from nothing to a running database.',
+        '  --project <project>  Add to this project (id, slug or unique name). Otherwise',
+        '                      uses projects use; without a selection, creates a project',
+        '                      named after the app (group it later: inquir projects move).',
+        '  --template <name>   postgres | redis: a volume, a private TCP port',
+        '                      (<slug>.apps.internal, reachable from your other',
+        '                      services), a generated password and the first release —',
+        '                      one command from nothing to a running database.',
         '  --volume-runner <id>  Pin volumes + container to a worker runner (id or',
-        '                      unique prefix); the data lives on that machine.',
-        '  --port, --tcp, --volume, --memory, --cpu, --health-command, --set KEY=VALUE',
+        '                      unique prefix); the data lives on that machine. With',
+        '                      --template the worker runs the operator\'s digest-pinned',
+        '                      mirror of the template image (APPS_TEMPLATE_IMAGES).',
+        '  --port, --tcp, --volume, --memory, --cpu, --drain-grace, --health-command, --set KEY=VALUE',
         '',
         'Examples:',
         '  inquir apps create mydb --template postgres',
@@ -559,6 +850,9 @@ const SUBCOMMAND_HELP = {
         'Writes the database connection URL into the target app\'s environment',
         '(DATABASE_URL for postgres, REDIS_URL for redis). The password never',
         'passes through your terminal. Takes effect on the target\'s next release.',
+        'The URL names the database\'s private address, <slug>.apps.internal:<port>,',
+        'on the control-plane runner and on a worker alike, once the platform has',
+        'verified it (`inquir apps status <db>` lists it).',
         '',
         '  --overwrite   Replace a DATABASE_URL/REDIS_URL the target already has —',
         '                e.g. to repoint it at the database\'s private address',
@@ -574,8 +868,55 @@ const SUBCOMMAND_HELP = {
     ],
 };
 const BACKUPS_USAGE = 'inquir apps backups <app> [list|create|restore <backupId>|delete <backupId>]';
+/**
+ * "2/3 ~10-08 14:00": the row's place among its volume's backups of the same
+ * kind, and roughly when it goes; "next cleanup" once past the limit.
+ */
+export function formatBackupKeeps(backup) {
+    const retention = backup.retention;
+    if (!retention)
+        return '';
+    const place = `${retention.position}/${retention.limit}`;
+    if (!retention.kept)
+        return `${place} next cleanup`;
+    if (!retention.expiresAt)
+        return place;
+    return `${place} ~${retention.expiresAt.slice(5, 16).replace('T', ' ')}`;
+}
+/** One line on what the workspace's backup policy keeps. */
+export function formatBackupPolicy(policy) {
+    const owner = policy.source === 'override' ? 'This workspace' : `Plan ${policy.planCode}`;
+    const every = policy.frequencyHours === 24 ? 'daily' : `every ${policy.frequencyHours}h`;
+    const automatic = policy.automatic
+        ? `the last ${policy.retainCount} automatic backup(s) (${every})`
+        : 'no automatic backups';
+    let line = `${owner} keeps ${automatic} and ${policy.maxManualBackups} manual backup(s) per volume`;
+    if (policy.grace)
+        line += `; after a plan change, up to ${policy.grace.retainCount} are kept until ${policy.grace.until.slice(0, 10)}`;
+    if (!policy.automaticAvailable && policy.automaticUnavailableReason === 'volume_on_worker') {
+        line += '; this app\'s volumes live on a worker, where the platform cannot back them up yet';
+    }
+    return line;
+}
+/**
+ * An empty backup list. A volume on a worker runner cannot be snapshotted by
+ * the platform yet, and `create` is refused there too: say so instead of
+ * suggesting it.
+ */
+export function emptyBackupsLines(appName, policy) {
+    if (policy && !policy.automaticAvailable && policy.automaticUnavailableReason === 'volume_on_worker') {
+        return [
+            `No backups for ${appName}: its volume lives on a worker runner, where the platform cannot back up volumes yet`,
+            '  (automatic or on demand; `backups create` is refused there too). Runner-side backups are in progress.',
+            '  Until then, see "Backups before risky changes" in the Node.js + Postgres tutorial:',
+            '  https://inquir.org/docs/node-postgres',
+        ];
+    }
+    return [`No backups for ${appName} yet — create one: inquir apps backups ${appName} create`];
+}
 /** The one backup table: `create` prints it too, once the rows settle. */
 function renderBackupTable(items) {
+    const keeps = items.some((b) => b.retention);
     printLine(formatTable(items.map((b) => ({
         id: b.id.slice(0, 8),
         volume: b.volumeName,
@@ -583,7 +924,10 @@ function renderBackupTable(items) {
         trigger: b.trigger,
         size: formatBytes(b.sizeBytes ?? b.artifactSizeBytes),
         created: b.createdAt.replace('T', ' ').slice(0, 19),
-    })), ['id', 'volume', 'status', 'trigger', 'size', 'created']));
+        keeps: formatBackupKeeps(b),
+    })), keeps
+        ? ['id', 'volume', 'status', 'trigger', 'size', 'created', 'keeps']
+        : ['id', 'volume', 'status', 'trigger', 'size', 'created']));
 }
 /** Accept a short id, the way the release commands do. */
 async function resolveBackup(applicationId, needle, identifier, apiOptions) {
@@ -655,9 +999,12 @@ async function backupsSubcommand(args, positionals, apiOptions) {
         if (json)
             return printLine(JSON.stringify(page, null, 2));
         if (page.items.length === 0) {
-            printInfo(`No backups for ${app.name} yet — create one: inquir apps backups ${app.name} create`);
+            for (const line of emptyBackupsLines(app.name, page.policy))
+                printInfo(line);
             return;
         }
+        if (page.policy)
+            printInfo(dim(formatBackupPolicy(page.policy)));
         renderBackupTable(page.items);
         if (page.nextCursor) {
             printInfo(dim(`  older: inquir apps backups ${app.name} list --cursor ${page.nextCursor}`));
@@ -729,6 +1076,90 @@ async function backupsSubcommand(args, positionals, apiOptions) {
     }
     throw usageError(`Unknown backups action '${verb}'`, BACKUPS_USAGE);
 }
+/**
+ * The refusals of `apps connect` and `apps connection-url`, told as what to do
+ * next. The server's code and message are kept; the cause, the fix and the
+ * command to try are the CLI's. Anything else passes through unchanged to the
+ * generic rendering.
+ */
+export function explainDatabaseConnectionError(error, context) {
+    if (!(error instanceof ApiError) || !error.code)
+        return error;
+    const { database, target } = context;
+    const base = {
+        code: error.code,
+        exitCode: ExitCode.ERROR,
+        requestId: error.requestId,
+        details: error.payload,
+    };
+    const status = `inquir apps status ${database}`;
+    const retry = target ? `inquir apps connect ${database} ${target}` : `inquir apps connection-url ${database}`;
+    switch (error.code) {
+        case 'APP_NOT_A_TEMPLATE':
+            return new CliError(`${database} was not created from a database template`, {
+                ...base,
+                explanation: 'connect and connection-url compose URLs only for postgres and redis template databases: the template says which variables hold the user, the password and the database.',
+                fix: target
+                    ? `Create the database with --template (on a worker too: --template postgres --volume-runner <runner>), or set the URL on ${target} yourself; a URL set by hand is not recorded as a dependency.`
+                    : 'Create the database with --template (on a worker too: --template postgres --volume-runner <runner>), or compose the URL from its own credentials and its private address.',
+                command: target ? `inquir apps update ${target} --set DATABASE_URL=<url>` : status,
+            });
+        case 'APP_PRIVATE_ENDPOINT_NOT_READY':
+            return new CliError(`${database} has no verified private address yet`, {
+                ...base,
+                explanation: error.message,
+                cause: 'The platform verifies a database\'s private proxy once its replica serves, on a worker runner too, and re-checks it about every 20 seconds.',
+                fix: `Retry in a minute. If it lasts, check that the database is serving: ${status}`,
+                command: retry,
+            });
+        case 'APP_NO_TCP_ENDPOINT':
+            return new CliError(error.message, {
+                ...base,
+                // An older control plane also answers this for a database a worker
+                // serves: it looked for the port only in the release's port mappings,
+                // which such a release never has (src/apps/app-connection-endpoint.ts).
+                cause: 'The server found no private TCP port on the database\'s production release: it declares none, or it runs on a worker runner and the control plane predates reading those ports.',
+                fix: `Check the release's ports with ${status}. If it declares one (e.g. --tcp postgres:5432), the control plane needs the update that reads worker-served ports; otherwise declare the port and deploy the database again.`,
+                command: status,
+            });
+        case 'PRIVATE_NETWORK_NOT_CONFIGURED':
+            return new CliError(error.message, {
+                ...base,
+                cause: 'The control plane offers no private address for this database.',
+                fix: target
+                    ? 'connect writes private URLs only. A client outside the platform can use the public URL once Public Access is enabled on the database. If other apps have private addresses here, the database\'s may just not be verified yet: retry in a minute.'
+                    : 'Enable Public Access on the database and ask for its public URL. If other apps have private addresses here, the database\'s may just not be verified yet: retry in a minute.',
+                command: `inquir apps connection-url ${database} --public`,
+            });
+        case 'APP_NO_PRODUCTION_RELEASE':
+            return new CliError(error.message, {
+                ...base,
+                fix: 'Deploy the database first; a template database ships its first release when it is created.',
+                command: status,
+            });
+        case 'APP_PRODUCTION_RELEASE_NOT_ACTIVE':
+            return new CliError(error.message, {
+                ...base,
+                fix: 'Wait until its release serves: on a worker runner the replica must start and pass its health check first.',
+                command: status,
+            });
+        case 'APP_CREDENTIALS_MISSING':
+            return new CliError(error.message, {
+                ...base,
+                cause: 'The running release\'s env has no password under the template\'s key (POSTGRES_PASSWORD, REDIS_PASSWORD).',
+                fix: 'Set it on the database to the password its data actually uses, then deploy the database again; a new value does not change the password of existing data.',
+                command: `inquir apps update ${database} --set <POSTGRES_PASSWORD|REDIS_PASSWORD>=<password>`,
+            });
+        case 'ENV_KEY_ALREADY_SET':
+            return new CliError(error.message, {
+                ...base,
+                fix: 'Replace it on purpose: the new URL applies on the target\'s next release.',
+                command: `${retry} --overwrite`,
+            });
+        default:
+            return error;
+    }
+}
 async function connectSubcommand(args, positionals, apiOptions) {
     const [dbIdentifier, targetIdentifier] = positionals;
     if (!dbIdentifier || !targetIdentifier) {
@@ -740,7 +1171,9 @@ async function connectSubcommand(args, positionals, apiOptions) {
     // is how an app is repointed at the database's current private address
     // (the composed URL never passes through this terminal).
     const overwrite = args.includes('--overwrite');
-    const result = await connectApps(db.id, targetIdentifier, { ...apiOptions, overwrite });
+    const result = await connectApps(db.id, targetIdentifier, { ...apiOptions, overwrite }).catch((error) => {
+        throw explainDatabaseConnectionError(error, { database: db.name, target: targetIdentifier });
+    });
     if (readJsonFlag(args)) {
         return printLine(JSON.stringify(result, null, 2));
     }
@@ -753,7 +1186,9 @@ async function connectionUrlSubcommand(args, positionals, apiOptions) {
         throw usageError('Missing application', 'inquir apps connection-url mydb');
     await requireAuth(apiOptions);
     const app = await resolveApplication(identifier, apiOptions);
-    const result = await getAppConnectionUrl(app.id, apiOptions);
+    const result = await getAppConnectionUrl(app.id, apiOptions).catch((error) => {
+        throw explainDatabaseConnectionError(error, { database: app.name });
+    });
     const requirePrivate = args.includes('--private');
     const requirePublic = args.includes('--public');
     if (requirePrivate && requirePublic) {
@@ -788,9 +1223,12 @@ export function selectConnectionUrl(result, preference = 'auto') {
         return { url: result.publicUrl, visibility: 'public' };
     }
     const requested = preference === 'auto' ? 'private or public' : preference;
-    throw usageError(`No ${requested} database connection URL is available`, preference === 'public'
+    const reason = preference !== 'public' ? result.privateUnavailable : undefined;
+    throw usageError(`No ${requested} database connection URL is available${reason ? `: ${reason.message}` : ''}`, preference === 'public'
         ? 'Enable Public Access in the application Networking settings.'
-        : 'Configure private networking, or use --public after explicitly enabling Public Access.');
+        : reason?.code === 'APP_PRIVATE_ENDPOINT_NOT_READY'
+            ? 'Retry in a minute; the private address is verified once the database serves.'
+            : 'Configure private networking, or use --public after explicitly enabling Public Access.');
 }
 async function deploySubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
@@ -960,7 +1398,11 @@ async function runSourceBuild(applicationId, appName, args, apiOptions) {
     const buildArgs = parseSetFlags(readMultiFlag(args, '--build-arg'));
     if (!json)
         printInfo(dim(`— packing ${dir} —`));
-    const sourceZipBase64 = await createZipBase64(dir);
+    const sourceZipBase64 = await packSourceForUpload(dir, {
+        json,
+        ...(readFlagValue(args, '--context') ? { context: readFlagValue(args, '--context') } : {}),
+        ...(readFlagValue(args, '--dockerfile') ? { dockerfile: readFlagValue(args, '--dockerfile') } : {}),
+    });
     const queued = await queueBuild(applicationId, {
         sourceZipBase64,
         source: 'cli',
@@ -977,65 +1419,242 @@ async function runSourceBuild(applicationId, appName, args, apiOptions) {
             ? `Build ${queued.buildId.slice(0, 8)} reused (identical source already built)`
             : `Build ${queued.buildId.slice(0, 8)} queued for ${appName}`);
     }
-    if (queued.deduplicated || isTerminalBuildStatus(queued.status)) {
-        return getBuild(queued.buildId, apiOptions);
+    return waitForBuild(queued.buildId, apiOptions, {
+        json, initial: queued, noLogs: queued.deduplicated || isTerminalBuildStatus(queued.status),
+    });
+}
+const BUILD_WAIT_PHASE = { QUEUED: 'queued', EXECUTING: 'building' };
+const BUILD_WAIT_ERROR = { QUEUE: 'BUILD_QUEUE_TIMEOUT', EXECUTION: 'BUILD_TIMEOUT', STATUS_REQUEST: 'BUILD_STATUS_TIMEOUT' };
+const BUILD_STATUS_REQUEST_TIMEOUT_MS = 15_000;
+const BUILD_STATUS_POLL_INTERVAL_MS = 1_000;
+const BUILD_STATUS_RETRY_BACKOFF_MS = 2_000;
+const BUILD_LOG_DRAIN_TIMEOUT_MS = 250;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const HTTP_TOO_MANY_REQUESTS = 429;
+const HTTP_SERVER_ERROR_MIN = 500;
+function buildWaitPolicy(value) {
+    if (!value || !Number.isSafeInteger(value.executionTimeoutMs) || value.executionTimeoutMs < 1 ||
+        !Number.isSafeInteger(value.queueTimeoutMs) || value.queueTimeoutMs < 1 ||
+        !Number.isSafeInteger(value.completionGraceMs) || value.completionGraceMs < 0 ||
+        value.executionTimeoutMs > MAX_TIMER_DELAY_MS || value.queueTimeoutMs > MAX_TIMER_DELAY_MS ||
+        value.completionGraceMs > MAX_TIMER_DELAY_MS) {
+        return DEFAULT_BUILD_TIMEOUT_POLICY;
     }
-    // Follow the build log to the terminal event; the SSE stream ends on completion.
-    for await (const event of streamBuildLogs(queued.buildId, apiOptions)) {
-        if (event.type === 'log' && event.line) {
-            if (json)
-                process.stderr.write(`${redact(event.line)}\n`);
-            else
-                printLine(dim(`  ${event.line}`));
+    return value;
+}
+function buildWaitSleep(ms, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { clearTimeout(timer); signal.removeEventListener('abort', onAbort); reject(signal.reason); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** Authoritative phase observation, independent of an open or broken log stream. */
+export async function waitForBuild(buildId, apiOptions, options = {}) {
+    const clock = () => globalThis.performance.now();
+    const controller = new AbortController();
+    const initialPolicy = buildWaitPolicy(options.initial?.timeoutPolicy);
+    const overallDeadline = clock() + initialPolicy.queueTimeoutMs + initialPolicy.executionTimeoutMs + initialPolicy.completionGraceMs;
+    let phase = options.initial?.status === BUILD_WAIT_PHASE.EXECUTING
+        ? BUILD_WAIT_PHASE.EXECUTING : BUILD_WAIT_PHASE.QUEUED;
+    let deadline = overallDeadline;
+    let timer;
+    let expire;
+    const expired = new Promise((_, reject) => { expire = reject; });
+    function observe(value) {
+        const next = value.status === BUILD_WAIT_PHASE.EXECUTING ? BUILD_WAIT_PHASE.EXECUTING : BUILD_WAIT_PHASE.QUEUED;
+        // A stale queued observation cannot restart an already-running budget.
+        if (phase === BUILD_WAIT_PHASE.EXECUTING && next === BUILD_WAIT_PHASE.QUEUED)
+            return;
+        const policy = buildWaitPolicy(value.timeoutPolicy ?? initialPolicy);
+        const cap = next === BUILD_WAIT_PHASE.QUEUED ? policy.queueTimeoutMs : policy.executionTimeoutMs + policy.completionGraceMs;
+        const remaining = typeof value.timeoutRemainingMs === 'number' && Number.isFinite(value.timeoutRemainingMs) && value.timeoutRemainingMs >= 0
+            ? Math.min(value.timeoutRemainingMs, cap) : cap;
+        const candidate = Math.min(overallDeadline, clock() + remaining);
+        deadline = next === phase ? Math.min(deadline, candidate) : candidate;
+        phase = next;
+        armDeadline();
+    }
+    function armDeadline() {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            // Node clamps oversized delays to 1ms. Keep long valid policies bounded
+            // by scheduling slices, and tolerate a timer waking before its deadline.
+            if (clock() < deadline) {
+                armDeadline();
+                return;
+            }
+            const error = new CliError(`Build ${buildId} exceeded the CLI ${phase === BUILD_WAIT_PHASE.QUEUED ? 'queue' : 'execution'} wait deadline`, {
+                code: phase === BUILD_WAIT_PHASE.QUEUED ? BUILD_WAIT_ERROR.QUEUE : BUILD_WAIT_ERROR.EXECUTION, exitCode: ExitCode.ERROR,
+                explanation: `The CLI stopped waiting for build ${buildId}; it has not cancelled the remote build. Check this build before retrying.`,
+                fix: `Inspect its logs: inquir apps logs ${buildId}`,
+            });
+            expire(error);
+            controller.abort(error);
+        }, Math.min(MAX_TIMER_DELAY_MS, Math.max(0, deadline - clock())));
+    }
+    async function statusRequest() {
+        controller.signal.throwIfAborted();
+        const request = new AbortController();
+        const onAbort = () => request.abort(controller.signal.reason);
+        controller.signal.addEventListener('abort', onAbort, { once: true });
+        let requestTimer;
+        const timedOut = new Promise((_, reject) => {
+            requestTimer = setTimeout(() => {
+                const error = new CliError('Build status request timed out', { code: BUILD_WAIT_ERROR.STATUS_REQUEST, exitCode: ExitCode.NETWORK });
+                reject(error);
+                request.abort(error);
+            }, Math.min(BUILD_STATUS_REQUEST_TIMEOUT_MS, Math.max(0, deadline - clock())));
+        });
+        try {
+            return await Promise.race([getBuild(buildId, apiOptions, request.signal), timedOut]);
         }
-        else if (event.type === 'complete') {
-            break;
+        finally {
+            clearTimeout(requestTimer);
+            controller.signal.removeEventListener('abort', onAbort);
+            request.abort();
         }
-        else if (event.type === 'error') {
-            printLine(dim(`— ${event.message ?? 'stream error'} —`));
-            break;
+    }
+    async function poll() {
+        for (;;) {
+            controller.signal.throwIfAborted();
+            try {
+                const build = await statusRequest();
+                controller.signal.throwIfAborted();
+                if (isTerminalBuildStatus(build.status))
+                    return build;
+                observe(build);
+            }
+            catch (error) {
+                controller.signal.throwIfAborted();
+                const retryable = error instanceof ApiError ? error.status === HTTP_TOO_MANY_REQUESTS || error.status >= HTTP_SERVER_ERROR_MIN : toCliError(error).exitCode === ExitCode.NETWORK;
+                if (!retryable)
+                    throw error;
+                await buildWaitSleep(BUILD_STATUS_RETRY_BACKOFF_MS, controller.signal);
+            }
+            await buildWaitSleep(BUILD_STATUS_POLL_INTERVAL_MS, controller.signal);
         }
     }
-    return waitForBuild(queued.buildId, apiOptions);
-}
-async function waitForBuild(buildId, apiOptions, timeoutMs = 20 * 60_000) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        const build = await getBuild(buildId, apiOptions);
-        if (isTerminalBuildStatus(build.status))
-            return build;
-        if (Date.now() > deadline) {
-            throw new CliError(`Build ${buildId} did not finish within ${Math.round(timeoutMs / 1000)}s`, {
-                code: 'BUILD_TIMEOUT',
-                exitCode: ExitCode.ERROR,
-                fix: `Check its logs: inquir apps logs ${buildId}`,
-            });
+    async function consumeLogs() {
+        if (options.noLogs)
+            return;
+        try {
+            for await (const event of streamBuildLogs(buildId, apiOptions, controller.signal)) {
+                if (controller.signal.aborted)
+                    break;
+                if (event.type === 'log' && event.line) {
+                    if (options.json)
+                        process.stderr.write(`${redact(event.line)}\n`);
+                    else
+                        printLine(dim(`  ${event.line}`));
+                }
+                else if (event.type === 'complete' || event.type === 'error')
+                    break;
+            }
+        }
+        catch {
+            // Logs are best effort. Only the build row decides the result.
         }
-        await new Promise((resolve) => setTimeout(resolve, 1000));
     }
+    observe(options.initial ?? { status: BUILD_WAIT_PHASE.QUEUED });
+    const logs = consumeLogs();
+    try {
+        const result = await Promise.race([poll(), expired]);
+        let drainTimer;
+        try {
+            await Promise.race([logs, new Promise((resolve) => {
+                    drainTimer = setTimeout(resolve, Math.max(0, Math.min(BUILD_LOG_DRAIN_TIMEOUT_MS, deadline - clock())));
+                })]);
+        }
+        finally {
+            clearTimeout(drainTimer);
+        }
+        return result;
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+    }
+}
+/**
+ * A release only the allocation plane serves (volumes pinned to a worker) stays
+ * STARTING while that runner refuses its starts, and the plane retries them
+ * forever with backoff. After this many failed attempts the wait reports the
+ * reason instead of sitting out its whole timeout.
+ */
+const FAILED_STARTS_BEFORE_REPORTING = 3;
+/** Every how many release polls a running replacement's phase is re-read. */
+const REPLACEMENT_PROBE_EVERY = 5;
+/**
+ * The phase of the stop-first production replacement a PENDING release is
+ * the target of. Bounded: the operation is read on the first PENDING poll
+ * and then every REPLACEMENT_PROBE_EVERY polls, and never again once a read
+ * fails or names no replacement for this release (a preview, an older
+ * server), so an ordinary deploy costs one extra request.
+ */
+export function createReplacementProbe(read, every = REPLACEMENT_PROBE_EVERY) {
+    let polls = 0;
+    let done = false;
+    let phase = '';
+    return {
+        async phaseOf(release) {
+            if (done)
+                return '';
+            polls += 1;
+            if ((polls - 1) % every !== 0)
+                return phase;
+            const operation = await read(release.applicationId).catch(() => null);
+            if (!operation || operation.targetReleaseId !== release.id) {
+                done = true;
+                phase = '';
+                return '';
+            }
+            phase = operation.phase;
+            return phase;
+        },
+    };
 }
 /** Poll until the release settles; the platform decides when it is healthy. */
 async function waitForRelease(releaseId, apiOptions, timeoutMs = 10 * 60_000) {
     const deadline = Date.now() + timeoutMs;
     const startedAt = Date.now();
-    let lastStatus = '';
+    let lastProgress = '';
     const json = readJsonFlag(process.argv);
+    let replacementClient;
+    const replacement = createReplacementProbe(async (applicationId) => {
+        replacementClient ??= await createApiClient(apiOptions);
+        return getProductionReplacement(applicationId, apiOptions, replacementClient);
+    });
     for (;;) {
         const release = await getRelease(releaseId, apiOptions);
-        if (release.status !== lastStatus) {
-            lastStatus = release.status;
+        // A failed start on the pinned runner changes the reason, not the status.
+        const reason = release.serving ? release.failureReason ?? '' : '';
+        // PENDING is also the whole of a stop-first replacement of production,
+        // which pulls nothing: its phase says what the wait is.
+        const phase = release.status === 'PENDING' ? await replacement.phaseOf(release) : '';
+        if (`${release.status}\n${reason}\n${phase}` !== lastProgress) {
+            lastProgress = `${release.status}\n${reason}\n${phase}`;
             // Say what is happening in words, with elapsed time — a two-minute health
             // gate in silence reads as a hang. Under --json only stdout must stay
             // parseable; progress goes to stderr.
             const shown = presentRelease(release);
-            const line = `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${shown.meaning ? `: ${shown.meaning}` : ''} —`;
-            if (json)
-                process.stderr.write(`${line}\n`);
-            else
-                printInfo(dim(line));
+            const meaning = (phase && replacementPhaseMeaning(phase)) || shown.meaning;
+            const lines = [
+                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${meaning ? `: ${meaning}` : ''} —`,
+                ...(reason ? [`  ${reason}`] : []),
+            ];
+            for (const line of lines) {
+                if (json)
+                    process.stderr.write(`${line}\n`);
+                else
+                    printInfo(dim(line));
+            }
         }
         if (isSettledReleaseStatus(release.status))
             return release;
+        if ((release.serving?.failedStarts ?? 0) >= FAILED_STARTS_BEFORE_REPORTING)
+            return release;
         if (Date.now() > deadline) {
             throw new CliError(`Release ${releaseId} did not settle within ${Math.round(timeoutMs / 1000)}s`, {
                 code: 'RELEASE_TIMEOUT',
@@ -1106,17 +1725,30 @@ export function releaseEndpointLines(release, previewUrl, options = {}) {
  */
 export function privateEndpointLines(detail, active, options = {}) {
     if (!detail.privateDomain) {
-        return options.privateNetworking
-            ? ['(provisioning — private DNS and routing are being verified)']
-            : [];
+        if (!options.privateNetworking)
+            return [];
+        // The address routes to production, so without one there is nothing to
+        // verify yet, and with no serving replica it is down, not provisioning.
+        if (!active)
+            return ['(none yet — production gets one once a release is promoted)'];
+        if (active.serving && active.serving.ready === 0) {
+            return ['(unavailable — no production replica is serving; see inquir apps describe <app>)'];
+        }
+        return ['(provisioning — private DNS and routing are being verified)'];
     }
     const lines = [];
     if (detail.privateBaseUrl)
         lines.push(detail.privateBaseUrl);
-    for (const port of active?.ports ?? []) {
-        if (port.protocol !== 'tcp' || !port.containerPort)
-            continue;
-        lines.push(`${detail.privateDomain}:${port.containerPort}  (${port.name})`);
+    // The private proxy listens on a TCP port's container port. A container the
+    // control plane started reports its ports on the release; a release the
+    // allocation plane serves on a worker reports none (its endpoints live on
+    // its allocations), so its declared TCP ports stand in.
+    const reported = (active?.ports ?? []).filter((port) => port.protocol === 'tcp' && port.containerPort);
+    const tcpPorts = reported.length > 0
+        ? reported.map((port) => ({ name: port.name, port: port.containerPort }))
+        : (active?.runtime?.ports ?? []).filter((port) => port.protocol === 'tcp');
+    for (const port of tcpPorts) {
+        lines.push(`${detail.privateDomain}:${port.port}  (${port.name})`);
     }
     return lines;
 }
@@ -1180,6 +1812,18 @@ function formatDurationSeconds(seconds) {
     }
     return parts.join(' ');
 }
+/** One line for a startup probe; defaults as the server applies them (src/apps/startup-probe.ts). */
+export function describeStartupProbe(probe) {
+    const period = probe.periodSeconds ?? 10;
+    const threshold = probe.failureThreshold ?? 3;
+    const delay = probe.initialDelaySeconds ?? 0;
+    const mode = probe.type ?? (probe.command ? 'command' : undefined);
+    const target = mode === 'command'
+        ? `command ${JSON.stringify(probe.command ?? '')}`
+        : `${mode ?? 'probe'}${probe.port ? ` port ${probe.port}` : ''}${mode !== 'tcp' ? ` ${probe.path ?? '/'}` : ''}`;
+    return `${target}, every ${period}s, ${threshold} failure${threshold === 1 ? '' : 's'} allowed` +
+        `${delay ? ` after ${delay}s` : ''} (up to ${delay + period * threshold}s before the healthcheck)`;
+}
 export function describeScalingPolicy(policy) {
     const range = `${policy.minReplicas}–${policy.maxReplicas} replicas`;
     if (policy.activation === 'http') {
@@ -1215,6 +1859,20 @@ async function statusSubcommand(args, positionals, apiOptions) {
     const pinnedRunner = detail.volumeRunnerId;
     if (pinnedRunner)
         printLine(`  volume pin: runner ${pinnedRunner}`);
+    // Experimental service location: shown only where the platform offers it.
+    if (limits?.features?.serviceLocations) {
+        const location = await getAppLocation(app.id, apiOptions).catch(() => null);
+        const line = location ? describeServiceLocation(location) : undefined;
+        if (line)
+            printLine(`  location:   ${line}`);
+    }
+    if (detail.runtime?.startupProbe)
+        printLine(`  startup:    ${describeStartupProbe(detail.runtime.startupProbe)}`);
+    const servingRelease = detail.releases.find((r) => r.id === detail.production?.activeReleaseId);
+    if (servingRelease?.serving && servingRelease.serving.ready < servingRelease.serving.desired) {
+        // Production points at it, but its replica does not answer on the runner yet.
+        printLine(`  serving:    not yet — ${servingRelease.failureReason ?? 'its replica is starting on the pinned runner'}`);
+    }
     if (detail.lastActivityAt)
         printLine(`  activity:   ${detail.lastActivityAt}`);
     if (detail.lastScaledAt)
@@ -1350,29 +2008,74 @@ async function logsSubcommand(args, positionals, apiOptions) {
     const build = await getBuild(identifier, apiOptions).catch(() => null);
     if (build) {
         printInfo(dim(`— build ${build.id.slice(0, 8)} (${build.status}) —`));
-        for await (const event of streamBuildLogs(build.id, apiOptions)) {
-            if (event.type === 'log' && event.line) {
-                if (json)
-                    process.stderr.write(`${redact(event.line)}\n`);
-                else
-                    printLine(event.line);
-            }
-            else if (event.type === 'complete') {
-                printInfo(dim(`— build ${event.status ?? 'finished'} —`));
-                break;
-            }
-            else if (event.type === 'error') {
-                printLine(dim(`— ${event.message ?? 'stream error'} —`));
-                break;
+        // A finished build replays its log and the stream ends by itself. A
+        // running one follows; with --no-follow, stop once the replay goes quiet.
+        const stop = new AbortController();
+        const quiet = hasFlag(args, '--no-follow') && !isTerminalBuildStatus(build.status)
+            ? createQuietStop(() => stop.abort())
+            : null;
+        try {
+            for await (const event of streamBuildLogs(build.id, apiOptions, stop.signal)) {
+                quiet?.heard();
+                if (event.type === 'log' && event.line) {
+                    if (json)
+                        process.stderr.write(`${redact(event.line)}\n`);
+                    else
+                        printLine(event.line);
+                }
+                else if (event.type === 'complete') {
+                    printInfo(dim(`— build ${event.status ?? 'finished'} —`));
+                    break;
+                }
+                else if (event.type === 'error') {
+                    printLine(dim(`— ${event.message ?? 'stream error'} —`));
+                    break;
+                }
             }
         }
+        catch (error) {
+            if (!stop.signal.aborted)
+                throw error;
+        }
+        finally {
+            quiet?.cancel();
+        }
+        if (stop.signal.aborted) {
+            printInfo(dim(`— build ${build.id.slice(0, 8)} is still running; follow it: inquir apps logs ${build.id} —`));
+        }
         return;
     }
     const releaseId = await resolveReleaseId(identifier, apiOptions);
     const tailRaw = readFlagValue(args, '--tail');
     const tail = tailRaw ? Number(tailRaw) : 200;
-    printInfo(dim(`— streaming logs for release ${releaseId.slice(0, 8)} (ctrl-c to stop) —`));
-    for await (const event of streamReleaseLogs(releaseId, { tail }, apiOptions)) {
+    if (!Number.isInteger(tail) || tail < 1 || tail > MAX_LOG_TAIL) {
+        throw usageError(`--tail must be an integer between 1 and ${MAX_LOG_TAIL}`, 'inquir apps logs <app> --tail 100');
+    }
+    const replica = readFlagValue(args, '--replica');
+    if (hasFlag(args, '--replica') && !replica?.trim())
+        throw usageError('Missing --replica value', 'inquir apps instances <app>');
+    let allocationId;
+    if (replica?.trim()) {
+        const release = await getRelease(releaseId, apiOptions);
+        // Only this release's replicas: an index or name of production would be another container.
+        allocationId = await resolveReplicaAllocationId(release.applicationId, replica, apiOptions, { releaseId: release.id });
+    }
+    if (hasFlag(args, '--no-follow')) {
+        const release = await getRelease(releaseId, apiOptions);
+        const client = await createApiClient(apiOptions);
+        const entries = await readRecentRuntimeLogs((query) => getAppLogHistory(client, release.applicationId, query), { releaseId, tail, ...(allocationId ? { allocationId } : {}) });
+        if (json) {
+            printLine(redact(JSON.stringify(entries, null, 2)));
+            return;
+        }
+        for (const entry of entries)
+            printLine(entry.message);
+        if (entries.length === 0)
+            printInfo(dim(`— no stored logs for release ${releaseId.slice(0, 8)} —`));
+        return;
+    }
+    printInfo(dim(`— streaming logs for release ${releaseId.slice(0, 8)}${allocationId ? `, replica ${allocationId.slice(0, 8)}` : ''} (ctrl-c to stop) —`));
+    for await (const event of streamReleaseLogs(releaseId, { tail, ...(allocationId ? { allocationId } : {}) }, apiOptions)) {
         if (event.type === 'log' && event.line) {
             // Under --json the log tail goes to stderr so stdout stays parseable.
             if (json)
@@ -1389,6 +2092,63 @@ async function logsSubcommand(args, positionals, apiOptions) {
         }
     }
 }
+/** The most lines `apps logs --tail` asks for (the API's own ceiling). */
+const MAX_LOG_TAIL = 2000;
+/**
+ * How far back `--no-follow` reads: inside the 7-day runtime retention with
+ * an hour to spare, so a client clock up to an hour off still names a window
+ * the API accepts. `to` is left to the server's clock.
+ */
+const RUNTIME_LOG_WINDOW_MS = 7 * 86_400_000 - 3_600_000;
+/** `logs --no-follow` on a running build: stop once its replay is this quiet... */
+const BUILD_LOG_QUIET_MS = 2_000;
+/** ...or when nothing at all arrived this long after the request (a slow connection). */
+const BUILD_LOG_FIRST_EVENT_MS = 15_000;
+/**
+ * Calls `stop` once a stream goes quiet: BUILD_LOG_FIRST_EVENT_MS before the
+ * first event (connecting may be slow), BUILD_LOG_QUIET_MS after the latest.
+ */
+export function createQuietStop(stop, timings = { firstEventMs: BUILD_LOG_FIRST_EVENT_MS, quietMs: BUILD_LOG_QUIET_MS }) {
+    let timer = setTimeout(stop, timings.firstEventMs);
+    return {
+        heard() {
+            clearTimeout(timer);
+            timer = setTimeout(stop, timings.quietMs);
+        },
+        cancel() {
+            clearTimeout(timer);
+        },
+    };
+}
+const LOG_HISTORY_PAGE = 200;
+/**
+ * `apps logs --no-follow`: the last `tail` stored lines of one release (one
+ * replica with `allocationId`), oldest first — what the live stream prints
+ * before it starts following, without the following.
+ */
+export async function readRecentRuntimeLogs(fetchPage, options) {
+    const now = options.now ?? Date.now();
+    // The first page fixes the window; later pages repeat it with the cursor.
+    let window = { from: new Date(now - RUNTIME_LOG_WINDOW_MS).toISOString() };
+    const newestFirst = [];
+    let cursor;
+    while (newestFirst.length < options.tail) {
+        const page = await fetchPage({
+            ...window,
+            releaseId: options.releaseId,
+            ...(options.allocationId ? { allocationId: options.allocationId } : {}),
+            limit: Math.min(LOG_HISTORY_PAGE, options.tail - newestFirst.length),
+            ...(cursor ? { cursor } : {}),
+        });
+        newestFirst.push(...page.entries);
+        if (!page.nextCursor || page.entries.length === 0)
+            break;
+        cursor = page.nextCursor;
+        if (page.from && page.to)
+            window = { from: page.from, to: page.to };
+    }
+    return newestFirst.slice(0, options.tail).reverse();
+}
 async function promoteSubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
     if (!identifier)
@@ -1399,9 +2159,11 @@ async function promoteSubcommand(args, positionals, apiOptions) {
     // Say up front what promotion does to this release: a preview-profile
     // release with production-only variables is restarted with them before
     // traffic moves, and its preview URL retires.
+    let release = null;
+    let app = null;
     if (!json) {
-        const release = await getRelease(releaseId, apiOptions).catch(() => null);
-        const app = release ? await getApplication(release.applicationId, apiOptions).catch(() => null) : null;
+        release = await getRelease(releaseId, apiOptions).catch(() => null);
+        app = release ? await getApplication(release.applicationId, apiOptions).catch(() => null) : null;
         if (release && release.envProfile !== 'production' && (app?.productionOnlyEnvKeys?.length ?? 0) > 0) {
             printInfo(dim('  the container restarts with production-only variables before traffic moves'));
         }
@@ -1418,6 +2180,12 @@ async function promoteSubcommand(args, positionals, apiOptions) {
             err.message = humanizeApiError(err.message);
         throw err;
     }
+    // 202: the server runs it as a rolling rollout and goes on in the
+    // background. An older server always answers with the outcome below.
+    if (isPromoteAccepted(result)) {
+        await followPromoteRollout(releaseId, result, { json, wait: !hasFlag(args, '--no-wait') }, apiOptions);
+        return;
+    }
     if (json) {
         printLine(JSON.stringify(result, null, 2));
         return;
@@ -1427,12 +2195,33 @@ async function promoteSubcommand(args, positionals, apiOptions) {
         printLine(`  ${url}`);
     }
     if ((result.productionUrls ?? []).length === 0 && !result.productionUrl) {
-        printInfo(dim('  no hostname — reach it at its TCP endpoints (inquir apps status <app>)'));
+        for (const line of promotedWithoutHostnameLines(release, app))
+            printInfo(dim(line));
     }
     if (result.previousReleaseId) {
         printInfo(dim(`  previous release ${result.previousReleaseId.slice(0, 8)} kept for rollback`));
     }
 }
+/**
+ * What to say after a promotion that produced no public URL. An HTTP service
+ * is private, not unreachable: same-workspace services reach it at its
+ * private address. Only a TCP-only service is reached at its TCP endpoints.
+ */
+export function promotedWithoutHostnameLines(release, app) {
+    const name = app?.name ?? '<app>';
+    // The server reads a port without a protocol as HTTP (src/apps/app-ports.ts).
+    const http = typeof release?.runtime?.port === 'number'
+        || (release?.runtime?.ports ?? []).some((port) => (port.protocol ?? 'http') === 'http');
+    if (http) {
+        return [
+            app?.privateBaseUrl
+                ? `  private — your other services reach it at ${app.privateBaseUrl}`
+                : `  private — your other services reach it at http://<slug>.apps.internal, listed by inquir apps status ${name} once routing is verified`,
+            `  public URL: inquir apps update ${name} --ingress public`,
+        ];
+    }
+    return [`  no hostname — reach it at its TCP endpoints (inquir apps status ${name})`];
+}
 async function rollbackSubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
     if (!identifier)
@@ -1572,7 +2361,8 @@ async function updateSubcommand(args, positionals, apiOptions) {
     await requireAuth(apiOptions);
     const app = await resolveApplication(identifier, apiOptions);
     const envVars = parseSetFlags(readMultiFlag(args, '--set'));
-    const runtimeSpec = buildRuntimeFromFlags(args, app.runtime);
+    const flagsRuntime = buildRuntimeFromFlags(args, app.runtime);
+    const runtimeSpec = applyNodeSelectorFlags(args, flagsRuntime ?? app.runtime) ?? flagsRuntime;
     const description = readFlagValue(args, '--description');
     const networkPolicy = buildNetworkPolicyPatch({
         egress: readFlagValue(args, '--egress'),
@@ -1580,9 +2370,11 @@ async function updateSubcommand(args, positionals, apiOptions) {
         current: app.networkPolicy,
     });
     const volumeRunner = readFlagValue(args, '--volume-runner');
+    const location = parseLocationFlag(readFlagValue(args, '--location'));
     const patch = {
         ...(description !== undefined ? { description } : {}),
         ...(volumeRunner ? { volumeRunner } : {}),
+        ...(location !== undefined ? { location } : {}),
         ...(runtimeSpec ? { runtime: runtimeSpec } : {}),
         // Only the keys given here change; the server merges masked values, so
         // untouched secrets survive.
@@ -1598,7 +2390,43 @@ async function updateSubcommand(args, positionals, apiOptions) {
         return;
     }
     printSuccess(`Updated ${updated.name}`);
-    printInfo(dim('  changes apply to the next release: inquir apps deploy ' + updated.name));
+    // Advisory: e.g. a node selector no server matches right now.
+    for (const warning of updated.warnings ?? [])
+        printInfo(`  warning: ${warning}`);
+    const ingress = readFlagValue(args, '--ingress');
+    for (const line of updateTimingLines(updated.name, {
+        hasProduction: Boolean(updated.productionReleaseId ?? app.productionReleaseId),
+        ingress: ingress === 'public' || ingress === 'private' ? ingress : undefined,
+        nextRelease: Object.keys(envVars).length > 0 || runtimeSpec !== undefined
+            || readFlagValue(args, '--egress') !== undefined || volumeRunner !== undefined
+            || location !== undefined,
+    })) {
+        printInfo(dim(line));
+    }
+}
+/**
+ * When an `apps update` takes effect. Public Networking is applied by the
+ * server at once (the generated route is created or removed in the same
+ * request); env, runtime, egress, placement and location are what the next
+ * release is built from.
+ */
+export function updateTimingLines(appName, changed) {
+    const lines = [];
+    const hasProduction = changed.hasProduction !== false;
+    if (changed.ingress === 'public') {
+        lines.push(hasProduction
+            ? `  public networking: applied now — the generated domain serves production (inquir apps status ${appName})`
+            : '  public networking: on — the generated domain serves production once a release is promoted');
+    }
+    else if (changed.ingress === 'private') {
+        lines.push('  public networking: removed now — the generated domain no longer serves it; the private address stays');
+    }
+    if (changed.nextRelease) {
+        // redeploy re-releases production and refuses without one.
+        const next = hasProduction ? `inquir apps redeploy ${appName}` : `inquir apps deploy ${appName}`;
+        lines.push(`  ${changed.ingress ? 'the other changes apply' : 'changes apply'} to the next release: ${next}`);
+    }
+    return lines;
 }
 async function execSubcommand(args, positionals, apiOptions) {
     const [identifier, ...commandParts] = positionals;
@@ -1608,14 +2436,15 @@ async function execSubcommand(args, positionals, apiOptions) {
     if (!command)
         throw usageError('Missing command', 'inquir apps exec <app> -- ls -la');
     await requireAuth(apiOptions);
-    // `apps exec` is intentionally application-scoped. Accepting a stale or
-    // preview release id here and then calling the production-only app endpoint
-    // would silently change the operator's target to production.
-    const application = await resolveApplication(identifier, apiOptions);
+    const application = await resolveExecApplication(identifier, apiOptions, readJsonFlag(args));
     const timeoutRaw = readFlagValue(args, '--timeout');
+    const replica = readFlagValue(args.slice(0, args.includes('--') ? args.indexOf('--') : args.length), '--replica');
+    if (hasFlag(args.slice(0, args.includes('--') ? args.indexOf('--') : args.length), '--replica') && !replica?.trim()) {
+        throw usageError('Missing --replica value', 'inquir apps exec <app> --replica <name|index> -- <command>');
+    }
     let result;
     try {
-        result = await execInApplication(application.id, command, timeoutRaw ? Number(timeoutRaw) : undefined, apiOptions);
+        result = await execInApplication(application.id, command, timeoutRaw ? Number(timeoutRaw) : undefined, apiOptions, replica?.trim() ? { replica: replica.trim() } : {});
     }
     catch (err) {
         if (err instanceof Error)
@@ -1626,6 +2455,9 @@ async function execSubcommand(args, positionals, apiOptions) {
         printLine(JSON.stringify(result, null, 2));
     }
     else {
+        if (replica && result.replicaIndex !== undefined) {
+            printInfo(dim(`— replica ${result.replicaIndex}${result.allocationId ? ` (${result.allocationId.slice(0, 8)})` : ''} —`));
+        }
         if (result.stdout)
             process.stdout.write(result.stdout);
         if (result.stderr)
@@ -1636,18 +2468,68 @@ async function execSubcommand(args, positionals, apiOptions) {
     if (result.exitCode !== 0)
         process.exitCode = ExitCode.ERROR;
 }
+/**
+ * `apps exec` runs in production through the application-scoped endpoint. An
+ * application name or id is the target; a release id is accepted only when it
+ * is that application's production release. A stale or preview release id
+ * would otherwise silently change the operator's target to production, so it
+ * is refused with the command that does run.
+ */
+async function resolveExecApplication(identifier, apiOptions, json) {
+    let appError;
+    try {
+        return await resolveApplication(identifier, apiOptions);
+    }
+    catch (error) {
+        appError = error;
+    }
+    const release = await getRelease(identifier, apiOptions).catch(() => null);
+    if (!release)
+        throw appError;
+    const detail = await getApplication(release.applicationId, apiOptions);
+    const production = detail.production?.activeReleaseId;
+    if (production !== release.id) {
+        throw new CliError(`Release ${release.id.slice(0, 8)} is not ${detail.name}'s production release`, {
+            code: 'EXEC_NOT_PRODUCTION',
+            exitCode: ExitCode.USAGE,
+            explanation: 'apps exec runs a command in the production container only.',
+            fix: production
+                ? `Run it in production (release ${production.slice(0, 8)}): inquir apps exec ${detail.name} -- <command>`
+                : `${detail.name} has no production release yet; promote one first: inquir apps promote ${release.id.slice(0, 8)}`,
+        });
+    }
+    const note = `— ${detail.name}, production release ${release.id.slice(0, 8)} —`;
+    if (json)
+        process.stderr.write(`${note}\n`);
+    else
+        printInfo(dim(note));
+    return detail;
+}
 function printVerificationInstructions(domain) {
     const v = domain.verification;
     if (!v)
         return;
-    printInfo(dim('  prove ownership, then verify:'));
-    printLine(`    TXT   ${v.txtName}  →  ${v.txtValue}`);
-    for (const target of v.cnameTargets)
-        printLine(`    CNAME ${domain.hostname}  →  ${target}`);
+    // A verified hostname keeps its records on display: they are what gets compared with the
+    // registrar when the name stops resolving.
+    printInfo(dim(domain.verified
+        ? `  ${domain.hostname} — verified with these records (the routing record must stay in place):`
+        : `  ${domain.hostname} — prove ownership, then verify:`));
+    const row = (label, name, value) => printLine(`    ${label.padEnd(8)} ${name}  →  ${value}`);
+    row('TXT', v.txtName, v.txtValue);
+    // One target, not a menu: every entry is accepted by verify and leads to the same ingress. The first is the
+    // app's own hostname when an apps suffix is configured, otherwise the platform target.
+    if (v.cnameTargets[0])
+        row('CNAME', domain.hostname, v.cnameTargets[0]);
     for (const ip of v.ingressIps)
-        printLine(`    A     ${domain.hostname}  →  ${ip}`);
+        row('A', domain.hostname, ip);
     if (v.ingressAliasTarget)
-        printLine(`    ALIAS ${domain.hostname}  →  ${v.ingressAliasTarget}`);
+        row('ALIAS', domain.hostname, v.ingressAliasTarget);
+    if (v.apexCnameTargets?.length) {
+        printInfo(dim(domain.verified
+            ? '  verified by the TXT record alone — where the apex points was never checked; traffic reaches the app only through ALIAS/ANAME/CNAME flattening onto:'
+            : '  an apex domain is verified by the TXT record alone; point it with ALIAS/ANAME/CNAME flattening so traffic reaches the app:'));
+        row('ALIAS', domain.hostname, v.apexCnameTargets[0]);
+    }
 }
 /**
  * `apps domain <app> [hostname] [--verify|--remove]` — bind a custom hostname
@@ -1678,8 +2560,7 @@ async function domainSubcommand(args, positionals, apiOptions) {
             verified: d.verified ? 'yes' : 'no',
         })), ['hostname', 'kind', 'source', 'verified']));
         for (const d of items)
-            if (!d.verified)
-                printVerificationInstructions(d);
+            printVerificationInstructions(d);
         return;
     }
     if (hasFlag(args, '--remove')) {
@@ -1704,6 +2585,14 @@ async function domainSubcommand(args, positionals, apiOptions) {
         printLine(JSON.stringify(domain, null, 2));
         return;
     }
+    if (domain.verified) {
+        // An operator-granted platform hostname verifies on bind: no records to publish.
+        printSuccess(`${domain.hostname} bound to ${app.name} and verified — it now serves ${app.name}`);
+        if (!domain.activeReleaseId) {
+            printInfo(dim('  no release is promoted yet: inquir apps promote <release>'));
+        }
+        return;
+    }
     printSuccess(`${domain.hostname} bound to ${app.name} (unverified)`);
     printVerificationInstructions(domain);
     printInfo(dim(`  then: inquir apps domain ${app.name} ${domain.hostname} --verify`));