@hasna/loops 0.4.27 → 0.4.29

package/docs/DEPLOYMENT_MODES.md

@@ -1,11 +1,11 @@
-# OpenLoops Deployment Modes
+# Loops Deployment Modes
 
-OpenLoops supports one active source of truth at a time. The public package
+Loops supports one active source of truth at a time. The public package
 defines the mode vocabulary, local cache behavior, API shape, and runner
 contract. Hosted multi-tenant operation is implemented outside this public
 package.
 
-Deployment modes describe **where the OpenLoops runtime stores and executes**
+Deployment modes describe **where the Loops runtime stores and executes**
 loops and workflows (`local` SQLite, `self_hosted` control plane, or `cloud`
 contract). They are runtime placement concerns, not the automation product
 surface — specs, queues, approvals, and audit for product automations remain in
@@ -17,7 +17,7 @@ surface — specs, queues, approvals, and audit for product automations remain i
 | Mode | Source of truth | Local storage role | Executor |
 | --- | --- | --- | --- |
 | `local` | SQLite in `LOOPS_DATA_DIR` | Authoritative | `loops-daemon` |
-| `self_hosted` | Hasna-owned AWS/RDS control plane served by `loops-serve`/`loops-api` | Cache and offline spool | `loops-runner` foundation |
+| `self_hosted` | Hasna-owned AWS/RDS control plane served by `loops-serve` using the embeddable `loops-api` contract | Cache and offline spool | `loops-runner` foundation |
 | `cloud` | A configured hosted control plane contract | Cache and offline spool | `loops-runner` foundation |
 
 `local` remains the default. It must keep working without network access,
@@ -29,29 +29,28 @@ the Postgres storage adapter, migrations, HTTP SDK, and runner contract for this
 mode.
 
 `cloud` is the hosted control-plane contract. The public package exposes the
-client and runner contract, but tenant auth, account administration, and hosted
-infrastructure stay outside this package. The public package must not depend on
+client and runner contract, tenant authentication, and tenant isolation; account
+provisioning and hosted infrastructure stay outside this package. The public package must not depend on
 private hosted packages or resource names. This release exposes status
 surfaces only.
 
 ## Mode Resolution
 
-`LOOPS_MODE` or `HASNA_LOOPS_MODE` may be set to `local`, `self_hosted`, or
-`cloud`. Hyphenated `self-hosted` is normalized to `self_hosted`.
+`HASNA_LOOPS_STORAGE_MODE` may be set to `local`, `self_hosted`, or
+`cloud`. Other spellings and legacy mode names are rejected.
 
-When no explicit mode is set, OpenLoops resolves the mode from configuration:
+When no explicit mode is set, Loops resolves the mode from configuration:
 
-1. `LOOPS_CLOUD_API_URL` or `HASNA_LOOPS_CLOUD_API_URL` selects `cloud`.
-2. `LOOPS_API_URL`, `HASNA_LOOPS_API_URL`, `LOOPS_DATABASE_URL`, or
+1. `HASNA_LOOPS_API_URL` or
    `HASNA_LOOPS_DATABASE_URL` selects `self_hosted`.
-3. Otherwise OpenLoops uses `local`.
+2. Otherwise Loops uses `local`.
 
-`LOOPS_API_URL` and `HASNA_LOOPS_API_URL` belong to `self_hosted`.
-`cloud` uses only `LOOPS_CLOUD_API_URL` or `HASNA_LOOPS_CLOUD_API_URL`.
+Both non-local modes use the canonical `HASNA_LOOPS_API_URL`; an explicit
+`HASNA_LOOPS_STORAGE_MODE=cloud` distinguishes hosted cloud from self-hosted.
 
 Tokens are represented only as presence signals in status output. Self-hosted
-status uses `LOOPS_API_TOKEN` or `HASNA_LOOPS_API_TOKEN`. Cloud status uses
-`LOOPS_CLOUD_TOKEN` or `HASNA_LOOPS_CLOUD_TOKEN`. URL credentials, query
+status uses `HASNA_LOOPS_API_KEY`. Cloud status uses
+`HASNA_LOOPS_API_KEY`. URL credentials, query
 strings, and fragments are not returned in status output.
 
 ## Commands
@@ -63,12 +62,12 @@ loops self-hosted status
 loops self-hosted migrate --dry-run
 loops self-hosted push --dry-run
 loops self-hosted pull --dry-run
-loops self-hosted runner-register --runner-id <id> --machine-id <machine>
-loops self-hosted runner-register --runner-id <id> --machine-id <machine> --apply
 loops cloud status
 loops-api status
 loops-serve version
-HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run
+HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve migrate --dry-run
+loops-serve db-credentials reconcile
+HASNA_LOOPS_DATABASE_URL=... HASNA_LOOPS_AUTH_DATABASE_URL=... loops-serve serve
 loops-runner status
 loops export --file ./loops-export.json --dry-run
 loops export --file ./loops-export.json
@@ -92,7 +91,7 @@ JSON uses these field names:
 - `localStore.role`: `authoritative` in local mode, `cache_and_spool` in
   non-local modes.
 - `controlPlane.configured`: true only when the current mode has enough
-  configuration to be usable. Cloud requires both a cloud URL and a cloud token
+  configuration to be usable. Cloud requires both the canonical API URL and a token
   presence signal.
 - `controlPlane.apiUrl`: a display-safe URL without credentials, query string,
   or fragment.
@@ -101,10 +100,11 @@ JSON uses these field names:
   non-local modes it is a cache, offline spool, and audit copy.
 - `schedulerState.remoteStore`: names the non-local scheduler contract:
   `api_control_plane_contract`, `postgres_contract`,
-  `hosted_control_plane_contract`, `unconfigured`, or `none`. Remote apply is
-  `false` in the standalone CLI until the control-plane API exposes
-  id-preserving import endpoints. `loops-serve` itself wires the Postgres
-  storage adapter for normal control-plane CRUD and runner protocol routes.
+  `hosted_control_plane_contract`, `unconfigured`, or `none`. The standalone
+  CLI never mutates Postgres directly; self-hosted apply goes through the
+  configured control-plane API import contract. `loops-serve` itself wires the
+  Postgres storage adapter for normal control-plane CRUD, id-preserving import,
+  and runner protocol routes.
 - `schedulerState.remoteStore.objectArtifacts`: `object_store_contract` means
   remote artifact/object storage is a control-plane contract. The public package
   does not create or mutate S3 buckets, AWS resources, or hosted credentials.
@@ -118,22 +118,48 @@ JSON uses these field names:
 package. It reads and writes Postgres directly, serves open foundation probes
 (`GET /health`, `/ready`, `/version`, `/openapi.json`), gates `/v1` loop/run and
 runner-protocol routes with API-key auth on non-local binds, and applies the
-Postgres migrations plus the shared `api_keys` table with `loops-serve migrate`.
-
-`loops-api` is the embeddable API contract and local/dev foundation server in
-the same public package. It is not a separate package because self-hosted users
-and the hosted service must share the same public contract. The standalone
-`loops-api serve` path still fails closed for storage-backed routes unless an
-embedding host injects a storage adapter; `loops-serve` is the shipped
-Postgres-backed self-hosted host.
+Postgres migrations, including the tenant-bound `api_keys` table, with the
+prepare/backfill/enforce `loops-serve migrate` sequence.
+
+The service requires separate database logins: `HASNA_LOOPS_DATABASE_URL` is
+the tenant-scoped runtime role, while `HASNA_LOOPS_AUTH_DATABASE_URL` is the
+authenticator-only role that can verify keys and append authentication audits.
+`HASNA_LOOPS_MIGRATOR_DATABASE_URL` is an offline schema-administrator login;
+tenant enforcement normalizes cluster role attributes and therefore requires
+the PostgreSQL privilege to alter role security attributes.
+
+The in-cluster credential reconciler is `loops-serve db-credentials reconcile`.
+It is source-only infrastructure glue for self-hosted deployments that use an
+RDS-managed master secret and separate app DSN secrets. The command must run
+with the ECS task role (`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`) and AWS
+Secrets Manager access to exactly four distinct same-region secret ARNs. It
+rejects static AWS credentials, profiles, web-identity inputs, full credential
+URIs, malformed secret ARNs, duplicate app secrets, endpoint mismatches, and
+master-secret JSON that does not exactly match the expected RDS instance id,
+endpoint, port, database, and master username.
+
+The reconciler never prints or stores raw passwords outside Secrets Manager and
+Postgres. For every app secret it writes an `AWSPENDING` DSN, changes that
+login password inside a database transaction, tests a fresh verify-full
+connection, then promotes the pending version to `AWSCURRENT`. If the current
+secret/password pair is already valid, it leaves the secret untouched. Before
+migration `0010_tenant_enforce`, runtime and authenticator logins are kept
+detached from service roles; after `0010`, each is attached only to its exact
+matching NOLOGIN role.
+
+`loops-api` is the embeddable API contract in the same public package. It is not
+a separate service because self-hosted users and the hosted service must share
+the same public contract. `loops-serve` is the only shipped Postgres-backed
+self-hosted host.
 
 `loops-runner` is the process that connects a machine to a non-local control
 plane. The current public package supports a bounded one-shot protocol:
-registration, claim polling, claim-token fenced heartbeat/finalization, and
-`loops-runner run-once` execution for non-workflow targets. Full fleet daemon
-mode and workflow target execution over the remote protocol still need
-follow-up releases before `loops-runner` is advertised as a complete always-on
-worker.
+claim polling, claim-token fenced lease heartbeat/finalization, and
+`loops-runner run-once` execution for command, agent, and workflow targets.
+Workflow execution uses runner-scoped workflow and goal APIs behind the claimed
+run lease. Durable machine registration, full fleet daemon mode, and
+always-on fleet observability still need follow-up releases before
+`loops-runner` is advertised as a complete always-on worker.
 
 ## Migration And Sync
 
@@ -159,6 +185,12 @@ refuses to write a no-loss bundle unless the operator explicitly uses
 requires `--apply`; existing rows with the same id are updated only with
 `--replace`. The CLI creates a local SQLite backup before a safe apply.
 
+`loops self-hosted push` applies an additional self-hosted safety rule. Imported
+workflow definitions are archived, and imported loops are paused with
+`nextRunAt`/`retryScheduledFor` cleared. That safety normalization can re-archive
+or re-pause existing same-id rows even when `--replace` is not supplied; explicit
+preserve flags are reserved for deliberate activation.
+
 No-loss validation blocks unsupported or live state instead of silently
 dropping it. The current migration bundle does not preserve workflow invocation
 rows, workflow work items, workflow run/step/event history, or goal run history.
@@ -167,37 +199,34 @@ later release adds full table-preserving migration. Active daemon leases,
 running loop runs, running workflow runs/steps, and leased work items also
 block migration; finish or stop that work first.
 
-Self-hosted sync commands are preview-only today:
+Self-hosted sync commands use the control-plane API:
 
 ```bash
 loops self-hosted migrate --dry-run
 loops self-hosted push --dry-run
+loops self-hosted push --apply
 loops self-hosted pull --dry-run
 ```
 
-They inspect local state, optionally inspect `LOOPS_API_URL`, and report the
-rows that would need to move. Remote apply is intentionally blocked because the
-current self-hosted API exposes normal loop CRUD and run listing, not
-id-preserving workflow/loop/run import endpoints. A normal remote loop create
-would generate new ids, so it is not a no-loss migration. Local SQLite remains
-authoritative until a safe import is applied; in non-local modes it may remain
-a cache, offline spool, and audit copy.
+They inspect local state, inspect `HASNA_LOOPS_API_URL` when configured, and
+report the rows that would move. `loops self-hosted push --apply` sends the
+id-preserving workflow and loop import bundle to `/v1/import`; imported
+workflows are archived and imported loops are paused with run pointers cleared.
+Local SQLite remains authoritative until an operator applies the import and
+records the rollout evidence; in non-local modes it may remain a cache, offline
+spool, and audit copy.
 
-`LOOPS_DATABASE_URL` or `HASNA_LOOPS_DATABASE_URL` selects the self-hosted
+`HASNA_LOOPS_DATABASE_URL` selects the self-hosted
 Postgres scheduler-state contract and is required by `loops-serve`. It does not
 make the standalone `loops` CLI mutate a remote database by itself. Remote
 execution still flows through a configured control-plane API and runner
-protocol. `loops-runner` needs `LOOPS_API_URL` or `HASNA_LOOPS_API_URL` to claim
+protocol. `loops-runner` needs `HASNA_LOOPS_API_URL` to claim
 work; a database URL alone is migration/readiness configuration.
 
-`loops self-hosted runner-register` is also preview-only unless `--apply` is
-present. The dry run prints the runner id, machine id, labels, and
-capabilities that would be posted, without exposing tokens.
-
 Cross-machine rollout evidence should record: machine id/hostname, package
 version, git/build version, command run, dry-run or apply mode, redacted API
 URL, source and target store ids, backup path, bundle hash, schema version,
-row counts, conflicts, blocked rows, runner registration id, daemon/runner
+row counts, conflicts, blocked rows, runner machine record id, daemon/runner
 status, and timestamp.
 
 ## Machine Placement
@@ -215,7 +244,7 @@ distinguishable from intentional fan-out.
 This is separate from existing local OpenMachines dispatch. In `local` mode,
 `loops-daemon` can still dispatch a loop target to a configured remote machine
 through the existing OpenMachines transport. In `self_hosted` or `cloud`,
-machine execution is runner-pull: a registered `loops-runner` claims work from
+machine execution is runner-pull: `loops-runner` claims work from
 the control plane. Operators should not treat local remote dispatch as cloud
 mode.
 
@@ -225,9 +254,8 @@ Non-local execution needs these follow-up releases before it is complete:
 
 - Long-running runner daemon mode with backoff, fleet observability, and
   durable machine registration records.
-- Workflow target execution over the remote protocol.
-- Id-preserving self-hosted import endpoints for workflow specs, loop
-  definitions, run history, workflow history, work items, goals, and audit rows.
+- Id-preserving self-hosted import coverage for run history, workflow history,
+  work items, goals, and audit rows.
 - Hosted product integration outside the public package.
 
 ## Public Package Boundary

package/docs/RUNTIME_BOUNDARY.md

@@ -1,6 +1,6 @@
-# OpenLoops Runtime Boundary
+# Loops Runtime Boundary
 
-OpenLoops is the **runtime, scheduler, and workflow engine** for automations.
+Loops is the **runtime, scheduler, and workflow engine** for automations.
 It executes work that external systems have already materialized or explicitly
 handed off. It is **not** the automation domain model: specs, triggers, queue
 ownership, approvals, DLQ/replay, idempotency, and audit evidence live in
@@ -14,15 +14,15 @@ deployment-mode vocabulary (local vs self-hosted vs cloud), see
 
 ## Ownership Split
 
-| Concern | Owner | OpenLoops role |
+| Concern | Owner | Loops role |
 | --- | --- | --- |
-| Automation specs and trigger materialization | `@hasna/automations` | None — do not store specs in OpenLoops |
+| Automation specs and trigger materialization | `@hasna/automations` | None — do not store specs in Loops |
 | Product automation action queues, leases, DLQ, replay, idempotency, approvals, audit | `@hasna/automations` | Execute claimed actions; complete/fail by action id + runner id |
 | Action compilation and action-target rendering | `@hasna/actions` | Accept planned upsert handoff; do not write SQLite rows directly |
-| Scheduler, daemon, loop/workflow storage | OpenLoops | Authoritative in `local` mode |
-| Workflow invocation, admission, execution, run manifests | OpenLoops | After explicit handoff or todos-task route admission |
-| Provider routing, worktrees, run artifacts | OpenLoops | Bounded by route and template policy |
-| Todos-task route drains (`auto:route`, `route_enabled`, `automation.allowed`) | OpenLoops-native | Opt-in task/event routing — **not** OpenAutomations queue replacement |
+| Scheduler, daemon, loop/workflow storage | Loops | Authoritative in `local` mode |
+| Workflow invocation, admission, execution, run manifests | Loops | After explicit handoff or todos-task route admission |
+| Provider routing, worktrees, run artifacts | Loops | Bounded by route and template policy |
+| Todos-task route drains (`auto:route`, `route_enabled`, `automation.allowed`) | Loops-native | Opt-in task/event routing — **not** OpenAutomations queue replacement |
 
 The SDK exposes the canonical boundary strings via `openAutomationsRuntimeBinding()`:
 
@@ -41,37 +41,37 @@ console.log(binding.nonGoals);
 
 - OpenAutomations owns automation specs, run materialization, queue state, DLQ,
   replay, idempotency, and approvals.
-- OpenLoops may execute claimed actions through explicit command or SDK handoff
+- Loops may execute claimed actions through explicit command or SDK handoff
   only.
-- OpenLoops may consume exported event envelopes only through explicit
+- Loops may consume exported event envelopes only through explicit
   `loops routes create` commands.
 - Workers must complete or fail actions by action id and runner id so
   OpenAutomations can enforce queue leases.
 
 **Non-goals (summary):**
 
-- OpenLoops must not become the OpenAutomations product surface.
-- OpenLoops must not store automation specs or replace the OpenAutomations queue.
-- OpenLoops must not infer automation trigger semantics from event transport
+- Loops must not become the OpenAutomations product surface.
+- Loops must not store automation specs or replace the OpenAutomations queue.
+- Loops must not infer automation trigger semantics from event transport
   alone.
 
 ## External Compiler Handoff Paths
 
 External compilers (`@hasna/automations`, `@hasna/actions`, event routers)
-materialize automation intent in their own stores. OpenLoops receives **rendered
+materialize automation intent in their own stores. Loops receives **rendered
 work** through one of the paths below. Do not bypass these boundaries by writing
-OpenLoops SQLite rows from another package.
+Loops SQLite rows from another package.
 
 ### 1. OpenAutomations claim-queue (implemented)
 
-OpenAutomations owns the action queue. An OpenLoops worker claims work, runs the
+OpenAutomations owns the action queue. A Loops worker claims work, runs the
 rendered target, and reports completion back to OpenAutomations.
 
 ```bash
 # Worker claims from the OpenAutomations queue
 automations queue claim --runner open-loops:<worker-id>
 
-# After OpenLoops executes the handed-off command/workflow:
+# After Loops executes the handed-off command/workflow:
 automations queue complete <action-id> --runner open-loops:<worker-id>
 # or on failure:
 automations queue fail <action-id> --runner open-loops:<worker-id> \
@@ -131,7 +131,7 @@ loops workflows upsert-one-shot ./workflow.json \
   --json
 ```
 
-OpenLoops returns durable refs (`workflowId`, `loopId`, `runId`, `manifestPath`)
+Loops returns durable refs (`workflowId`, `loopId`, `runId`, `manifestPath`)
 so `@hasna/actions` can inspect, cancel, or replay without querying SQLite.
 Full semantics (idempotency on `idempotencyKey` + `specHash`, redaction,
 strict-mode policy) are specified in the design doc — not duplicated here.
@@ -139,7 +139,7 @@ strict-mode policy) are specified in the design doc — not duplicated here.
 ### 3. Event envelope handoff (implemented, explicit only)
 
 For workflows that should run from a normalized event envelope — **without**
-OpenAutomations materializing automation specs inside OpenLoops — pipe an
+OpenAutomations materializing automation specs inside Loops — pipe an
 exported envelope into the generic route:
 
 ```bash
@@ -147,9 +147,9 @@ automations --json webhooks event <route> --body-json '<json>' \
   | loops --json routes create generic
 ```
 
-This is **not** automation materialization in OpenLoops. OpenAutomations still
+This is **not** automation materialization in Loops. OpenAutomations still
 owns deterministic automation specs, webhook normalization, queue state,
-approvals, DLQ, and replay. OpenLoops owns agent workflow invocation after the
+approvals, DLQ, and replay. Loops owns agent workflow invocation after the
 operator routes the envelope to `loops routes create generic`.
 
 ```ts
@@ -158,9 +158,9 @@ console.log(eventHandoff.handlerCommand); // "loops routes create generic"
 console.log(eventHandoff.boundary);
 ```
 
-## OpenLoops-Native Path: Todos-Task Routes
+## Loops-Native Path: Todos-Task Routes
 
-Todos-task routing is an **OpenLoops-native** admission path. It is separate from
+Todos-task routing is a **Loops-native** admission path. It is separate from
 the OpenAutomations product queue:
 
 ```bash
@@ -170,7 +170,7 @@ cat task-created-event.json | loops routes create todos-task \
 ```
 
 Tasks must opt in (`auto:route`, `route_enabled=true`, or
-`automation.allowed=true`). OpenLoops admits deduped one-shot workflow loops,
+`automation.allowed=true`). Loops admits deduped one-shot workflow loops,
 drains them on a schedule, and writes run manifests under
 `.hasna/loops/runs/<project-slug>/<subject-key>/<run-id>/`.
 
@@ -186,10 +186,10 @@ provider rules, and drain examples.
 
 Do **not**:
 
-- Store automation specs in OpenLoops loop/workflow rows.
+- Store automation specs in Loops loop/workflow rows.
 - Infer automation triggers from event transport alone.
 - Replace the OpenAutomations queue with loop/workflow rows.
-- Write OpenLoops SQLite directly from `@hasna/actions` or `@hasna/automations`.
+- Write Loops SQLite directly from `@hasna/actions` or `@hasna/automations`.
 - Dispatch or paste task prompts into tmux panes from route drains (use headless
   workflow templates instead).
 

package/docs/SHARED-DATABASE-TRANSFER.md

@@ -0,0 +1,95 @@
+# Shared Apps To Dedicated Loops Database Transfer
+
+Status: source-side tooling and protected workflow source only. Do not run this
+against live AWS or any live database without an approved maintenance window,
+fresh recovery evidence, and the protected GitHub environment approval.
+
+This transfer is intentionally selective. The source is the shared RDS database
+`apps`; the target is the dedicated Loops database `loops`. Never snapshot
+restore the shared cluster or shared database into the target.
+
+## Fixed Command
+
+The only production command for this lane is the no-option service command:
+
+```bash
+bun dist/serve/index.js shared-to-dedicated-transfer
+```
+
+Operators do not pass DSNs, table names, shell snippets, SQL files, or archive
+paths. The command reads only these ECS task secret environment variables:
+
+```text
+HASNA_LOOPS_TRANSFER_SOURCE_DATABASE_URL
+HASNA_LOOPS_TRANSFER_TARGET_DATABASE_URL
+```
+
+The source DSN must point at database `apps`. The target DSN must point at
+database `loops`. The command converts both DSNs into a private `pg_service.conf`
+inside a mode `0700` ephemeral directory so PostgreSQL client argv contains only
+`service=openloops_transfer_source` and `service=openloops_transfer_target`.
+The archive directory is removed in `finally` after success or failure.
+
+## Sequence
+
+1. Verify PostgreSQL 16 client binaries: `pg_dump`, `pg_restore`, and `psql`.
+2. Verify source migration ledger checksums for Loops migrations
+   `0001_core_runtime` through `0007_work_item_gate_deaths`.
+3. Verify source quiescence: no active loop runs, workflow runs, workflow step
+   runs, runner leases, or leased/running work items.
+4. Initialize the dedicated target schema through migration
+   `0007_work_item_gate_deaths` using the normal checksum ledger.
+5. Verify the target ledger is exactly migrations `0001` through `0007` and no
+   later row is present.
+6. Use `pg_dump --format=custom --data-only --no-owner --no-privileges` for the
+   exact Loops table allowlist:
+
+```text
+loops
+workflow_specs
+runner_machines
+goals
+loop_runs
+workflow_invocations
+workflow_runs
+workflow_work_items
+workflow_step_runs
+workflow_events
+goal_plan_nodes
+goal_runs
+runner_leases
+audit_events
+run_receipts
+daemon_lease
+```
+
+7. Use `pg_restore --data-only --single-transaction --exit-on-error` into the
+   dedicated target.
+8. Apply migration `0008_tenant_prepare` on the target. This creates the
+   tenant-prep tables and `api_keys` table needed for the next copy.
+9. Use filtered `COPY` for only:
+
+```sql
+SELECT kid, app, agent, scopes, token_hash, issued_at, expires_at, revoked_at,
+       revoked_reason, last_used_at, created_by, created_at
+  FROM public.api_keys
+ WHERE app = 'loops'
+ ORDER BY kid;
+```
+
+10. Verify source and target row counts, canonical SHA-256 row evidence,
+    target non-loop API key count, FK orphan checks, and unexpected database
+    objects across schemas, tables, functions, sequences, and views.
+11. Stop after producing evidence. The next approved sequence is:
+    `loops-serve tenant-backfill-s3`, then
+    `loops-serve migrate --enforce-tenancy`.
+
+## Protected Workflow
+
+`.github/workflows/shared-database-transfer.yml` is a manual protected source
+surface. It accepts only a confirmation string, assumes the environment's OIDC
+role, and runs one ECS Fargate task with the fixed command above. Database URLs
+must come from the ECS task definition secrets, not from GitHub inputs,
+repository variables, workflow logs, or operator shell overrides.
+
+The workflow has no RDS restore or snapshot API path.