@hasna/loops 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -5,6 +5,59 @@ documented in this file. Version entries are generated from the
 conventional-commit git history; one commit maps to one released patch version
 unless noted.
 
+## 0.4.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
+directly (no handoff artifact — the cursor pattern) now complete instead of
+failing the pr-handoff step and skipping the verifier.
+
+### Fixed
+
+- **pr-handoff — no-artifact/direct-PR path exited 1 instead of 0:** the step
+  runs as `bash -lc` (a login shell). The no-artifact guard ended with an
+  explicit `exit 0` while `set -e` was active; under systemd (`SHLVL` unset →
+  bash sets 1) an explicit exit sources `~/.bash_logout`, whose `clear_console`
+  fails without a controlling TTY, and errexit handed that failure back as the
+  step's exit code. The workflow failed, the verifier (which depends on
+  pr-handoff) was skipped, and the source task was stranded `in_progress`.
+  Both guard branches now route through bun heredocs and fall through the `if`'s
+  natural end — no top-level shell `exit` — so the intended status is preserved
+  on the local and remote execution paths alike (gate steps already ended
+  naturally, which is why only pr-handoff failed). (#34)
+
+### Added
+
+- **Worker-opened PR detection on the no-artifact path:** when no handoff
+  artifact exists, pr-handoff now looks up the worker's own open PR for the
+  workflow branch (`gh pr list --head <branch> --state open`), records the same
+  `openloops:pr-handoff=done task=… pr=… commit=… branch=…` comment the
+  artifact path records, and exits 0 — so direct-PR (cursor-style) completions
+  carry PR evidence into the verifier and merge lane. Best-effort and
+  fail-open on lookup: a missing PR or a `gh`/`git`/`todos` error is logged,
+  writes no done-evidence, and never fails the step. The artifact (codewith)
+  handoff path is unchanged. (#34)
+
 ## 0.4.12 (2026-07-05)
 
 Drain throughput: `--max-active` is now a per-route ceiling instead of a
@@ -445,13 +498,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

@@ -38,6 +38,16 @@ 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`.
 
+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`.
+
 Useful status commands:
 
 ```bash
@@ -301,6 +311,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:
@@ -430,22 +453,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
-```
-
-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.
+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
+```
+
+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
 {
@@ -524,11 +563,12 @@ workflow unless the event data or metadata has `route_enabled=true`,
 `automation.allowed=true`, or a task tag containing `auto:route`. It also skips
 blocked, completed/done, cancelled/canceled, failed, archived, manual,
 approval-required, or `no-auto` tasks. Terminal route work items such as
-failed, dead-letter, cancelled, or succeeded history stay deduped until an
-operator runs `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, operator reason, new attempt, workflow id, and loop
-id.
+failed, dead-letter, cancelled, or succeeded history are re-admitted only when
+the todos task is still actionable, the per-attempt backoff has elapsed, and the
+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.
 
 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
@@ -785,6 +825,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
@@ -799,6 +842,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

package/dist/api/index.d.ts

@@ -1,10 +1,30 @@
 #!/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;
@@ -12,6 +32,21 @@ export interface LoopsApiServerOptions {
     bodyLimitBytes?: number;
     evidenceLimitBytes?: 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>;