@hasna/loops 0.4.13 → 0.4.22

package/CHANGELOG.md

@@ -5,6 +5,52 @@ documented in this file. Version entries are generated from the
 conventional-commit git history; one commit maps to one released patch version
 unless noted.
 
+## Unreleased
+
+### Added
+
+- `loops-mcp` now serves a shared Streamable HTTP transport (default
+  `http://127.0.0.1:8890/mcp`, `GET /health`) in addition to stdio. Running
+  it as one long-lived daemon with the routing env baked in (e.g.
+  `HASNA_LOOPS_API_URL` + `HASNA_LOOPS_API_KEY`) makes every connecting agent
+  route CRUD deterministically to the same backend regardless of the caller's
+  own shell environment (including non-login SSH). Select the transport with
+  `--http`/`MCP_HTTP=1` (default) or `--stdio`/`MCP_STDIO=1`; the port is set
+  via `--port` or `MCP_HTTP_PORT`.
+
+### Changed
+
+- Documentation now names `loops-serve` as the Postgres-backed Hasna-owned
+  self-hosted control-plane host, keeps `loops-api` as the shared embeddable API
+  contract, and reserves `cloud` wording for the hosted SaaS contract rather
+  than the Hasna-owned self-hosted deployment.
+- The cutover and migration docs now match the 0.4.14 self-hosted backend:
+  `PostgresLoopStorage`, API-key auth, HTTP SDK, ARM64 deploy artifacts, and
+  `loops-serve migrate` are shipped; long-running runner daemon mode, workflow
+  execution over the runner protocol, and id-preserving remote import remain
+  follow-up work.
+
+## 0.4.14 (2026-07-06)
+
+Self-hosted control-plane service brought to the full Hasna standard: all four
+surfaces (CLI, MCP, serve, SDK) are real over the Postgres backend, with
+internet-facing API-key auth and a deployable ARM64 image.
+
+### Added
+
+- **`loops-serve` HTTP control plane:** RDS-direct (Amendment A1) Postgres
+  storage wired into the serve; public `GET /health`, `/ready` (storage
+  reachable + fully migrated), `/version` (all `{status, version, mode}`) and
+  `/openapi.json`; the versioned `/v1` loops + runs API is gated behind
+  `@hasna/contracts` API-key auth (`verifyApiKey`, strict revocation via the
+  shared `api_keys` table). `loops-serve migrate` applies the ledger-tracked
+  schema + api_keys table.
+- **Generated HTTP SDK:** `@hasna/loops/sdk/http` exports a typed dependency-free
+  `LoopsClient` generated from `openapi/loops.json` (the serve contract).
+- **Deploy artifacts:** ARM64/bun `Dockerfile` (Amazon RDS CA baked for
+  verify-full TLS), `docker-compose.yml`, `hasna.contract.json` service
+  manifest, and a `migrations/` mirror of the ledger migrations.
+
 ## 0.4.13 (2026-07-05)
 
 `--pr-handoff` workflows whose worker pushes its own branch and opens the PR
@@ -477,13 +523,63 @@ CLI/MCP/SDK surface with deprecation aliases.
   npm installs), and `@hasna/machines` is now an optional dependency —
   installs without it simply disable remote-machine assignment.
 
+## 0.3.60 (2026-07-01)
+
+Experimental Codewith durable-agent controller for long workflow steps.
+
+### Fixed
+
+- **Codewith executor:** run Codewith agent steps through the durable
+  `codewith agent start` background-agent lifecycle with rollout progress
+  recording into workflow step runs.
+
+Superseded in **0.4.9**: task-lifecycle and route workers now dispatch Codewith
+via non-interactive `codewith exec --json` because `agent start` reloaded
+multi-megabyte rollout history every turn and stalled workers with silent
+`context_length_exceeded` completions.
+
+## 0.3.59 (2026-07-01)
+
+Harden append-only workflow goal-wrapper migration.
+
+### Fixed
+
+- **`migrate-goal-wrappers`:** dry-run and apply paths now use compact migration
+  summaries, block retarget while a loop run is active, and route failures
+  through `cloneWorkflowWithoutGoalAndRetargetLoop` so only loops with both a
+  loop-level goal and a workflow-level top-level goal migrate.
+- **Store:** `cloneWorkflowWithoutGoalAndRetargetLoop` inserts a goal-free
+  workflow spec, retargets the loop, and optionally archives the old spec when
+  unreferenced — matching the append-only semantics of
+  `migrate-agent-timeouts`.
+
+## 0.3.58 (2026-07-01)
+
+Break nested workflow goal deadlocks and add a migration path.
+
+### Fixed
+
+- **Workflow loops — nested top-level goals:** a loop-level goal wrapping a
+  workflow that also defined a top-level `"goal"` deadlocked because each layer
+  waited on the other. New workflow loops that combine both wrappers are
+  rejected at creation; retargeting onto a dual-goal workflow is blocked. When
+  only a legacy dual-wrapper loop remains, the runner strips the workflow goal
+  for execution so the loop-level goal can drive orchestration.
+- **Workflow runner:** loop-level goals on workflow loops execute the underlying
+  workflow with the workflow-level goal removed when both were present.
+
+### Added
+
+- **`loops workflows migrate-goal-wrappers`:** append-only migrator that clones
+  a goal-free workflow spec and retargets eligible non-running workflow loops
+  that still carry redundant workflow-level goal wrappers alongside a loop-level
+  goal. Supports `--loop`, `--apply`, and `--archive-old` like
+  `migrate-agent-timeouts`.
+
 ## 0.3.x
 
 Compact history for the 0.3 line, newest first (`version (date) commit subject`).
 
-- 0.3.60 (2026-07-01) fix: run Codewith loops as durable agents
-- 0.3.59 (2026-07-01) fix: harden workflow goal migration
-- 0.3.58 (2026-07-01) fix: avoid nested workflow goal deadlocks
 - 0.3.57 (2026-07-01) feat: harden loop routing and add MCP server
 - 0.3.56 (2026-06-30) fix: allow worktree agents to write git metadata
 - 0.3.55 (2026-06-30) fix: agent workflow timeout policy

package/README.md

@@ -5,8 +5,14 @@ OpenLoops is a local CLI and daemon for persistent loops and workflows: schedule
 Naming: the product is **OpenLoops**, 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-runner`, and
-`loops-mcp`.
+binaries are `loops`, `loops-daemon`, `loops-api`, `loops-serve`,
+`loops-runner`, and `loops-mcp`.
+
+OpenLoops 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
+compiler handoff examples.
 
 It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
@@ -22,7 +28,14 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 OpenLoops has three deployment modes:
 
 - `local`: SQLite in `LOOPS_DATA_DIR` is authoritative and `loops-daemon` executes scheduled work.
-- `self_hosted`: a user-operated `loops-api` control plane contract. 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 remote apply are follow-up work.
+- `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 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.
 
 `local` is the default and requires no network, token, Postgres, or hosted
@@ -42,25 +55,33 @@ 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
 loops --json mode
 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
+loops import ./loops-export.json --apply
 loops cloud status
 loops-api status
+loops-serve version
+HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run
 loops-runner status
 ```
 
@@ -70,9 +91,10 @@ and machine-placement contract.
 ## Install
 
 **OpenLoops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
-`loops`, `loops-daemon`, `loops-api`, `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 runtime.
+`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
+runtime.
 
 From npm (with Bun installed):
 
@@ -311,6 +333,19 @@ 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
+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.
+
+Step-level goals inside workflow JSON remain valid. When a loop-level goal wraps
+a workflow that still carries a legacy top-level goal, the runner strips the
+workflow goal for that execution only; migrate away from the redundant wrapper
+with the append-only migrator (see **Workflows** below).
+
 ## Workflows
 
 Create a workflow JSON file:
@@ -380,13 +415,20 @@ 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
+[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.
 `event-worker-verifier` handles any Hasna event envelope and then verifies the
 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
@@ -421,6 +463,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:
@@ -440,22 +488,38 @@ worker finishes; pass `--verifier-idle-timeout none` or template variable
 `verifierIdleTimeoutMs=none` only when another heartbeat is guaranteed. Use a
 positive numeric `timeoutMs` only when an agentic step is intentionally bounded.
 
-To migrate existing workflow loops, do not edit `workflow_specs.steps_json`
-directly because historical workflow runs must keep pointing at their original
-spec. Use the append-only migrator:
+To migrate existing agentic loops, use the timeout migrator instead of editing
+the database directly. Workflow loops are migrated append-only because
+historical workflow runs must keep pointing at their original spec; direct
+agent loops selected with `--loop` update their stored target in place for
+future executions:
 
 ```bash
 loops workflows migrate-agent-timeouts --loop <loop-id-or-name>
 loops workflows migrate-agent-timeouts --loop <loop-id-or-name> --apply
+loops workflows migrate-goal-wrappers --loop <loop-id-or-name>
+loops workflows migrate-goal-wrappers --loop <loop-id-or-name> --apply
+loops workflows migrate-goal-wrappers --loop <loop-id-or-name> --apply --archive-old
 ```
 
-The command dry-runs by default. With `--apply`, it creates a new workflow spec
-with the requested agent timeout policy, retargets only future executions of
-eligible non-running workflow loops, and leaves terminal timed-out workflow runs
-as audit history. Use `loops workflows recover` only for interrupted `running`
-workflow runs whose recorded child process is gone; terminal `timed_out` runs
-must be requeued with `loops routes requeue <work-item-id> --reason "<cause fixed>"` before
-re-delivering or draining the original task/event route.
+Both migrators dry-run by default. For eligible non-running workflow loops,
+`--apply` creates a new workflow spec and retargets only future executions;
+historical workflow runs keep pointing at their original spec. For direct agent
+loops selected with `--loop`, `migrate-agent-timeouts --apply` updates the
+stored target in place for future executions. Use `--archive-old` to archive
+superseded workflow specs when no active loops still reference them.
+
+`migrate-agent-timeouts` clones the workflow with the requested agent timeout
+policy (`--timeout none` by default). `migrate-goal-wrappers` targets loops that
+define both a loop-level goal and a redundant workflow-level top-level goal: it
+clones a goal-free workflow spec, retargets the loop, and leaves the loop-level
+goal as the sole orchestration wrapper. Loops with only a workflow-level goal or
+only a loop-level goal are skipped.
+
+Use `loops workflows recover` only for interrupted `running` workflow runs
+whose recorded child process is gone; terminal `timed_out` runs must be
+requeued with `loops routes requeue <work-item-id> --reason "<cause fixed>"`
+before re-delivering or draining the original task/event route.
 
 ```json
 {
@@ -540,6 +604,9 @@ redispatch cap has not been reached. Operators can still force a retry with
 `loops routes requeue <work-item-id> --reason "<cause fixed>"`. The next
 route-created output records `requeue` evidence with the previous work item id,
 previous attempts, reason, new attempt, workflow id, and loop id.
+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
@@ -549,13 +616,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
 ```
 
@@ -634,6 +708,10 @@ 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
@@ -644,6 +722,22 @@ loops routes requeue <work-item-id> --reason "fixed upstream blocker"
 loops routes invocations
 ```
 
+Named route policies let operators create and inspect recurring task-drain
+routes without copying the full live command. Built-in policies are
+`repoops-pr-queue`, `oss`, `pilot`, and `machine-sync`:
+
+```bash
+loops routes policies render oss
+loops routes schedule todos-task machine-oss-task-lifecycle-router --policy oss
+```
+
+Scheduling with a policy stores explicit route drain args plus
+`--route-policy-evidence <id>` instead of replaying `--policy`, so audits can see
+the exact task list, filters, account pool, throttles, worktree mode, evidence
+directory, and name prefix used for future runs. The `pilot` policy is a manual
+break-glass lane using `danger-full-access`; applying it requires an explicit
+`--manual-break-glass`.
+
 For OSS task-created routing, use a deterministic drain instead of tmux
 dispatch:
 
@@ -663,21 +757,45 @@ 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 \
   --max-per-profile 2 \
+  --launch-gate "pa19-controlled-launch" \
+  --launch-gate-blocker "$HOME/workspace/example/opensource/open-codewith::2d9d931b" \
+  --launch-gate-blocker "$HOME/workspace/example/opensource/open-loops::816e99db" \
   --worktree-mode required \
   --evidence-dir "$HOME/.hasna/loops/reports/oss-task-route-drain" \
   --compact
 ```
 
+Use `--launch-gate-blocker <todos-project-path>::<task-id>` for staged
+launches where a scheduled drain must create zero worker loops until explicit
+blocker tasks are completed. While any blocker is still pending, in progress,
+failed, cancelled, missing, or unreadable, the drain fails closed before reading
+the ready queue, writes launch-gate evidence, and leaves source tasks untouched.
+Scheduled route drains preserve these gate flags in their stored argv.
+
 `--max-active` counts active routed workflows **per route**. Scope precedence:
 an explicit `--max-active-scope <key>` wins, else the running loop's
 `LOOPS_LOOP_NAME`, else the route key — so each router's limit is its own
 ceiling rather than a store-wide total shared by every router.
+Compact drain output includes route reservation IDs, work-item status,
+machine ID, workflow ID, loop ID, and route scope for each considered task.
 `--max-active-per-project` and `--max-active-per-project-group` remain cross-route
 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
+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
+--json` before creating workflow loops and defer when `activeRunCount >= n`.
+Add `--provider-admission-check` when drains should also fail closed on provider
+diagnostics failure, unsupported providers, or Codewith reports with no
+available admission slots. Backlog prioritizer and drain loops should use these
+first-class flags instead of shell-wrapping a temporary diagnostics guard.
+
 Only route tasks that explicitly opt in with `auto:route`, `route_enabled=true`,
 or `automation.allowed=true`. Use Codewith account pools, required worktrees,
 max-active throttles, and bounded evidence directories. Do not dispatch or paste
@@ -693,30 +811,25 @@ Workflow run manifests are written under
 
 ## OpenAutomations Runtime Binding
 
-OpenLoops can be used as an execution runtime for deterministic OpenAutomations
-product automations, but it does not own the automation product surface.
-`@hasna/automations` owns automation specs, trigger materialization, product
-automation action queues, DLQ/replay, idempotency, approvals, and audit
-evidence. OpenLoops owns agent workflow invocation/admission/runs. OpenLoops
-only executes work that OpenAutomations has explicitly handed off; it does not
-make OpenAutomations the queue owner for todos task/PR/review agent workflows.
+OpenLoops 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
+explicit event-envelope routing), todos-task route distinction, and
+anti-patterns.
 
-The SDK exposes the boundary descriptor:
+Quick reference:
 
 ```ts
 import { openAutomationsRuntimeBinding } from "@hasna/loops";
-
 const binding = openAutomationsRuntimeBinding();
-console.log(binding.handoff); // "claim-queue"
-console.log(binding.eventHandoff.handlerCommand); // "loops routes create generic"
+// binding.handoff === "claim-queue"
+// binding.eventHandoff.handlerCommand === "loops routes create generic"
 ```
 
-The claim-queue handoff uses the OpenAutomations CLI or SDK:
-
 ```bash
 automations queue claim --runner open-loops:<worker-id>
 automations queue complete <action-id> --runner open-loops:<worker-id>
-automations queue fail <action-id> --runner open-loops:<worker-id> --code <code> --message <message>
 ```
 
 For explicit event workflow routing, OpenAutomations can export the normalized
@@ -753,6 +866,12 @@ required semantics (dry-run/preflight/commit modes, `idempotencyKey` +
 are specified in `docs/AUTOMATION_RUNTIME_DESIGN.md`; this README intentionally
 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
+workflow, then returns workflow refs for action-owned evidence.
+
 The same design doc covers the planned DLQ/dead-letter lifecycle, including
 `loops dlq list/show/replay/resolve`, idempotent replay keys, and compatibility
 rules for `@hasna/actions`.
@@ -796,6 +915,9 @@ Use `--json` for machine-readable output. Prompt bodies and run stdout/stderr ar
 
 ```bash
 loops health --json
+loops health scan --include active,paused --latest-run --doctor --daemon --json
+loops health scan --include active,paused --latest-run --doctor --daemon \
+  --upsert-todos --dry-run --max-actions 5 --evidence-dir ~/.hasna/loops/reports/health-scan
 loops expectations <loop-id-or-name> --json
 loops health route-tasks --project ~/.hasna/loops --task-list loop-error-self-heal --max-actions 5
 loops hygiene names --json
@@ -810,6 +932,16 @@ mutating path: it upserts deduped Todos tasks for failed expectations and marks
 them with `no_tmux_dispatch=true` metadata. Use `--dry-run --json` before
 turning it into a production loop.
 
+`health scan` is the first-class replacement for local loop-error self-heal
+scripts. It inventories active/paused loops by default, can include doctor,
+daemon, preflight, latest-run, and stale-running findings, writes bounded
+`summary.json` and `report.md` files under
+`$LOOPS_DATA_DIR/reports/health-scan`, and prints compact human or stable JSON
+output. It is read-only unless `--upsert-todos` is supplied. The only built-in
+self-heal is `--start-daemon`, which attempts to start the daemon when status
+proves it is not running; it never stops, resumes, deletes, archives, or reaps
+loops.
+
 Add `--evidence-dir <dir>` to `health route-tasks` or `hygiene route-tasks`
 when the deterministic loop should write a durable JSON heartbeat/report in
 addition to loop stdout. Add `--auto-route` only for task lists that are
@@ -922,4 +1054,4 @@ The adapters intentionally use provider command surfaces instead of pretending e
 - `--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 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. Remote machine runs with a required worktree are verified fail-closed on the remote side before the target executes.
+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.

package/dist/api/index.d.ts

@@ -1,17 +1,53 @@
 #!/usr/bin/env bun
 import type { LoopStorageContract } from "../lib/storage/contract.js";
+/** The serve OpenAPI document (source of the generated SDK), version-synced. */
+export declare function openApiDocument(): Record<string, unknown>;
 export declare function apiStatus(): {
     ok: boolean;
     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;
+    }>;
+}
 export interface LoopsApiServerOptions {
     host?: string;
     port?: number;
     storage?: LoopStorageContract;
     bodyLimitBytes?: number;
     evidenceLimitBytes?: number;
+    importLimitBytes?: number;
     now?: () => Date;
+    /**
+     * 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
+     * the internet-facing auth path (no bearer token, no loopback bypass).
+     */
+    authenticator?: ApiAuthenticator;
+    /**
+     * Readiness probe. Should prove the storage backend is reachable AND fully
+     * migrated. Returns `{ ready, detail? }`. Defaults to a storage list probe.
+     */
+    readyCheck?: () => Promise<{
+        ready: boolean;
+        detail?: string;
+    }>;
 }
 export declare function createLoopsApiServer(opts?: LoopsApiServerOptions): Bun.Server<undefined>;
 export declare function main(argv?: string[]): Promise<void>;