@hasna/loops 0.4.14 → 0.4.22

package/docs/DEPLOYMENT_MODES.md

@@ -5,19 +5,28 @@ 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**
+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
+`@hasna/automations` and `@hasna/actions`. See
+[Runtime Boundary](./RUNTIME_BOUNDARY.md).
+
 ## Modes
 
 | Mode | Source of truth | Local storage role | Executor |
 | --- | --- | --- | --- |
 | `local` | SQLite in `LOOPS_DATA_DIR` | Authoritative | `loops-daemon` |
-| `self_hosted` | A user-operated `loops-api` control plane contract | Cache and offline spool | `loops-runner` foundation |
+| `self_hosted` | Hasna-owned AWS/RDS control plane served by `loops-serve`/`loops-api` | 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,
 tokens, Postgres, or hosted infrastructure.
 
-`self_hosted` is for users or teams running their own control plane. The public
-`@hasna/loops` package owns the API and runner contract for this mode.
+`self_hosted` is the Hasna-owned AWS/RDS control-plane deployment. The public
+`@hasna/loops` package owns `loops-serve`, the embeddable `loops-api` contract,
+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
@@ -58,6 +67,8 @@ 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
 loops-runner status
 loops export --file ./loops-export.json --dry-run
 loops export --file ./loops-export.json
@@ -88,11 +99,12 @@ JSON uses these field names:
 - `schedulerState.localStore`: always names the local SQLite store and local
   run artifact files. In `local` mode this store is authoritative; in
   non-local modes it is a cache, offline spool, and audit copy.
-- `schedulerState.remoteStore`: names the remote scheduler contract:
+- `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 this public package until a control-plane host wires a full
-  storage adapter.
+  `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.
 - `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.
@@ -102,13 +114,18 @@ JSON uses these field names:
   Live active counts use admitted/running work items; dry-runs do not open or
   migrate the live store to compute counts.
 
-`loops-api` is a separate process in the same public package. It is not a
-separate package at this stage because self-hosted users and the hosted service
-must share the same public contract. The API server can expose storage-backed
-`/v1` loop CRUD and run listing when an embedding host injects the public
-storage contract. The standalone `loops-api serve` binary still fails closed
-for those routes until a self-hosted storage adapter is wired by the operator or
-platform host.
+`loops-serve` is the self-hosted HTTP control-plane binary in this public
+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.
 
 `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:
@@ -166,9 +183,10 @@ 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.
 
-`LOOPS_DATABASE_URL` selects the self-hosted Postgres scheduler-state contract,
-but it does not make the standalone CLI mutate a remote database by itself.
-Remote execution still flows through a configured control-plane API and runner
+`LOOPS_DATABASE_URL` or `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
 work; a database URL alone is migration/readiness configuration.
 
@@ -203,9 +221,8 @@ mode.
 
 ## Follow-Up Work
 
-Non-local execution needs these follow-up releases before it is live:
+Non-local execution needs these follow-up releases before it is complete:
 
-- A full Postgres control-plane adapter behind the public storage contract.
 - Long-running runner daemon mode with backoff, fleet observability, and
   durable machine registration records.
 - Workflow target execution over the remote protocol.

package/docs/RUNTIME_BOUNDARY.md

@@ -0,0 +1,203 @@
+# OpenLoops Runtime Boundary
+
+OpenLoops 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
+`@hasna/automations`, `@hasna/actions`, and related product packages.
+
+Use this document when you need a single operator-facing boundary reference.
+For the planned upsert/DLQ/strict-mode contract, see
+[`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md). For
+deployment-mode vocabulary (local vs self-hosted vs cloud), see
+[`DEPLOYMENT_MODES.md`](./DEPLOYMENT_MODES.md).
+
+## Ownership Split
+
+| Concern | Owner | OpenLoops role |
+| --- | --- | --- |
+| Automation specs and trigger materialization | `@hasna/automations` | None — do not store specs in OpenLoops |
+| 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 |
+
+The SDK exposes the canonical boundary strings via `openAutomationsRuntimeBinding()`:
+
+```ts
+import { openAutomationsRuntimeBinding } from "@hasna/loops";
+
+const binding = openAutomationsRuntimeBinding();
+// binding.handoff === "claim-queue"
+// binding.queueOwner === "open-automations"
+// binding.runtimeOwner === "open-loops"
+console.log(binding.guarantees);
+console.log(binding.nonGoals);
+```
+
+**Guarantees (summary):**
+
+- OpenAutomations owns automation specs, run materialization, queue state, DLQ,
+  replay, idempotency, and approvals.
+- OpenLoops may execute claimed actions through explicit command or SDK handoff
+  only.
+- OpenLoops 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
+  alone.
+
+## External Compiler Handoff Paths
+
+External compilers (`@hasna/automations`, `@hasna/actions`, event routers)
+materialize automation intent in their own stores. OpenLoops receives **rendered
+work** through one of the paths below. Do not bypass these boundaries by writing
+OpenLoops SQLite rows from another package.
+
+### 1. OpenAutomations claim-queue (implemented)
+
+OpenAutomations owns the action queue. An OpenLoops 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:
+automations queue complete <action-id> --runner open-loops:<worker-id>
+# or on failure:
+automations queue fail <action-id> --runner open-loops:<worker-id> \
+  --code <code> --message <message>
+```
+
+Keep `HASNA_AUTOMATIONS_DIR` pointing at the owning OpenAutomations data root.
+Preserve the runner id in every complete/fail call so OpenAutomations can enforce
+action leases.
+
+SDK reference:
+
+```ts
+const binding = openAutomationsRuntimeBinding();
+console.log(binding.claimCommand);   // "automations queue claim"
+console.log(binding.completeCommand); // "automations queue complete"
+console.log(binding.failCommand);    // "automations queue fail"
+```
+
+### 2. `@hasna/actions` compiler → planned upsert-one-shot (design)
+
+`@hasna/actions` compiles action targets into a fully rendered one-shot workflow
+loop request. The stable handoff is an **idempotent upsert** — not direct
+SQLite access.
+
+**Status:** `loops workflows upsert-one-shot` and the matching SDK method are
+**planned** (see [`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md)).
+The shapes below are the contract target; they are not shipped in this release.
+
+Example request the compiler would send (abbreviated):
+
+```ts
+type WorkflowUpsertRequest = {
+  idempotencyKey: "actions:<action-id>:<version>",
+  source: { kind: "action", id: "<action-id>" },
+  subject: { kind: "repo", path: "/path/to/repo" },
+  workflow: { name: "action-<action-id>", steps: [/* rendered steps */] },
+  loop: { name: "action-<action-id>", schedule: { type: "once", at: "2026-07-01T12:00:00Z" } },
+  mode: "preflight",       // dry-run | preflight | commit
+  dispatch: "schedule",    // schedule | run-now | none
+};
+```
+
+Planned CLI mirror:
+
+```bash
+loops workflows upsert-one-shot ./workflow.json \
+  --idempotency-key actions:<action-id>:<version> \
+  --source-kind action \
+  --source-id <action-id> \
+  --subject-kind repo \
+  --subject-path /path/to/repo \
+  --loop-name action-<action-id> \
+  --at 2026-07-01T12:00:00Z \
+  --mode preflight \
+  --dispatch schedule \
+  --json
+```
+
+OpenLoops 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.
+
+### 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
+exported envelope into the generic route:
+
+```bash
+automations --json webhooks event <route> --body-json '<json>' \
+  | loops --json routes create generic
+```
+
+This is **not** automation materialization in OpenLoops. OpenAutomations still
+owns deterministic automation specs, webhook normalization, queue state,
+approvals, DLQ, and replay. OpenLoops owns agent workflow invocation after the
+operator routes the envelope to `loops routes create generic`.
+
+```ts
+const { eventHandoff } = openAutomationsRuntimeBinding();
+console.log(eventHandoff.handlerCommand); // "loops routes create generic"
+console.log(eventHandoff.boundary);
+```
+
+## OpenLoops-Native Path: Todos-Task Routes
+
+Todos-task routing is an **OpenLoops-native** admission path. It is separate from
+the OpenAutomations product queue:
+
+```bash
+cat task-created-event.json | loops routes create todos-task \
+  --template task-lifecycle \
+  --worktree-mode required
+```
+
+Tasks must opt in (`auto:route`, `route_enabled=true`, or
+`automation.allowed=true`). OpenLoops 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>/`.
+
+This path does **not** make OpenAutomations the queue owner for todos task/PR/review
+agent workflows. It also does **not** replace OpenAutomations action queues for
+product automations. Choose the handoff path that matches who owns the queue and
+audit trail for your automation.
+
+See [`USAGE.md`](./USAGE.md) § Templates And Task Events for templates,
+provider rules, and drain examples.
+
+## Anti-Patterns
+
+Do **not**:
+
+- Store automation specs in OpenLoops 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`.
+- Dispatch or paste task prompts into tmux panes from route drains (use headless
+  workflow templates instead).
+
+## Related Docs
+
+- [`AUTOMATION_RUNTIME_DESIGN.md`](./AUTOMATION_RUNTIME_DESIGN.md) — planned
+  upsert SDK, DLQ/replay, strict automation execution mode.
+- [`USAGE.md`](./USAGE.md) — templates, todos-task routes, provider pools.
+- [`DEPLOYMENT_MODES.md`](./DEPLOYMENT_MODES.md) — local/self-hosted/cloud;
+  deployment concerns are runtime placement, not automation product surface.
+- README § OpenAutomations Runtime Binding — short summary and quick references.

package/docs/USAGE.md

@@ -15,12 +15,13 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 OpenLoops defaults to `local`, where SQLite in `LOOPS_DATA_DIR` is
 authoritative and `loops-daemon` executes scheduled work. The package also
-defines `self_hosted` and `cloud` contracts for future non-local control
-planes:
+defines `self_hosted` and `cloud` contracts for non-local control planes:
 
-- `self_hosted`: user-operated `loops-api` control-plane contract; this
-  release exposes storage-backed API/runner foundations plus local migration
-  previews.
+- `self_hosted`: the Hasna-owned AWS/RDS control-plane deployment, served by
+  `loops-serve` and backed by Postgres, with the embeddable `loops-api` contract
+  shared by serve, SDK, and tests. This release exposes storage-backed `/v1`
+  loop CRUD and run listing, runner registration/claim/heartbeat/finalize
+  foundations, and local migration previews.
 - `cloud`: hosted control-plane contract; this release exposes client/runner
   status only, and requires `LOOPS_CLOUD_API_URL` plus `LOOPS_CLOUD_TOKEN` or
   `HASNA_LOOPS_CLOUD_TOKEN` before status can report ready.
@@ -29,13 +30,16 @@ Scheduler state is explicit in status JSON. `schedulerState.localStore` is
 SQLite plus local run artifact files: authoritative in `local`, cache/spool in
 non-local modes. `schedulerState.remoteStore` names the non-local contract
 (`api_control_plane_contract`, `postgres_contract`, or
-`hosted_control_plane_contract`) and reports `applySupported=false` because this
-public package does not directly mutate remote Postgres, S3/object storage, AWS
-resources, or hosted credentials. Route admission remains bounded by
-`max_dispatch`, `max_active`, `max_active_per_project`,
-`max_active_per_project_group`, `max_active_scope`, and `max_per_profile`.
+`hosted_control_plane_contract`). The standalone `loops` CLI reports
+`applySupported=false` for non-local apply because it does not perform
+id-preserving remote migration, S3/object storage mutation, AWS resource
+mutation, or hosted credential mutation. `loops-serve` mutates self-hosted
+Postgres for normal control-plane CRUD and runner protocol routes when it is
+explicitly configured. Route admission remains bounded by `max_dispatch`,
+`max_active`, `max_active_per_project`, `max_active_per_project_group`,
+`max_active_scope`, and `max_per_profile`.
 
-Useful status commands:
+Useful status and setup commands:
 
 ```bash
 loops mode
@@ -48,6 +52,8 @@ 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
 loops-runner status
 ```
 
@@ -93,14 +99,16 @@ The preview may inspect `LOOPS_API_URL`/`HASNA_LOOPS_API_URL`, but it refuses
 remote apply because normal loop CRUD would generate new ids. Use
 `loops self-hosted runner-register` to verify runner registration against an
 API, then use `loops-runner run-once` for the current bounded non-workflow
-claim/execute/finalize protocol.
+claim/execute/finalize protocol. `loops-serve migrate` applies the Postgres
+schema and `api_keys` table for a self-hosted control-plane host; the standalone
+CLI migration previews still do not perform id-preserving remote apply.
 Runner registration is preview-only unless `--apply` is present.
 
 ## Install
 
 **OpenLoops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
-installed binaries are `loops`, `loops-daemon`, `loops-api`, `loops-runner`, and
-`loops-mcp`; each uses a `#!/usr/bin/env bun` shebang.
+installed binaries are `loops`, `loops-daemon`, `loops-api`, `loops-serve`,
+`loops-runner`, and `loops-mcp`; each uses a `#!/usr/bin/env bun` shebang.
 
 From npm:
 
@@ -208,6 +216,23 @@ failures are recorded as failed loop runs with a `runtime preflight failed`
 error, so health/routing checks can create follow-up tasks without spawning the
 worker.
 
+For controlled launches, scheduled todos-task drains can be guarded by blocker
+tasks:
+
+```bash
+loops routes schedule todos-task platform-drain \
+  --every 5m \
+  --todos-project /path/to/source/todos-project \
+  --tags auto:route \
+  --launch-gate "pa19-controlled-launch" \
+  --launch-gate-blocker "/path/to/open-codewith::2d9d931b" \
+  --launch-gate-blocker "/path/to/open-loops::816e99db" \
+  --worktree-mode required
+```
+
+The drain creates zero worker loops while any blocker task is not completed.
+Each blocked tick writes launch-gate evidence and leaves source tasks untouched.
+
 Run a Claude loop every morning:
 
 ```bash
@@ -418,6 +443,13 @@ for those. Set `"blockedExitCodes": []` on a gate-named step to opt out.
 
 ## Templates And Task Events
 
+OpenLoops is the runtime/scheduler/workflow engine for these flows — not the
+automation domain model. Todos-task routes are OpenLoops-native admission; they
+do not replace the OpenAutomations product queue. See
+[Runtime Boundary](./RUNTIME_BOUNDARY.md) for ownership split and external
+compiler handoff paths (`@hasna/automations` claim-queue,
+`@hasna/actions` planned upsert-one-shot).
+
 Built-in templates turn common orchestration flows into reusable workflow JSON.
 `todos-task-worker-verifier` performs one todos task and then verifies it.
 `event-worker-verifier` handles any Hasna event envelope and then verifies the
@@ -425,7 +457,11 @@ handling. `bounded-agent-worker-verifier` is for recurring bounded agent work:
 one worker runs a narrow objective, then a fresh verifier audits the result.
 The catalog also includes `task-lifecycle`, `pr-review`, `scheduled-audit`,
 `knowledge-refresh`, `report-only`, `incident-response`, and
-`deterministic-check-create-task` for common operator workflows.
+`deterministic-check-create-task` for common operator workflows. Use
+`routing-remediation` for bounded routing-doctor repair runs: it dry-runs by
+default, gates `safe_auto` capacity, applies only supported
+`todos doctor routing --apply` repairs when explicitly enabled, and files
+blocker tasks for human/cross-repo/unsupported findings.
 
 ```bash
 loops templates list
@@ -459,6 +495,12 @@ loops templates render pr-review \
 loops templates render deterministic-check-create-task \
   --var projectPath=/path/to/repo \
   --var checkCommand='your deterministic check and todos upsert command'
+loops templates render routing-remediation \
+  --var projectPath=/path/to/repo \
+  --var todosProjectPath=/path/to/todos-project \
+  --var shard=0/6 \
+  --var maxRepairs=25 \
+  --var idempotencyKey=routing-health:repo:shard0
 ```
 
 Custom reusable workflow templates live under the OpenLoops app data directory:
@@ -579,12 +621,14 @@ on the remote machine. The generated agent target includes worktree metadata
 inspection expose the exact checkout.
 
 Before a worker starts, worktree preparation verifies that any existing
-managed path is a real git worktree with the same top-level checkout, the same
-git common directory as the source repo, and the expected generated branch. A
-detached HEAD or unexpected branch fails closed with evidence
-(`worktreeMode=required`) instead of silently running a mutating workflow in
-the wrong state; `worktreeMode=auto` falls back to the original checkout and
-records the fallback.
+managed path is a real git worktree with the same top-level checkout and the
+same git common directory as the source repo. If the checkout is on a detached
+HEAD or unexpected branch, OpenLoops only reattaches it to the expected
+generated branch when the worktree is clean. Dirty worktrees, symlinked paths,
+non-worktree paths, different common dirs, and unrecoverable branch switches
+fail closed with cleanup evidence (`worktreeMode=required`) instead of
+silently running a mutating workflow in the wrong state; `worktreeMode=auto`
+falls back to the original checkout and records the fallback.
 
 Use explicit main/default checkout mode only when the task truly requires it:
 
@@ -628,6 +672,9 @@ blocked, completed/done, cancelled/canceled, failed, archived, manual,
 approval-required, or `no-auto` tasks. This guard exists even when the upstream
 `@hasna/events` webhook filter is misconfigured, so task existence alone is not
 permission to execute agent work.
+Route work items are the durable reservation ledger: they include the stable
+idempotency key, task/event references, project/group keys, admitting machine
+ID, route scope, workflow/loop IDs, and the current terminal or active status.
 
 Task route drains can select providers from task metadata instead of running one
 fixed provider/account pool for the whole drain. Add one or more
@@ -637,13 +684,20 @@ matching rule wins. Rule profiles become a Codewith auth-profile pool for
 can also carry `provider_hint`/`route_provider`, `auth_profile_pool`, or
 `account_pool` metadata. Dry-run, drain evidence, and route invocation scope
 include `providerRouting` so operators can see why a provider/account was
-selected.
+selected. Selector values may contain `:`; the parser treats the colon before a
+supported provider id as the route delimiter, so exact tag selectors such as
+`tags=area:frontend:claude:account003,account015` and
+`tags=provider:claude-code:claude:account003,account015` match literal task
+tags `area:frontend` and `provider:claude-code`.
 
 ```bash
 loops routes drain todos-task \
   --dry-run \
+  --provider-rule tags=area:frontend:claude:account003,account015 \
+  --provider-rule tags=provider:claude-code:claude:account003,account015 \
   --provider-rule area=frontend:claude:claude-ui-a,claude-ui-b \
   --provider-rule area=backend:codewith:account001,account002 \
+  --provider-rule tags=task-lifecycle:codewith:account001,account002 \
   --worktree-mode required
 ```
 
@@ -721,6 +775,10 @@ equivalent directory-scoped write controls.
 Inspect route state with:
 
 ```bash
+loops routes policies list
+loops routes policies show oss
+loops routes policies render oss
+loops routes policies validate
 cat task-created-event.json | loops routes preview todos-task --sandbox workspace-write
 cat task-created-event.json | loops routes create todos-task --sandbox workspace-write
 loops routes drain todos-task --task-list oss --max-dispatch 2 --compact
@@ -731,6 +789,29 @@ loops routes requeue <work-item-id> --reason "fixed upstream blocker"
 loops routes invocations
 ```
 
+Compact drain output includes route reservation IDs, work-item status, machine
+ID, workflow ID, loop ID, and route scope for each considered task.
+
+Named route policies expand the long recurring drain commands used by the live
+task routers into explicit, replayable options. `repoops-pr-queue`, `oss`,
+`pilot`, and `machine-sync` are built in. Operators can inspect the policy,
+render the exact `loops --json routes drain todos-task ...` command, and validate
+that the rendered args no longer depend on `--policy`/`--preset`:
+
+```bash
+loops routes policies render oss
+loops routes schedule todos-task machine-oss-task-lifecycle-router --policy oss
+```
+
+Scheduled policy routes store explicit drain args plus
+`--route-policy-evidence <id>`, so future runs remain auditable even if a policy
+definition changes later. Policy drains and dry-runs include `routePolicy`
+evidence with the source, safety class, guards, expanded options, and rendered
+args. Passing a conflicting explicit option fails before the route is created.
+The `pilot` policy uses `sandbox=danger-full-access` and is treated as a paused
+manual break-glass lane; applying it requires the operator to pass
+`--manual-break-glass` explicitly.
+
 When a workflow run starts from an admitted work item, OpenLoops writes a
 manifest under:
 
@@ -762,6 +843,8 @@ loops routes drain todos-task \
   --max-active-per-project 1 \
   --max-active-per-project-group 4 \
   --max-active 12 \
+  --provider-active-cap 6 \
+  --provider-admission-check \
   --worktree-mode required \
   --evidence-dir "$HOME/.hasna/loops/reports/task-drain"
 ```
@@ -779,6 +862,16 @@ when requested, and leaves excess ready tasks in todos for a later drain pass.
 Use `--dry-run` to preview candidates and rendered workflows without mutating
 OpenLoops state.
 
+The route throttle flags count OpenLoops routed workflow work items, not the
+live background-agent slots inside a provider. For Codewith drains, add
+`--provider-active-cap <n>` (or `--codewith-active-cap <n>`) so each candidate
+checks `codewith agent diagnostics --json` before workflow-loop creation and
+defers when `activeRunCount >= n`. Use `--provider-admission-check` when the
+drain should also fail closed on diagnostics errors, unsupported providers, or
+Codewith reports with no available admission slots. Backlog prioritizer and
+drain loops should use these first-class flags rather than a shell guard around
+`codewith agent diagnostics`.
+
 For an OSS task-created route, keep the drain deterministic and narrow:
 
 ```bash
@@ -797,6 +890,8 @@ loops routes schedule todos-task oss-task-route-drain \
   --max-active-per-project 1 \
   --max-active-per-project-group 4 \
   --max-active 12 \
+  --provider-active-cap 6 \
+  --provider-admission-check \
   --worktree-mode required \
   --evidence-dir "$HOME/.hasna/loops/reports/oss-task-route-drain" \
   --compact
@@ -807,11 +902,13 @@ in with the `auto:route` tag, `route_enabled=true`, or
 `automation.allowed=true` should be routed. Keep repo-mutating worker/verifier
 runs on a Codewith account pool with `--worktree-mode required`. Do not dispatch
 or paste task prompts into tmux panes. Use max-active throttles and
-`--max-dispatch` to bound agent fan-out, and write compact evidence into a
-bounded reports directory so operators can audit each drain without unbounded
-stdout or loop history growth. Keep `--scan-limit` large enough for the current
-ready-task backlog; if the scan is exhausted before matching tasks appear, the
-drain will correctly do no work.
+`--max-dispatch` to bound OpenLoops agent fan-out, and use
+`--provider-active-cap` plus `--provider-admission-check` to bound live Codewith
+background-agent admission. Write compact evidence into a bounded reports
+directory so operators can audit each drain without unbounded stdout or loop
+history growth. Keep `--scan-limit` large enough for the current ready-task
+backlog; if the scan is exhausted before matching tasks appear, the drain will
+correctly do no work.
 
 Generated task/event route workflow specs are lifecycle-managed. After a
 generated one-shot route workflow run reaches `succeeded`, `failed`,
@@ -847,6 +944,27 @@ 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.
 
+## Run Receipts
+
+Use run receipts when an agent, scheduler, route, or external workflow needs a
+stable run outcome without parsing raw stdout or wrapper-script text. Receipts
+are scheduler-neutral JSON records with these public snake_case fields:
+`loop_id`, `run_id`, `machine`, `repo`, `task_ids`, `knowledge_ids`,
+`digest_id`, `started_at`, `finished_at`, `status`, `exit_code`, `summary`, and
+`evidence_paths`. The summary contains bounded, scrubbed excerpts and byte
+counts; raw unbounded stdout/stderr stays out of the receipt contract.
+
+```bash
+cat receipt.json | loops --json receipts write --file -
+loops --json receipts read run_123
+loops --json receipts list --loop-id loop_123 --task-id task_123
+```
+
+MCP clients can use `loops_receipt_read`, `loops_receipts_list`, and the
+mutation-gated `loops_receipt_write`. The SDK exposes `writeReceipt`,
+`receipt`, and `receipts`; the HTTP API exposes `POST /v1/receipts`,
+`GET /v1/receipts/{runId}`, and `GET /v1/receipts`.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.4.14",
+  "version": "0.4.22",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -110,7 +110,6 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@hasna/contracts": "^0.4.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -120,7 +119,8 @@
     "zod": "4.4.3"
   },
   "optionalDependencies": {
-    "@hasna/machines": "0.0.49"
+    "@hasna/machines": "0.0.49",
+    "@hasna/contracts": "^0.4.2"
   },
   "devDependencies": {
     "@types/bun": "latest",