@hasna/loops 0.4.28 → 0.4.29

package/CHANGELOG.md

@@ -1,10 +1,83 @@
 # Changelog
 
-All notable changes to OpenLoops (npm `@hasna/loops`, repo `hasna/loops`) are
+All notable changes to Loops (npm `@hasna/loops`, repo `hasna/loops`) are
 documented in this file. Version entries are generated from the
 conventional-commit git history; one commit maps to one released patch version
 unless noted.
 
+## 0.4.29 (2026-07-21)
+
+This source release gives the post-`npm/loops/v0.4.28` code line a new,
+unambiguous package, OpenAPI, and generated HTTP SDK identity.
+
+### Added
+
+- **Tenant-bound authentication and PostgreSQL row isolation:** migrations
+  `0008_tenant_prepare`, `0009_tenant_backfill`, and
+  `0010_tenant_enforce` add tenant/principal/membership/API-key state, require
+  an explicit complete tenant assignment before enforcement, and install the
+  closed-world owner/migrator/runtime/authenticator role model with
+  tenant-scoped privileges and RLS. The API now validates tenant-bound keys,
+  roles, scopes, and token kinds and emits structured denial evidence.
+- **Tenant migration operations:** encrypted tenant-backfill delivery,
+  provider credential reconciliation, PostgreSQL 16 bootstrap membership
+  gates, and protected shared-database transfer tooling now support rehearsed,
+  auditable cutovers without command overrides or unverified TLS targets.
+- **Runner and workflow execution:** long-running runner readiness and workflow
+  execution are implemented, with operator recovery, replayable advancement,
+  workflow-definition provenance in `0011_workflow_run_provenance`, and loop
+  labels in `0012_loop_labels`.
+
+### Changed
+
+- **Product identity:** user-facing product and documentation naming is now
+  **Loops**, while published compatibility identifiers and paths such as
+  the legacy uppercase environment-variable namespace, `open_loops`,
+  `.openloops`, `openloops`, `runtimeOwner`, MCP identifiers, project slugs,
+  and the `loops-api` compatibility binary/waiver remain stable.
+- **Runtime and supply chain:** the runtime image now uses pinned Bun Alpine
+  packages, runs the runner as non-root, pins CI actions, adds a protected ECR
+  candidate workflow, and fails closed on high-severity or malformed scan
+  results. Packed artifacts are checked for private-host leakage, branding
+  regressions, storage-kit drift, and contract conformance.
+- **Public contracts:** the OpenAPI document and generated HTTP SDK cover the
+  expanded tenant, runner, workflow, recovery, labels, count, archive, and
+  operational surfaces. MCP output is bounded, and public or persisted
+  workflow output is scrubbed before truncation.
+
+### Fixed
+
+- **Agent boundaries:** Codewith auth profiles are resolved from exact
+  JSON-first inventory, unusable or malformed profiles and extra arguments
+  fail closed, session creation is atomic, root agent directories are rejected,
+  route agent allowlists propagate correctly, and Cursor provider/retry
+  handling no longer weakens trust boundaries.
+- **API and claim safety:** tenant error compatibility is preserved while
+  runner endpoints, route admission, loop updates, runner clocks, local claims,
+  recovery snapshots, and persisted workflow/session contracts reject
+  ambiguous, stale, or cross-boundary state.
+- **Archive and finalization:** ambiguous archive names fail closed and resolve
+  against target state; PostgreSQL finalization conflicts are enforced
+  directly; SQLite generated-route finalization matches PostgreSQL behavior;
+  and public CLI errors and pagination avoid leaking unsafe context.
+- **Recovery and advancement:** workflow recovery ownership is fenced,
+  advancement is unified across schedulers, replay is idempotent, successor and
+  completion parity gaps are closed, and recovery cannot double-claim local
+  work or regenerate already-finalized routes.
+- **Security boundaries:** private and encoded infrastructure hostnames are
+  removed from publishable output, encoded separator bypasses are rejected,
+  trusted contracts and legacy events are validated, and the shared transfer
+  gate accepts only verified TLS DSNs.
+
+### Upgrade warning
+
+- **`0010_tenant_enforce` is a rollback boundary.** After this migration is
+  applied, the immutable published `0.4.28` image cannot pass readiness because
+  it does not contain the `0008`-`0010` tenant migration lineage. Do not roll
+  the binary back in place. Recovery requires rolling forward to `0.4.29` or a
+  later compatible image, or restoring the rehearsed pre-cutover database
+  target before starting the older image.
+
 ## 0.4.26
 
 ### Fixed
@@ -19,6 +92,16 @@ unless noted.
 
 ## Unreleased
 
+### Fixed
+
+- **Codewith auth-profile preflight:** use JSON-first exact profile matching for
+  local and remote runs. Root `data`/`profiles` entries are authoritative:
+  `usable: false` is rejected, legacy entries without `usable` remain accepted,
+  and `currentProfile` does not add inventory membership. Human-table parsing,
+  including active `*` rows, is used only when JSON mode is unsupported or its
+  inventory is structurally unavailable. NUL-containing names, missing
+  profiles, and non-fallback profile-list failures fail closed.
+
 ### Added
 
 - `loops-mcp` now serves a shared Streamable HTTP transport (default

package/README.md

@@ -1,14 +1,14 @@
-# OpenLoops
+# Loops
 
-OpenLoops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
+Loops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
 
-Naming: the product is **OpenLoops**, published on npm as
+Naming: the product is **Loops**, published on npm as
 [`@hasna/loops`](https://www.npmjs.com/package/@hasna/loops) and developed in the
 [`hasna/loops`](https://github.com/hasna/loops) repository. The installed
 binaries are `loops`, `loops-daemon`, `loops-api`, `loops-serve`,
 `loops-runner`, and `loops-mcp`.
 
-OpenLoops is the **runtime, scheduler, and workflow engine** for automations —
+Loops is the **runtime, scheduler, and workflow engine** for automations —
 not the automation domain model. Specs, triggers, queue ownership, approvals,
 DLQ/replay, and audit live in `@hasna/automations` and `@hasna/actions`; see
 [Runtime Boundary](docs/RUNTIME_BOUNDARY.md) for ownership split and external
@@ -25,7 +25,7 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 ## Deployment Modes
 
-OpenLoops has three deployment modes:
+Loops has three deployment modes:
 
 - `local`: SQLite in `LOOPS_DATA_DIR` is authoritative and `loops-daemon` executes scheduled work.
 - `self_hosted`: the Hasna-owned AWS/RDS control-plane deployment, served by
@@ -33,23 +33,20 @@ OpenLoops has three deployment modes:
   shared by serve, SDK, and tests. This release exposes status, storage-backed
   `/v1` loop CRUD and run listing, runner claim/heartbeat/finalize protocol
   endpoints, a one-shot `loops-runner run-once` execution path for embedded
-  control-plane hosts, id-preserving local export/import, and preview-only
-  self-hosted migration/sync commands; full fleet rollout and id-preserving
-  remote apply are follow-up work.
-- `cloud`: a hosted control-plane contract. This release exposes client/runner status only; hosted tenant auth and infrastructure live outside this package.
+  control-plane hosts, id-preserving local export/import, tenant-bound API-key
+  authentication, and forced Postgres row-level tenant isolation.
+- `cloud`: a hosted control-plane contract using the same tenant-bound API.
 
 `local` is the default and requires no network, token, Postgres, or hosted
-service. Set `LOOPS_MODE` or `HASNA_LOOPS_MODE` to `local`, `self_hosted`, or
-`cloud` to choose explicitly. Without an explicit mode, `LOOPS_CLOUD_API_URL`
-selects `cloud`, while `LOOPS_API_URL` or `LOOPS_DATABASE_URL` selects
-`self_hosted`.
+service. Set `HASNA_LOOPS_STORAGE_MODE` to `local`, `self_hosted`, or
+`cloud` to choose explicitly. Without an explicit mode,
+`HASNA_LOOPS_API_URL` or `HASNA_LOOPS_DATABASE_URL` selects `self_hosted`.
 
 The public `@hasna/loops` package owns the local runtime, mode resolver,
-self-hosted API contract, runner contract, SDK, MCP server, and CLI. Hosted
-tenant auth, account administration, and infrastructure live outside this
-package. Cloud mode is a public contract until a cloud-specific hosted URL and
-cloud token are configured through `LOOPS_CLOUD_API_URL` plus
-`LOOPS_CLOUD_TOKEN` or `HASNA_LOOPS_CLOUD_TOKEN`.
+self-hosted API contract, tenant authentication and authorization, runner
+contract, SDK, MCP server, and CLI. Account provisioning and infrastructure
+deployment remain operator responsibilities. Cloud clients use
+`HASNA_LOOPS_API_URL` plus `HASNA_LOOPS_API_KEY`.
 
 Scheduler state is explicit in status JSON. `schedulerState.localStore` is
 SQLite plus local run artifact files: authoritative in `local`, cache/spool in
@@ -73,7 +70,6 @@ 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> --apply
 loops export --file ./loops-export.json --dry-run
 loops export --file ./loops-export.json
 loops import ./loops-export.json
@@ -81,7 +77,9 @@ loops import ./loops-export.json --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
 ```
 
@@ -94,9 +92,40 @@ preserve flags only for an intentional activation.
 See [Deployment Modes](docs/DEPLOYMENT_MODES.md) for the full package boundary
 and machine-placement contract.
 
+### Provider database credentials
+
+`loops-serve db-credentials reconcile` is the fixed in-cluster reconciler for
+provider-managed RDS app credentials. It reads the RDS-managed master secret
+with the AWS Secrets Manager SDK, builds `sslmode=verify-full` DSNs only in
+memory, and writes each app DSN to that app's Secrets Manager secret through
+`AWSPENDING` before promoting `AWSCURRENT`. It never accepts database URLs,
+passwords, access keys, profiles, or secret material as command flags.
+
+Required environment is intentionally strict: `AWS_REGION`,
+`AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`, `HASNA_LOOPS_RDS_MASTER_SECRET_ARN`,
+`HASNA_LOOPS_MIGRATOR_DATABASE_URL_SECRET_ARN`,
+`HASNA_LOOPS_RUNTIME_DATABASE_URL_SECRET_ARN`,
+`HASNA_LOOPS_AUTH_DATABASE_URL_SECRET_ARN`, `HASNA_LOOPS_RDS_INSTANCE_ID`,
+`HASNA_LOOPS_RDS_ENDPOINT`, `HASNA_LOOPS_RDS_PORT`,
+`HASNA_LOOPS_RDS_DATABASE`, and `HASNA_LOOPS_RDS_MASTER_USERNAME`. Static AWS
+credential environment variables, profile/web-identity inputs, full credential
+URIs, non-RDS-style endpoints, duplicate secret ARNs, cross-region secret ARNs,
+and malformed identifiers fail closed before any secret or database operation.
+
+The command normalizes the fixed NOLOGIN database roles
+`open_loops_owner`, `open_loops_migrator`, `open_loops_runtime`, and
+`open_loops_authenticator`; manages exactly three LOGIN users
+`open_loops_migrator_login`, `open_loops_runtime_login`, and
+`open_loops_authenticator_login`; grants only the migrator login exact
+owner/migrator membership plus `CREATEROLE`; and keeps runtime/authenticator
+without memberships until migration `0010_tenant_enforce` has landed. After
+`0010`, runtime and authenticator are attached only to their matching roles.
+If PostgreSQL 16 implicit creator memberships cannot be normalized, the
+reconciler fails before publishing app credentials.
+
 ## Install
 
-**OpenLoops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
+**Loops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
 `loops`, `loops-daemon`, `loops-api`, `loops-serve`, `loops-runner`, and
 `loops-mcp` binaries run with a `#!/usr/bin/env bun` shebang, so Bun must be on
 `PATH` even when the package is installed with npm. Node.js is not a supported
@@ -132,7 +161,7 @@ The CLI stores state in `~/.hasna/loops` by default. Set `LOOPS_DATA_DIR` to iso
 
 ## MCP Server
 
-OpenLoops ships a stdio MCP server for safe loop and workflow inspection from
+Loops ships a stdio MCP server for safe loop and workflow inspection from
 MCP-capable agents:
 
 ```bash
@@ -149,6 +178,7 @@ import { createLoopsMcpServer } from "@hasna/loops/mcp";
 Available read tools include `loops_list`, `loops_show`, `loops_runs`,
 `loops_doctor`, `loops_workflows_list`, `loops_workflow_read`, and
 `loops_workflow_validate`.
+`loops_list` and `loops_runs` accept label arrays with AND semantics.
 Resources are available at `loops://runtime` and `loops://tools`.
 Those tools use the same `Store`, public redaction helpers, and workflow parser
 as the CLI and SDK, so read output and validation behavior stay aligned across
@@ -158,12 +188,16 @@ Mutation tools are disabled by default. Start the server with
 `LOOPS_MCP_ALLOW_MUTATIONS=true` only for a trusted local MCP host that should be
 allowed to change loop state. The guarded mutation tools use canonical names:
 `loops_pause`, `loops_resume`, `loops_stop`, `loops_run_now`, `loops_archive`,
-`loops_unarchive`, `loops_create_command`, and `loops_create_workflow`.
+`loops_unarchive`, `loops_labels_update`, `loops_create_command`, and
+`loops_create_workflow`.
 Deprecated `loop_*` aliases are still registered where compatibility needs them,
 but callers should use the `loops_*` names. Mutation tools do not require or
 accept confirmation-string parameters; the server-side environment opt-in is the
 gate. MCP `loops_run_now` schedules the loop for immediate daemon pickup; inline
 execution remains CLI-only.
+When `showOutput` is enabled, `loops_runs` caps each stdout/stderr field at
+32,000 characters, caps output-bearing pages at 25 runs, and caps the aggregate
+MCP JSON response at 128,000 characters.
 
 Keep host-affecting or long-running operations on the CLI: daemon
 start/stop/install/logs, inline `run-now`, `tick`, loop deletion, workflow
@@ -223,8 +257,41 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+Codewith `--auth-profile` is provider-native, not an OpenAccounts selector.
+Local and remote preflight first request `codewith profile list --json` and
+match the requested name exactly against the root `data` or `profiles`
+inventory. That inventory is authoritative: `usable: false` rejects a profile,
+legacy entries without `usable` remain usable, and `currentProfile` does not add
+inventory membership. Loops falls back to the human-readable table,
+including active `*` rows, only when JSON mode is unsupported or its inventory
+is structurally unavailable. Embedded NUL bytes, missing profiles, and
+non-fallback profile-list failures fail closed.
+
+## Labels
+
+Command, agent, and workflow loops accept repeatable labels:
+
+```bash
+loops create command repo-status --every 1m --cmd "git status --short" \
+  --label BrowserPlan --label maintenance
+loops list --label browserplan --label maintenance
+loops runs --label browserplan
+```
+
+Labels are normalized to lowercase, deduplicated, limited to 32 per loop, and
+must match `[a-z0-9][a-z0-9._-]{0,63}` after normalization. Repeated filters use
+AND semantics. Run filtering uses the loop's current labels rather than a
+historical snapshot on each run.
+
+```bash
+loops labels add repo-status urgent
+loops labels remove repo-status maintenance
+loops labels set repo-status browserplan nightly
+loops labels clear repo-status
+```
+
 Run an OpenCode loop with an explicit provider/model. OpenCode reads
-`~/.config/opencode/config.json` when no model is supplied, so OpenLoops rejects
+`~/.config/opencode/config.json` when no model is supplied, so Loops rejects
 OpenCode agent targets without `--model` instead of inheriting a stale or
 machine-specific default.
 
@@ -237,6 +304,32 @@ loops create agent opencode-smoke \
   --prompt "Reply with exactly OK."
 ```
 
+Direct agent loops can persist an auditable session contract:
+
+```bash
+loops create agent repo-check \
+  --provider codewith \
+  --every 15m \
+  --cwd /path/to/repo \
+  --sandbox workspace-write \
+  --prompt "Check the repo and report concrete failures." \
+  --allow-tool functions.exec_command \
+  --allow-command git,bun \
+  --safety-reason "isolated repository status inspection"
+```
+
+Tool and command lists are advisory metadata, not provider-enforced policy.
+Loops stores the reason with the direct loop target, adds an explicit
+advisory contract to provider stdin, and exports `LOOPS_AGENT_SESSION_CONTRACT`.
+A direct agent loop has no workflow run, so it does not create a workflow event.
+Agent steps inside workflows that carry an audit contract additionally receive
+one server-derived `agent_session_contract` event per step and workflow run.
+
+Codewith/Codex `danger-full-access`, Cursor `sandbox=disabled`, and provider
+bypass modes (Claude, Cursor, AI Copilot, and OpenCode) require both a non-empty
+safety reason and `--manual-break-glass`. A reason cannot replace explicit
+operator approval.
+
 For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
 
 ```bash
@@ -280,7 +373,7 @@ resolve from the workflow JSON file's directory:
 }
 ```
 
-OpenLoops records `promptSource` metadata and redacts prompt bodies in public
+Loops records `promptSource` metadata and redacts prompt bodies in public
 CLI output by default, including `templates render`. Use
 `~/.hasna/loops/prompts/<stable-name>.md` as the default prompt store for
 production loops.
@@ -291,7 +384,7 @@ non-secret routing/configuration data.
 
 ## Goals
 
-Add `--goal` to wrap a command, agent, or workflow loop in an AI-SDK orchestration layer. OpenLoops asks the configured model to create a flat DAG plan, then executes ready plan nodes by re-running the underlying target once per node. Each node run is parameterized with that node's objective: agent prompts get the goal and node objective appended, and every wrapped process receives `LOOPS_GOAL_NODE_KEY` and `LOOPS_GOAL_NODE_OBJECTIVE` in its environment. An adversarial achievement audit runs before the goal is marked complete.
+Add `--goal` to wrap a command, agent, or workflow loop in an AI-SDK orchestration layer. Loops asks the configured model to create a flat DAG plan, then executes ready plan nodes by re-running the underlying target once per node. Each node run is parameterized with that node's objective: agent prompts get the goal and node objective appended, and every wrapped process receives `LOOPS_GOAL_NODE_KEY` and `LOOPS_GOAL_NODE_OBJECTIVE` in its environment. An adversarial achievement audit runs before the goal is marked complete.
 
 The goal `autoExecute` mode is honored: `off` plans and persists the DAG without executing any nodes (the run reports the persisted plan), while `readyOnly` (the default) and `aiDirected` run the dependency-driven execution loop over ready nodes.
 
@@ -342,7 +435,7 @@ Workflow JSON can also embed goals at the workflow or step level:
 For **workflow loops** (`loops create workflow ...`), prefer a single loop-level
 `--goal` wrapper around the scheduled workflow. Do not also define a top-level
 `"goal"` on the workflow JSON spec: nested loop-level and workflow-level goal
-wrappers deadlocked execution because each layer waited on the other. OpenLoops
+wrappers deadlocked execution because each layer waited on the other. Loops
 now rejects new workflow loops that combine both wrappers at creation time, and
 blocks retargeting a loop-level goal loop onto a workflow that also carries a
 top-level goal.
@@ -421,7 +514,7 @@ Use `shell: true` only when you intentionally want shell parsing:
 ## Templates And Task Events
 
 Built-in templates turn common orchestration flows into reusable workflow JSON.
-Todos-task routes are OpenLoops-native runtime admission — see
+Todos-task routes are Loops-native runtime admission — see
 [Runtime Boundary](docs/RUNTIME_BOUNDARY.md) for how this differs from
 OpenAutomations queue ownership.
 `todos-task-worker-verifier` performs one todos task and then verifies it.
@@ -477,7 +570,7 @@ loops templates render routing-remediation \
   --var idempotencyKey=routing-health:repo:shard0
 ```
 
-Custom reusable workflow templates live under the OpenLoops app data directory:
+Custom reusable workflow templates live under the Loops app data directory:
 `~/.hasna/loops/templates` by default, or `$LOOPS_DATA_DIR/templates` when
 `LOOPS_DATA_DIR` is set. Store templates as declarative JSON files; listing,
 showing, and rendering templates never executes workflow steps or mutates the
@@ -581,6 +674,8 @@ arguments, and implicit Codewith/Codex full-access defaults. If a custom
 Codewith/Codex template uses `permissionMode: "bypass"`, it must also set
 `sandbox` to `workspace-write` or `read-only`. Use built-in templates with
 explicit break-glass handling for emergency workflows that need full access.
+Claude, Cursor, AI Copilot, and OpenCode bypass modes always require explicit
+break-glass plus a non-empty safety reason.
 
 For event-driven task automation, `loops routes create todos-task` reads a
 Hasna event envelope from stdin or `HASNA_EVENT_JSON`, records a
@@ -682,10 +777,10 @@ cat event.json | loops routes create generic \
 ```
 
 This is the intended deterministic-to-agentic path: a producer creates a todos
-task, `@hasna/events` delivers `task.created`, OpenLoops records the invocation
-and admission item, OpenLoops creates a worker/verifier workflow when admitted,
+task, `@hasna/events` delivers `task.created`, Loops records the invocation
+and admission item, Loops creates a worker/verifier workflow when admitted,
 and the workflow updates todos with evidence. Use account pools so worker and
-verifier steps do not burn the same profile. For live Codewith drains, OpenLoops
+verifier steps do not burn the same profile. For live Codewith drains, Loops
 spreads each route to the **least-loaded** pool account (counting running steps
 per account) and still keeps the verifier on a different profile than the worker;
 the deterministic hash is the tie-break, so a cold store reproduces the previous
@@ -698,9 +793,9 @@ Use `--dry-run` to inspect the rendered invocation, work item, workflow, and
 loop input without storing anything.
 
 Generated worker/verifier workflows fail closed when `sandbox=danger-full-access`
-is requested without `manualBreakGlass=true`. Use `workspace-write` for
-unattended task/event routes. Full access is an explicit manual emergency path,
-not a default automation mode.
+is requested without both `manualBreakGlass=true` and a non-empty
+`safetyReason`. Use `workspace-write` for unattended task/event routes. Full
+access is an explicit manual emergency path, not a default automation mode.
 
 When a sandboxed Codewith/Codex worker must update app stores outside the repo
 worktree, pass those stores explicitly with `--add-dir` or template `addDirs`.
@@ -792,7 +887,21 @@ anti-hog caps counted over all routes. Raise a router's `--max-active`
 deliberately once counting is per-route; keep `--max-per-profile` set so the
 extra concurrency spreads across subscription accounts.
 
-`--max-active` and related route throttles count OpenLoops routed workflow work
+Route flags or an expanded named policy are authoritative ceilings. Positive
+integer task/event fields (`max_active`, `max_active_per_project`, and
+`max_active_per_project_group`, including camel-case aliases) may only tighten
+an already configured ceiling for that admission attempt; metadata cannot
+create a cap, raise it, or override an explicit `--project-group`. Generated
+workflow prompts and invocation manifests include the resolved route scope,
+project group, and throttle limits so the admission decision is auditable from
+the same evidence the agent sees.
+
+These caps are local-store admission controls, not a distributed semaphore. The
+count and admission write are serialized in one transaction for routers sharing
+the same local `loops.db`; different `LOOPS_DATA_DIR` databases or machines do
+not share project-group counts.
+
+`--max-active` and related route throttles count Loops routed workflow work
 items; they do not know whether Codewith is already at its live background-agent
 admission limit. Add `--provider-active-cap <n>` (or the Codewith-specific alias
 `--codewith-active-cap <n>`) to make the route run `codewith agent diagnostics
@@ -817,7 +926,7 @@ Workflow run manifests are written under
 
 ## OpenAutomations Runtime Binding
 
-OpenLoops executes automations that external compilers have materialized; it
+Loops executes automations that external compilers have materialized; it
 does not own the automation product surface. See
 [Runtime Boundary](docs/RUNTIME_BOUNDARY.md) for the full ownership table,
 three handoff paths (claim-queue, planned `@hasna/actions` upsert-one-shot, and
@@ -839,7 +948,7 @@ automations queue complete <action-id> --runner open-loops:<worker-id>
 ```
 
 For explicit event workflow routing, OpenAutomations can export the normalized
-event envelope and OpenLoops can consume it through the existing generic event
+event envelope and Loops can consume it through the existing generic event
 route:
 
 ```bash
@@ -847,13 +956,13 @@ automations --json webhooks event <route> --body-json '<json>' \
   | loops --json routes create generic
 ```
 
-This is not automation materialization in OpenLoops. It is an explicit
+This is not automation materialization in Loops. It is an explicit
 event-envelope workflow handoff: OpenAutomations owns deterministic automation
-specs, webhook normalization, queue state, approvals, DLQ, and replay; OpenLoops
+specs, webhook normalization, queue state, approvals, DLQ, and replay; Loops
 owns agent workflow invocation after the operator routes the envelope to
 `loops routes create generic`.
 
-Do not store automation specs in OpenLoops, infer automation triggers from event
+Do not store automation specs in Loops, infer automation triggers from event
 transport alone, or replace the OpenAutomations queue with loop/workflow rows.
 When a loop or workflow is used for execution, keep `HASNA_AUTOMATIONS_DIR`
 pointing at the owning OpenAutomations data root and preserve the runner id in
@@ -862,7 +971,7 @@ completion/failure calls so OpenAutomations can enforce action leases.
 ### Planned Workflow Upsert SDK
 
 External compilers such as `@hasna/actions` and `@hasna/automations` should not
-write OpenLoops SQLite rows directly. The stable contract should be an
+write Loops SQLite rows directly. The stable contract should be an
 idempotent CLI/SDK upsert that accepts a fully rendered one-shot workflow loop
 request and returns durable refs.
 
@@ -875,7 +984,7 @@ does not duplicate that spec.
 That design doc also defines the planned `@hasna/actions` target binding. The
 binding reuses `ActionManifest`, `ActionInvocation`, `ActionRunStatus`,
 `ActionQueueStatus`, action-owned idempotency keys, action audit events, and
-dead-letter/replay records. OpenLoops only admits and executes the handed-off
+dead-letter/replay records. Loops only admits and executes the handed-off
 workflow, then returns workflow refs for action-owned evidence.
 
 The same design doc covers the planned DLQ/dead-letter lifecycle, including
@@ -889,7 +998,7 @@ work.
 
 ## Transcript-Driven Loops
 
-OpenLoops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
+Loops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
 
 ```bash
 loops workflows validate /path/to/repo/.openloops/transcript-feedback-to-loops.json --preflight
@@ -999,7 +1108,7 @@ Archived loops are hidden from the default `loops list`, excluded from daemon sc
 
 `loops run-now` reports the manual run source:
 
-- `source=ad_hoc`: the loop was not due yet, so OpenLoops created a one-off manual slot. This is a single immediate attempt and does not schedule retries or consume the future scheduled slot.
+- `source=ad_hoc`: the loop was not due yet, so Loops created a one-off manual slot. This is a single immediate attempt and does not schedule retries or consume the future scheduled slot.
 - `source=due_slot`: the persisted scheduled slot was already due, so the manual run claims that slot and advances or retries the loop using normal scheduler rules.
 - `source=retry_slot`: the loop was waiting on a failed slot retry, so the manual run claims that retry slot and advances the loop using normal retry rules.
 
@@ -1048,16 +1157,84 @@ On Linux this writes a user systemd service. On macOS it writes a LaunchAgent pl
 The adapters intentionally use provider command surfaces instead of pretending every agent has one SDK:
 
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
-- Codewith runs non-interactive `codewith --ask-for-approval never exec --json` sessions by default. exec starts a fresh session per invocation, avoiding the multi-megabyte rollout history that `codewith agent start` reloaded every turn (which drove `context_length_exceeded` silent no-ops), and it keeps network egress for gh/git — the `workspace-write` sandbox opts back into `sandbox_workspace_write.network_access`. Codewith exec is remote-capable like codex. OpenLoops rejects Codewith `extraArgs` that try to force `exec`, `--ephemeral`, `--json`, or other exec launch flags that the adapter already manages.
+- Codewith runs non-interactive `codewith --ask-for-approval never exec --json` sessions by default. exec starts a fresh session per invocation, avoiding the multi-megabyte rollout history that `codewith agent start` reloaded every turn (which drove `context_length_exceeded` silent no-ops), and it keeps network egress for gh/git — the `workspace-write` sandbox opts back into `sandbox_workspace_write.network_access`. Codewith exec is remote-capable like codex.
 - AI Copilot and OpenCode use `run --format json --pure`. OpenCode requires an explicit provider/model id because ambient OpenCode config is machine-specific.
-- Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
+- Cursor is CLI-first for now via the standalone `agent -p` binary. Loops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
 - Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
 - Agent prompts are sent through child stdin instead of argv where the provider supports stdin, including Codewith `exec` (which reads instructions from stdin when no positional prompt is given), so the prompt never lands on argv.
-- When `--account` or a step `account` is set, OpenLoops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
-- `--auth-profile` and step `authProfile` are provider-native auth selectors. They currently apply to Codewith and are passed to Codewith as `--auth-profile <name>` on the `exec` invocation; they do not call OpenAccounts.
+- When `--account` or a step `account` is set, Loops resolves `accounts env <profile> --tool <tool>` before spawning the target, strips inherited tool home/API-key variables, and applies the selected profile only to that process. Missing account profiles fail before the provider binary receives the prompt.
+- `--auth-profile` and step `authProfile` are provider-native Codewith selectors passed as `--auth-profile <name>` on the `exec` invocation; they do not call OpenAccounts. Local and remote preflight share the JSON-first, exact-name contract described above, use human-table parsing only as a compatibility fallback, and fail closed for unusable or missing profiles, NUL-containing names, and non-fallback list failures.
 - `--sandbox` maps to provider-native sandbox flags. Codewith/Codex accept `read-only`, `workspace-write`, or `danger-full-access`; Cursor accepts `enabled` or `disabled`.
+- `--allow-tool` and `--allow-command` declare advisory, metadata-only
+  restrictions and require `--safety-reason`. The exact contract is persisted
+  and emitted for audit, but Loops does not claim provider-side enforcement.
+  Relaxed sandboxes and native provider bypass modes also require explicit
+  `--manual-break-glass`.
 - `--permission-mode` maps `plan`, `auto`, and `bypass` where the provider supports it. Claude uses native permission modes, Cursor maps bypass to `--force`, and OpenCode/AICopilot map bypass to `--dangerously-skip-permissions`.
+- `extraArgs` is fail-closed: every provider currently rejects non-empty
+  passthrough arguments, including unknown options, positional subcommands,
+  split values, `--option=value`, and attached short-option forms. Configure
+  execution, output, permissions, sandboxing, model, cwd, and other supported
+  behavior through the modeled agent-target fields. A passthrough option must
+  be explicitly reviewed and added to the provider allowlist before use.
+  Legacy persisted targets are not silently accepted or rewritten: execution
+  fails validation until `extraArgs` is removed and replaced with modeled
+  fields. API and migration imports reject those targets instead of stripping
+  the arguments; update the source record and retry the import.
 - `--variant` is provider-specific reasoning/model effort. Claude maps it to `--effort`, Codewith/Codex map it to `model_reasoning_effort`, and OpenCode/AICopilot pass `--variant`.
 - Daemon and scheduled runs prepend common user executable directories such as `~/.local/bin` and `~/.bun/bin` before resolving provider CLIs.
 
+For hosted workflow runs, the control plane derives any required agent session
+contract from the stored workflow step and persists it before execution. Reusing an
+older workflow run backfills a missing valid contract idempotently. Stored
+pre-contract workflows with unsafe/invalid agent options, mismatched stored
+contracts, duplicate contracts, command-step contracts, and client-fabricated
+contracts fail closed. Direct agent loops continue to expose their contract
+through prompt/environment metadata only.
+
 For production loops that can mutate repos, use disposable worktrees (`--worktree-mode required` / `worktreeMode=required`) and explicit prompts that name allowed write scope. Worktrees are executor-enforced: when a target carries worktree metadata, the executor prepares and enters the git worktree before spawning the child process, records the worktree it entered, and with `mode=required` fails the run closed instead of falling back to the original checkout when preparation fails. Existing managed worktrees are reused only after top-level and git-common-dir checks; a clean detached or stale-branch checkout may be reattached to the expected generated branch, while dirty or unsafe mismatches fail with cleanup evidence. Remote machine runs with a required worktree apply the same checks on the remote side before the target executes.
+
+## Immutable ECR Candidate Images
+
+`.github/workflows/ecr-candidate.yml` is the repository workflow for building
+an AWS ECR release candidate. It is manual and source-only: it does not update
+`latest`, ECS task definitions, services, or deployments. The job checks out
+an exact full commit SHA, proves that commit is reachable from `origin/main`,
+builds the `Dockerfile` `runner` target natively for `linux/arm64`, blocks on
+local Trivy critical/high findings, and only then assumes the ECR push role.
+After the immutable push it waits for ECR scanning and blocks on critical/high
+findings there as well. The retained artifact contains the local scan report,
+a CycloneDX SBOM, an unsigned in-toto/SLSA provenance statement, and bounded
+ECR scan counts. The statement is evidence, not a cryptographic attestation.
+
+Before the first run, repository administrators must create a protected GitHub
+environment named `ecr-candidate` with required reviewers and no deployment
+branches other than `main`. Configure these repository variables (not secrets):
+
+- `AWS_REGION`: AWS region containing the existing candidate repository.
+- `AWS_ROLE_ARN`: OIDC role dedicated to this workflow.
+- `ECR_REPOSITORY`: existing ECR repository name. It must use immutable tags
+  and scan-on-push.
+
+The OIDC role trust must constrain `token.actions.githubusercontent.com:aud`
+to `sts.amazonaws.com` and `token.actions.githubusercontent.com:sub` to exactly
+`repo:hasna/loops:environment:ecr-candidate`. Its permissions should allow
+`ecr:GetAuthorizationToken` on `*`, and only these actions on the configured
+repository ARN: `ecr:DescribeRepositories`, `ecr:BatchCheckLayerAvailability`,
+`ecr:GetDownloadUrlForLayer`, `ecr:BatchGetImage`, `ecr:InitiateLayerUpload`,
+`ecr:UploadLayerPart`, `ecr:CompleteLayerUpload`, `ecr:PutImage`,
+`ecr:DescribeImages`, and `ecr:DescribeImageScanFindings`. No static AWS access
+key is used.
+
+Dispatch only after the source commit is merged to `main`:
+
+```bash
+sha="$(git rev-parse origin/main)"
+gh workflow run ecr-candidate.yml --repo hasna/loops --ref main \
+  -f source_sha="${sha}" -f confirmation="push ${sha}"
+```
+
+Dispatch is an AWS mutation and requires the applicable operator approval and
+fresh release preflight. Do not run it merely because the source workflow has
+merged. Review the workflow summary and retained evidence; promote only by
+the reported immutable digest through the separate deployment process.