@hasna/loops 0.4.0 → 0.4.2

package/dist/sdk/index.js

@@ -1203,7 +1203,7 @@ function discardWorkflowRunManifest(staged) {
 var DEFAULT_RECOVERY_BATCH_LIMIT = 100;
 var DEFAULT_RECOVERY_SCAN_MULTIPLIER = 5;
 var LIVE_EXPIRED_RUN_GRACE_MS = 60000;
-var SCHEMA_USER_VERSION = 6;
+var SCHEMA_USER_VERSION = 7;
 var TERMINAL_RUN_STATUSES = ["succeeded", "failed", "timed_out", "abandoned", "skipped"];
 var PRUNE_BATCH_SIZE = 400;
 var GENERATED_ROUTE_TEMPLATE_IDS = new Set(["todos-task-worker-verifier", "task-lifecycle", "event-worker-verifier"]);
@@ -1573,6 +1573,13 @@ class Store {
           this.addColumnIfMissing("loop_runs", "pgid", "INTEGER");
           this.addColumnIfMissing("loop_runs", "process_started_at", "TEXT");
         }
+      },
+      {
+        id: "0007_run_claim_tokens",
+        apply: () => {
+          this.addColumnIfMissing("loop_runs", "claim_token", "TEXT");
+          this.db.exec("CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL");
+        }
       }
     ];
   }
@@ -1614,6 +1621,7 @@ class Store {
         started_at TEXT,
         finished_at TEXT,
         claimed_by TEXT,
+        claim_token TEXT,
         lease_expires_at TEXT,
         pid INTEGER,
         pgid INTEGER,
@@ -1632,6 +1640,7 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_runs_status ON loop_runs(status);
       CREATE INDEX IF NOT EXISTS idx_runs_status_lease ON loop_runs(status, lease_expires_at);
       CREATE INDEX IF NOT EXISTS idx_runs_scheduled ON loop_runs(scheduled_for);
+      CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL;
 
       CREATE TABLE IF NOT EXISTS daemon_lease (
         id TEXT PRIMARY KEY,
@@ -3503,6 +3512,7 @@ class Store {
   }
   claimRun(loop, scheduledFor, runnerId, now = new Date, opts = {}) {
     const startedAt = now.toISOString();
+    const claimToken = opts.claimToken ?? genId();
     this.db.exec("BEGIN IMMEDIATE");
     try {
       this.assertDaemonLeaseFence(opts, startedAt);
@@ -3525,12 +3535,13 @@ class Store {
             return;
           }
           const res3 = this.db.query(`UPDATE loop_runs SET status='running', started_at=$started, finished_at=NULL,
-               claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
+               claimed_by=$claimedBy, claim_token=$claimToken, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
                duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
                WHERE id=$id AND status='running' AND lease_expires_at <= $now`).run({
             $id: existing.id,
             $started: startedAt,
             $claimedBy: runnerId,
+            $claimToken: claimToken,
             $lease: leaseExpiresAt,
             $updated: startedAt,
             $now: startedAt
@@ -3539,7 +3550,7 @@ class Store {
           if (res3.changes !== 1)
             return;
           const run3 = this.getRun(existing.id);
-          return run3 ? { run: run3, loop } : undefined;
+          return run3 ? { run: run3, loop, claimToken } : undefined;
         }
         if (existing.status === "succeeded" || existing.status === "skipped") {
           this.db.exec("COMMIT");
@@ -3547,7 +3558,7 @@ class Store {
         }
         const attempt = existing.attempt + 1;
         const res2 = this.db.query(`UPDATE loop_runs SET attempt=$attempt, status='running', started_at=$started, finished_at=NULL,
-             claimed_by=$claimedBy, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
+             claimed_by=$claimedBy, claim_token=$claimToken, lease_expires_at=$lease, pid=NULL, pgid=NULL, process_started_at=NULL, exit_code=NULL,
              duration_ms=NULL, stdout=NULL, stderr=NULL, error=NULL, updated_at=$updated
              WHERE id=$id
                AND status IN ('failed', 'timed_out', 'abandoned')
@@ -3556,6 +3567,7 @@ class Store {
           $attempt: attempt,
           $started: startedAt,
           $claimedBy: runnerId,
+          $claimToken: claimToken,
           $lease: leaseExpiresAt,
           $updated: startedAt,
           $maxAttempts: loop.maxAttempts
@@ -3564,12 +3576,12 @@ class Store {
         if (res2.changes !== 1)
           return;
         const run2 = this.getRun(existing.id);
-        return run2 ? { run: run2, loop } : undefined;
+        return run2 ? { run: run2, loop, claimToken } : undefined;
       }
       const id = genId();
       const res = this.db.query(`INSERT OR IGNORE INTO loop_runs (id, loop_id, loop_name, scheduled_for, attempt, status, started_at, finished_at,
-            claimed_by, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
-           VALUES ($id, $loopId, $loopName, $scheduledFor, 1, 'running', $started, NULL, $claimedBy, $lease,
+            claimed_by, claim_token, lease_expires_at, pid, exit_code, duration_ms, stdout, stderr, error, created_at, updated_at)
+           VALUES ($id, $loopId, $loopName, $scheduledFor, 1, 'running', $started, NULL, $claimedBy, $claimToken, $lease,
             NULL, NULL, NULL, NULL, NULL, NULL, $created, $updated)`).run({
         $id: id,
         $loopId: loop.id,
@@ -3577,6 +3589,7 @@ class Store {
         $scheduledFor: scheduledFor,
         $started: startedAt,
         $claimedBy: runnerId,
+        $claimToken: claimToken,
         $lease: leaseExpiresAt,
         $created: startedAt,
         $updated: startedAt
@@ -3585,7 +3598,7 @@ class Store {
       if (res.changes !== 1)
         return;
       const run = this.getRun(id);
-      return run ? { run, loop } : undefined;
+      return run ? { run, loop, claimToken } : undefined;
     } catch (error) {
       try {
         this.db.exec("ROLLBACK");
@@ -3608,16 +3621,18 @@ class Store {
       $error: error ?? null,
       $updated: finishedAt,
       $claimedBy: opts.claimedBy ?? null,
+      $claimToken: opts.claimToken ?? null,
       $now: (opts.now ?? new Date).toISOString(),
       $daemonLeaseId: opts.daemonLeaseId ?? null
     };
     return this.transact(() => {
-      const res = opts.claimedBy ? this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+      const res = opts.claimedBy ? this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, claim_token=NULL, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
                duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated
                WHERE id=$id AND status='running' AND claimed_by=$claimedBy AND lease_expires_at > $now
+                 AND ($claimToken IS NULL OR claim_token=$claimToken)
                  AND ($daemonLeaseId IS NULL OR EXISTS (
                    SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
-                 ))`).run(params) : this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
+                 ))`).run(params) : this.db.query(`UPDATE loop_runs SET status=$status, finished_at=$finished, claim_token=NULL, lease_expires_at=NULL, pid=$pid, exit_code=$exitCode,
                duration_ms=$durationMs, stdout=$stdout, stderr=$stderr, error=$error, updated_at=$updated WHERE id=$id`).run(params);
       const run = this.getRun(id);
       if (!run)
@@ -3645,11 +3660,13 @@ class Store {
     const expiresAt = new Date(now.getTime() + leaseMs).toISOString();
     const res = this.db.query(`UPDATE loop_runs SET lease_expires_at=$expires, updated_at=$updated
          WHERE id=$id AND status='running' AND claimed_by=$claimedBy AND lease_expires_at > $now
+           AND ($claimToken IS NULL OR claim_token=$claimToken)
            AND ($daemonLeaseId IS NULL OR EXISTS (
              SELECT 1 FROM daemon_lease WHERE id=$daemonLeaseId AND expires_at > $now
            ))`).run({
       $id: id,
       $claimedBy: claimedBy,
+      $claimToken: opts.claimToken ?? null,
       $expires: expiresAt,
       $updated: now.toISOString(),
       $now: now.toISOString(),
@@ -5544,11 +5561,12 @@ function publicLoop(loop) {
     target
   };
 }
-function publicRun(run, showOutput = false) {
+function publicRun(run, showOutput = false, opts = {}) {
   return {
     ...run,
     stdout: showOutput ? run.stdout : run.stdout ? `[redacted ${run.stdout.length} chars]` : undefined,
-    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined
+    stderr: showOutput ? run.stderr : run.stderr ? `[redacted ${run.stderr.length} chars]` : undefined,
+    error: opts.redactError ? redact(run.error) : run.error
   };
 }
 function publicExecutorResult(result, showOutput = false) {
@@ -7417,15 +7435,15 @@ function openAutomationsRuntimeBinding(overrides = {}) {
     failCommand: "automations queue fail",
     eventHandoff: {
       envelopeCommand: "automations webhooks event",
-      handlerCommand: "loops events handle generic",
-      pipeExample: "automations --json webhooks event <route> --body-json '<json>' | loops --json events handle generic",
+      handlerCommand: "loops routes create generic",
+      pipeExample: "automations --json webhooks event <route> --body-json '<json>' | loops --json routes create generic",
       boundary: "Use only for explicit event-envelope workflow handoff. OpenAutomations still owns deterministic automation materialization and queue state; OpenLoops owns workflow invocation."
     },
     requiredEnvironment: ["HASNA_AUTOMATIONS_DIR"],
     guarantees: [
       "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 events handle commands.",
+      "OpenLoops may consume exported event envelopes only through explicit routes create commands.",
       "Workers must complete or fail actions by action id and runner id so OpenAutomations can enforce queue leases."
     ],
     nonGoals: [

package/dist/types.d.ts

@@ -55,7 +55,7 @@ export interface OpenAutomationsRuntimeBinding {
     failCommand: "automations queue fail";
     eventHandoff: {
         envelopeCommand: "automations webhooks event";
-        handlerCommand: "loops events handle generic";
+        handlerCommand: "loops routes create generic";
         pipeExample: string;
         boundary: string;
     };

package/docs/DEPLOYMENT_MODES.md

@@ -0,0 +1,148 @@
+# OpenLoops Deployment Modes
+
+OpenLoops supports one active source of truth at a time. The public package
+defines the mode vocabulary, local cache behavior, API shape, and runner
+contract. Hosted multi-tenant operation is implemented outside this public
+package.
+
+## 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 |
+| `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.
+
+`cloud` is the hosted control-plane contract. The public package exposes the
+client and runner contract, but tenant auth, account administration, and hosted
+infrastructure stay outside this package. The public package must not depend on
+private hosted packages or resource names. This release exposes status
+surfaces only; non-local claim/lease execution is follow-up work.
+
+## Mode Resolution
+
+`LOOPS_MODE` or `HASNA_LOOPS_MODE` may be set to `local`, `self_hosted`, or
+`cloud`. Hyphenated `self-hosted` is normalized to `self_hosted`.
+
+When no explicit mode is set, OpenLoops resolves the mode from configuration:
+
+1. `LOOPS_CLOUD_API_URL` or `HASNA_LOOPS_CLOUD_API_URL` selects `cloud`.
+2. `LOOPS_API_URL`, `HASNA_LOOPS_API_URL`, `LOOPS_DATABASE_URL`, or
+   `HASNA_LOOPS_DATABASE_URL` selects `self_hosted`.
+3. Otherwise OpenLoops uses `local`.
+
+`LOOPS_API_URL` and `HASNA_LOOPS_API_URL` belong to `self_hosted`.
+`cloud` uses only `LOOPS_CLOUD_API_URL` or `HASNA_LOOPS_CLOUD_API_URL`.
+
+Tokens are represented only as presence signals in status output. Self-hosted
+status uses `LOOPS_API_TOKEN` or `HASNA_LOOPS_API_TOKEN`. Cloud status uses
+`LOOPS_CLOUD_TOKEN` or `HASNA_LOOPS_CLOUD_TOKEN`. URL credentials, query
+strings, and fragments are not returned in status output.
+
+## Commands
+
+```bash
+loops mode
+loops --json mode
+loops self-hosted status
+loops cloud status
+loops-api status
+loops-runner status
+```
+
+Human status output is intentionally compact:
+
+```text
+deploymentMode=local active source=default truth=local_sqlite local=authoritative control_plane=none
+```
+
+JSON uses these field names:
+
+- `deploymentMode`: the requested status perspective.
+- `activeDeploymentMode`: the mode selected from the current environment.
+- `deploymentModeSource`: the env var or default that selected the active mode.
+- `sourceOfTruth`: `local_sqlite`, `self_hosted_control_plane`, or
+  `cloud_control_plane`.
+- `localStore.role`: `authoritative` in local mode, `cache_and_spool` in
+  non-local modes.
+- `controlPlane.configured`: true only when the current mode has enough
+  configuration to be usable. Cloud requires both a cloud URL and a cloud token
+  presence signal.
+- `controlPlane.apiUrl`: a display-safe URL without credentials, query string,
+  or fragment.
+
+`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-runner` is the process that connects a machine to a non-local control
+plane. The current public package supports a bounded one-shot protocol:
+registration, claim polling, claim-token fenced heartbeat/finalization, and
+`loops-runner run-once` execution for non-workflow targets. Full fleet daemon
+mode, workflow target execution over the remote protocol, and import/export
+migration still need follow-up releases before `loops-runner` is advertised as
+a complete always-on worker.
+
+## Machine Placement
+
+A loop can eventually target:
+
+- one specific machine,
+- a machine pool selected by capability labels,
+- or multiple machines intentionally.
+
+Single-run loops need a lease so only one runner executes each scheduled slot.
+Multi-machine loops must record per-machine run evidence so duplicate work is
+distinguishable from intentional fan-out.
+
+This is separate from existing local OpenMachines dispatch. In `local` mode,
+`loops-daemon` can still dispatch a loop target to a configured remote machine
+through the existing OpenMachines transport. In `self_hosted` or `cloud`,
+machine execution is runner-pull: a registered `loops-runner` claims work from
+the control plane. Operators should not treat local remote dispatch as cloud
+mode.
+
+## Follow-Up Work
+
+Non-local execution needs these follow-up releases before it is live:
+
+- 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.
+- Import/export migration between local SQLite state and a control plane.
+- Hosted product integration outside the public package.
+
+## Public Package Boundary
+
+The public package owns:
+
+- local SQLite scheduling and daemon execution,
+- the mode resolver and status surfaces,
+- the self-hosted API contract,
+- the runner contract,
+- local cache/spool semantics,
+- import/export and migration commands,
+- SDK, MCP, and CLI primitives.
+
+Hosted product code owns:
+
+- tenant account management,
+- hosted authentication and invitations,
+- hosted observability and admin operations,
+- cloud infrastructure deployment,
+- product UI and customer lifecycle flows.
+
+The public package must document cloud behavior as a contract unless a hosted
+URL and token are explicitly configured. It must not claim that cloud service is
+live by default.

package/docs/USAGE.md

@@ -11,8 +11,36 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 - `opencode run`
 - `codex exec`
 
+## Deployment Modes
+
+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:
+
+- `self_hosted`: user-operated `loops-api` control-plane contract; this
+  release exposes API/runner status foundations only.
+- `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.
+
+Useful status commands:
+
+```bash
+loops mode
+loops --json mode
+loops self-hosted status
+loops cloud status
+loops-api status
+loops-runner status
+```
+
 ## 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.
+
 From npm:
 
 ```bash
@@ -57,8 +85,9 @@ The package also exports the server factory for embedded hosts:
 import { createLoopsMcpServer } from "@hasna/loops/mcp";
 ```
 
-Available read tools include `loops_list`, `loops_show`, `loop_runs`,
-`loops_doctor`, `workflows_list`, `workflow_read`, and `workflow_validate`.
+Available read tools include `loops_list`, `loops_show`, `loops_runs`,
+`loops_doctor`, `loops_workflows_list`, `loops_workflow_read`, and
+`loops_workflow_validate`.
 Resources are available at `loops://runtime` and `loops://tools`.
 Those tools use the same `Store`, public redaction helpers, and workflow parser
 as the CLI and SDK, so read output and validation behavior stay aligned across
@@ -66,15 +95,19 @@ surfaces.
 
 Mutation tools are disabled by default. Start the server with
 `LOOPS_MCP_ALLOW_MUTATIONS=true` only for a trusted local MCP host that should be
-allowed to change loop state. Even then, mutation tools require exact
-confirmation strings: `loop_pause`, `loop_resume`, `loop_run_now`,
-`loop_create_command`, and `loop_create_workflow`. MCP `loop_run_now` schedules
-the loop for immediate daemon pickup; inline execution remains CLI-only.
+allowed to change loop state. The guarded mutation tools use canonical names:
+`loops_pause`, `loops_resume`, `loops_stop`, `loops_run_now`, `loops_archive`,
+`loops_unarchive`, `loops_create_command`, and `loops_create_workflow`.
+Deprecated `loop_*` aliases are still registered where compatibility needs them,
+but callers should use the `loops_*` names. Mutation tools do not require or
+accept confirmation-string parameters; the server-side environment opt-in is the
+gate. MCP `loops_run_now` schedules the loop for immediate daemon pickup; inline
+execution remains CLI-only.
 
 Keep host-affecting or long-running operations on the CLI: daemon
-start/stop/install/logs, inline `run-now`, `tick`, loop removal/archive
-maintenance, workflow create/migrate/cancel/recover, agent loop creation,
-template materialization, and event-route drains.
+start/stop/install/logs, inline `run-now`, `tick`, loop deletion, workflow
+create/migrate/cancel/recover, agent loop creation, template materialization,
+and event-route drains.
 
 ## Create Loops
 
@@ -95,8 +128,8 @@ loops create command repo-status \
 ```
 
 `--preflight` is available on `loops create command`, `loops create agent`,
-`loops create workflow`, `loops workflows create`, and event-router commands such
-as `loops events handle todos-task` and `loops events handle generic`. It checks
+`loops create workflow`, `loops workflows create`, and route commands such as
+`loops routes create todos-task` and `loops routes create generic`. It checks
 target executables and configured account profiles before loop or workflow rows
 are stored, so a missing command, provider binary, OpenAccounts profile, native
 Codewith auth profile, or workflow step dependency fails without creating a
@@ -340,11 +373,11 @@ loops templates render todos-task-worker-verifier \
   --var taskTitle="Fix parser" \
   --var projectPath=/path/to/repo \
   --var provider=codewith \
-  --var authProfilePool=account004,account005,account006 \
+  --var authProfilePool=account001,account002,account003 \
   --var sandbox=workspace-write \
   --var todosProjectPath=$HOME/.hasna/loops \
   --var addDirs=$HOME/.hasna/todos,$HOME/.hasna/loops
-loops templates create-workflow todos-task-worker-verifier \
+loops workflows create --template todos-task-worker-verifier \
   --var taskId=<task-id> \
   --var projectPath=/path/to/repo
 loops templates render event-worker-verifier \
@@ -357,7 +390,7 @@ loops templates render bounded-agent-worker-verifier \
   --var objective="Check docs drift and queue tasks for gaps" \
   --var projectPath=/path/to/repo \
   --var provider=codewith \
-  --var authProfilePool=account004,account005 \
+  --var authProfilePool=account001,account002 \
   --var sandbox=workspace-write
 loops templates render pr-review \
   --var prUrl=https://github.com/hasna/loops/pull/123 \
@@ -441,14 +474,15 @@ loops templates show custom-report
 loops templates render custom-report \
   --var objective="Check docs drift" \
   --var projectPath=/path/to/repo
-loops templates create-workflow custom-report \
+loops workflows create --template custom-report \
   --var objective="Check docs drift" \
   --var projectPath=/path/to/repo
 ```
 
 Use `--source builtin`, `--source custom`, or `--source all` on
-`list`, `show`, `render`, and `create-workflow` when automation needs an
-explicit source. Custom template ids and names cannot override built-ins.
+`templates list`, `templates show`, `templates render`, and
+`workflows create --template` when automation needs an explicit source. Custom
+template ids and names cannot override built-ins.
 Custom templates fail closed for `danger-full-access`, dangerous passthrough
 arguments, and implicit Codewith/Codex full-access defaults. If a custom
 Codewith/Codex template uses `permissionMode: "bypass"`, it must also set
@@ -491,16 +525,16 @@ PR review and merge route workers may fetch, rebase, or merge base branches
 inside the isolated worktree when the task requires it, but they must not
 mutate the primary main checkout.
 
-For event-driven task automation, `loops events handle todos-task` reads a
+For event-driven task automation, `loops routes create todos-task` reads a
 Hasna event envelope from stdin or `HASNA_EVENT_JSON`, records a
 `WorkflowInvocation`, upserts an admission work item, and admits that work item
 into a deduped one-shot workflow loop when route capacity allows:
 
 ```bash
-cat task-created-event.json | loops events handle todos-task \
+cat task-created-event.json | loops routes create todos-task \
   --template task-lifecycle \
   --provider codewith \
-  --auth-profile-pool account004,account005,account006 \
+  --auth-profile-pool account001,account002,account003 \
   --permission-mode bypass \
   --sandbox workspace-write \
   --todos-project "$HOME/.hasna/loops" \
@@ -530,7 +564,7 @@ selected.
 loops routes drain todos-task \
   --dry-run \
   --provider-rule area=frontend:claude:claude-ui-a,claude-ui-b \
-  --provider-rule area=backend:codewith:account004,account005 \
+  --provider-rule area=backend:codewith:account001,account002 \
   --worktree-mode required
 ```
 
@@ -568,9 +602,9 @@ Use route throttles to avoid stampeding agents when a producer creates many
 tasks at once:
 
 ```bash
-cat task-created-event.json | loops events handle todos-task \
+cat task-created-event.json | loops routes create todos-task \
   --provider codewith \
-  --auth-profile-pool account004,account005,account006 \
+  --auth-profile-pool account001,account002,account003 \
   --project-group oss \
   --max-active-per-project 1 \
   --max-active-per-project-group 4 \
@@ -633,14 +667,14 @@ hand. It scans `todos ready --json`, so tasks with incomplete dependencies,
 locks, or non-pending states stay queued in todos and are not routed:
 
 ```bash
-loops events drain todos-task \
+loops routes drain todos-task \
   --todos-project "$HOME/.hasna/loops" \
   --template task-lifecycle \
   --task-list repoops-pr-queue \
   --tags auto:route \
-  --project-path-prefix /home/hasna/workspace/hasna/opensource \
+  --project-path-prefix "$HOME/workspace/example/opensource" \
   --provider codewith \
-  --auth-profile-pool account004,account005,account006 \
+  --auth-profile-pool account001,account002,account003 \
   --add-dir "$HOME/.hasna/todos,$HOME/.hasna/loops" \
   --project-group oss \
   --max-dispatch 2 \
@@ -665,17 +699,17 @@ 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.
 
-For the Hasna OSS task-created route, keep the drain deterministic and narrow:
+For an OSS task-created route, keep the drain deterministic and narrow:
 
 ```bash
 loops routes schedule todos-task oss-task-route-drain \
   --every 5m \
   --todos-project "$HOME/.hasna/loops" \
   --template task-lifecycle \
-  --project-path-prefix /home/hasna/workspace/hasna/opensource \
+  --project-path-prefix "$HOME/workspace/example/opensource" \
   --tags auto:route \
   --provider codewith \
-  --auth-profile-pool account004,account005,account006 \
+  --auth-profile-pool account001,account002,account003 \
   --add-dir "$HOME/.hasna/todos,$HOME/.hasna/loops" \
   --project-group oss \
   --max-dispatch 2 \
@@ -688,7 +722,7 @@ loops routes schedule todos-task oss-task-route-drain \
   --compact
 ```
 
-Only tasks under `/home/hasna/workspace/hasna/opensource` that explicitly opt
+Only tasks under `$HOME/workspace/example/opensource` that explicitly opt
 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
@@ -709,9 +743,9 @@ For other Hasna apps that expose `@hasna/events` webhooks, use the generic
 handler:
 
 ```bash
-cat event.json | loops events handle generic \
+cat event.json | loops routes create generic \
   --provider codewith \
-  --auth-profile-pool account004,account005,account006 \
+  --auth-profile-pool account001,account002,account003 \
   --permission-mode bypass \
   --sandbox workspace-write \
   --project-path /path/to/repo \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",
@@ -8,6 +8,8 @@
   "bin": {
     "loops": "dist/cli/index.js",
     "loops-daemon": "dist/daemon/index.js",
+    "loops-api": "dist/api/index.js",
+    "loops-runner": "dist/runner/index.js",
     "loops-mcp": "dist/mcp/index.js"
   },
   "exports": {
@@ -23,9 +25,37 @@
       "types": "./dist/mcp/index.d.ts",
       "import": "./dist/mcp/index.js"
     },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "import": "./dist/runner/index.js"
+    },
+    "./mode": {
+      "types": "./dist/lib/mode.d.ts",
+      "import": "./dist/lib/mode.js"
+    },
     "./storage": {
       "types": "./dist/lib/store.d.ts",
       "import": "./dist/lib/store.js"
+    },
+    "./storage/contract": {
+      "types": "./dist/lib/storage/contract.d.ts",
+      "import": "./dist/lib/storage/contract.js"
+    },
+    "./storage/sqlite": {
+      "types": "./dist/lib/storage/sqlite.d.ts",
+      "import": "./dist/lib/storage/sqlite.js"
+    },
+    "./storage/postgres": {
+      "types": "./dist/lib/storage/postgres.d.ts",
+      "import": "./dist/lib/storage/postgres.js"
+    },
+    "./storage/postgres-schema": {
+      "types": "./dist/lib/storage/postgres-schema.d.ts",
+      "import": "./dist/lib/storage/postgres-schema.js"
     }
   },
   "files": [
@@ -36,14 +66,15 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "test:boundary": "bun run scripts/no-private-cloud-boundary.mjs",
     "prepare": "test -d dist || bun run build",
     "dev:cli": "bun run src/cli/index.ts",
     "dev:daemon": "bun run src/daemon/index.ts",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run build && bun run test:boundary"
   },
   "keywords": [
     "loops",