@hasna/loops 0.4.27 → 0.4.29

package/dist/types.d.ts

@@ -2,6 +2,12 @@ import type { GoalSpec } from "./lib/goal/types.js";
 export type { Goal, GoalAutoExecute, GoalExecutorResult, GoalPlan, GoalPlanNode, GoalPlanNodeStatus, GoalPlanStatus, GoalRollup, GoalRun, GoalSpec, GoalStatus, } from "./lib/goal/types.js";
 export type LoopStatus = "active" | "paused" | "stopped" | "expired";
 export type RunStatus = "running" | "succeeded" | "failed" | "timed_out" | "abandoned" | "skipped";
+export interface RecoveredLeaseRunSnapshotEntry {
+    updatedAt: string;
+    scheduledFor: string;
+    id: string;
+    attempt: number;
+}
 export type CatchUpPolicy = "none" | "latest" | "all";
 export type OverlapPolicy = "skip" | "allow";
 export type IntervalAnchor = "fixed_rate" | "fixed_delay";
@@ -80,10 +86,13 @@ export type AgentProvider = "claude" | "cursor" | "codewith" | "aicopilot" | "op
 export type AgentConfigIsolation = "safe" | "none";
 export type AgentPermissionMode = "default" | "plan" | "auto" | "bypass";
 export type AgentSandbox = "read-only" | "workspace-write" | "danger-full-access" | "enabled" | "disabled";
+export type AgentAllowlistEnforcement = "metadata_only";
 export interface AgentAllowlistSpec {
+    /** Advisory provider metadata. Restrictions require this non-empty audit reason. */
     tools?: string[];
     commands?: string[];
-    enforcement?: "metadata_only";
+    enforcement?: AgentAllowlistEnforcement;
+    safetyReason?: string;
 }
 export type AgentWorktreeMode = "auto" | "required" | "off" | "main";
 export interface AgentWorktreeSpec {
@@ -108,6 +117,25 @@ export interface AgentRoutingSpec {
      *  for per-account attribution and least-loaded auth-profile pool selection. */
     role?: "triage" | "planner" | "worker" | "verifier";
 }
+/** Server-derived audit contract for an agent step inside a workflow run. */
+export interface AgentSessionContract {
+    version: 1;
+    provider: AgentProvider;
+    model?: string;
+    cwd?: string;
+    permissionMode: AgentPermissionMode;
+    sandbox: AgentSandbox | "provider-default";
+    manualBreakGlass: boolean;
+    routing?: AgentRoutingSpec;
+    timeoutMs: TimeoutMs;
+    restrictions: {
+        tools?: string[];
+        commands?: string[];
+        enforcement: AgentAllowlistEnforcement;
+        providerEnforced: false;
+    };
+    safetyReason?: string;
+}
 export interface AgentPromptSource {
     type: "file";
     path: string;
@@ -120,6 +148,11 @@ export interface AgentTargetBase {
     variant?: string;
     agent?: string;
     authProfile?: string;
+    /**
+     * Provider CLI passthrough arguments. Fail-closed: omitted or empty is valid,
+     * while every non-empty or malformed entry is rejected until that exact
+     * provider option is explicitly reviewed and allowlisted by the adapter.
+     */
     extraArgs?: string[];
     addDirs?: string[];
     timeoutMs?: TimeoutMs;
@@ -127,6 +160,8 @@ export interface AgentTargetBase {
     configIsolation?: AgentConfigIsolation;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
+    /** Explicit operator acknowledgement required with a non-empty safetyReason for relaxed sandbox or provider bypass modes. */
+    manualBreakGlass?: boolean;
     allowlist?: AgentAllowlistSpec;
     worktree?: AgentWorktreeSpec;
     routing?: AgentRoutingSpec;
@@ -223,6 +258,16 @@ export interface WorkflowWorkItem {
     priority: number;
     status: WorkflowWorkItemStatus;
     attempts: number;
+    /**
+     * Consecutive non-productive "gate death" finishes (runs that failed at
+     * worktree prep or a fast triage/planner gate before any real work). Gate
+     * deaths refund their redispatch attempt, so this second counter bounds a
+     * deterministic infrastructure fault: at the ceiling the item is
+     * dead-lettered instead of retrying forever. Reset by a run that reaches
+     * the worker (success, productive failure, or tempfail) and by an
+     * operator requeue with attempts reset.
+     */
+    gateDeaths: number;
     nextAttemptAt?: string;
     leaseExpiresAt?: string;
     workflowId?: string;
@@ -233,6 +278,7 @@ export interface WorkflowWorkItem {
     updatedAt: string;
 }
 export interface UpsertWorkflowWorkItemInput {
+    id?: string;
     routeKey: string;
     idempotencyKey: string;
     invocationId: string;
@@ -339,19 +385,44 @@ export interface WorkflowStepRun {
     createdAt: string;
     updatedAt: string;
 }
-export interface WorkflowEvent {
+export type WorkflowLifecycleEventType = "created" | "workflow_archived" | "todos_workflow_pointers_synced" | "todos_workflow_pointers_sync_failed" | "step_started" | "step_progress" | "recovered" | "step_pending" | "step_running" | "step_succeeded" | "step_failed" | "step_timed_out" | "step_skipped" | "step_cancelled" | "succeeded" | "failed" | "timed_out" | "cancelled";
+export interface WorkflowEventBase {
     id: string;
     workflowRunId: string;
     sequence: number;
-    eventType: string;
     stepId?: string;
     payload?: Record<string, unknown>;
     createdAt: string;
 }
+/** Raw persisted event shape used inside storage adapters before public validation. */
+export interface StoredWorkflowEvent extends WorkflowEventBase {
+    eventType: string;
+}
+export interface GenericWorkflowEvent extends WorkflowEventBase {
+    eventType: WorkflowLifecycleEventType;
+}
+export interface AgentSessionContractWorkflowEvent extends Omit<WorkflowEventBase, "stepId" | "payload"> {
+    eventType: "agent_session_contract";
+    stepId: string;
+    payload: AgentSessionContract;
+}
+/**
+ * Backwards-compatible public shape for historical or mixed-version custom
+ * events. `eventKind` makes the generic branch unambiguous without weakening
+ * the schemas of server-owned lifecycle and agent-session-contract events.
+ */
+export interface CustomWorkflowEvent extends WorkflowEventBase {
+    eventKind: "custom";
+    eventType: string;
+}
+export type WorkflowEvent = AgentSessionContractWorkflowEvent | GenericWorkflowEvent;
+export type PublicWorkflowEvent = WorkflowEvent | CustomWorkflowEvent;
 export interface Loop {
     id: string;
     name: string;
     description?: string;
+    /** Persisted loop labels. Legacy in-memory fixtures may omit this; stores normalize it to an empty array. */
+    labels?: string[];
     status: LoopStatus;
     archivedAt?: string;
     archivedFromStatus?: LoopStatus;
@@ -446,6 +517,7 @@ export interface WriteRunReceiptInput {
 export interface CreateLoopInput {
     name: string;
     description?: string;
+    labels?: string[];
     schedule: ScheduleSpec;
     target: LoopTargetInput;
     goal?: GoalSpec;

package/docs/AUTOMATION_RUNTIME_DESIGN.md

@@ -1,10 +1,10 @@
 # Automation Runtime Design
 
-OpenLoops can execute workflow work that external automation systems have
+Loops can execute workflow work that external automation systems have
 already materialized, but it must not become the automation product surface.
 `@hasna/automations` and `@hasna/actions` own automation specs, trigger
 materialization, queue state, approvals, DLQ/replay, idempotency, and audit
-evidence. OpenLoops owns workflow invocation, admission, execution, run
+evidence. Loops owns workflow invocation, admission, execution, run
 manifests, and provider routing once work is explicitly handed off.
 
 For operator-facing ownership tables, handoff path examples, and anti-patterns,
@@ -12,7 +12,7 @@ see [Runtime Boundary](./RUNTIME_BOUNDARY.md).
 
 ## Planned Workflow Upsert SDK
 
-External compilers should not write OpenLoops SQLite rows directly. The stable
+External compilers should not 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.
 
@@ -63,7 +63,7 @@ type WorkflowUpsertResult = {
 Required semantics:
 
 - `mode="dry-run"` validates, canonicalizes, hashes, and returns the same JSON
-  shape without mutating OpenLoops state.
+  shape without mutating Loops state.
 - `mode="preflight"` additionally checks provider binaries, machine routing,
   accounts/auth profiles, prompt files, and workflow target compatibility before
   commit.
@@ -81,8 +81,8 @@ Required semantics:
 
 `@hasna/actions` now exposes typed action contracts: `ActionManifest`,
 `ActionInvocation`, `ActionRun`, `ActionRunStatus`, `ActionQueueStatus`,
-`ActionAuditEvent`, `EvidenceRef`, and `ActionDeadLetter`. A future OpenLoops
-action binding must reuse those contracts instead of adding an OpenLoops-owned
+`ActionAuditEvent`, `EvidenceRef`, and `ActionDeadLetter`. A future Loops
+action binding must reuse those contracts instead of adding a Loops-owned
 action status, action queue, or idempotency dialect.
 
 The binding should be a workflow-admission descriptor, not a direct executor in
@@ -124,14 +124,14 @@ The planned implementation path is:
    support, idempotency requirement, guardrails, audit fields, evidence fields,
    and rollback policy using `@hasna/actions`.
 2. The action owner passes only a normalized `ActionTargetBindingRequest` or
-   `WorkflowUpsertRequest` to OpenLoops. Large inputs, private prompts, secret
+   `WorkflowUpsertRequest` to Loops. Large inputs, private prompts, secret
    values, and mutable action state stay in the action store or a referenced
    artifact.
-3. OpenLoops admits a one-shot workflow loop through the planned upsert
+3. Loops admits a one-shot workflow loop through the planned upsert
    contract, records workflow/run/manifests refs, and reports those refs back to
    the action owner.
 4. The action owner records `ActionAuditEvent` and `EvidenceRef` entries that
-   include the returned OpenLoops refs. OpenLoops may store source refs for
+   include the returned Loops refs. Loops may store source refs for
    lookup, but `@hasna/actions` remains the source of truth for action runs and
    queue state.
 
@@ -160,36 +160,36 @@ const request: WorkflowUpsertRequest = {
 };
 ```
 
-`specHash` must be computed from the canonical OpenLoops workflow request plus
+`specHash` must be computed from the canonical Loops workflow request plus
 the stable action contract identity: action id, manifest version, idempotency
 key or invocation id, selected executor binding kind/ref, route policy, and
 execution policy. It must not include raw secret values, raw credentials, or
 unredacted prompt bodies. If `@hasna/actions` later publishes its own manifest
-hash, OpenLoops should include that hash instead of re-hashing action internals.
+hash, Loops should include that hash instead of re-hashing action internals.
 
 `WorkflowUpsertResult` keeps its existing semantics:
 
 - `idempotencyKey` is the action-owned idempotency key selected above.
-- `specHash` identifies the exact OpenLoops workflow admission request and
+- `specHash` identifies the exact Loops workflow admission request and
   action contract identity that produced it.
 - `refs.workflowId`, `refs.loopId`, `refs.invocationId`, `refs.workItemId`,
-  `refs.runId`, and `refs.manifestPath` are OpenLoops refs that the action
+  `refs.runId`, and `refs.manifestPath` are Loops refs that the action
   owner can store as `EvidenceRef` or audit event data.
-- `action="created" | "updated" | "reused" | "rejected"` describes OpenLoops
+- `action="created" | "updated" | "reused" | "rejected"` describes Loops
   materialization only. It is not an action run status.
 - Action run fields such as `status`, `dedupedFromRunId`, `evidence`, `events`,
   and `error` remain on `ActionRun`.
 
 ### Status Translation
 
-OpenLoops should translate its workflow and work-item state into action-owned
+Loops should translate its workflow and work-item state into action-owned
 status updates without persisting a new action status enum.
 
 Recommended initial translation:
 
 - An accepted dry-run/preflight maps to an `ActionRun` that remains
   `planned`, `previewed`, or `awaiting_approval` according to
-  `@hasna/actions`; OpenLoops only returns preflight details.
+  `@hasna/actions`; Loops only returns preflight details.
 - A scheduled workflow maps to action queue status `queued` or
   `waiting_approval`, depending on action-owned approval gates.
 - A claimed/running workflow maps to action queue status `claimed` and action
@@ -202,8 +202,8 @@ Recommended initial translation:
 - Operator cancellation maps to action queue status `cancelled` and action run
   status `cancelled`.
 
-These mappings are adapter behavior. OpenLoops should expose its own workflow
-statuses for OpenLoops APIs and should call or return enough refs for
+These mappings are adapter behavior. Loops should expose its own workflow
+statuses for Loops APIs and should call or return enough refs for
 `@hasna/actions` to update `ActionRun`, `ActionQueueStatus`, audit events, and
 dead-letter records.
 
@@ -212,19 +212,19 @@ dead-letter records.
 Failure handling must flow through action-owned APIs:
 
 - Provider, worktree, account, policy, and command failures are classified by
-  OpenLoops and returned as redacted workflow error evidence.
+  Loops and returned as redacted workflow error evidence.
 - The action owner turns those failures into `ActionError`,
   `ActionDeadLetter`, `ActionAuditEvent`, and `EvidenceRef` records.
 - Replay starts from an action-owned replay decision and a new action-owned
-  idempotency key. OpenLoops then receives a new upsert request whose
+  idempotency key. Loops then receives a new upsert request whose
   `source.dedupeKey` and `idempotencyKey` are the replay keys.
-- OpenLoops DLQ commands may mirror or inspect linked workflow failures, but
+- Loops DLQ commands may mirror or inspect linked workflow failures, but
   they must not fabricate action queue entries or mark an action replayable on
   their own.
 
 ### Mode And Dispatch Examples
 
-Dry-run without OpenLoops mutation:
+Dry-run without Loops mutation:
 
 ```bash
 actions run deploy.manifest.json \
@@ -282,9 +282,9 @@ loops workflows upsert-one-shot deploy-workflow.json \
 
 ### Non-Goals
 
-- Do not let `@hasna/actions` write OpenLoops SQLite/Postgres rows directly.
-- Do not duplicate the action queue in OpenLoops.
-- Do not materialize triggers in OpenLoops; action and automation owners decide
+- Do not let `@hasna/actions` write Loops SQLite/Postgres rows directly.
+- Do not duplicate the action queue in Loops.
+- Do not materialize triggers in Loops; action and automation owners decide
   when a concrete invocation exists.
 - Do not store secret values, unredacted prompts, credentials, or private
   action input payloads in workflow specs, prompts, manifests, task comments,
@@ -421,7 +421,7 @@ Required check domains:
   result.
 - `connector`: ask the owning action/connector system whether the connector
   credential handle exists, is scoped for the source action, and is usable; do
-  not make OpenLoops the connector credential store.
+  not make Loops the connector credential store.
 - `permissions`: reject unsafe `permissionMode="bypass"`, unsafe
   `configIsolation="none"`, mutable command targets without an explicit policy,
   or missing approval evidence when strict automation requires it.
@@ -463,7 +463,7 @@ worktrees for repo mutation, missing prompt files, and machine route mismatch.
 ## Planned Compact Evidence API
 
 Every public surface should expose the same compact evidence shape so callers
-can hand results across `@hasna/actions`, `@hasna/automations`, OpenLoops route
+can hand results across `@hasna/actions`, `@hasna/automations`, Loops route
 drains, MCP tools, and CLI scripts without scraping SQLite or leaking secrets.
 
 ```ts
@@ -515,7 +515,7 @@ Persistence and output rules:
   work item, and owning external action/automation refs through public APIs.
 - Failed preflight evidence should be persistable when a commit attempt is
   rejected, but pure `dry-run`/`preflight` calls should return it directly
-  without creating OpenLoops database rows.
+  without creating Loops database rows.
 - Redaction happens before persistence and before API return. Tests should
   exercise both flat secret-looking text and nested JSON evidence values.
 
@@ -548,7 +548,7 @@ secret-safe without depending on ambient shell state.
 `execution.mode="strict"` means:
 
 - Do not inherit full `process.env`. Start from a minimal runtime environment:
-  `PATH`, `HOME`, `TMPDIR`, locale keys, OpenLoops metadata keys, and tool
+  `PATH`, `HOME`, `TMPDIR`, locale keys, Loops metadata keys, and tool
   config dirs explicitly produced by account/secret resolution.
 - Pass only named `envAllowlist` values and `secretRefs`; never embed secret
   values in workflow specs, prompts, metadata, manifests, or task comments.
@@ -600,7 +600,7 @@ enforcement surface is missing.
 
 ## Planned DLQ And Replay
 
-OpenLoops already models terminal route work items and has a manual
+Loops already models terminal route work items and has a manual
 `routes requeue` command. The automation runtime contract needs a stricter DLQ
 layer for exhausted side-effecting work, because external action systems need to
 distinguish "failed attempt", "dead until operator action", and "resolved".
@@ -615,7 +615,7 @@ Route work items should keep these meanings:
   as unsafe to retry without operator action.
 - `cancelled`: an operator or owner intentionally stopped the work.
 - `succeeded`: the work completed and remains deduped history.
-- `resolved`: planned external DLQ state for `@hasna/actions`; OpenLoops can
+- `resolved`: planned external DLQ state for `@hasna/actions`; Loops can
   mirror it as `dead_letter` plus a resolution event until a first-class status
   is added.
 
@@ -648,7 +648,7 @@ provider code; it only records why the DLQ entry no longer needs execution.
 - Replay of side-effecting work should default to `mode=preflight`; promotion
   to `mode=commit` is a separate operator/API decision unless the owning
   `@hasna/actions` policy marks the action safely replayable.
-- If `@hasna/actions` owns the queue, OpenLoops calls the action replay API and
+- If `@hasna/actions` owns the queue, Loops calls the action replay API and
   stores the returned action/run refs instead of fabricating queue state.
 
 ### Dead-Letter Classification

package/docs/CUTOVER-RUNBOOK.md

@@ -5,16 +5,14 @@ complete.** Do not flip scheduled production execution away from local SQLite
 until the runner and migration follow-ups below are green.
 
 Deployment vocabulary: `self_hosted` is the Hasna-owned AWS/RDS control-plane
-deployment. `cloud` is the future hosted SaaS contract for outside users. The
-vendored `@hasna/contracts` storage kit still calls direct Postgres storage
-mode `cloud`; treat that as a storage-kit implementation term, not the
-OpenLoops deployment mode.
+deployment. `cloud` is the future hosted SaaS contract for outside users.
 
 ## What Shipped
 
 - `loops-serve` HTTP control plane: RDS-direct Postgres, `GET /health`,
   `/ready`, `/version`, `/openapi.json`, storage-backed `/v1` loop CRUD and run
-  listing, and runner registration/claim/heartbeat/finalize protocol routes.
+  listing, and runner claim/lease heartbeat/finalize protocol routes. Durable
+  runner registration remains a cutover gate and is not advertised as a route.
 - `@hasna/contracts` API-key auth on non-local `loops-serve` binds, backed by
   the shared `api_keys` table and a signing secret.
 - Full `PostgresLoopStorage` behind `LoopStorageContract`, plus
@@ -23,7 +21,7 @@ OpenLoops deployment mode.
   and ensures the `api_keys` table.
 - `@hasna/loops/sdk/http`, generated from `openapi/loops.json`.
 - ARM64/Bun `Dockerfile`, local `docker-compose.yml`, `hasna.contract.json`,
-  and a generated `migrations/` mirror for review.
+  generated storage kit, and a generated `migrations/` mirror for review.
 
 ## Local Postgres Smoke For loops-serve
 
@@ -37,42 +35,171 @@ curl -fsS http://127.0.0.1:8787/ready
 curl -fsS http://127.0.0.1:8787/openapi.json
 ```
 
-`loops-serve` may bind to loopback without an API signing secret for local
-development. A non-local bind must set `HASNA_LOOPS_API_SIGNING_KEY`,
-`HASNA_API_SIGNING_KEY`, or `API_KEY_SIGNING_SECRET`; otherwise the service
-fails closed before exposing `/v1`.
+`loops-serve` always requires `HASNA_LOOPS_API_SIGNING_KEY`. There is no
+loopback authentication bypass.
 
 ## AWS Self-Hosted Gates
 
-1. Apply migrations with the ECS one-shot task or an operator command:
-   `HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run`, then
-   `HASNA_LOOPS_DATABASE_URL=... loops-serve migrate`.
-2. Start `loops-serve` with `HASNA_LOOPS_MODE=self_hosted`,
-   `HASNA_LOOPS_DATABASE_URL`, and the API signing secret from the approved
-   vault item. Do not log or copy the secret value into task evidence.
-3. Verify `/health`, `/ready`, `/version`, and `/openapi.json`.
-4. Verify an authenticated `/v1` read/write smoke against a throwaway loop and
-   a runner registration/claim/finalize smoke if a runner API URL is configured.
-5. Record package version, git SHA, image tag, database migration plan/result,
-   redacted API URL, health/readiness responses, and rollback handle.
+Before step 1, satisfy and preserve evidence for these hard gates:
+
+- For the shared `apps` to dedicated `loops` database transfer lane, use only
+  the selective logical transfer in `docs/SHARED-DATABASE-TRANSFER.md`. Do not
+  snapshot-restore the shared cluster or shared database into the dedicated
+  Loops target. The protected workflow may start only the fixed
+  `bun dist/serve/index.js shared-to-dedicated-transfer` ECS command, with DSNs
+  supplied by ECS task secrets.
+- Use a dedicated Loops PostgreSQL cluster, not only a dedicated database.
+  PostgreSQL roles are cluster-global: inventory every database, role
+  membership, database owner, and `pg_shdepend` row for the four reserved
+  `open_loops_*` roles. The enforcement preflight fails if a reserved role owns
+  another database or has a cross-database dependency. No reserved role may be
+  `LOGIN`; the command fails closed instead of silently detaching a credential.
+- Prove recovery before mutation. Confirm PITR is inside its retention window,
+  identify the exact pre-cutover recovery point, and complete an isolated
+  restore rehearsal from that point. Record the recovery point, restored
+  database identifier, verification command/results, elapsed restore time, and
+  cleanup result. Backup configuration without a successful restore is not
+  sufficient evidence.
+- Enter a maintenance window before the first non-dry-run migration. Stop new
+  API writes, drain in-flight work, stop every service/runner that can write the
+  database, and verify no non-operator sessions or open write transactions
+  remain. Run exactly one migrator. The binary also takes a transaction-scoped
+  advisory lock and recomputes the ledger plan after acquiring it, but the lock
+  does not replace application quiescence.
+
+1. Provision the four NOLOGIN database roles and the separate enforcement
+   login. Tenant enforcement must run through a
+   provider-level bootstrap administrator against a dedicated Loops
+   database owned by that bootstrap login (or use a true superuser). Do not run enforcement in a database shared with another
+   application: migration `0010` normalizes ACLs across every non-system
+   schema, table, sequence, and function in the current database. `CREATEROLE`, control of the
+   `public` schema, and the ability to `SET ROLE` to `open_loops_owner` and
+   `open_loops_migrator` are minimum requirements. With PostgreSQL 16's default
+   `createrole_self_grant=''`, a non-superuser must use four pre-provisioned,
+   already-normalized Loops roles and must have only direct owner/migrator
+   memberships with `ADMIN FALSE`, `INHERIT TRUE`, and `SET TRUE`. It must not
+   be a member of the runtime or authenticator roles. No LOGIN role may inherit
+   runtime or authenticator yet; attach service credentials only after `0010`
+   succeeds. Creating the roles as the
+   non-superuser is not sufficient: PostgreSQL adds an implicit `ADMIN TRUE`,
+   `INHERIT FALSE`, `SET FALSE` creator row that only a superuser can revoke.
+   The command transactionally exercises and rolls back the exact membership,
+   `SET ROLE`, migration-ledger ownership/write, ACL, and service-login cleanup
+   operations before migration `0010`; static role flags are not accepted as
+   proof. Provider/bootstrap identities are never passed to `DROP OWNED`, and
+   unsafe LOGIN memberships fail closed instead of being silently detached.
+   After enforcement, the runtime and authenticator service logins must be
+   members only of their matching roles, granted with `ADMIN FALSE`, `INHERIT
+   TRUE`, and `SET TRUE`.
+   Never reuse the bootstrap DSN in `loops-serve`.
+2. Prepare the tenant schema with the ECS one-shot task or an operator command:
+   `HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve migrate --dry-run`, then
+   `HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve migrate`.
+3. In ECS, load the reviewed explicit ownership bundle with the fixed,
+   no-argument command
+   `HASNA_LOOPS_MIGRATOR_DATABASE_URL=... HASNA_LOOPS_BACKFILL_BUCKET=... AWS_REGION=... loops-serve tenant-backfill-s3`.
+   The task role must expose only a valid
+   `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`. The bucket must contain exactly one
+   object under `approved/`, named `approved/sha256-<64 lowercase hex>.json`,
+   and no more than 10 MiB. The command verifies the raw-byte digest before
+   parsing, loads transactionally, deletes the selected object on success or
+   failure, and treats deletion failure as fatal. Record its bounded digest and
+   counts log only. For a local operator rehearsal, the compatible file command
+   remains `HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve tenant-backfill --input <bundle>`.
+   Before delivery, require named operator approval of tenant, principal,
+   membership, API-key, and row-owner counts; compute and record the bundle's
+   SHA-256; and transfer it only through the approved encrypted artifact path.
+   For local file delivery only, verify the hash and restrictive file
+   permissions before use, then remove the staged artifact after the
+   transaction and evidence capture complete. Record only the hash, counts,
+   approver, and bounded command result—never bundle contents or credentials.
+4. Enforce tenant keys, composite foreign keys, and forced RLS with
+   `HASNA_LOOPS_MIGRATOR_DATABASE_URL=... loops-serve migrate --enforce-tenancy`.
+   After this succeeds, have provider automation attach the runtime and
+   authenticator logins to their matching roles; do not reuse the enforcement
+   login for either service.
+   Keep the write plane quiesced while validating migration-ledger ownership,
+   exact role memberships, forced RLS, runtime/authenticator connection safety,
+   and `/ready`. If any gate fails, keep the service stopped and use the
+   rehearsed recovery procedure; do not continue from a partially understood
+   state.
+5. Build and deploy an image from this repository's pinned Bun base-image
+   digest. The runner image must pass the CI high/critical vulnerability scan
+   and must not replace the locked `@hasna/contracts` package with a vendored
+   overlay.
+6. Configure the ECS service before traffic is shifted:
+   - desired count at least `2`;
+   - tasks spread across at least two private subnets/AZs;
+   - capacity provider strategy with an on-demand Fargate base of at least one
+     task before any Spot capacity;
+   - deployment circuit breaker with rollback enabled;
+   - ALB target group health check path `/ready`;
+   - CloudWatch log retention at least 30 days with KMS encryption;
+   - alarm actions wired to the approved incident notification target.
+7. Store runtime values in Secrets Manager or the approved vault surface:
+   `HASNA_LOOPS_DATABASE_URL`, `HASNA_LOOPS_AUTH_DATABASE_URL`,
+   `HASNA_LOOPS_MIGRATOR_DATABASE_URL`, and
+   `HASNA_LOOPS_API_SIGNING_KEY`. Enable rotation for the signing secret and
+   database credentials where the provider supports it. Do not put secret values
+   in task definitions, task comments, logs, or rollout evidence.
+8. When provider-managed RDS credentials are used, run
+   `loops-serve db-credentials reconcile` from the in-cluster task role before
+   starting the service. Required inputs are secret ARNs and expected RDS
+   metadata only, not secret values. The command reads the RDS-managed master
+   secret through AWS Secrets Manager, writes app DSNs through `AWSPENDING`,
+   changes each login password transactionally, verifies a fresh
+   `sslmode=verify-full` connection, and promotes `AWSCURRENT` only after the
+   fresh connection succeeds. It logs only bounded status metadata. Before
+   migration `0010_tenant_enforce`, runtime/authenticator logins remain detached;
+   after `0010`, they attach only to their matching NOLOGIN roles.
+9. Wire minimum alarms before cutover: ALB unhealthy hosts, ALB 5xx, ALB target
+   latency, ECS running count below desired count, ECS task exits, RDS CPU,
+   RDS connections, RDS free storage, and log error-rate/auth-anomaly signals.
+10. Start `loops-serve` with `HASNA_LOOPS_STORAGE_MODE=self_hosted`, separate
+   `HASNA_LOOPS_DATABASE_URL` and `HASNA_LOOPS_AUTH_DATABASE_URL` logins, and the API signing secret from the approved
+   vault item. The signing key must be at least 16 bytes. Do not log or copy the
+   secret value into task evidence.
+11. Verify `/health`, `/ready`, `/version`, and `/openapi.json`.
+12. Verify an authenticated `/v1` read/write smoke against a throwaway loop and
+   a claim/finalize smoke if a runner API URL is configured.
+13. Record package version, git SHA, image tag and digest, database migration
+   plan/result, evidence that the target database is dedicated to Loops,
+   redacted API URL, health/readiness responses, capacity-provider strategy,
+   desired/running task counts, alarm action ARNs/names, log retention/KMS
+   identifiers, rotation status, and rollback handle.
 
 ## Still Pending Before Daemon Cutover
 
 - Long-running `loops-runner` daemon mode with backoff, fleet observability, and
   durable machine registration records.
-- Workflow target execution over the runner protocol.
-- Id-preserving self-hosted import endpoints for workflow specs, loop
-  definitions, run history, workflow history, work items, goals, and audit rows.
-- A no-loss migration path from local SQLite into the self-hosted control plane.
-  Current `loops export`/`loops import` are local-store tools, and
-  `loops self-hosted migrate|push|pull` remain previews.
+- Id-preserving self-hosted import coverage for run history, workflow history,
+  work items, goals, and audit rows.
+- A full-history no-loss migration path from local SQLite into the self-hosted
+  control plane. Current `loops export`/`loops import` and
+  `loops self-hosted push --apply` cover workflow specs and loop definitions
+  with safe paused/archived defaults; they intentionally block unsupported live
+  history.
 - Hosted SaaS integration outside this public package.
 
 ## Rollback
 
-For the self-hosted service, roll back by moving traffic to the previous image
-or stopping the new `loops-serve` task. Local scheduled execution remains on
-SQLite unless operators explicitly configure a runner/control-plane cutover, so
-removing `LOOPS_API_URL`, `HASNA_LOOPS_API_URL`, `LOOPS_DATABASE_URL`, or
+Before migration `0010_tenant_enforce` is applied, an image-only rollback may
+redeploy the previous digest or shift the ALB target group to the previous
+service revision, provided its migration checksum contract still matches the
+database. After `0010` succeeds, do not point a previous image at the enforced
+database: the `c506685e` base carries the superseded `0010` checksum and the
+published `0.4.28` image has no `0008`-`0010`, so neither can pass readiness
+against this schema.
+
+Post-`0010`, either roll forward with a schema-compatible image, or restore the
+rehearsed pre-cutover PITR point to a separate database target. For the restore
+path, repoint the previous service revision's runtime/auth credentials and
+endpoint to that separate target, verify the restored migration ledger and
+expected row counts, then prove the previous image's `/ready`, authenticated
+loop CRUD, runner claim/finalize, and
+`loops self-hosted push --dry-run --no-runs`. Never attempt an in-place reverse
+migration or overwrite the enforced database during rollback.
+Local scheduled execution remains on SQLite unless operators explicitly
+configure a runner/control-plane cutover, so removing `HASNA_LOOPS_API_URL` and
 `HASNA_LOOPS_DATABASE_URL` returns the standalone CLI/daemon perspective to
 `local`.