cpflow 5.2.0 → 6.0.0.rc.0

data/docs/rds-private-networking.md

@@ -6,13 +6,14 @@ path — not the public internet.
 
 This guide covers the recommended setup: **CPLN Cloud Wormhole via an Agent**.
 
-> **Sourcing note — verify field casing before you apply.** Field names, schema, and limits in this guide
-> are sourced from the public Control Plane documentation at <https://shakadocs.controlplane.com> as of
-> May 2026 and have **not** been end-to-end verified against a live org. This matters because a casing
-> mismatch **fails silently**: `cpln apply` accepts the file, ignores the unrecognized field, and the
-> workload then can't reach the database — with no error pointing back to the YAML. Before applying in
-> production, diff your edited files against a fresh `cpln identity get <name> -o yaml-slim` (and
-> `cpln agent get <name> -o yaml`) export to confirm the exact field names, and consult
+> **Field casing verified.** Sanitized `cpln identity get <name> -o yaml-slim` exports from live orgs
+> confirmed the `networkResources` nesting and the common `name`, `agentLink`, `FQDN`, and `ports` field casing.
+> The current Control Plane [Identity reference](https://shakadocs.controlplane.com/reference/identity) and
+> [Identity API](https://shakadocs.controlplane.com/api-reference/identity/get-an-identity-by-gvc-and-name)
+> confirm the alternative `IPs` form and optional `resolverIP` spelling; neither appeared in the inspected
+> live resources. Field names are case-sensitive: `cpln apply` can accept an unrecognized field while omitting
+> the intended route, without pointing back to the identity YAML. Before applying in production, check the new
+> block against these casing sources, diff your edited file against a fresh identity export, and consult
 > `cpln <command> --help` for the latest CLI flags.
 
 ## Why private networking
@@ -234,11 +235,10 @@ cpln identity get my-app-production-identity \
 Edit `identity-db.yaml` and **add** the `networkResources` block — keep every other apply-safe field
 exactly as exported:
 
-> ⚠️ **Verify field casing against your org before applying.** The field names below (`FQDN`, `IPs`,
-> `agentLink`, `resolverIP`) are sourced from public CPLN docs. If the live API uses different casing,
-> `cpln apply` will accept the file but silently ignore the resource — workloads will hit
-> `could not translate host name` with no obvious link to the identity YAML. Diff your edited file
-> against the original `yaml-slim` export from `cpln identity get` to confirm.
+> **Apply-safe editing:** start from a fresh `yaml-slim` export and diff your edited file against the
+> original before applying. This helps detect unintended changes to exported fields, but it does not validate
+> the newly added `networkResources` block. Check every key in that block, including `agentLink`, `FQDN`/`IPs`,
+> `resolverIP`, and `ports`, against the verified casing sources above.
 
 ```yaml
 # identity-db.yaml (after edit — abbreviated, your file will have more fields)

data/docs/releasing.md

@@ -23,6 +23,11 @@ Always update `CHANGELOG.md` before running the release task.
    - Fixes, improvements, deprecations, removals, or security updates: patch
 4. Merge the changelog PR before releasing.
 
+A minimum Ruby version change is a breaking change. Merge the gemspec floor,
+CI coverage for each supported Ruby minor, and an `Unreleased` breaking-change
+entry together. Keep `Cpflow::VERSION` unchanged in that implementation PR.
+The release task applies the required major version when the change ships.
+
 If updating the changelog manually, move the relevant `Unreleased` entries into
 a versioned header:
 
@@ -49,9 +54,13 @@ With no arguments, `rake release`:
 
 1. Reads the first versioned `CHANGELOG.md` header, such as `## [4.2.0]`.
 2. Uses that version when it is newer than the current gem version.
-3. Uses the current version if the changelog version matches the gem version
-   but has not been tagged yet.
-4. Falls back to a patch bump if no new changelog version is found.
+3. Keeps using that version when it matches the current gem version, including
+   on a retry after a release attempt created the version commit or tag.
+4. Lets the existing-tag policy stop an incomplete retry instead of silently
+   selecting a different version.
+5. Falls back to a patch bump only from a stable current version when the
+   changelog does not name the current or a newer version. Prereleases require
+   an explicit target if the changelog cannot supply one.
 
 Other supported forms:
 
@@ -152,4 +161,6 @@ bundle exec rake "sync_github_release[4.2.0]"
 ```
 
 If the tag was pushed but the gem was not published, delete or correct the tag
-and version commit intentionally before trying again.
+and version commit intentionally before trying again. A no-argument retry keeps
+the changelog version authoritative and refuses to reinterpret a prerelease as
+its stable version.

data/docs/secrets-and-env-values.md

@@ -97,6 +97,14 @@ to every configured shared policy. `cpflow deploy-image` repairs missing shared
 updated, which helps existing review apps recover after the config is added. `cpflow delete` and `cpflow cleanup-stale-apps`
 remove those shared policy bindings when a review app is deleted.
 
+The generated Postgres template ships with `the_password` as a password placeholder. When a `shared_secret_grants`
+target still has that exact value in its `password` field, `cpflow setup-app` and `cpflow deploy-image` warn before
+release or deployment work because review apps will fail authentication until the value is replaced. The diagnostic
+does not print secret values. It makes one bounded, non-retried reveal attempt with the current Control Plane token and
+skips the check without blocking setup or deployment when that token cannot reveal the shared secret. Do not validate the replacement only by connecting to PostgreSQL through `127.0.0.1`:
+a loopback `trust` rule in `pg_hba.conf` can allow that connection without checking the password and produce a false
+pass. Verify the credential through a non-loopback path that uses the same authentication route as the review app.
+
 For shared databases, keep runtime data isolated by using a per-review-app database name, schema, or tenant key. A common
 pattern is to keep the host, user, and password in the shared secret, then have `hooks.post_creation` create the
 PR-specific database/schema. Avoid a generic `hooks.pre_deletion` that drops the database: `cpflow delete` runs the

data/docs/tips.md

@@ -18,6 +18,7 @@
 13. [Minimizing Non-Production App Costs](#minimizing-non-production-app-costs)
     - [Share One Control Plane Postgres for Staging and Review Apps](#share-one-control-plane-postgres-for-staging-and-review-apps)
     - [Enable Capacity AI for Demo and Starter Staging Apps](#enable-capacity-ai-for-demo-and-starter-staging-apps)
+    - [Use an Always-Available Landing Page for a Serverless App](#use-an-always-available-landing-page-for-a-serverless-app)
     - [Delete or Pause Abandoned Apps with `cleanup-stale-apps`](#delete-or-pause-abandoned-apps-with-cleanup-stale-apps)
     - [Pause and Resume with `ps:stop` / `ps:start`](#pause-and-resume-with-psstop--psstart)
 14. [Right-Sizing Non-Production Workloads](#right-sizing-non-production-workloads)
@@ -616,6 +617,23 @@ migration and can interrupt traffic.
 > **Warning:** Treat a `standard` to `serverless` conversion as an operational migration because deleting a running
 > workload can interrupt traffic.
 
+### Use an Always-Available Landing Page for a Serverless App
+
+For a public demo, review app, or staging app where the first request's cold start would be a poor first impression,
+serve a lightweight landing page independently of the app that scales to zero. Route visitors to that landing page
+first, then have a button on that page request the separate serverless app. The page can immediately explain that the
+app is starting while the serverless workload wakes; it does not remove the cold start, but it keeps that wait out of
+the initial page render.
+
+```text
+always-available landing page -> Open app request -> serverless app (minScale: 0) -> cold start -> app response
+```
+
+The landing page, its hosting, and any DNS, proxy, rewrite, or redirect rules are application infrastructure you
+choose and operate. `cpflow` does not create that routing infrastructure. Keep the app as a separate serverless
+workload from its first deployment (or perform the planned delete/recreate migration above); it cannot convert an
+existing standard workload in place. The wake-up path also requires the HTTP autoscaling configuration shown above.
+
 > **Note:** if you later suspend the app with `cpflow ps:stop`, Control Plane will not auto-wake it on the next
 > request. Run `cpflow ps:start` explicitly first. See
 > [Pause and Resume](#pause-and-resume-with-psstop--psstart).

data/examples/controlplane.yml

@@ -104,6 +104,11 @@ aliases:
     # If not specified, defaults to 21600 (6 hours).
     runner_job_timeout: 1000
 
+    # Sets how long `cpflow run` waits for Control Plane to reconcile a cron job status
+    # after the non-interactive command prints its completion marker.
+    # If not specified, defaults to 1200 (20 minutes).
+    runner_job_status_reconciliation_timeout: 1200
+
     # Apps with a deployed image created before this amount of days will be listed for deletion
     # when running the command `cpflow cleanup-stale-apps`.
     stale_app_image_deployed_days: 5

data/lib/command/ai_github_flow_prompt.rb

@@ -32,7 +32,7 @@ module Command
       <<~PROMPT
         Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
 
-        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers: the only downstream Control Plane Flow pin should be the reusable workflow `uses: ...@vX.Y.Z` value generated from the installed `cpflow` gem version, and upstream workflows load their matching shared actions automatically. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
+        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in workflows and local actions move together. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
 
         Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
 

data/lib/command/apply_template.rb

@@ -9,7 +9,8 @@ module Command
       app_option(required: true),
       location_option,
       skip_confirm_option,
-      add_app_identity_option
+      add_app_identity_option,
+      preserve_existing_runtime_option
     ].freeze
     DESCRIPTION = "Applies application-specific configs from templates"
     LONG_DESCRIPTION = <<~DESC
@@ -17,6 +18,8 @@ module Command
       - Publishes (creates or updates) those at Control Plane infrastructure
       - Picks templates from the `.controlplane/templates` directory
       - Templates are ordinary Control Plane templates but with variable preprocessing
+      - Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+      - Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
       **Preprocessed template variables:**
 
@@ -58,6 +61,7 @@ module Command
       @skipped_templates = []
 
       templates = @template_parser.parse(@names_to_filenames.values)
+      templates = preserve_existing_runtime(templates) if config.options[:preserve_existing_runtime]
       pending_templates = confirm_templates(templates)
       add_app_identity_template(pending_templates) if config.options[:add_app_identity]
       pending_templates.each do |template|
@@ -117,7 +121,7 @@ module Command
     end
 
     def confirm_workload(template) # rubocop:disable Naming/PredicateMethod
-      workload = cp.fetch_workload(template["name"])
+      workload = fetch_workload(template["name"])
       return true unless workload
 
       confirmed = confirm_apply("Workload '#{template['name']}' already exists, do you want to re-create it?")
@@ -146,6 +150,104 @@ module Command
       pending_templates
     end
 
+    def preserve_existing_runtime(templates)
+      cache_existing_workloads(templates)
+      ready_fallback_image = unambiguous_ready_app_image
+
+      templates.filter_map do |template|
+        if template["kind"] == "secret" && cp.fetch_secret(template["name"])
+          report_skipped(template)
+          next
+        end
+
+        preserve_workload_images(template, ready_fallback_image) if template["kind"] == "workload"
+        template
+      end
+    end
+
+    def cache_existing_workloads(templates)
+      template_names = templates.filter_map { |template| template["name"] if template["kind"] == "workload" }
+      workloads = cp.fetch_workloads
+      cp.fetch_gvc! unless workloads
+      @existing_workloads = Array(workloads.fetch("items")).to_h do |workload|
+        [workload.fetch("name"), workload]
+      end
+      template_names.each { |name| @existing_workloads[name] = nil unless @existing_workloads.key?(name) }
+    end
+
+    def fetch_workload(name)
+      return @existing_workloads[name] if @existing_workloads&.key?(name)
+
+      cp.fetch_workload(name)
+    end
+
+    def unambiguous_ready_app_image
+      app_images = ready_existing_app_workloads.flat_map do |workload|
+        Array(workload.dig("spec", "containers")).filter_map do |container|
+          container["image"] if deployable_app_image?(container["image"])
+        end
+      end
+      image_prefix = "/org/#{config.org}/image/"
+      canonical_images = app_images.map { |image| image.delete_prefix(image_prefix) }
+      app_images.first if canonical_images.uniq.one?
+    end
+
+    def ready_existing_app_workloads
+      @existing_workloads.values.compact.filter_map do |workload|
+        next unless Array(workload.dig("spec", "containers")).any? do |container|
+          deployable_app_image?(container["image"])
+        end
+
+        workload = workload_with_readiness(workload)
+        workload if workload_ready?(workload)
+      end
+    end
+
+    def preserve_workload_images(template, ready_fallback_image) # rubocop:disable Metrics/MethodLength
+      existing_workload = fetch_workload(template["name"])
+      existing_containers = Array(existing_workload&.dig("spec", "containers"))
+                            .to_h { |container| [container["name"], container] }
+
+      Array(template.dig("spec", "containers")).each do |container|
+        next unless app_image?(container["image"])
+
+        existing_image = existing_containers.dig(container["name"], "image")
+        preserved_image = preserved_image(existing_image, ready_fallback_image)
+        unless preserved_image
+          raise "Cannot safely refresh app image for workload '#{template['name']}' " \
+                "without a valid existing workload image or an unambiguous ready fallback image."
+        end
+
+        container["image"] = preserved_image
+      end
+    end
+
+    def preserved_image(existing_image, ready_fallback_image)
+      return existing_image if deployable_app_image?(existing_image)
+
+      ready_fallback_image
+    end
+
+    def workload_ready?(workload)
+      workload&.dig("status", "readyLatest") == true
+    end
+
+    def workload_with_readiness(workload)
+      return workload unless workload.dig("status", "readyLatest").nil?
+
+      cp.fetch_workload_with_status(workload.fetch("name")) || workload
+    end
+
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
+    def deployable_app_image?(image)
+      app_image?(image) && !image.to_s.end_with?(Controlplane::NO_IMAGE_AVAILABLE)
+    end
+
     def add_app_identity_template(templates)
       app_template_index = templates.index { |template| template["name"] == config.app }
       app_identity_template_index = templates.index { |template| template["name"] == config.identity }

data/lib/command/base.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "shellwords"
 require_relative "../core/helpers"
 
 module Command
@@ -11,6 +12,7 @@ module Command
     VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS = %w[config].freeze
     VALIDATIONS_WITH_ADDITIONAL_OPTIONS = %w[templates].freeze
     ALL_VALIDATIONS = VALIDATIONS_WITHOUT_ADDITIONAL_OPTIONS + VALIDATIONS_WITH_ADDITIONAL_OPTIONS
+    GENERATED_POSTGRES_PASSWORD_PLACEHOLDER = "the_password"
 
     # Used to call the command (`cpflow SUBCOMMAND_NAME NAME`)
     SUBCOMMAND_NAME = nil
@@ -459,6 +461,28 @@ module Command
       }
     end
 
+    def self.refresh_templates_option(required: false)
+      {
+        name: :refresh_templates,
+        params: {
+          desc: "Refreshes configured templates for an existing app without running post-creation hooks",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
+    def self.preserve_existing_runtime_option(required: false)
+      {
+        name: :preserve_existing_runtime,
+        params: {
+          desc: "Preserves deployed app images and skips existing secret resources entirely while applying templates",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
     def self.skip_pre_deletion_hook_option(required: false)
       {
         name: :skip_pre_deletion_hook,
@@ -528,10 +552,12 @@ module Command
       end
     end
 
-    # NOTE: use simplified variant atm, as shelljoin do different escaping
-    # TODO: most probably need better logic for escaping various quotes
     def args_join(args)
-      args.join(" ")
+      # A single CLI argument is an intentional shell program (for example, an env assignment or pipeline).
+      # Multiple CLI arguments are argv elements and must be escaped before entering the remote shell script.
+      return args.first if args.size == 1
+
+      Shellwords.join(args)
     end
 
     def progress
@@ -619,9 +645,32 @@ module Command
       raise shared_secret_policy_missing_message(grant) if policy.nil?
 
       ensure_shared_secret_policy_targets_secret!(grant, policy)
+      warn_if_shared_secret_uses_generated_password_placeholder(grant)
       policy
     end
 
+    def warn_if_shared_secret_uses_generated_password_placeholder(grant)
+      secret_name = grant.fetch(:secret_name)
+      secret = cp.reveal_secret(secret_name)
+      return unless secret&.dig("data", "password") == GENERATED_POSTGRES_PASSWORD_PLACEHOLDER
+
+      Shell.warn(
+        "Shared secret grant '#{grant.fetch(:name)}' targets secret '#{secret_name}', whose password " \
+        "is still the generated placeholder. Review apps will fail authentication until it is replaced."
+      )
+    # This is a best-effort warning. API, transport, and response-shape failures
+    # must not turn an optional diagnostic into a deployment blocker.
+    rescue StandardError
+      debug_shared_secret_placeholder_check_failure(secret_name)
+    end
+
+    def debug_shared_secret_placeholder_check_failure(secret_name)
+      Shell.debug(
+        "WARN",
+        "Could not inspect shared secret '#{secret_name}'; continuing without the optional placeholder diagnostic."
+      )
+    end
+
     def bind_shared_secret_policy_grant(grant, policy)
       policy_name = grant.fetch(:policy_name)
       return if identity_bound_to_policy_with_reveal?(policy)

data/lib/command/cleanup_stale_apps.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Command
-  class CleanupStaleApps < Base
+  class CleanupStaleApps < Base # rubocop:disable Metrics/ClassLength
     CLEANUP_MODE_OPTION = {
       name: :mode,
       params: {
@@ -24,7 +24,7 @@ module Command
     LONG_DESCRIPTION = <<~DESC
       - Acts on stale apps based on the creation date of the latest image, or the GVC if no images exist
       - With `--mode=delete` (default): deletes the whole app (GVC with all workloads, all volumesets and all images), and unbinds the app from the secrets policy and any configured `shared_secret_grants` policies as long as both the identity and each policy exist (and are bound)
-      - With `--mode=stop`: suspends all workloads via `cpflow ps:stop` — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
+      - With `--mode=stop`: suspends configured workloads that exist in the live GVC through Control Plane — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
       - `--mode=stop` only suspends workloads listed in `app_workloads` + `additional_workloads`; workloads present in the live GVC but missing from the config are skipped silently
       - `--mode=stop` returns once each workload is marked suspended; it does not wait for the workload to reach a not-ready state
       - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
@@ -101,14 +101,38 @@ module Command
     def process_app(app)
       if mode == "stop"
         progress.puts("Stopping app '#{app}'")
-        run_cpflow_command("ps:stop", "-a", app)
+        stop_configured_live_workloads(app)
       else
         run_cpflow_command("delete", "-a", app, "--yes")
       end
     end
 
+    def stop_configured_live_workloads(app)
+      app_config = config.find_app_config(app)
+      raise "Can't find config for stale app '#{app}'." unless app_config
+
+      configured_workloads = required_app_option(app_config, app, :app_workloads) +
+                             required_app_option(app_config, app, :additional_workloads)
+      live_workloads = (cp.fetch_workloads(app)&.fetch("items", []) || []).map { |workload| workload.fetch("name") }
+
+      (configured_workloads & live_workloads).each do |workload|
+        step("Stopping workload '#{workload}'") do
+          cp.set_workload_suspend(workload, true, app, missing_ok: true)
+        end
+      end
+    end
+
+    def required_app_option(app_config, app, option)
+      raise "Can't find option '#{option}' for app '#{app}' in 'controlplane.yml'." unless app_config.key?(option)
+
+      value = app_config.fetch(option)
+      raise "Option '#{option}' for app '#{app}' in 'controlplane.yml' must be an array." unless value.is_a?(Array)
+
+      value
+    end
+
     def action_description
-      mode == "stop" ? "suspend all workloads in" : "delete"
+      mode == "stop" ? "suspend configured workloads in" : "delete"
     end
 
     def mode

data/lib/command/copy_image_from_upstream.rb

@@ -80,6 +80,9 @@ module Command
         upstream_image = cp.latest_image(@upstream, @upstream_org) if !upstream_image || upstream_image == "latest"
         @commit = cp.extract_image_commit(upstream_image)
         @upstream_image_url = "#{@upstream_org}.registry.cpln.io/#{upstream_image}"
+      rescue ControlplaneApiDirect::ForbiddenError => e
+        Shell.write_to_tmp_stderr(e.message)
+        false
       end
     end
 

data/lib/command/deploy_image.rb

@@ -4,6 +4,12 @@ require "resolv"
 
 module Command
   class DeployImage < Base # rubocop:disable Metrics/ClassLength
+    WORKLOAD_IMAGE_UPDATE_MAX_ATTEMPTS = 30
+    # Preserve the general failure cap; only optimistic-concurrency conflicts get the longer convergence window.
+    WORKLOAD_IMAGE_UPDATE_CONFLICT_MAX_ATTEMPTS = 120
+    WORKLOAD_IMAGE_UPDATE_CONFLICT_PATTERN =
+      /(?:\b409\b|(?:\A|\n)[ \t]*(?:error:[ \t]*)?conflict[ \t]*(?:\r?\n|\z))/i
+
     NAME = "deploy-image"
     OPTIONS = [
       app_option(required: true),
@@ -107,17 +113,26 @@ module Command
       @requested_workload_names ||= Array(config.options[:workload]).map(&:to_s).uniq
     end
 
+    def app_image?(image)
+      image.to_s.match?(
+        %r{\A(?:/org/#{Regexp.escape(config.org)}/image/)?#{Regexp.escape(config.app)}[:@]}
+      )
+    end
+
     def deploy_image_to_workloads(image, workload_data_by_name) # rubocop:disable Metrics/MethodLength
       deployed_endpoints = {}
 
       workload_data_by_name.each do |workload, workload_data|
         workload_data.dig("spec", "containers").each do |container|
-          next unless container["image"].match?(%r{^/org/#{config.org}/image/#{config.app}[:@]})
+          next unless app_image?(container["image"])
 
           container_name = container["name"]
           step("Deploying image '#{image}' for workload '#{workload}'") do
-            cp.workload_set_image_ref(workload, container: container_name, image: image)
+            update_workload_image_ref(workload, container_name, image)
+
             deployed_endpoints[workload] = endpoint_for_workload(workload_data)
+            # A missing public endpoint is valid; the image update still completed successfully.
+            true
           end
           # Deploy the first matching app-image container per workload; CPLN workloads
           # are expected to have a single container that runs the app image.
@@ -128,10 +143,40 @@ module Command
       deployed_endpoints
     end
 
+    def update_workload_image_ref(workload, container, image)
+      attempts = 0
+
+      loop do
+        attempts += 1
+        result = cp.workload_set_image_ref(workload, container: container, image: image)
+        return true if result.fetch(:success)
+
+        output = result.fetch(:output).to_s
+        raise workload_image_update_error(output) if attempts >= workload_image_update_limit(output)
+
+        wait_before_workload_image_update_retry
+      end
+    end
+
+    def workload_image_update_limit(output)
+      return WORKLOAD_IMAGE_UPDATE_CONFLICT_MAX_ATTEMPTS if output.match?(WORKLOAD_IMAGE_UPDATE_CONFLICT_PATTERN)
+
+      WORKLOAD_IMAGE_UPDATE_MAX_ATTEMPTS
+    end
+
+    def workload_image_update_error(output)
+      output.strip.empty? ? "Command exited with non-zero status." : output
+    end
+
+    def wait_before_workload_image_update_retry
+      progress.print(".")
+      Kernel.sleep(1)
+    end
+
     def print_deployed_endpoints(deployed_endpoints)
       progress.puts("\nDeployed endpoints:")
       deployed_endpoints.each do |workload, endpoint|
-        progress.puts("  - #{workload}: #{endpoint}")
+        progress.puts("  - #{workload}: #{endpoint || '(no public endpoint)'}")
       end
     end
 
@@ -172,9 +217,15 @@ module Command
 
     def endpoint_for_workload(workload_data)
       endpoint = workload_data.dig("status", "endpoint")
+      return fallback_endpoint_for_workload(workload_data) unless endpoint
+
       Resolv.getaddress(endpoint.split("/").last)
       endpoint
     rescue Resolv::ResolvError
+      fallback_endpoint_for_workload(workload_data)
+    end
+
+    def fallback_endpoint_for_workload(workload_data)
       deployments = cp.fetch_workload_deployments(workload_data["name"])
       deployments.dig("items", 0, "status", "endpoint")
     end