@hasna/loops 0.4.27 → 0.4.29

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,16 +77,55 @@ 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
 ```
 
+`loops self-hosted push` is safe by default: imported workflows are archived and
+imported loops are paused with `nextRunAt`/`retryScheduledFor` cleared. Even
+without `--replace`, the control-plane import boundary may rewrite existing
+same-id workflows/loops into that disabled representation; use explicit
+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
@@ -126,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
@@ -143,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
@@ -152,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
@@ -217,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.
 
@@ -231,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
@@ -274,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.
@@ -285,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.
 
@@ -336,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.
@@ -415,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.
@@ -471,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
@@ -575,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
@@ -676,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
@@ -692,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`.
@@ -786,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
@@ -811,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
@@ -833,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
@@ -841,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
@@ -856,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.
 
@@ -869,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
@@ -883,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
@@ -993,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.
 
@@ -1042,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.

package/dist/api/index.d.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
+import { type CircuitBreakerThreshold } from "../lib/advancement.js";
 import type { LoopStorageContract } from "../lib/storage/contract.js";
+import { type RoutePolicy } from "../lib/auth/route-policy.js";
+import type { TenantAuthContext, TenantAuthDecision } from "../lib/auth/tenant-auth.js";
 /** The serve OpenAPI document (source of the generated SDK), version-synced. */
 export declare function openApiDocument(): Record<string, unknown>;
 export declare function apiStatus(): {
@@ -7,23 +10,12 @@ export declare function apiStatus(): {
     service: string;
     status: import("../index.js").LoopDeploymentStatus;
 };
-/**
- * Framework-agnostic API-key verifier shape (matches
- * `@hasna/contracts/auth` `ApiKeyVerifier`). Kept structural so the api module
- * has no hard dependency on the auth package: the serve entry injects the real
- * verifier built from the vendored kit's client + the HMAC signing secret.
- */
 export interface ApiAuthenticator {
-    authenticate(headers: Headers, context?: {
-        method?: string | null;
-        path?: string | null;
-        requiredScopes?: readonly string[];
-    }): Promise<{
-        ok: boolean;
-        status: number;
-        reason?: string;
-        message?: string;
-    }>;
+    authenticate(headers: Headers, context: {
+        method: string;
+        path: string;
+        policy: RoutePolicy;
+    }): Promise<TenantAuthDecision>;
 }
 export interface LoopsApiServerOptions {
     host?: string;
@@ -33,21 +25,30 @@ export interface LoopsApiServerOptions {
     evidenceLimitBytes?: number;
     importLimitBytes?: number;
     now?: () => Date;
+    random?: () => number;
+    circuitBreakerThreshold?: CircuitBreakerThreshold;
     /**
      * API-key verifier (from `@hasna/contracts/auth`). When present, every
      * request outside the open foundation probes (`/health`, `/ready`,
-     * `/version`, `/status`) must present a valid `loops:*` scoped key. This is
+     * `/version`, `/openapi.json`) must present a valid `loops:*` scoped key. This is
      * the internet-facing auth path (no bearer token, no loopback bypass).
      */
     authenticator?: ApiAuthenticator;
+    withTenantStorage?: <T>(principal: TenantAuthContext, fn: (storage: LoopStorageContract) => Promise<T>) => Promise<T>;
     /**
      * Readiness probe. Should prove the storage backend is reachable AND fully
-     * migrated. Returns `{ ready, detail? }`. Defaults to a storage list probe.
+     * migrated. Returns a stable public code only. Defaults to a storage list probe.
      */
     readyCheck?: () => Promise<{
         ready: boolean;
-        detail?: string;
+        code?: "storage_unconfigured" | "storage_unreachable" | "auth_unreachable" | "unsafe_database_role" | "pending_migrations" | "unknown_migrations" | "migration_checksum_mismatch";
     }>;
 }
+export declare function contractHealthResponse(env?: Record<string, string | undefined>): {
+    status: "ok";
+    version: string;
+    mode: "local" | "cloud";
+};
 export declare function createLoopsApiServer(opts?: LoopsApiServerOptions): Bun.Server<undefined>;
+export declare function logApiCommandFailure(error: unknown): void;
 export declare function main(argv?: string[]): Promise<void>;