@inquir/compute-cli 0.3.0 → 0.4.0

package/dist/commands/apps.js

@@ -1,16 +1,22 @@
 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 { 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 { listAppBackups, getAppBackup, createAppBackup, deleteAppBackup, restoreAppBackup, getAppConnectionUrl, connectApps, addApplicationDomain, archiveApplication, cancelBuild, createApplication, getBuild, listApplicationDomains, listBuilds, queueBuild, removeApplicationDomain, createRelease, redeployApplication, execInApplication, getAppLimits, getApplication, getProject, getRelease, listApplications, promoteRelease, isPromoteAccepted, requireAuth, resolveApplication, rollbackApplication, stopRelease, streamBuildLogs, streamReleaseLogs, updateApplication, wakeApplication, pauseApplication, verifyApplicationDomain, } from '../utils/api.js';
+import { ApiError, DEFAULT_BUILD_TIMEOUT_POLICY, createZipBase64, isSettledReleaseStatus, isTerminalBuildStatus } from '../sdk.js';
 import { formatBytes, formatElapsed, humanizeApiError, permanentAddress, presentRelease, } 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';
 /** Value flags across every subcommand — readPositionalArgs must know them all. */
 const VALUE_FLAGS = [
+    ...OBSERVATION_VALUE_FLAGS,
+    ...RESOURCES_VALUE_FLAGS,
     '--project',
     '--template',
     '--image',
@@ -22,6 +28,7 @@ const VALUE_FLAGS = [
     '--set',
     '--memory',
     '--cpu',
+    '--drain-grace',
     '--health-path',
     '--health-command',
     '--description',
@@ -76,7 +83,19 @@ 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 'promote':
             return promoteSubcommand(args, rest, apiOptions);
         case 'rollback':
@@ -124,7 +143,12 @@ 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',
+        'describe <app>              Why it is (not) running: conditions, placement, events',
         'logs <app|release|build>    Stream container (or build) logs',
+        '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',
@@ -137,7 +161,7 @@ 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',
@@ -153,6 +177,7 @@ function printAppsHelp() {
         '--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',
@@ -306,6 +331,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) {
@@ -375,6 +401,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,6 +418,7 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
     const volumeValues = readMultiFlag(args, '--volume');
     const memory = readFlagValue(args, '--memory');
     const cpu = readFlagValue(args, '--cpu');
+    const drainGraceRaw = readFlagValue(args, '--drain-grace');
     const healthPath = readFlagValue(args, '--health-path');
     const healthCommand = readFlagValue(args, '--health-command');
     const ports = tcpValues.map(parseTcpPortFlag);
@@ -390,7 +427,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 +441,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 +497,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 +521,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 +549,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 +567,46 @@ 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 = {
+    ...OBSERVATION_HELP,
+    ...RESOURCES_HELP,
+    ...DESCRIBE_HELP,
+    logs: [
+        'Usage: inquir apps logs <app|release|build> [--tail <n>]',
+        '  Streams container or build logs. Ctrl-C stops following.',
+        '  --history selects persisted history instead; see apps log-history --help.',
+    ],
+    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 +622,17 @@ 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.',
+        '  --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: volume, pinned public TCP port,',
         '                      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 +659,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',
@@ -729,6 +832,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 +927,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 +942,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 +979,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;
@@ -977,65 +1171,202 @@ 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;
 /** 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);
     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 ?? '' : '';
+        if (`${release.status}\n${reason}` !== lastProgress) {
+            lastProgress = `${release.status}\n${reason}`;
             // 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 lines = [
+                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${shown.meaning ? `: ${shown.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',
@@ -1113,10 +1444,16 @@ export function privateEndpointLines(detail, active, options = {}) {
     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;
 }
@@ -1215,6 +1552,11 @@ async function statusSubcommand(args, positionals, apiOptions) {
     const pinnedRunner = detail.volumeRunnerId;
     if (pinnedRunner)
         printLine(`  volume pin: runner ${pinnedRunner}`);
+    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)
@@ -1418,6 +1760,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;
@@ -1640,14 +1988,27 @@ 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 +2039,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 +2064,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`));