@plainconceptsplatform/workflows 1.18.1 → 1.20.0

package/dist/workflow-catalog.js

@@ -16,7 +16,7 @@ export const workflowRoutes = [
     { name: "merge-gate", worker: "agent-merge-gate.md", description: "Decides what happens to the pull request the merge train hands it, the bot's or a person's: repair it, merge it, or hand it to a human.", defaultEnabled: true },
     { name: "audit", worker: "agent-audit.md", description: "Read-only repository audit. Finds 5-7 problems, scores each 1-10, and files a tracking report plus one story issue per top finding, each sized for Refine.", defaultEnabled: true },
     { name: "docs-audit", worker: "agent-docs-audit.md", description: "Read-only documentation audit, every fortnight. Checks the documentation against the code and the Platform standard, and files one issue that Refine then sizes and splits, only when something is stale.", defaultEnabled: false },
-    { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job opens a version-bump pull request with auto-merge; once it merges, release-tag.yml tags the commit and publishes the GitHub Release. Manual dispatch only (operation=release).", defaultEnabled: true, companions: ["release-tag.yml"] },
+    { name: "release", worker: "agent-release.md", description: "Writes release notes from the commit log, then a deterministic job opens a version-bump pull request with auto-merge; once it merges, release-tag.yml tags the commit and publishes the GitHub Release. Manual dispatch only (operation=release), or release-to-production.yml, which also deploys the new tag to production.", defaultEnabled: true, companions: ["release-tag.yml", "release-to-production.yml"] },
 ];
 /** What an install with no explicit selection gets. An optional worker is added by name. */
 export const defaultRouteNames = workflowRoutes

package/loops/actions/decide-agent-retry/action.yml

@@ -1,6 +1,6 @@
 # Managed by @plainconceptsplatform/workflows. Source: loops/actions/decide-agent-retry/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.
 name: Decide agent retry
-description: Say whether an agent job that failed is worth running again, from how long it ran and how many attempts have been made.
+description: Say whether an agent job that failed is worth running again, from how long it ran, how many attempts have been made, and which step it stopped in.
 inputs:
   token:
     description: GitHub token with actions read access, used to read this run's own jobs.
@@ -26,8 +26,14 @@ outputs:
     description: How long the agent job ran, or -1 when that could not be read.
     value: ${{ steps.decide.outputs.minutes }}
   cause:
-    description: 'Why a retry was chosen: short-run, runner-shutdown or cut-off. "none" when there is none.'
+    description: 'Why a retry was chosen: short-run, runner-shutdown or cut-off. "configuration" when a preflight step failed and nothing is retried; "cancelled" for a cancelled job; "none" when there is none.'
     value: ${{ steps.decide.outputs.cause }}
+  failed-step:
+    description: The name of the first step the agent job failed in, or empty.
+    value: ${{ steps.decide.outputs.failed-step }}
+  reason:
+    description: For a configuration failure, one paragraph for the issue naming the step and the fix. Empty otherwise.
+    value: ${{ steps.decide.outputs.reason }}
 runs:
   using: composite
   steps:
@@ -47,6 +53,12 @@ runs:
     # apply-review parked instead -- an Odyssey refine died in three minutes on
     # `Model 'glm-5-2' not found`, a gateway fault that clears in seconds, and waited on the
     # janitor's six-hourly sweep. Five copies of sixty lines is how one rule becomes five.
+    #
+    # And one failure is never repeated, however short: a preflight step (the harness sync and
+    # doctor, the CI provider merge) that refused the repository's own setup. It ended a consumer's
+    # refine in a minute, which read as a short run, and five attempts were spent and commented as
+    # a provider outage when the fix was one missing file (#527). classify-failure.sh names it
+    # `configuration` from the failed step's name, and that verdict wins over the duration.
     - name: Decide whether this failure is worth repeating
       id: decide
       shell: bash
@@ -72,24 +84,39 @@ runs:
         [ -n "$attempts" ] || attempts=0
         retry=false
         cause=none
-        # An unknown duration is treated as a long run: never retry on a guess.
-        if [ "$minutes" -ge 0 ] && [ "$minutes" -lt "$UNDER_MINUTES" ] && [ "$attempts" -lt "$PARK_AT" ]; then
-          retry=true
-          cause=short-run
+        failed_step=""
+        reason=""
+        work="$(mktemp -d)"
+        # The reads are best effort: a step list, a log or an annotation list that cannot be
+        # fetched leaves the decision to the duration, exactly as before these checks existed.
+        if [ -n "${job_id:-}" ]; then
+          gh api "repos/$REPO/actions/jobs/$job_id" --jq '.steps[]? | select(.conclusion == "failure") | .name' >"$work/failed-steps" 2>/dev/null || true
+          failed_step="$(head -1 "$work/failed-steps" 2>/dev/null || true)"
         fi
-        # A long run is repeated only when it was killed, not when it was wrong. The reads are best
-        # effort: a log or an annotation list that cannot be fetched leaves the run parked, exactly
-        # as before this check existed.
-        if [ "$retry" != true ] && [ "$attempts" -lt "$PARK_AT" ] && [ -n "${job_id:-}" ]; then
-          work="$(mktemp -d)"
+        kind=none
+        if [ -n "${job_id:-}" ] && [ "${conclusion:-}" != cancelled ]; then
           gh api "repos/$REPO/check-runs/$job_id/annotations" --paginate --jq '.[].message' >"$work/annotations" 2>/dev/null || true
           gh api "repos/$REPO/actions/jobs/$job_id/logs" >"$work/log" 2>/dev/null || true
-          kind="$(bash "$ACTION_PATH/classify-failure.sh" "$work/log" "$work/annotations" || echo none)"
-          if [ "$kind" != none ]; then
+          kind="$(bash "$ACTION_PATH/classify-failure.sh" "$work/log" "$work/annotations" "$work/failed-steps" || echo none)"
+        fi
+        rm -rf "$work"
+        if [ "$kind" = configuration ]; then
+          # Not a provider outage and not the agent's verdict: the model never started. The next
+          # attempt would fail the same way in the same minute, so no attempt is spent on it.
+          cause=configuration
+          fix="$(bash "$ACTION_PATH/classify-failure.sh" --fix "$failed_step")"
+          reason="The agent job stopped in its preflight step **${failed_step}** before the model started. That is this repository's configuration, not a provider outage, so it was not retried. ${fix} Once that is fixed, start the work again."
+        else
+          # An unknown duration is treated as a long run: never retry on a guess.
+          if [ "$minutes" -ge 0 ] && [ "$minutes" -lt "$UNDER_MINUTES" ] && [ "$attempts" -lt "$PARK_AT" ]; then
+            retry=true
+            cause=short-run
+          fi
+          # A long run is repeated only when it was killed, not when it was wrong.
+          if [ "$retry" != true ] && [ "$attempts" -lt "$PARK_AT" ] && [ "$kind" != none ]; then
             retry=true
             cause="$kind"
           fi
-          rm -rf "$work"
         fi
         # A cancelled agent job is a person or a newer run taking the work back, not an outage.
         # Pliny-Bot #816: refine was cancelled by hand and its label removed, then this step read
@@ -104,5 +131,7 @@ runs:
           echo "next=$((attempts + 1))"
           echo "minutes=$minutes"
           echo "cause=$cause"
+          echo "failed-step=$failed_step"
+          echo "reason=$reason"
         } >> "$GITHUB_OUTPUT"
-        echo "agent job ran for ${minutes}m; attempts so far ${attempts}; retry=${retry}; cause=${cause}"
+        echo "agent job ran for ${minutes}m; attempts so far ${attempts}; failed step '${failed_step}'; retry=${retry}; cause=${cause}"

package/loops/actions/decide-agent-retry/classify-failure.sh

@@ -20,19 +20,64 @@
 # shutdown is read from the annotations, which only GitHub writes, and the cut-off from the one line
 # immediately above the sandbox teardown.
 #
-# Usage: classify-failure.sh LOG_FILE ANNOTATIONS_FILE
-# Prints one word: runner-shutdown, cut-off or none.
+# One cause is the opposite, and repeating it is the wrong answer:
+#
+#   configuration    the job stopped in a preflight step before the model was ever started: the
+#                    harness sync and doctor (`sync-agents.mjs --strict`, `harness-doctor.mjs
+#                    --strict`) or the CI provider merge. Those read this repository's own files,
+#                    so the next attempt fails the same way in the same minute. A consumer with no
+#                    specialist `*-engineer.md` saw five of them, each commented as a provider
+#                    outage (#527). It is read from the name of the step GitHub marked failed,
+#                    which the jobs API reports and no tool output can forge.
+#
+# Usage: classify-failure.sh LOG_FILE ANNOTATIONS_FILE [FAILED_STEPS_FILE]
+#        classify-failure.sh --fix STEP_NAME
+# The first form prints one word: runner-shutdown, configuration, cut-off or none. FAILED_STEPS_FILE
+# holds the names of the job's failed steps, one per line. The second form prints what a person
+# does about a configuration failure in that step.
+
+# The fix sentences quote commands in backticks for Markdown, not for the shell.
+# shellcheck disable=SC2016
 
 set -euo pipefail
 
+# The steps in loops/workflows/shared/opencode-ci.md that only fail on the repository's own setup.
+# Kept here, next to the sentence that tells a person how to fix each, so the two cannot drift.
+preflight_fix() {
+  case "$1" in
+    "Sync harness agents and print model routing")
+      echo 'Run `node .opencode/scripts/sync-agents.mjs --strict` and `node .opencode/scripts/harness-doctor.mjs --strict` locally and fix what they report. `no *-engineer.md templates found` means the repository has no specialist engineer yet: run `/make-engineer` from agent-harness and commit the result.'
+      ;;
+    "Merge the CI-only OpenCode provider into opencode.jsonc")
+      echo 'The step error names the file: `opencode.ci.json` must exist and be valid JSON (`workflows update` installs it), and a tracked `opencode.jsonc` must be comment-free JSON.'
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+if [ "${1:-}" = "--fix" ]; then
+  preflight_fix "${2:-}" || echo 'Read the failed step in the run log and fix the repository setup it reports.'
+  exit 0
+fi
+
 log="${1:-}"
 annotations="${2:-}"
+failed_steps="${3:-}"
 
 if [ -n "$annotations" ] && [ -f "$annotations" ] && grep -qiE 'exit code 143|runner has received a shutdown signal|lost communication with the server|runner.*(was|has been) (deleted|terminated)' "$annotations"; then
   echo runner-shutdown
   exit 0
 fi
 
+if [ -n "$failed_steps" ] && [ -f "$failed_steps" ]; then
+  while IFS= read -r step; do
+    if preflight_fix "$step" >/dev/null; then
+      echo configuration
+      exit 0
+    fi
+  done < "$failed_steps"
+fi
+
 if [ -n "$log" ] && [ -f "$log" ]; then
   # The line the sandbox teardown starts on. grep exits 1 for none, which is an answer here.
   stop=$(grep -n '\[INFO\] Stopping containers' "$log" | head -1 | cut -d: -f1 || true)

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -25,6 +25,18 @@ MERGE_GATE_WORKER_MD="${WORKFLOWS_DIR}/agent-merge-gate.md"
 router_env() {
   sed -n "s/^  $1: *//p" "$ROUTER_YML" | head -1 | sed -e 's/^"\(.*\)"$/\1/' -e "s/^'\(.*\)'$/\1/"
 }
+# The App's login is the repository variable BOT_LOGIN with the package default, written as the
+# one expression `vars.BOT_LOGIN || 'platform-devbox[bot]'` wherever it is needed: the router's
+# TRUSTED_BOTS, bot-approve's `if:` and every worker's GH_AW_ALLOWED_BOTS. Resolve it the way
+# GitHub does, for a repository that sets the variable (pass the login) and one that does not
+# (pass nothing). A `${{ }}` copy resolves to the login, a bare one in an `if:` to a quoted string.
+resolve_bot_login() {
+  local login="${1:-}" with='\1'
+  [ -z "$login" ] || with="$login"
+  sed -E \
+    -e "s/\\\$\\{\\{ vars\\.BOT_LOGIN \\|\\| '([^']*)' \\}\\}/${with}/g" \
+    -e "s/vars\\.BOT_LOGIN \\|\\| '([^']*)'/'${with}'/g"
+}
 AUDIT_CRON="$(router_env AUDIT_CRON)"
 DOCS_AUDIT_CRON="$(router_env DOCS_AUDIT_CRON)"
 export AUDIT_CRON DOCS_AUDIT_CRON
@@ -396,7 +408,7 @@ fi
 # Bot logins are the same shape of problem. Most sites read env.TRUSTED_BOTS, but a job-level
 # `if:` cannot: GitHub does not expose the env context there, so bot-approve keeps literals and
 # they have to agree. Assert every bot login written anywhere in the router is in the list.
-trusted="$(router_env TRUSTED_BOTS)"
+trusted="$(router_env TRUSTED_BOTS | resolve_bot_login)"
 if [ -z "$trusted" ]; then
   MIRROR_OK=0; echo "FAIL: work-router.yml defines no TRUSTED_BOTS in its env: block" >&2
 else
@@ -2808,6 +2820,188 @@ assert "the hourly sweep's assume pass reaches refine in assume mode" assume \
 
 if [ "$RETRY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 
+echo "── Bot login ─────────────────────────────────────────────────────────────"
+
+# A repository with its own GitHub App was silently untrusted (#527): the App's bot-working label
+# reached the router from an actor the router did not know, `authorize` said false, call-refine
+# skipped, and the issue sat at `refine,bot-working` with no comment and no error. The login is
+# the repository variable BOT_LOGIN now, defaulting to platform-devbox[bot]. Each assertion here
+# runs the real router and worker text with the variable resolved both ways.
+BOT_OK=1
+CUSTOM_BOT='custom-app[bot]'
+
+# One expression, one default. A second spelling is a second thing to keep in step, and a bare
+# literal is the hard-coded login coming back.
+bot_files=("$ROUTER_YML")
+for route in "${ALL_WORKER_ROUTES[@]}"; do
+  if worker_installed "$route"; then bot_files+=("${WORKFLOWS_DIR}/agent-${route}.md"); fi
+done
+bot_exprs=$(cat "${bot_files[@]}" | grep -v '^ *#' | { grep -oE "vars\.BOT_LOGIN[^}')]*('[^']*')?" || true; } | sort -u)
+if [ -n "$bot_exprs" ] && [ "$bot_exprs" != "vars.BOT_LOGIN || 'platform-devbox[bot]'" ]; then
+  BOT_OK=0
+  echo "FAIL: BOT_LOGIN is spelled more than one way: $(printf '%s' "$bot_exprs" | tr '\n' ';')" >&2
+fi
+stray=$(grep -n 'platform-devbox\[bot\]' "${bot_files[@]}" | grep -vE ':[0-9]+: *#' |
+  grep -vF "vars.BOT_LOGIN || 'platform-devbox[bot]'" || true)
+if [ -n "$stray" ]; then
+  BOT_OK=0
+  echo "FAIL: platform-devbox[bot] is hard-coded outside the BOT_LOGIN expression:" >&2
+  printf '%s\n' "$stray" >&2
+fi
+
+# The router's authorize step, executed. `gh` answers nothing, as it does for an App, which has
+# no collaborator permission, so only TRUSTED_BOTS can make it trusted.
+authorize_script=$(awk '
+  /- name: Check the actor can start an agent/ { found = 1 }
+  found && /^ +run: \|$/ { body = 1; next }
+  body && /^ {0,9}[^ ]/ { exit }
+  body { print substr($0, 11) }' "$ROUTER_YML")
+fake_bin="$(mktemp -d)"
+printf '#!/usr/bin/env bash\nexit 1\n' > "${fake_bin}/gh"
+chmod +x "${fake_bin}/gh"
+authorize_as() {
+  local actor="$1" login="$2" out
+  out="$(mktemp)"
+  if ! PATH="${fake_bin}:$PATH" GITHUB_OUTPUT="$out" GITHUB_REPOSITORY=o/r EVENT=issues ACTOR="$actor" \
+    TRUSTED_BOTS="$(router_env TRUSTED_BOTS | resolve_bot_login "$login")" \
+    bash -c "$authorize_script" >/dev/null 2>&1; then
+    echo error
+  else
+    sed -n 's/^trusted=//p' "$out"
+  fi
+  rm -f "$out"
+}
+if [ -z "$authorize_script" ]; then
+  BOT_OK=0
+  echo "FAIL: could not extract the authorize step from work-router.yml" >&2
+else
+  assert "default config still trusts platform-devbox[bot]" true "$(authorize_as 'platform-devbox[bot]' '')"
+  assert "default config does not trust an unknown App" false "$(authorize_as "$CUSTOM_BOT" '')"
+  assert "BOT_LOGIN makes the router trust that App" true "$(authorize_as "$CUSTOM_BOT" "$CUSTOM_BOT")"
+fi
+rm -rf "$fake_bin"
+# And the trusted App's hand-off reaches refine: the classifier routes it, the caller requires the
+# trust asserted above, and the worker's pre_activation admits the same login.
+assert_route "a trusted custom App's bot-working label routes refine" refine \
+  EVENT=issues ACTION=labeled LABEL=bot-working ACTOR="$CUSTOM_BOT" \
+  'ISSUE_LABELS=["refine","bot-working"]' EVENT_ISSUE_NUMBER=42
+if ! grep -qE "^    if: needs\.classify\.outputs\.route == 'refine' && needs\.authorize\.outputs\.trusted == 'true'" "$ROUTER_YML"; then
+  BOT_OK=0
+  echo "FAIL: call-refine no longer gates on authorize.outputs.trusted" >&2
+fi
+for route in "${ALL_WORKER_ROUTES[@]}"; do
+  worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
+  [ -f "$worker_md" ] || continue
+  allowed=$(sed -n 's/^  GH_AW_ALLOWED_BOTS: *//p' "$worker_md" | head -1)
+  [ -n "$allowed" ] || continue
+  case ",$(printf '%s' "$allowed" | resolve_bot_login | tr -d '"')," in
+    *",platform-devbox[bot],"*) ;;
+    *) BOT_OK=0; echo "FAIL: agent-${route} no longer admits platform-devbox[bot] by default" >&2 ;;
+  esac
+  case ",$(printf '%s' "$allowed" | resolve_bot_login "$CUSTOM_BOT" | tr -d '"')," in
+    *",${CUSTOM_BOT},"*) ;;
+    *) BOT_OK=0; echo "FAIL: agent-${route} GH_AW_ALLOWED_BOTS ignores BOT_LOGIN, so pre_activation rejects that App" >&2 ;;
+  esac
+done
+
+# bot-approve's `if:` cannot read env, so it reads the variable itself.
+approve_if=$(awk '/^  bot-approve:$/{found=1} found && /^    if: >$/{body=1; next} body && /^    [a-z-]+:/{exit} body{print}' "$ROUTER_YML")
+if ! printf '%s' "$approve_if" | resolve_bot_login | grep -qF "github.actor == ('platform-devbox[bot]')"; then
+  BOT_OK=0
+  echo "FAIL: bot-approve no longer accepts platform-devbox[bot] by default" >&2
+fi
+if ! printf '%s' "$approve_if" | resolve_bot_login "$CUSTOM_BOT" | grep -qF "github.actor == ('${CUSTOM_BOT}')"; then
+  BOT_OK=0
+  echo "FAIL: bot-approve does not accept the App named by BOT_LOGIN" >&2
+fi
+
+if [ "$BOT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
+echo "── Preflight failures are configuration ──────────────────────────────────"
+
+# A preflight step that refused the repository's setup ended a consumer's refine in a minute; the
+# retry rule read a short run, commented "That is what a provider outage looks like" and spent all
+# five attempts (#527). It is classified from the failed step's name, never retried, and reported
+# with the step and the fix.
+PREFLIGHT_OK=1
+RETRY_DIR="${HERE}/../decide-agent-retry"
+classify_steps() {
+  local steps annotations
+  steps="$(mktemp)"; annotations="$(mktemp)"
+  printf '%s\n' "$1" > "$steps"
+  printf '%s\n' "${2:-}" > "$annotations"
+  bash "${RETRY_DIR}/classify-failure.sh" "" "$annotations" "$steps"
+  rm -f "$steps" "$annotations"
+}
+assert "a failed harness sync is a configuration failure" configuration \
+  "$(classify_steps 'Sync harness agents and print model routing')"
+assert "a failed CI provider merge is a configuration failure" configuration \
+  "$(classify_steps 'Merge the CI-only OpenCode provider into opencode.jsonc')"
+assert "a failed agent step is not a configuration failure" none \
+  "$(classify_steps 'Execute OpenCode CLI')"
+assert "a runner shutdown still wins over the step it interrupted" runner-shutdown \
+  "$(classify_steps 'Sync harness agents and print model routing' 'Process completed with exit code 143.')"
+if ! bash "${RETRY_DIR}/classify-failure.sh" --fix 'Sync harness agents and print model routing' | grep -qF '/make-engineer'; then
+  PREFLIGHT_OK=0
+  echo "FAIL: the harness sync fix no longer names /make-engineer" >&2
+fi
+# The names are matched exactly, so a renamed step in the shared setup disables the rule silently.
+while IFS= read -r step; do
+  [ -n "$step" ] || continue
+  if ! grep -qF -- "- name: ${step}" "${WORKFLOWS_DIR}/shared/opencode-ci.md"; then
+    PREFLIGHT_OK=0
+    echo "FAIL: classify-failure.sh names preflight step '${step}', which shared/opencode-ci.md no longer has" >&2
+  fi
+done < <(sed -n 's/^    "\(.*\)")$/\1/p' "${RETRY_DIR}/classify-failure.sh")
+
+# The decision itself, executed with a fake `gh`: a one-minute run that died in the harness sync
+# is not retried even with every attempt left, and the same minute dying in the agent step is.
+decide_script=$(awk '/^      run: \|$/{body=1; next} body{print substr($0, 9)}' "${RETRY_DIR}/action.yml")
+decide_with_failed_step() {
+  local step="$1" bin out
+  bin="$(mktemp -d)"; out="$(mktemp)"
+  {
+    echo '#!/usr/bin/env bash'
+    echo 'case "$*" in'
+    echo '  *"/runs/"*"/jobs"*) echo "7 2026-01-01T00:00:00Z 2026-01-01T00:01:00Z failure" ;;'
+    echo "  *\"/actions/jobs/7 \"*) echo \"${step}\" ;;"
+    echo '  *) exit 0 ;;'
+    echo 'esac'
+  } > "${bin}/gh"
+  chmod +x "${bin}/gh"
+  PATH="${bin}:$PATH" GITHUB_OUTPUT="$out" REPO=o/r RUN_ID=1 ACTION_PATH="$RETRY_DIR" \
+    ATTEMPTS=0 PARK_AT=5 UNDER_MINUTES=10 bash -c "$decide_script" >/dev/null 2>&1 || echo "error=true" >> "$out"
+  tr '\n' ' ' < "$out"
+  rm -rf "$bin" "$out"
+}
+config_decision=$(decide_with_failed_step 'Sync harness agents and print model routing')
+case "$config_decision" in
+  *"retry=false "*"cause=configuration "*"failed-step=Sync harness agents and print model routing "*"reason=The agent job stopped in its preflight step"*) PASS=$((PASS + 1)) ;;
+  *) FAIL=$((FAIL + 1)); echo "FAIL: a failed harness sync is not reported as configuration without a retry: ${config_decision}" >&2 ;;
+esac
+outage_decision=$(decide_with_failed_step 'Execute OpenCode CLI')
+case "$outage_decision" in
+  *"retry=true "*"cause=short-run "*) PASS=$((PASS + 1)) ;;
+  *) FAIL=$((FAIL + 1)); echo "FAIL: a short run that died in the agent step is no longer retried: ${outage_decision}" >&2 ;;
+esac
+
+# Every worker that uses the rule reports the configuration failure, keeps the outage wording off
+# it, and parks it without `stalled`, which the janitor would retry into the same failure.
+for route in refine implement triage apply-review; do
+  worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
+  [ -f "$worker_md" ] || continue
+  if ! grep -qF "steps.decide.outputs.cause == 'configuration'" "$worker_md" ||
+     ! grep -qF '${{ steps.decide.outputs.reason }}' "$worker_md"; then
+    PREFLIGHT_OK=0
+    echo "FAIL: agent-${route} does not report a configuration failure with its step and fix" >&2
+  fi
+  if ! grep -qF "steps.decide.outputs.cause != 'configuration' && env.STALLED_LABEL" "$worker_md"; then
+    PREFLIGHT_OK=0
+    echo "FAIL: agent-${route} flags a configuration failure as stalled, so the janitor retries it" >&2
+  fi
+done
+if [ "$PREFLIGHT_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo "── Ways a run ends with nothing ──────────────────────────────────────────"
 
 # A run can end without a pull request in five ways and they need different answers. One sentence
@@ -3162,7 +3356,7 @@ for job in authorize classify; do
   sed -n "/^  ${job}:\$/,/^    runs-on:/p" "${WORKFLOWS_DIR}/work-router.yml" | grep -qF "if: vars.AGENTIC_WORKFLOWS_DISABLED == ''" ||
     { OFF_OK=0; echo "FAIL: the router's ${job} job ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
 done
-for f in "${WORKFLOWS_DIR}/authorize-bot-work.yml" "${WORKFLOWS_DIR}/release-tag.yml"; do
+for f in "${WORKFLOWS_DIR}/authorize-bot-work.yml" "${WORKFLOWS_DIR}/release-tag.yml" "${WORKFLOWS_DIR}/release-to-production.yml"; do
   [ -f "$f" ] || continue
   grep -qF "vars.AGENTIC_WORKFLOWS_DISABLED == ''" "$f" ||
     { OFF_OK=0; echo "FAIL: $(basename "$f") ignores AGENTIC_WORKFLOWS_DISABLED" >&2; }
@@ -3476,6 +3670,30 @@ fi
   if [ "$GATE_RUN_ID_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Release to production ──────────────────────────────────────────────────"
+
+# One button ships a release: release-to-production.yml runs the release worker with deploy=true
+# (the router's workflow_dispatch is at GitHub's ten-input limit), the release pull request carries
+# a marker, and release-tag.yml deploys the tag only when it finds it. A release without the marker
+# must keep not deploying.
+RTP_YML="${WORKFLOWS_DIR}/release-to-production.yml"
+RT_YML="${WORKFLOWS_DIR}/release-tag.yml"
+if [ -f "$RTP_YML" ] && worker_installed release; then
+  RTP_OK=1
+  rtp() { grep -qE "$1" "$2" || { RTP_OK=0; echo "FAIL: release to production: $3" >&2; }; }
+  rtp 'uses: \./\.github/workflows/agent-release\.lock\.yml' "$RTP_YML" 'the button must run the release worker'
+  rtp '^      deploy: "true"$' "$RTP_YML" 'the button must ask the release worker for a deploy'
+  rtp 'default: minor' "$RTP_YML" 'the button must default to a minor bump'
+  rtp '^    permissions: write-all$' "$RTP_YML" 'the button must grant the worker write-all, or the run never starts'
+  if grep -qE '^      deploy:' "$ROUTER_YML"; then RTP_OK=0; echo "FAIL: release to production: the router's workflow_dispatch is at the ten-input limit; deploy belongs to the button" >&2; fi
+  rtp '<!-- release-deploy -->' "${WORKFLOWS_DIR}/agent-release.md" 'the release worker never writes the deploy marker'
+  rtp 'if \[ "\$DEPLOY" = "true" \]' "${WORKFLOWS_DIR}/agent-release.md" 'the deploy marker must depend on the deploy input'
+  rtp "if: steps.release.outputs.deploy == 'true'" "$RT_YML" 'release-tag.yml must deploy only when the release asked for it'
+  rtp 'gh workflow run "\$DEPLOY_WORKFLOW" --repo "\$REPO" --ref "\$TAG"' "$RT_YML" 'release-tag.yml must start the deploy on the tag'
+  rtp '^  DEPLOY_WORKFLOW: ' "$RT_YML" 'release-tag.yml does not declare DEPLOY_WORKFLOW'
+  if [ "$RTP_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+fi
+
 echo "── App error privacy ─────────────────────────────────────────────────────"
 
 # The application error report files into the private repository rather than out of it, so

package/loops/docs/diagrams.md

@@ -336,10 +336,12 @@ flowchart TD
     implRetry{"Died under 6 minutes<br/>with no answer?"}
     implRetry -->|"yes: provider outage"| implAgain(("Retry<br/>attempt N of 5, label kept"))
     implRetry -.->|"no: it answered, wrongly"| implFail
+    implRetry -.->|"no: a preflight step refused<br/>the repository's setup"| implConfig
     implAgain -->|"re-enters via the router"| implStart
     implHandoff(("Handed off<br/>PR open, bot-working removed,<br/>the gate decides next"))
     implIdle(("Idle<br/>closed, or held by future"))
     implFail(("Parked<br/>review added, a rerun<br/>would fail the same way"))
+    implConfig(("Parked as configuration<br/>review, no stalled, one comment<br/>naming the step and the fix"))
 
     implStackStart("check-stack-branch<br/>(router job, rung 1)<br/>the issue carries<br/>stack-root-branch?") -.->|"no: flat mode,<br/>nothing happens"| implIdle
     implStackStart -->|"yes: the workflow dispatches<br/>this worker with ref: feat/N<br/>so the agent never fetches"| implStart
@@ -354,14 +356,16 @@ flowchart TD
     class implReserve,implFacts,implTodos,implCode,implPr,implStackStart action
     class implEligible,implCheck,implVerify,implRetry decision
     class implIdle idle
-    class implFail failure
+    class implFail,implConfig failure
     class implHandoff,implAgain success
 ```
 
 The retry belt exists because a provider outage kills a run in a couple of minutes with no answer,
 and that used to burn the issue and hand it to a human. A run that worked for half an hour and then
 failed produced an answer that was wrong; repeating it costs the whole fleet the same half hour to
-be wrong again, so only the short deaths are retried.
+be wrong again, so only the short deaths are retried. A short death in a preflight step (the harness
+sync and doctor, the CI provider merge) is the exception: it is the repository's setup, not the
+provider, so it is reported as a configuration failure with the step and the fix and never retried.
 
 A stacked child enters the same worker through a different door: the router's `check-stack-branch`
 job reads the issue's markers before anything runs, and dispatches the compiled workflow with
@@ -595,6 +599,7 @@ nothing reaches `main` except through a pull request.
 ```mermaid
 flowchart TD
     relStart("Work Router<br/>release route<br/>operation=release") --> relFacts
+    relButton("Release to production button<br/>bump (default minor), deploy=true") --> relFacts
     relFacts("Facts (rung 3)<br/>Commit log since the last tag<br/>and the current version, to disk") --> relAgent
     relAgent("Agent (rung 5)<br/>Categorise by conventional-commit<br/>prefix, write release-notes.md.<br/>The only judgement in this route") --> relNoop
     relNoop("noop<br/>the agent writes a file,<br/>not a GitHub object") --> relConclude
@@ -603,7 +608,11 @@ flowchart TD
     relMerge{"CI green and<br/>auto-merge allowed?"}
     relMerge -->|yes| relTag
     relMerge -.->|auto-merge disabled| relOpen
-    relTag("release-tag.yml on push to main<br/>GITHUB_TOKEN: tag vX.Y.Z,<br/>Release with the PR body as notes") --> relDone
+    relTag("release-tag.yml on push to main<br/>GITHUB_TOKEN: tag vX.Y.Z,<br/>Release with the PR body as notes") --> relDeployQ
+    relDeployQ{"Deploy marker<br/>on the release PR?"}
+    relDeployQ -->|no| relDone
+    relDeployQ -->|yes| relDeploy
+    relDeploy(("Deploying<br/>DEPLOY_WORKFLOW started on the tag,<br/>pro reviewers still apply"))
     relConclude -.->|fails| relFail
     relOpen(("PR left open<br/>warning names the fix"))
     relDone(("Released<br/>tag and Release published,<br/>no tag-triggered workflow fired"))
@@ -616,16 +625,20 @@ flowchart TD
     classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
     classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
     class relStart start
-    class relFacts,relAgent,relNoop,relPr,relTag action
-    class relConclude,relMerge decision
+    class relButton,relFacts,relAgent,relNoop,relPr,relTag action
+    class relConclude,relMerge,relDeployQ decision
     class relFail failure
     class relOpen idle
-    class relDone success
+    class relDone,relDeploy success
 ```
 
 The version bump, the tag and the Release are deterministic on purpose. The agent's only output is
 a file on disk, so a confused model cannot publish a release. The tag and the Release use
 `GITHUB_TOKEN` so that a consumer deploying on `v*` tags does not deploy because a release was cut.
+The **Release to production** button (`release-to-production.yml`) is the one way a release deploys:
+it runs the worker directly with `deploy=true` (the router's dispatch is at GitHub's ten-input
+limit), the release pull request carries `<!-- release-deploy -->`,
+and only then does `release-tag.yml` start `DEPLOY_WORKFLOW` on the tag, explicitly.
 
 
 ---

package/loops/workflows/agent-apply-review.md

@@ -37,7 +37,9 @@ env:
   RETRY_COMMENT: "That is what a provider outage looks like -- the run ended before it could produce an answer -- so this is being tried again from the start. It is a fresh run rather than a continuation: nothing is carried over from the attempt that failed."
   INCOMPLETE_COMMENT: "Applying the review feedback ended without an outcome. This worker has no retry of its own: it runs again when somebody reviews or comments on the pull request, and the issue is flagged so it is not lost until then."
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
-  GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
+  # The bot actors pre_activation admits. BOT_LOGIN is the repository variable naming the App's
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The router trusts the same login.
+  GH_AW_ALLOWED_BOTS: "${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }},github-actions[bot]"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"
@@ -383,6 +385,9 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ needs.subject.outputs.issue }}
           labels: ${{ env.WORKING_LABEL }}
+      # A configuration failure is parked for a person without `stalled`: the janitor retries
+      # stalled work, and a preflight step that refused the repository's setup fails the same way
+      # on every retry until somebody changes the repository (#527).
       - name: Flag for human review
         if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
         uses: ./.github/actions/add-issue-labels
@@ -391,9 +396,19 @@ jobs:
           issue-number: ${{ needs.subject.outputs.issue }}
           labels: |-
             ${{ env.REVIEW_LABEL }}
-            ${{ env.STALLED_LABEL }}
+            ${{ steps.decide.outputs.cause != 'configuration' && env.STALLED_LABEL || '' }}
+      - name: Report the configuration failure
+        if: steps.decide.outputs.cause == 'configuration'
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ needs.subject.outputs.issue }}
+          body: |
+            ${{ env.REVIEW_MARKER }}
+            ${{ steps.decide.outputs.reason }}
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
       - name: Report missing review feedback outcome
-        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
+        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled' && steps.decide.outputs.cause != 'configuration'
         uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}

package/loops/workflows/agent-implement.md

@@ -83,7 +83,9 @@ env:
   # copied here before the agent starts. Context only: the prompt says how it may be used.
   MOCKUP_BRANCH: mockups
   MOCKUP_DIR: /tmp/gh-aw/agent/mockup
-  GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
+  # The bot actors pre_activation admits. BOT_LOGIN is the repository variable naming the App's
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The router trusts the same login.
+  GH_AW_ALLOWED_BOTS: "${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }},github-actions[bot]"
 description: |
   Implements an issue and opens a pull request. Stops there: the merge decision belongs to
   `agent-merge-gate.md`, which runs once CI has reported. Replaces the `impl-*` chain in
@@ -617,6 +619,9 @@ jobs:
           labels: |
             ${{ env.WORKING_LABEL }}
             implement
+      # A configuration failure is parked for a person without `stalled`: the janitor retries
+      # stalled work, and a preflight step that refused the repository's setup fails the same way
+      # on every retry until somebody changes the repository (#527).
       - name: Flag for human review
         if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
         uses: ./.github/actions/add-issue-labels
@@ -625,9 +630,19 @@ jobs:
           issue-number: ${{ inputs.issue-number }}
           labels: |-
             ${{ env.REVIEW_LABEL }}
-            ${{ env.STALLED_LABEL }}
+            ${{ steps.decide.outputs.cause != 'configuration' && env.STALLED_LABEL || '' }}
+      - name: Report the configuration failure
+        if: steps.decide.outputs.cause == 'configuration'
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ inputs.issue-number }}
+          body: |
+            ${{ env.IMPLEMENT_MARKER }}
+            ${{ steps.decide.outputs.reason }}
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
       - name: Report missing implementation outcome
-        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
+        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled' && steps.decide.outputs.cause != 'configuration'
         uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}

package/loops/workflows/agent-merge-gate.md

@@ -105,10 +105,12 @@ env:
   # one unusable report can keep every other bot pull request in the repository waiting.
   PARK_AT_UNUSABLE_OUTPUT: "2"
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
-  GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
+  # The bot actors pre_activation admits. BOT_LOGIN is the repository variable naming the App's
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The router trusts the same login.
+  GH_AW_ALLOWED_BOTS: "${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }},github-actions[bot]"
   # The bots whose pull requests the gate takes, in every spelling GitHub uses for one account.
   # Any other author needs write access to the repository, as they would to push the branch.
-  TRUSTED_BOTS: "github-actions[bot] app/github-actions platform-devbox[bot]"
+  TRUSTED_BOTS: "github-actions[bot] app/github-actions ${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }}"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"

package/loops/workflows/agent-refine.md

@@ -92,7 +92,9 @@ env:
   INCOMPLETE_COMMENT: "Automated refinement ended without an outcome. The refine label remains for a retry."
   SAFE_OUTPUT_COMMENT_PREFIX: "Refinement update"
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
-  GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
+  # The bot actors pre_activation admits. BOT_LOGIN is the repository variable naming the App's
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The router trusts the same login.
+  GH_AW_ALLOWED_BOTS: "${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }},github-actions[bot]"
   REFINE_ISSUE_PATH: /tmp/gh-aw/refine-issue.json
   REFINE_COMMENTS_PATH: /tmp/gh-aw/refine-comments.json
   GIT_AUTHOR_NAME: "github-actions[bot]"
@@ -939,6 +941,9 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ inputs.issue-number }}
           labels: ${{ env.WORKING_LABEL }}
+      # A configuration failure is parked for a person without `stalled`: the janitor retries
+      # stalled work, and a preflight step that refused the repository's setup fails the same way
+      # on every retry until somebody changes the repository (#527).
       - name: Flag for human review
         if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
         uses: ./.github/actions/add-issue-labels
@@ -947,9 +952,19 @@ jobs:
           issue-number: ${{ inputs.issue-number }}
           labels: |-
             ${{ env.REVIEW_LABEL }}
-            ${{ env.STALLED_LABEL }}
+            ${{ steps.decide.outputs.cause != 'configuration' && env.STALLED_LABEL || '' }}
+      - name: Report the configuration failure
+        if: steps.decide.outputs.cause == 'configuration'
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ inputs.issue-number }}
+          body: |
+            ${{ env.REFINE_MARKER }}
+            ${{ steps.decide.outputs.reason }}
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
       - name: Report missing refinement outcome
-        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
+        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled' && steps.decide.outputs.cause != 'configuration'
         uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}

package/loops/workflows/agent-release.md

@@ -40,6 +40,11 @@ on:
         required: false
         type: string
         default: "auto"
+      deploy:
+        description: "true when release-to-production.yml asked for a deploy: the release PR then carries the deploy marker"
+        required: false
+        type: string
+        default: "false"
 
 runs-on: agents-arc
 runs-on-slim: agents-arc
@@ -233,10 +238,18 @@ jobs:
           BASE: ${{ steps.branch.outputs.base }}
           BRANCH: ${{ steps.branch.outputs.branch }}
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          DEPLOY: ${{ inputs.deploy }}
         run: |
           set -euo pipefail
+          # The deploy marker is what makes release-tag.yml start the production deploy on the
+          # new tag. Only release-to-production.yml asks for it; a plain release route never does.
           {
             echo "<!-- release:v${NEW_VERSION} -->"
+            if [ "$DEPLOY" = "true" ]; then
+              echo "<!-- release-deploy -->"
+              echo "> Deploys to production once this merges and v${NEW_VERSION} is tagged."
+              echo
+            fi
             cat /tmp/release-notes.md
           } > /tmp/release-pr-body.md
           url=$(gh pr create \

package/loops/workflows/agent-triage.md

@@ -45,7 +45,9 @@ env:
   SAFE_OUTPUT_COMMENT_PREFIX: "Triage assessment"
   ISSUE_CONTEXT_PATH: /tmp/gh-aw/agent/issue-context.json
   OPEN_ISSUES_PATH: /tmp/gh-aw/agent/open-issues.json
-  GH_AW_ALLOWED_BOTS: "platform-devbox[bot],github-actions[bot]"
+  # The bot actors pre_activation admits. BOT_LOGIN is the repository variable naming the App's
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The router trusts the same login.
+  GH_AW_ALLOWED_BOTS: "${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }},github-actions[bot]"
   GIT_AUTHOR_NAME: "github-actions[bot]"
   GIT_AUTHOR_EMAIL: "github-actions[bot]@users.noreply.github.com"
   GIT_COMMITTER_NAME: "github-actions[bot]"
@@ -389,6 +391,9 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           issue-number: ${{ inputs.issue-number }}
           labels: ${{ env.WORKING_LABEL }}
+      # A configuration failure is parked for a person without `stalled`: the janitor retries
+      # stalled work, and a preflight step that refused the repository's setup fails the same way
+      # on every retry until somebody changes the repository (#527).
       - name: Flag for human review
         if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
         uses: ./.github/actions/add-issue-labels
@@ -397,9 +402,19 @@ jobs:
           issue-number: ${{ inputs.issue-number }}
           labels: |-
             ${{ env.REVIEW_LABEL }}
-            ${{ env.STALLED_LABEL }}
+            ${{ steps.decide.outputs.cause != 'configuration' && env.STALLED_LABEL || '' }}
+      - name: Report the configuration failure
+        if: steps.decide.outputs.cause == 'configuration'
+        uses: ./.github/actions/create-issue-comment
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ inputs.issue-number }}
+          body: |
+            ${{ env.TRIAGE_MARKER }}
+            ${{ steps.decide.outputs.reason }}
+            [View this workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
       - name: Report missing triage outcome
-        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled'
+        if: steps.decide.outputs.retry != 'true' && steps.decide.outputs.cause != 'cancelled' && steps.decide.outputs.cause != 'configuration'
         uses: ./.github/actions/create-issue-comment
         with:
           token: ${{ steps.app-token.outputs.token }}

package/loops/workflows/release-tag.yml

@@ -19,6 +19,14 @@ on:
 permissions:
   contents: write
   pull-requests: read
+  # Starting DEPLOY_WORKFLOW on the tag when the release pull request asked for a deploy.
+  actions: write
+
+env:
+  # The workflow that deploys a `v*` tag to production. Started on the new tag, with GITHUB_TOKEN,
+  # only when the release pull request carries the deploy marker (release-to-production.yml).
+  DEPLOY_WORKFLOW: app-deploy.yml
+  DEPLOY_MARKER: "<!-- release-deploy -->"
 
 concurrency:
   group: release-tag
@@ -38,6 +46,7 @@ jobs:
         with:
           persist-credentials: false
       - name: Tag the release commit and publish the GitHub Release
+        id: release
         env:
           GH_TOKEN: ${{ github.token }}
           REPO: ${{ github.repository }}
@@ -80,12 +89,19 @@ jobs:
           marker="<!-- release:${tag} -->"
           gh api "repos/$REPO/commits/$SHA/pulls" > /tmp/pulls.json
           MARKER="$marker" node -e '
-            const pulls = JSON.parse(require("fs").readFileSync("/tmp/pulls.json", "utf8"));
+            const fs = require("fs");
+            const pulls = JSON.parse(fs.readFileSync("/tmp/pulls.json", "utf8"));
             const pr = pulls.find((p) => p.merged_at && (p.body || "").includes(process.env.MARKER));
             if (!pr) process.exit(3);
-            const notes = pr.body.split(/\r?\n/).filter((line) => line.trim() !== process.env.MARKER).join("\n").trim();
-            require("fs").writeFileSync("/tmp/release-notes.md", notes + "\n");
-            console.log(`Notes from #${pr.number}`);
+            const deploy = pr.body.includes(process.env.DEPLOY_MARKER);
+            // Neither marker nor the deploy notice belongs in the published release notes.
+            const notes = pr.body.split(/\r?\n/)
+              .filter((line) => line.trim() !== process.env.MARKER && line.trim() !== process.env.DEPLOY_MARKER)
+              .filter((line) => !line.startsWith("> Deploys to production once this merges"))
+              .join("\n").trim();
+            fs.writeFileSync("/tmp/release-notes.md", notes + "\n");
+            fs.writeFileSync("/tmp/release-deploy", deploy ? "true" : "false");
+            console.log(`Notes from #${pr.number}${deploy ? ", deploy requested" : ""}`);
           ' || status=$?
 
           if [ "${status:-0}" -eq 3 ]; then
@@ -98,3 +114,30 @@ jobs:
             gh release create "$tag" --repo "$REPO" --target "$SHA" --title "$tag" --notes-file /tmp/release-notes.md
           fi
           echo "Tagged $SHA as $tag and published the GitHub Release."
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "deploy=$(cat /tmp/release-deploy 2>/dev/null || echo false)" >> "$GITHUB_OUTPUT"
+
+      # The tag above was created with GITHUB_TOKEN, so its push starts no workflow: a release does
+      # not ship by itself. A workflow_dispatch is the exception GitHub allows that token, so a
+      # release that asked for a deploy starts DEPLOY_WORKFLOW on the tag explicitly. The deploy
+      # workflow's own `pro` environment rules (required reviewers) still apply.
+      - name: Deploy the release to production
+        if: steps.release.outputs.deploy == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ steps.release.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ ! -f ".github/workflows/${DEPLOY_WORKFLOW}" ]; then
+            echo "::warning::The release asked for a deploy, but .github/workflows/${DEPLOY_WORKFLOW} does not exist; $TAG was tagged and not deployed."
+            exit 0
+          fi
+          gh workflow run "$DEPLOY_WORKFLOW" --repo "$REPO" --ref "$TAG"
+          echo "Started $DEPLOY_WORKFLOW on $TAG."
+          {
+            echo "### $TAG is deploying to production"
+            echo
+            echo "Follow it in [${DEPLOY_WORKFLOW}](${GITHUB_SERVER_URL}/${REPO}/actions/workflows/${DEPLOY_WORKFLOW})."
+          } >> "$GITHUB_STEP_SUMMARY"

package/loops/workflows/release-to-production.yml

@@ -0,0 +1,50 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/release-to-production.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+name: Release to production
+# The one button for a production release, run from the repository's Actions tab (or the badge in
+# its README): Run workflow, then Run workflow again. It runs the release worker with the bump
+# chosen here and deploy=true: the worker opens the `chore(release): vX.Y.Z` pull request carrying a
+# deploy marker, it auto-merges, release-tag.yml tags it, and because of the marker starts
+# DEPLOY_WORKFLOW on the new tag, which ships to production. A `pro` environment with required
+# reviewers still asks a person before the production stage runs.
+#
+# It calls the worker directly, as the router's call-release job does, because the router's
+# workflow_dispatch is at GitHub's limit of ten inputs and has no room for a deploy flag. Running a
+# workflow by hand already requires write access to the repository, which is what the router's
+# authorize job checks. The release route on its own (Main Work Router, operation=release) is
+# unchanged: it tags and publishes a release without deploying anything.
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version bump
+        required: true
+        type: choice
+        default: minor
+        options:
+          - minor
+          - patch
+          - major
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-to-production
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Release with a deploy
+    # AGENTIC_WORKFLOWS_DISABLED, a repository variable with any value, turns the automation off.
+    if: vars.AGENTIC_WORKFLOWS_DISABLED == ''
+    uses: ./.github/workflows/agent-release.lock.yml
+    # The caller grants what the worker requests; narrower grants make the whole run fail to start.
+    permissions: write-all
+    with:
+      version-bump: ${{ inputs.bump }}
+      deploy: "true"
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.FORGE_API_KEY }}
+      # The release PR is pushed and opened with the App token so its CI runs; see the worker's conclude.
+      BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
+      BOT_PRIVATE_KEY: ${{ secrets.BOT_PRIVATE_KEY }}

package/loops/workflows/work-router.yml

@@ -138,7 +138,12 @@ env:
   # separated, and every login the same account can present: GitHub reports an App as
   # `name[bot]` on some endpoints and `app/name` on others, so both spellings belong here.
   # Adding a third bot used to mean finding four hand-written comparisons across this file.
-  TRUSTED_BOTS: "github-actions[bot] app/github-actions platform-devbox[bot]"
+  # The App the repository's BOT_APP_ID belongs to is the repository variable BOT_LOGIN, its
+  # `<slug>[bot]` login; unset, it is platform-devbox[bot]. The same expression sits in
+  # bot-approve's `if:` and in every worker's GH_AW_ALLOWED_BOTS, so one variable moves all three.
+  # Without it a repository with its own App was silently untrusted: the App's bot-working label
+  # left `authorize` false and the worker never ran, with no comment and no error (#527).
+  TRUSTED_BOTS: "github-actions[bot] app/github-actions ${{ vars.BOT_LOGIN || 'platform-devbox[bot]' }}"
   # How long an issue may sit parked with `stalled` before the janitor retries it, and how many
   # times it tries before leaving the issue to a person. Only machine failures are retried; a
   # verdict the agent reached on purpose is reported and never re-run, because re-running a
@@ -1215,7 +1220,7 @@ jobs:
     needs: classify
     if: >
       needs.classify.outputs.route == 'bot-approve' &&
-        (github.actor == 'app/github-actions' || github.actor == 'platform-devbox[bot]')
+        (github.actor == 'app/github-actions' || github.actor == (vars.BOT_LOGIN || 'platform-devbox[bot]'))
     runs-on: [agents-aw, "affinity-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}"]
     timeout-minutes: 5
     permissions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",