@meffecta/agent 1.0.3 → 1.0.8

package/scripts/lib/cli-names.sh

@@ -0,0 +1,55 @@
+# What to call the next command, in output an operator reads. Sourced, never run.
+#
+# Almost every operator reaches these scripts through the CLI — `meffecta-agent deploy` —
+# and has never seen a .sh file: the engine's repo is private, so a deployment run by
+# someone outside Meffecta cannot clone it, and the scripts arrive vendored inside the npm
+# package or lifted out of the image. Printing "run ./scripts/deploy.sh next" names a file
+# they do not have.
+#
+# The CLI exports MEFFECTA_CLI with the invocation it was reached by, which is both the
+# name to print and the proof that a CLI is there at all. Without it, the operator is
+# running the file directly and the filename IS the answer.
+#
+# This is its own lib rather than part of deployment.sh because create-project.sh and
+# update-tooling.sh deliberately avoid the deployment config — they run before there is
+# one, or beside it — and still have to name their next step.
+
+CLI_LIB_SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# cmd <subcommand> → "meffecta-agent deploy", or "/path/to/scripts/deploy.sh"
+cmd() {
+  if [ -n "${MEFFECTA_CLI:-}" ]; then
+    printf '%s %s' "${MEFFECTA_CLI}" "$1"
+    return
+  fi
+  local file
+  case "$1" in
+    setup-infra) file="setup-infrastructure.sh" ;;
+    artifact-cleanup) file="set-artifact-cleanup.sh" ;;
+    mint-gmail) file="mint-gmail-token.mjs" ;;
+    mint-graph) file="mint-graph-token.mjs" ;;
+    verify-credentials) file="verify-credentials.mjs" ;;
+    *) file="$1.sh" ;;
+  esac
+  printf '%s/%s' "${CLI_LIB_SCRIPTS_DIR}" "${file}"
+}
+
+# The same for the running script naming itself — "run this again from there". $0 is an
+# absolute path inside node_modules when the CLI spawned it, which is not a thing anyone
+# would type.
+self_cmd() {
+  [ -n "${MEFFECTA_CLI:-}" ] || { printf '%s' "$0"; return; }
+  local base
+  base="$(basename "$0")"
+  case "${base}" in
+    setup-infrastructure.sh) printf '%s setup-infra' "${MEFFECTA_CLI}" ;;
+    set-artifact-cleanup.sh) printf '%s artifact-cleanup' "${MEFFECTA_CLI}" ;;
+    mint-gmail-token.mjs) printf '%s mint-gmail' "${MEFFECTA_CLI}" ;;
+    mint-graph-token.mjs) printf '%s mint-graph' "${MEFFECTA_CLI}" ;;
+    *) printf '%s %s' "${MEFFECTA_CLI}" "${base%.*}" ;;
+  esac
+}
+
+# True when the operator has the CLI, i.e. when there is a `meffecta-agent doctor` to point
+# at. Guards the lines that only make sense with one.
+has_cli() { [ -n "${MEFFECTA_CLI:-}" ]; }

package/scripts/lib/deployment.sh

@@ -22,6 +22,9 @@
 # Config file format is plain KEY=value lines, # comments allowed. See
 # deployment.env.example.
 
+# What to call the next command in output: cmd / self_cmd / has_cli.
+. "$(dirname "${BASH_SOURCE[0]}")/cli-names.sh"
+
 # Consume --config <file> from a script's arguments before it parses its own.
 # Usage: eval "$(extract_config_flag "$@")" — sets CONFIG_FILE and rewrites "$@".
 CONFIG_FILE=""
@@ -62,6 +65,13 @@ resolve_deployment() {
   REGION="${REGION:-europe-west1}"
   ARTIFACT_REPO="${ARTIFACT_REPO:-${SERVICE:-agent}-images}"
   GHCR_IMAGE="${GHCR_IMAGE:-ghcr.io/meffecta/agent}"
+  # How the engine image reaches Cloud Run, which can only ever pull from Artifact
+  # Registry. `proxy` makes ARTIFACT_REPO a remote repository in front of ghcr.io, so AR
+  # fetches on demand and no local docker is involved at all. `mirror` is the older path:
+  # pull from ghcr.io on the operator's machine, retag, push — which needs docker, and
+  # pushes several gigabytes for every engine version.
+  REGISTRY_MODE="${REGISTRY_MODE:-proxy}"
+  GHCR_PATH="${GHCR_IMAGE#*/}"   # ghcr.io/meffecta/agent → meffecta/agent
   TIMEZONE="${TIMEZONE:-Europe/Stockholm}"
 
   # The runtime shape, asserted by deploy.sh on every rollout so the deployed service
@@ -85,10 +95,15 @@ No deployment.env found in $(pwd).
 That file lives in the deployment's content repo (committed — none of it is
 secret), so the usual fix is to run this from there:
 
-    cd /path/to/your-content-repo && ${0}
+    cd /path/to/your-content-repo && $(self_cmd)
 
-Creating one: copy scripts/deployment.env.example beside your jobs/. Or point
-at a file explicitly with --config /path/to/deployment.env.
+$(if has_cli; then
+  echo "Creating one: ${MEFFECTA_CLI} init, in that repo."
+else
+  echo "Creating one: copy deployment.env.example (it ships beside these scripts)"
+  echo "beside your jobs/."
+fi)
+Or point at a file explicitly with --config /path/to/deployment.env.
 EOF
     exit 2
   fi

package/scripts/lib/read-json.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Pull single values out of the JSON that setup-scheduler.sh reads from gcloud and from the
+// Pull single values out of the JSON that sync-triggers.sh reads from gcloud and from the
 // running service. Shell cannot parse JSON and node is already required by the operator
 // tooling (mint-gmail-token.mjs, verify-credentials.mjs), so this replaces what used to be
 // inline python3 — one fewer thing a deployment has to have installed.

package/scripts/lib/tasks-queue.sh

@@ -0,0 +1,24 @@
+# The Cloud Tasks queue that carries a scale-to-zero deployment's work back to it.
+#
+# Two scripts create it, which is why it lives here rather than in either of them.
+# setup-infrastructure.sh provisions it with the deployment's other static resources — it
+# is ordinary infrastructure, and knows nothing about jobs. sync-triggers.sh ensures it
+# too, for a deployment provisioned before that was true and for the standalone re-sync.
+# Duplicating the settings in both would mean a deployment's retry behaviour depending on
+# which script last touched it.
+#
+# From the caller: GC (gcloud with --project), REGION, RUNTIME_SA, and a run() wrapper that
+# honours DRY_RUN.
+ensure_tasks_queue() {
+  local queue="$1"
+  if ! ${GC} tasks queues describe "${queue}" --location="${REGION}" >/dev/null 2>&1; then
+    run ${GC} tasks queues create "${queue}" --location="${REGION}" --quiet
+  fi
+  # max-concurrent-dispatches leaves room for several held attempts at once; the engine's
+  # own queue is serial, so this bounds requests waiting, not jobs running.
+  run ${GC} tasks queues update "${queue}" --location="${REGION}" \
+    --max-attempts=4 --min-backoff=5s --max-backoff=30s --max-doublings=2 \
+    --max-concurrent-dispatches=8 --max-dispatches-per-second=2 --quiet
+  run ${GC} tasks queues add-iam-policy-binding "${queue}" --location="${REGION}" \
+    --member="serviceAccount:${RUNTIME_SA}" --role="roles/cloudtasks.enqueuer" --quiet
+}

package/scripts/link-billing.sh

@@ -136,7 +136,7 @@ if [ "$(gcloud billing projects describe "${PROJECT}" --format='value(billingEna
   echo "✔ billingEnabled: true"
   echo ""
   echo "Next: create the content repo (step 3), then provision from inside it —"
-  echo "    $(dirname "$0")/setup-infrastructure.sh"
+  echo "    $(cmd setup-infra)"
 else
   echo "✖ Linked, but billingEnabled is still false — check the account is open and funded." >&2
   exit 1

package/scripts/mint-gmail-token.mjs

@@ -16,7 +16,7 @@
 // Sign in as WHICHEVER account the token is for when the browser opens — run once
 // per account (private Gmail → GMAIL_REFRESH_TOKEN; additional accounts →
 // --account NAME → GMAIL_<NAME>_REFRESH_TOKEN). --readonly mints read scopes only,
-// which is the right level for an account Marcus doesn't administer alone (a
+// which is the right level for an account this deployment doesn't administer alone (a
 // company mailbox: read the mail, never send from that identity).
 // Gmail scopes are "restricted", so an unverified app
 // shows a warning — Advanced → continue is fine for your own account. A Workspace
@@ -120,7 +120,12 @@ if (!res.ok || !json.refresh_token) {
   process.exit(1);
 }
 
+// How the operator reached this script, so the line telling them to pipe it into
+// gcloud is one they can actually type. MEFFECTA_CLI is set when the CLI spawned us;
+// without it they ran the file directly, and the file path is the honest answer.
+const self = process.env.MEFFECTA_CLI ? `${process.env.MEFFECTA_CLI} mint-gmail` : `node ${process.argv[1]}`;
+
 // Refresh token to stdout (pipe straight into gcloud), everything else to stderr.
 console.error(`\nRefresh token minted — it is ${tokenVar}. Store it without it touching your shell history:`);
-console.error(`  node scripts/mint-gmail-token.mjs ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
+console.error(`  ${self} ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
 console.log(json.refresh_token);

package/scripts/mint-graph-token.mjs

@@ -26,7 +26,7 @@
 //   4. Note the Application (client) ID and the Directory (tenant) ID.
 //
 // Usage:
-//   node scripts/mint-graph-token.mjs --account MOXSEA --tenant <tenant-id> \
+//   node scripts/mint-graph-token.mjs --account WORK --tenant <tenant-id> \
 //     --client-id <id> --client-secret <secret> [--no-calendar]
 //
 // Sign in as the mailbox the token is for when the browser opens — the everyday
@@ -146,7 +146,12 @@ if (!res.ok || !json.refresh_token) {
   process.exit(1);
 }
 
+// How the operator reached this script, so the line telling them to pipe it into
+// gcloud is one they can actually type. MEFFECTA_CLI is set when the CLI spawned us;
+// without it they ran the file directly, and the file path is the honest answer.
+const self = process.env.MEFFECTA_CLI ? `${process.env.MEFFECTA_CLI} mint-graph` : `node ${process.argv[1]}`;
+
 // Refresh token to stdout (pipe straight into gcloud), everything else to stderr.
 console.error(`\nRefresh token minted — it is ${tokenVar}. Store it without it touching your shell history:`);
-console.error(`  node scripts/mint-graph-token.mjs ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
+console.error(`  ${self} ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
 console.log(json.refresh_token);

package/scripts/set-secret.sh

@@ -35,7 +35,7 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-[ -n "${NAME}" ] || { echo "Which secret? e.g. scripts/set-secret.sh GITHUB_TOKEN" >&2; exit 2; }
+[ -n "${NAME}" ] || { echo "Which secret? e.g. $(self_cmd) GITHUB_TOKEN" >&2; exit 2; }
 case "${NAME}" in
   [A-Z]*[A-Z0-9]|[A-Z]) ;;
   *) echo "Secret names are UPPER_SNAKE_CASE: got '${NAME}'" >&2; exit 2 ;;

package/scripts/setup-infrastructure.sh

@@ -14,20 +14,79 @@ set -euo pipefail
 #
 # Which deployment it provisions comes from ./deployment.env (or --config <file>) —
 # see deployment.env.example. Nothing is defaulted to another deployment's project.
+#
+#   ... setup-infra              # provision
+#   ... setup-infra --dry-run    # print every change it would make, touch nothing
+#
+# --dry-run still READS the project, so it reports what it would do to the project you
+# actually have — what is missing, what is already there — rather than a fixed list of
+# steps. Nothing it prints needs billing, which is also what makes this path testable
+# before anyone runs it for real.
 
 . "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+. "$(dirname "${BASH_SOURCE[0]}")/lib/tasks-queue.sh"
+
+DRY_RUN=false
 
 while [ $# -gt 0 ]; do
   case "$1" in
     --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
     -h|--help) sed -n '4,25p' "$0"; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; exit 2 ;;
   esac
 done
 
+# Every call that CHANGES something goes through this; the describe calls that ask what is
+# already there do not, so a dry run reads a real project and reports what it would do to
+# it rather than a fixed script of steps.
+#
+# This is the script that creates a service account and grants it roles inside someone
+# else's GCP project, run by an operator who cannot read it — it is published tooling, and
+# the repo behind it is private. Being able to see exactly what it will do, first, is the
+# least a vendor can offer for that. It also makes the client path testable without a
+# project, which is the only way it gets exercised at all before a client runs it.
+run() {
+  if [ "${DRY_RUN}" = true ]; then
+    echo "   (dry run) $*"
+    return 0
+  fi
+  "$@"
+}
+
+# The same, for calls whose success output is a full IAM policy dump nobody reads. The
+# redirect has to live HERE rather than on the call, or it swallows the dry-run line too —
+# which it did, leaving every IAM grant, the most consequential thing this script does, as
+# the one thing a dry run did not show.
+run_quiet() {
+  if [ "${DRY_RUN}" = true ]; then
+    echo "   (dry run) $*"
+    return 0
+  fi
+  "$@" >/dev/null
+}
+
+# Deploys are not wired to the engine repo's CI: it publishes images to GHCR, and a
+# deployment rolls one out when it chooses. The deployer SA + Workload Identity
+# Federation below are therefore optional — provision them only if THIS deployment wants
+# a CI deploy job of its own, from its own content repo:
+#   SETUP_CI_DEPLOY=true GITHUB_REPO=<owner>/<your-content-repo> ...
+#
+# GITHUB_REPO has NO DEFAULT, and that is the point. The value becomes a trust condition:
+# the named repo's GitHub Actions may impersonate the deployer SA, which holds run.admin
+# on this project. A default would hand that to whoever the default names — someone else
+# entirely — on behalf of an operator who never typed a repo at all.
+SETUP_CI_DEPLOY="${SETUP_CI_DEPLOY:-false}"
+GITHUB_REPO="${GITHUB_REPO:-}" # owner/repo a CI deploy would run from
+if [ "${SETUP_CI_DEPLOY}" = "true" ] && ! printf '%s' "${GITHUB_REPO}" | grep -Eq '^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$'; then
+  echo "SETUP_CI_DEPLOY=true needs GITHUB_REPO=<owner>/<repo> — the repo allowed to deploy." >&2
+  echo "It is written into a trust condition, so there is nothing safe to guess." >&2
+  exit 2
+fi
+
 require_gcloud
 resolve_deployment
-announce_target "Provisioning infrastructure"
+announce_target "Provisioning infrastructure$([ "${DRY_RUN}" = true ] && echo " (dry run — reads only)")"
 
 ACCOUNT="${ACCOUNT:-}"
 MEMORY_BUCKET="${PROJECT}-memory"
@@ -36,22 +95,13 @@ RUNTIME_SA_NAME="agent-runtime"
 RUNTIME_SA="${RUNTIME_SA_NAME}@${PROJECT}.iam.gserviceaccount.com"
 DEPLOY_SA_NAME="github-deployer"
 DEPLOY_SA="${DEPLOY_SA_NAME}@${PROJECT}.iam.gserviceaccount.com"
-# Deploys are not wired to the engine repo's CI: it publishes images to GHCR, and a
-# deployment rolls one out when it chooses (scripts/deploy.sh). The deployer SA +
-# Workload Identity Federation below are therefore optional — provision them only if
-# THIS deployment wants a CI deploy job of its own, from its content repo:
-#   SETUP_CI_DEPLOY=true GITHUB_REPO=meffecta/agent-home ./scripts/setup-infrastructure.sh
-SETUP_CI_DEPLOY="${SETUP_CI_DEPLOY:-false}"
-GITHUB_REPO="${GITHUB_REPO:-meffecta/agent-home}" # owner/repo a CI deploy would run from
-
 # ACCOUNT is optional: unset means whichever account gcloud is currently logged in as.
 GC="gcloud --project=${PROJECT}"
 [ -n "${ACCOUNT}" ] && GC="${GC} --account=${ACCOUNT}"
 
 echo "🔧 Enabling APIs..."
-${GC} services enable \
+run ${GC} services enable \
   run.googleapis.com \
-  cloudbuild.googleapis.com \
   artifactregistry.googleapis.com \
   secretmanager.googleapis.com \
   iamcredentials.googleapis.com \
@@ -69,19 +119,50 @@ ${GC} services enable \
   analyticsdata.googleapis.com \
   iam.googleapis.com
 
-echo "🐳 Artifact Registry repo..."
+echo "🐳 Artifact Registry repo (${REGISTRY_MODE})..."
 if ! ${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" &>/dev/null; then
-  ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" --repository-format=docker
+  if [ "${REGISTRY_MODE}" = "proxy" ]; then
+    # A remote repository standing in front of ghcr.io. Cloud Run can only pull from
+    # Artifact Registry, and this is how that requirement is met without a local docker:
+    # AR fetches the public engine image itself, on demand, and caches it. No upstream
+    # credentials — the engine package is public, which is what makes this the simple path.
+    run ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" \
+      --repository-format=docker --mode=remote-repository \
+      --remote-docker-repo="https://${GHCR_IMAGE%%/*}" \
+      --description="Proxy of ${GHCR_IMAGE%%/*} — the engine image is fetched on demand"
+  else
+    run ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" --repository-format=docker
+  fi
+else
+  ACTUAL_MODE=$(${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" --format='value(mode)')
+  case "${ACTUAL_MODE}:${REGISTRY_MODE}" in
+    REMOTE_REPOSITORY:proxy|STANDARD_REPOSITORY:mirror) ;;
+    *)
+      # A repository's mode is fixed at creation, so this is not something to "fix" here —
+      # deploy.sh would resolve an image path the repository cannot serve, and the failure
+      # would arrive as a Cloud Run pull error with nothing pointing back to this.
+      echo "⚠ ${ARTIFACT_REPO} is a ${ACTUAL_MODE} but REGISTRY_MODE=${REGISTRY_MODE}." >&2
+      echo "  A repository's mode cannot be changed. Either set REGISTRY_MODE to match, or" >&2
+      echo "  name a different ARTIFACT_REPO in deployment.env and re-run this." >&2
+      ;;
+  esac
 fi
 # The images here are a cache of ghcr.io/meffecta/agent, not an archive, so they are worth
 # expiring — see set-artifact-cleanup.sh for why that is safe and what the policy keeps.
-"$(dirname "${BASH_SOURCE[0]}")/set-artifact-cleanup.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"} >/dev/null
+# Captured rather than streamed: gcloud narrates this one on stderr ("Updated repository",
+# "Dry run is disabled"), which reads like something went wrong in the middle of a set-up.
+# Housekeeping, so a failure is a warning rather than the end of provisioning.
+if ! CLEANUP_LOG=$("$(dirname "${BASH_SOURCE[0]}")/set-artifact-cleanup.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"} ${DRY_RUN:+$([ "${DRY_RUN}" = true ] && echo --dry-run)} 2>&1); then
+  echo "${CLEANUP_LOG}" >&2
+  echo "⚠ Could not set the registry cleanup policy — old images will accumulate." >&2
+fi
 
 # --- Runtime service account (everything the agent itself can do) ---
 if ! ${GC} iam service-accounts describe "${RUNTIME_SA}" &>/dev/null; then
   echo "🆕 Creating runtime service account: ${RUNTIME_SA}"
-  ${GC} iam service-accounts create "${RUNTIME_SA_NAME}" --display-name="Meffecta Agent"
-  for _ in $(seq 1 12); do
+  run ${GC} iam service-accounts create "${RUNTIME_SA_NAME}" --display-name="Meffecta Agent"
+  # IAM takes a moment to propagate; a dry run has nothing to wait for.
+  [ "${DRY_RUN}" = true ] || for _ in $(seq 1 12); do
     ${GC} iam service-accounts describe "${RUNTIME_SA}" &>/dev/null && break
     sleep 5
   done
@@ -90,33 +171,20 @@ fi
 # --- Buckets: memory (mounted, agent-writable) + audit (write-once, never mounted) ---
 if ! ${GC} storage buckets describe "gs://${MEMORY_BUCKET}" &>/dev/null; then
   echo "🆕 Creating memory bucket: ${MEMORY_BUCKET}"
-  ${GC} storage buckets create "gs://${MEMORY_BUCKET}" --location="${REGION}" --uniform-bucket-level-access
+  run ${GC} storage buckets create "gs://${MEMORY_BUCKET}" --location="${REGION}" --uniform-bucket-level-access
 fi
 if ! ${GC} storage buckets describe "gs://${AUDIT_BUCKET}" &>/dev/null; then
   echo "🆕 Creating audit bucket: ${AUDIT_BUCKET} (365d retention)"
-  ${GC} storage buckets create "gs://${AUDIT_BUCKET}" --location="${REGION}" --uniform-bucket-level-access \
+  run ${GC} storage buckets create "gs://${AUDIT_BUCKET}" --location="${REGION}" --uniform-bucket-level-access \
     --retention-period=365d
 fi
-# Cloud Build source staging — only for a deployment that builds images in GCP rather
-# than pulling the published one. Source tarballs are transient, so a 30-day lifecycle
-# keeps it from growing.
-CLOUDBUILD_BUCKET="${PROJECT}-cloudbuild"
-if [ "${SETUP_CI_DEPLOY}" = "true" ] && ! ${GC} storage buckets describe "gs://${CLOUDBUILD_BUCKET}" &>/dev/null; then
-  echo "🆕 Creating Cloud Build staging bucket: ${CLOUDBUILD_BUCKET}"
-  ${GC} storage buckets create "gs://${CLOUDBUILD_BUCKET}" --location="${REGION}" --uniform-bucket-level-access
-  LIFECYCLE_FILE=$(mktemp)
-  printf '{"rule":[{"action":{"type":"Delete"},"condition":{"age":30}}]}' >"${LIFECYCLE_FILE}"
-  ${GC} storage buckets update "gs://${CLOUDBUILD_BUCKET}" --lifecycle-file="${LIFECYCLE_FILE}"
-  rm -f "${LIFECYCLE_FILE}"
-fi
-
 echo "🔐 Runtime IAM..."
-${GC} storage buckets add-iam-policy-binding "gs://${MEMORY_BUCKET}" \
-  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectAdmin" --quiet >/dev/null
-${GC} storage buckets add-iam-policy-binding "gs://${AUDIT_BUCKET}" \
-  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectCreator" --quiet >/dev/null
-${GC} projects add-iam-policy-binding "${PROJECT}" \
-  --member="serviceAccount:${RUNTIME_SA}" --role="roles/secretmanager.secretAccessor" --quiet >/dev/null
+run_quiet ${GC} storage buckets add-iam-policy-binding "gs://${MEMORY_BUCKET}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectAdmin" --quiet
+run_quiet ${GC} storage buckets add-iam-policy-binding "gs://${AUDIT_BUCKET}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/storage.objectCreator" --quiet
+run_quiet ${GC} projects add-iam-policy-binding "${PROJECT}" \
+  --member="serviceAccount:${RUNTIME_SA}" --role="roles/secretmanager.secretAccessor" --quiet
 
 PROJECT_NUMBER=$(${GC} projects describe "${PROJECT}" --format='value(projectNumber)')
 
@@ -124,51 +192,46 @@ PROJECT_NUMBER=$(${GC} projects describe "${PROJECT}" --format='value(projectNum
 if [ "${SETUP_CI_DEPLOY}" = "true" ]; then
 if ! ${GC} iam service-accounts describe "${DEPLOY_SA}" &>/dev/null; then
   echo "🆕 Creating deployer service account: ${DEPLOY_SA}"
-  ${GC} iam service-accounts create "${DEPLOY_SA_NAME}" --display-name="GitHub Actions deployer"
-  for _ in $(seq 1 12); do
+  run ${GC} iam service-accounts create "${DEPLOY_SA_NAME}" --display-name="GitHub Actions deployer"
+  [ "${DRY_RUN}" = true ] || for _ in $(seq 1 12); do
     ${GC} iam service-accounts describe "${DEPLOY_SA}" &>/dev/null && break
     sleep 5
   done
 fi
-for role in roles/run.admin roles/cloudbuild.builds.editor roles/artifactregistry.writer \
-  roles/storage.admin roles/serviceusage.serviceUsageConsumer; do
-  ${GC} projects add-iam-policy-binding "${PROJECT}" \
-    --member="serviceAccount:${DEPLOY_SA}" --role="${role}" --quiet >/dev/null
-done
-# Cloud Build runs as its default SA; the deployer must be allowed to hand work to it,
-# and both must be able to deploy a service that runs as the runtime SA.
-${GC} iam service-accounts add-iam-policy-binding "${RUNTIME_SA}" \
-  --member="serviceAccount:${DEPLOY_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
-CLOUDBUILD_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
-${GC} iam service-accounts add-iam-policy-binding "${RUNTIME_SA}" \
-  --member="serviceAccount:${CLOUDBUILD_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
-# `gcloud builds submit` runs the build as the default compute SA: the deployer must be
-# allowed to act as it, and it needs to read staged source, push images, and deploy.
-${GC} iam service-accounts add-iam-policy-binding "${CLOUDBUILD_SA}" \
-  --member="serviceAccount:${DEPLOY_SA}" --role="roles/iam.serviceAccountUser" --quiet >/dev/null
-for role in roles/cloudbuild.builds.builder roles/artifactregistry.writer roles/run.admin; do
-  ${GC} projects add-iam-policy-binding "${PROJECT}" \
-    --member="serviceAccount:${CLOUDBUILD_SA}" --role="${role}" --quiet >/dev/null
+# What a DEPLOY needs, and nothing a BUILD would: roll out a revision, pull (or in mirror
+# mode push) the engine image, and read this project's enabled services.
+#
+# Deliberately NOT granted: secretmanager.secretAccessor. deploy.sh re-syncs the Cloud
+# Scheduler triggers, and that step reads the API secret — so a CI deploy runs
+# `deploy --no-scheduler`, and an operator re-runs sync-triggers by hand when a cron
+# changes. The alternative is a CI identity that can read every credential the deployment
+# holds, which is a poor trade for skipping one occasional command.
+for role in roles/run.admin roles/artifactregistry.writer roles/serviceusage.serviceUsageConsumer; do
+  run_quiet ${GC} projects add-iam-policy-binding "${PROJECT}" \
+    --member="serviceAccount:${DEPLOY_SA}" --role="${role}" --quiet
 done
+# Deploying a service that runs as the runtime SA means acting as it, once.
+run_quiet ${GC} iam service-accounts add-iam-policy-binding "${RUNTIME_SA}" \
+  --member="serviceAccount:${DEPLOY_SA}" --role="roles/iam.serviceAccountUser" --quiet
 
 POOL_ID="github-pool"
 PROVIDER_ID="github-provider"
 if ! ${GC} iam workload-identity-pools describe "${POOL_ID}" --location=global &>/dev/null; then
   echo "🆕 Creating Workload Identity pool + provider for GitHub Actions..."
-  ${GC} iam workload-identity-pools create "${POOL_ID}" --location=global --display-name="GitHub Actions"
+  run ${GC} iam workload-identity-pools create "${POOL_ID}" --location=global --display-name="GitHub Actions"
 fi
 if ! ${GC} iam workload-identity-pools providers describe "${PROVIDER_ID}" \
   --location=global --workload-identity-pool="${POOL_ID}" &>/dev/null; then
-  ${GC} iam workload-identity-pools providers create-oidc "${PROVIDER_ID}" \
+  run ${GC} iam workload-identity-pools providers create-oidc "${PROVIDER_ID}" \
     --location=global --workload-identity-pool="${POOL_ID}" \
     --display-name="GitHub OIDC" \
     --issuer-uri="https://token.actions.githubusercontent.com" \
     --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
     --attribute-condition="assertion.repository == '${GITHUB_REPO}'"
 fi
-${GC} iam service-accounts add-iam-policy-binding "${DEPLOY_SA}" \
+run_quiet ${GC} iam service-accounts add-iam-policy-binding "${DEPLOY_SA}" \
   --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/attribute.repository/${GITHUB_REPO}" \
-  --role="roles/iam.workloadIdentityUser" --quiet >/dev/null
+  --role="roles/iam.workloadIdentityUser" --quiet
 else
   echo "⏭️  Skipping deployer SA + Workload Identity Federation (SETUP_CI_DEPLOY is not true)."
 fi
@@ -176,14 +239,44 @@ fi
 # --- Cloud Run service shell (placeholder image; scripts/deploy.sh rolls out a real one) ---
 if ! ${GC} run services describe "${SERVICE}" --region="${REGION}" &>/dev/null; then
   echo "🆕 Creating Cloud Run service: ${SERVICE}"
-  ${GC} run services deploy "${SERVICE}" --region="${REGION}" \
+  run ${GC} run services deploy "${SERVICE}" --region="${REGION}" \
     --image="gcr.io/cloudrun/hello" --allow-unauthenticated \
     --service-account="${RUNTIME_SA}" 2>/dev/null ||
-    ${GC} run deploy "${SERVICE}" --region="${REGION}" \
+    run ${GC} run deploy "${SERVICE}" --region="${REGION}" \
       --image="gcr.io/cloudrun/hello" --allow-unauthenticated \
       --service-account="${RUNTIME_SA}"
 fi
 
+# The transport for a deployment that scales to zero. It is static infrastructure — it
+# knows nothing about jobs — so it belongs here with everything else that is created once,
+# rather than in sync-triggers.sh, which cannot run until an engine is deployed and can
+# be asked what jobs exist.
+#
+# Setting AGENT_TASKS_QUEUE here is also what lets `deploy` create the Cloud Scheduler
+# triggers on the FIRST rollout: it syncs them for a deployment that has opted into
+# external triggers, and these two variables are that opt-in. Without this the two waited
+# on each other and a deployment needed a separate sync-triggers run to break the tie.
+#
+# Only for scale-to-zero. An always-on deployment drives itself with in-process timers, and
+# giving it external triggers as well would fire every cron twice.
+TRIGGER_ENV=""
+if [ "${SCALING}" = "scale-to-zero" ]; then
+  QUEUE="${QUEUE_NAME:-${SERVICE}-runs}"
+  echo "📥 Cloud Tasks queue ${QUEUE}..."
+  ensure_tasks_queue "${QUEUE}"
+  AGENT_URL=$(${GC} run services describe "${SERVICE}" --region="${REGION}" \
+    --format='value(status.url)' 2>/dev/null || true)
+  if [ -z "${AGENT_URL}" ] && [ "${DRY_RUN}" = true ]; then
+    AGENT_URL="<the service URL, once it exists>"
+  fi
+  if [ -n "${AGENT_URL}" ]; then
+    TRIGGER_ENV=",AGENT_TASKS_QUEUE=projects/${PROJECT}/locations/${REGION}/queues/${QUEUE},AGENT_PUBLIC_URL=${AGENT_URL}"
+  else
+    # Not fatal: sync-triggers.sh sets both, and deploy runs it once they are there.
+    echo "   ⚠️  Could not read the service URL — $(cmd sync-triggers) will set these."
+  fi
+fi
+
 echo "⚙️  Applying service settings (instances, memory volume, env)..."
 VOLUME_FLAGS=()
 if ! ${GC} run services describe "${SERVICE}" --region="${REGION}" --format=yaml 2>/dev/null | grep -q "name: memory"; then
@@ -194,7 +287,7 @@ fi
 #
 # Scale to zero means CPU billed only while a request is open. That is affordable because
 # the service is idle almost all day, and it is only correct because nothing here fires on
-# its own: scripts/setup-scheduler.sh gives the deployment its external triggers, and every
+# its own: scripts/sync-triggers.sh gives the deployment its external triggers, and every
 # run happens inside a request the handler holds open (src/keyed-runs.ts). REQUEST_TIMEOUT
 # is the ceiling on one such held request; --cpu-boost pays for the cold start each wake-up
 # costs, which for this service includes cloning the content repo. MAX_INSTANCES=1 keeps
@@ -206,58 +299,52 @@ case "${SCALING}" in
   always-on) SCALE_FLAGS=(--min-instances=1 --no-cpu-throttling) ;;
   *) echo "Unknown SCALING=\"${SCALING}\" — use scale-to-zero or always-on." >&2; exit 2 ;;
 esac
-${GC} run services update "${SERVICE}" --region="${REGION}" \
+run ${GC} run services update "${SERVICE}" --region="${REGION}" \
   --service-account="${RUNTIME_SA}" \
   --max-instances="${MAX_INSTANCES}" \
   "${SCALE_FLAGS[@]}" \
   --memory="${MEMORY}" --cpu="${CPU}" --timeout="${REQUEST_TIMEOUT}" \
   --execution-environment=gen2 \
   ${VOLUME_FLAGS[@]+"${VOLUME_FLAGS[@]}"} \
-  --update-env-vars="TIMEZONE=${TIMEZONE},AUDIT_BUCKET=${AUDIT_BUCKET}"
+  --update-env-vars="TIMEZONE=${TIMEZONE},AUDIT_BUCKET=${AUDIT_BUCKET}${TRIGGER_ENV}"
 
 echo ""
 echo "============================================================"
-echo "✅ Infrastructure ready. Manual steps:"
-echo ""
-echo "   1. Point this deployment at its content repo — jobs, worlds, SYSTEM.md:"
-echo "        gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\"
-echo "          --update-env-vars GIT_REPO_URL=https://github.com/<owner>/<content-repo>.git"
-echo "      GITHUB_TOKEN (below) must be able to clone it, and every repo its jobs name."
-echo ""
-echo "   2. Gmail OAuth (once): in this project's console — OAuth consent screen"
-echo "      (External, PUBLISH to production) + a Desktop-app OAuth client. Then per"
-echo "      account: node scripts/mint-gmail-token.mjs --client-id ... --client-secret ..."
-echo "      [--account <NAME>] [--readonly] (sign in as that account)."
+if [ "${DRY_RUN}" = true ]; then
+  echo "🔍 Dry run — nothing above was created, changed or granted."
+else
+  echo "✅ Infrastructure ready."
+fi
 echo ""
-echo "   3. Create + wire the secrets:"
-echo "        printf '%s' '<value>' | gcloud secrets create <NAME> --data-file=- --project ${PROJECT}"
-echo "        gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\"
-echo "          --update-secrets '<NAME>=<NAME>:latest'"
-echo "      Required: AGENT_API_SECRET, CLAUDE_CODE_OAUTH_TOKEN (claude setup-token), GITHUB_TOKEN"
-echo "      Gmail:    GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN — and one"
-echo "                GMAIL_<NAME>_REFRESH_TOKEN per extra account (e.g. GMAIL_MEVISIO_REFRESH_TOKEN)"
-echo "      Optional: GRAFANA_LOGS_HOST/USERNAME + GRAFANA_API_KEY"
-echo "      Plain vars (--update-env-vars, not secrets): GMAIL_ADDRESS, GMAIL_<NAME>_ADDRESS"
+echo "   Created: the Google APIs, the registry the engine image is served from, the login"
+echo "   the agent acts as, a bucket for its memory, a write-once bucket for the audit"
+echo "   trail, the queue that carries work back to the service, and the service itself —"
+echo "   empty, waiting for an engine."
 echo ""
-echo "   4. Roll out an engine image (the engine repo's CI publishes them to GHCR):"
-echo "        PROJECT=${PROJECT} REGION=${REGION} SERVICE=${SERVICE} ./scripts/deploy.sh"
-echo "      (defaults to the newest published image; --tag sha-<short> pins one)"
-echo "      Content changes need no deploy at all — they are live on the next run."
+echo "   Next, from this directory:"
 echo ""
-echo "   5. Give it its triggers — the service scales to zero and fires nothing by itself:"
-echo "        ./scripts/setup-scheduler.sh"
-echo "      Creates the Cloud Tasks queue and one Cloud Scheduler job per cron: in the"
-echo "      content repo, reading the job list from the running service. Needs step 4 done"
-echo "      first, and re-run it whenever those registrations change (deploy.sh then does)."
+echo "     $(cmd set-env) GIT_REPO_URL=https://github.com/<owner>/<content-repo>.git"
+echo "     $(cmd set-secret) AGENT_API_SECRET --random"
+echo "     $(cmd set-secret) CLAUDE_CODE_OAUTH_TOKEN     # from: claude setup-token"
+echo "     $(cmd set-secret) GITHUB_TOKEN                # must be able to clone the repo above"
+echo "     $(cmd deploy)                              # rolls out the engine, then creates its triggers"
+if has_cli; then
+  echo ""
+  echo "   Then give it one ability at a time — mail, analytics, a CRM, a database:"
+  echo ""
+  echo "     ${MEFFECTA_CLI} connect            # lists them; connect <name> walks through one"
+  echo ""
+  echo "   ${MEFFECTA_CLI} steps     the whole set-up, in order"
+  echo "   ${MEFFECTA_CLI} doctor    what is still missing, once something is running"
+fi
 if [ "${SETUP_CI_DEPLOY}" = "true" ]; then
   WIF_PROVIDER="projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/providers/${PROVIDER_ID}"
   echo ""
   echo "   6. For a CI deploy from ${GITHUB_REPO} → Settings → Secrets → Actions:"
   echo "        GCP_WORKLOAD_IDENTITY_PROVIDER = ${WIF_PROVIDER}"
   echo "        GCP_DEPLOY_SERVICE_ACCOUNT     = ${DEPLOY_SA}"
+  echo "      That identity may deploy and nothing else — it cannot read your secrets, so"
+  echo "      the CI step runs \`deploy --no-scheduler\`. Re-sync triggers yourself when a"
+  echo "      job's cron: changes:  $(cmd sync-triggers)"
 fi
-echo ""
-echo "   Inspect everything the agent can do:"
-echo "     gcloud projects get-iam-policy ${PROJECT} --flatten='bindings[].members' \\"
-echo "       --filter='bindings.members:${RUNTIME_SA}'"
 echo "============================================================"