@inquir/compute-cli 0.4.0 → 0.4.2

package/dist/commands/apps.js

@@ -2,17 +2,20 @@ 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, 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 { 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, 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,
@@ -26,6 +29,7 @@ const VALUE_FLAGS = [
     '--volume-runner',
     '--env',
     '--set',
+    '--unset',
     '--memory',
     '--cpu',
     '--drain-grace',
@@ -52,6 +56,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 });
@@ -96,6 +102,8 @@ export async function appsCommand(args) {
             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':
@@ -144,7 +152,8 @@ function printAppsHelp() {
         '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',
+        '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',
@@ -152,29 +161,36 @@ function printAppsHelp() {
         '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)',
-        'domain <app> [hostname]     Bind a hostname (or list them); --verify / --remove',
+        "domain <app> [hostname]     Bind a hostname (or list them); --verify / --remove; '*.example.com' needs --yes (not recommended)",
         'delete <app>                Archive an application (stops every release)',
         '',
         'Create/deploy flags:',
         '--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: .)',
         '--build-arg KEY=VALUE       Docker build argument (repeatable)',
         '--build <buildId>           Release an existing successful build',
         '--port <n>                  HTTP port (omit for a TCP-only service)',
-        '--tcp <name:port[:public]>  Extra TCP port; endpoint port is platform-managed (repeatable)',
+        '--tcp <name:port[:public]>  Extra TCP port on the private network (repeatable); :public (or a\n' +
+            '                            numeric host-port pin, which implies it) is refused while the server\n' +
+            '                            offers no public TCP (inquir.org: not at the moment)',
         '--volume <name:/path[:ro]> Persistent volume mount (repeatable)',
         '--volume-runner <id>        Pin volumes (and the container) to a worker runner',
-        '--set KEY=VALUE             Environment variable (repeatable)',
+        '--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             create/update: environment variable (repeatable)',
+        '--unset KEY                 update: remove an environment variable and its production-only marker (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)',
@@ -195,8 +211,7 @@ function printAppsHelp() {
         'inquir apps create web --port 3000',
         'inquir apps deploy web                # builds ./Dockerfile, then releases it',
         'inquir apps deploy web --image nginx:alpine',
-        'inquir apps deploy cache --image redis:7-alpine --tcp redis:6379:public \\',
-        '  --health-command "redis-cli ping"',
+        'inquir apps create cache --template redis   # volume + private TCP endpoint',
         'inquir apps deploy db --image postgres:16 --volume data:/var/lib/postgresql/data',
         'inquir apps scale web http --idle-timeout 15m',
         'inquir apps wake web',
@@ -207,16 +222,24 @@ function printAppsHelp() {
     ]);
 }
 /**
- * `--tcp name:port[:public][:hostPort]` — ordinary usage stops at `public` and
- * lets the platform lease a stable endpoint port. The final numeric modifier
- * remains an API/CLI compatibility escape hatch for an existing installation.
+ * Public TCP availability, for hints. Grep marker for when cluster L4 ingress
+ * lands: PUBLIC_TCP_UNAVAILABLE (server error code, docs and copy say "not
+ * available at the moment").
+ */
+const PUBLIC_TCP_NOTE = 'public TCP ports are not available on inquir.org at the moment (PUBLIC_TCP_UNAVAILABLE), so a client outside the platform has no public URL: run it as an application of this workspace';
+/**
+ * `--tcp name:port[:public][:hostPort]` — ordinary usage stops at `name:port`
+ * (private) or `public` (the platform leases a stable endpoint port). The
+ * final numeric modifier remains an API/CLI compatibility escape hatch for an
+ * existing installation; it implies `public`, so a server without public TCP
+ * refuses it exactly like `:public` (400 PUBLIC_TCP_UNAVAILABLE).
  */
 export function parseTcpPortFlag(value) {
     const parts = value.split(':');
     const [name, portRaw, ...flags] = parts;
     const port = Number(portRaw);
     if (!name || !Number.isInteger(port) || port < 1 || port > 65535) {
-        throw usageError(`Invalid --tcp value '${value}'`, 'inquir apps deploy <app> --tcp postgres:5432:public');
+        throw usageError(`Invalid --tcp value '${value}'`, 'inquir apps deploy <app> --tcp postgres:5432');
     }
     const spec = { name, port, protocol: 'tcp' };
     for (const flag of flags) {
@@ -231,10 +254,81 @@ export function parseTcpPortFlag(value) {
             spec.public = true;
             continue;
         }
-        throw usageError(`Invalid --tcp modifier '${flag}' in '${value}'`, 'inquir apps deploy <app> --tcp postgres:5432:public');
+        throw usageError(`Invalid --tcp modifier '${flag}' in '${value}'`, 'inquir apps deploy <app> --tcp postgres:5432');
     }
     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) {
@@ -340,7 +434,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) {
@@ -419,7 +513,12 @@ export function buildRuntimeFromFlags(args, baseRuntime) {
     const memory = readFlagValue(args, '--memory');
     const cpu = readFlagValue(args, '--cpu');
     const drainGraceRaw = readFlagValue(args, '--drain-grace');
-    const healthPath = readFlagValue(args, '--health-path');
+    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);
@@ -589,15 +688,129 @@ async function landingProjectLines(app, requestedProject, apiOptions) {
 }
 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>]',
-        '  Streams container or build logs. Ctrl-C stops following.',
+        '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, --memory, --cpu, ...) as in apps --help.',
+        '  Environment variables are not deploy flags: set them with',
+        '  inquir apps update <app> --set KEY=VALUE, then deploy or redeploy.',
+        '',
+        '  inquir.yaml services.web.env: non-secret defaults, applied by the next release',
+        '  where the platform enables it (APPS_MANIFEST_ENV=on); an application variable',
+        '  (apps update --set, dashboard, API) with the same name wins. Otherwise the deploy warns that',
+        '  the section was not applied. Never put secrets in inquir.yaml.',
+    ],
+    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] [--unset KEY] [--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, --unset, --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] [--yes] [--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.',
+        '',
+        "  Advanced, not recommended: a quoted mask '*.example.com' binds every",
+        '  first-level subdomain (a.example.com, not a.b.example.com) when the server',
+        '  enables it. It asks for confirmation, or --yes. Prove it with a wildcard',
+        '  CNAME *.example.com and TXT _inquir-verify.example.com.',
+    ],
+    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]',
         '',
@@ -625,9 +838,10 @@ const SUBCOMMAND_HELP = {
         '  --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.',
+        '  --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. With',
         '                      --template the worker runs the operator\'s digest-pinned',
@@ -677,8 +891,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,
@@ -686,7 +947,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) {
@@ -758,9 +1022,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}`));
@@ -883,8 +1150,10 @@ export function explainDatabaseConnectionError(error, context) {
                 ...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.',
+                    ? 'connect writes private URLs only. If other apps have private addresses here, the database\'s may just not be verified yet: retry in a minute. ' +
+                        'A public URL exists only where the server offers public TCP and Public Access is on; ' + PUBLIC_TCP_NOTE + '.'
+                    : 'If other apps have private addresses here, the database\'s may just not be verified yet: retry in a minute. ' +
+                        'A public URL exists only where the server offers public TCP and Public Access is on; ' + PUBLIC_TCP_NOTE + '.',
                 command: `inquir apps connection-url ${database} --public`,
             });
         case 'APP_NO_PRODUCTION_RELEASE':
@@ -981,10 +1250,10 @@ export function selectConnectionUrl(result, preference = 'auto') {
     const requested = preference === 'auto' ? 'private or public' : preference;
     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.'
+        ? `A public URL needs public TCP and Public Access on the database; ${PUBLIC_TCP_NOTE}.`
         : 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.');
+            : `Configure private networking. --public works only where the server offers public TCP; ${PUBLIC_TCP_NOTE}.`);
 }
 async function deploySubcommand(args, positionals, apiOptions) {
     const [identifier] = positionals;
@@ -1033,6 +1302,7 @@ async function deploySubcommand(args, positionals, apiOptions) {
         printInfo(`Release ${queued.releaseId.slice(0, 8)} queued for ${app.name} (${image ?? `build ${buildId.slice(0, 8)}`})`);
         if (promote)
             printInfo(dim('  it takes production by itself once healthy'));
+        printManifestEnvOutcome(queued);
     }
     if (hasFlag(args, '--no-wait')) {
         if (json)
@@ -1043,6 +1313,20 @@ async function deploySubcommand(args, positionals, apiOptions) {
     }
     await followQueuedRelease(app, queued, promote, json, apiOptions);
 }
+/**
+ * What the server did with inquir.yaml `services.web.env` (docs/MANIFEST_ENV.md).
+ * Read structurally: a control plane that predates manifest env sends neither
+ * field, and then nothing is printed.
+ */
+export function printManifestEnvOutcome(queued) {
+    const outcome = queued;
+    const applied = Array.isArray(outcome.manifestEnv?.applied) ? outcome.manifestEnv.applied : [];
+    if (applied.length > 0)
+        printInfo(dim(`  inquir.yaml env applied: ${applied.join(', ')}`));
+    const warnings = Array.isArray(outcome.warnings) ? outcome.warnings : [];
+    for (const warning of warnings)
+        printWarning(`  warning: ${warning}`);
+}
 /**
  * Wait for a queued release to settle and say where it ended up; with
  * promote-on-ready, also wait for production to point at it.
@@ -1134,6 +1418,7 @@ async function redeploySubcommand(args, positionals, apiOptions) {
         printInfo(`Release ${queued.releaseId.slice(0, 8)} queued for ${app.name} (redeploy of ${queued.redeployOf.slice(0, 8)})`);
         if (promote)
             printInfo(dim('  it takes production by itself once healthy'));
+        printManifestEnvOutcome(queued);
     }
     if (hasFlag(args, '--no-wait')) {
         if (json)
@@ -1154,7 +1439,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',
@@ -1336,24 +1625,64 @@ export async function waitForBuild(buildId, apiOptions, options = {}) {
  * 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 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);
         // 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}`;
+        // 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 meaning = (phase && replacementPhaseMeaning(phase)) || shown.meaning;
             const lines = [
-                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${shown.meaning ? `: ${shown.meaning}` : ''} —`,
+                `— ${shown.label} (${formatElapsed(Date.now() - startedAt)})${meaning ? `: ${meaning}` : ''} —`,
                 ...(reason ? [`  ${reason}`] : []),
             ];
             for (const line of lines) {
@@ -1437,9 +1766,16 @@ 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)
@@ -1517,6 +1853,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') {
@@ -1552,6 +1900,15 @@ 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.
@@ -1692,29 +2049,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)
@@ -1731,6 +2133,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)
@@ -1741,9 +2200,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'));
         }
@@ -1775,12 +2236,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)
@@ -1920,7 +2402,23 @@ 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 unset = readMultiFlag(args, '--unset');
+    const productionOnly = app.productionOnlyEnvKeys ?? [];
+    for (const key of unset) {
+        if (Object.hasOwn(envVars, key))
+            throw usageError(`--set and --unset both name ${key}`, `inquir apps update <app> --unset ${key}`);
+        // A production-only marker without a value is still worth clearing: it
+        // would refuse the same key from inquir.yaml (docs/MANIFEST_ENV.md).
+        if (!Object.hasOwn(app.envVars ?? {}, key) && !productionOnly.includes(key)) {
+            throw usageError(`${app.name} has no variable ${key}`, `inquir apps update ${app.name} --unset <KEY>`);
+        }
+    }
+    const unsetVariables = unset.filter((key) => Object.hasOwn(app.envVars ?? {}, key));
+    const envChanged = Object.keys(envVars).length > 0 || unsetVariables.length > 0;
+    // --unset removes the production-only marker with the variable.
+    const unsetMarkers = unset.filter((key) => productionOnly.includes(key));
+    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'),
@@ -1928,13 +2426,22 @@ 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.
-        ...(Object.keys(envVars).length > 0 ? { envVars: { ...(app.envVars ?? {}), ...envVars } } : {}),
+        // The map replaces the stored set, so a key left out is removed (--unset).
+        ...(envChanged ? {
+            envVars: {
+                ...Object.fromEntries(Object.entries(app.envVars ?? {}).filter(([key]) => !unset.includes(key))),
+                ...envVars,
+            },
+        } : {}),
+        ...(unsetMarkers.length > 0 ? { productionOnlyEnvKeys: productionOnly.filter((key) => !unsetMarkers.includes(key)) } : {}),
         ...(networkPolicy ? { networkPolicy } : {}),
     };
     if (Object.keys(patch).length === 0) {
@@ -1946,7 +2453,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: envChanged || unsetMarkers.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;
@@ -1956,14 +2499,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)
@@ -1974,6 +2518,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)
@@ -1984,8 +2531,62 @@ 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;
+}
+/** The warning a wildcard bind must be confirmed against (dashboard text, CLI words). */
+export function wildcardRiskWarning(hostname) {
+    return [
+        `${hostname} is a mask — not recommended.`,
+        '  It sends every first-level subdomain to this application, including services you may not',
+        '  know about (APIs, webhooks, integrations), and those stop working. Requests meant for them',
+        '  start arriving at the application with their cookies and tokens. Each subdomain gets its own',
+        "  certificate on its first request, and only a limited number of new ones per week (the Let's",
+        '  Encrypt limit is shared by the whole domain); anyone can use that allowance up by requesting',
+        '  random names, and new subdomains then get no certificate for up to a week.',
+        '  Prefer binding the subdomains you need one by one; a mask suits',
+        '  an application that serves many hosts itself (for example, a subdomain per customer).',
+    ];
+}
 function printVerificationInstructions(domain) {
     const v = domain.verification;
+    if (domain.certificates) {
+        printInfo(dim(`  ${domain.hostname} — ${domain.certificates.issuedThisWeek} of ${domain.certificates.weeklyLimit} new certificates this week`));
+    }
     if (!v)
         return;
     // A verified hostname keeps its records on display: they are what gets compared with the
@@ -2059,7 +2660,20 @@ async function domainSubcommand(args, positionals, apiOptions) {
         }
         return;
     }
-    const domain = await addApplicationDomain(app.id, hostname, apiOptions);
+    const wildcard = hostname.trim().startsWith('*.');
+    if (wildcard) {
+        // Not recommended, so never by accident: the API refuses it unless the
+        // request says the risks were confirmed, which only happens here.
+        for (const line of wildcardRiskWarning(hostname.trim()))
+            printWarning(line);
+        if (!runtime().yes) {
+            const approved = await confirm(`Bind every subdomain matched by ${hostname.trim()} to ${app.name}?`, false);
+            if (!approved) {
+                throw usageError(`Refusing to bind the mask ${hostname.trim()} without confirmation`, `inquir apps domain ${app.name} '${hostname.trim()}' --yes`);
+            }
+        }
+    }
+    const domain = await addApplicationDomain(app.id, hostname, apiOptions, wildcard ? { acknowledgeWildcardRisks: true } : {});
     if (readJsonFlag(args)) {
         printLine(JSON.stringify(domain, null, 2));
         return;