@hasna/loops 0.4.12 → 0.4.13

package/dist/sdk/index.js

@@ -4266,7 +4266,7 @@ class Store {
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.12",
+  version: "0.4.13",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -4457,6 +4457,50 @@ function sourceOfTruthForMode(mode) {
     return "self_hosted_control_plane";
   return "cloud_control_plane";
 }
+var ROUTE_ADMISSION_GATES = [
+  "max_dispatch",
+  "max_active",
+  "max_active_per_project",
+  "max_active_per_project_group",
+  "max_active_scope",
+  "max_per_profile"
+];
+function remoteSchedulerBackendForMode(mode, config) {
+  if (mode === "local")
+    return "none";
+  if (mode === "cloud")
+    return config.cloudApiUrl ? "hosted_control_plane_contract" : "unconfigured";
+  if (config.databaseUrlPresent)
+    return "postgres_contract";
+  if (config.apiUrl)
+    return "api_control_plane_contract";
+  return "unconfigured";
+}
+function schedulerStateForMode(args) {
+  const nonLocal = args.deploymentMode !== "local";
+  return {
+    authority: args.sourceOfTruth,
+    localStore: {
+      backend: "sqlite",
+      role: args.localRole,
+      runArtifacts: "local_files",
+      routeAdmissionState: "workflow_work_items"
+    },
+    remoteStore: {
+      backend: remoteSchedulerBackendForMode(args.deploymentMode, args.config),
+      configured: nonLocal && args.controlPlaneConfigured,
+      applySupported: false,
+      objectArtifacts: nonLocal ? "object_store_contract" : "none",
+      mutatesAws: false
+    },
+    routeAdmission: {
+      stateStore: nonLocal ? "control_plane_contract" : "local_sqlite",
+      activeStatuses: ["admitted", "running"],
+      gates: ROUTE_ADMISSION_GATES,
+      dryRunEvaluatesLiveCounts: false
+    }
+  };
+}
 function displayControlPlaneUrl(value) {
   if (!value)
     return;
@@ -4482,6 +4526,9 @@ function buildDeploymentStatus(opts = {}) {
   if (deploymentMode === "self_hosted" && !controlPlaneConfigured) {
     warnings.push("self_hosted mode needs LOOPS_API_URL or LOOPS_DATABASE_URL before it can become authoritative");
   }
+  if (deploymentMode === "self_hosted" && config.databaseUrlPresent && !config.apiUrl) {
+    warnings.push("LOOPS_DATABASE_URL selects the self_hosted storage contract; loops-runner still needs LOOPS_API_URL to claim remote work");
+  }
   if (deploymentMode === "cloud" && config.apiUrl && !config.cloudApiUrl) {
     warnings.push("LOOPS_API_URL selects self_hosted; cloud mode uses LOOPS_CLOUD_API_URL");
   }
@@ -4515,6 +4562,13 @@ function buildDeploymentStatus(opts = {}) {
       required: deploymentMode !== "local",
       role: deploymentMode === "local" ? "daemon" : "control_plane_worker"
     },
+    schedulerState: schedulerStateForMode({
+      deploymentMode,
+      sourceOfTruth: sourceOfTruthForMode(deploymentMode),
+      localRole: deploymentMode === "local" ? "authoritative" : "cache_and_spool",
+      controlPlaneConfigured,
+      config
+    }),
     warnings
   };
 }
@@ -4527,6 +4581,7 @@ function deploymentStatusLine(status) {
     `source=${status.deploymentModeSource}`,
     `truth=${status.sourceOfTruth}`,
     `local=${status.localStore.role}`,
+    `scheduler=${status.schedulerState.routeAdmission.stateStore}`,
     `control_plane=${configured}`
   ].join(" ");
 }
@@ -5827,6 +5882,21 @@ function runDoctor(store) {
   checks.push(status.running ? { id: "daemon", status: "ok", message: `daemon is running pid=${status.pid}` } : { id: "daemon", status: status.stale ? "warn" : "ok", message: status.stale ? "daemon pid file is stale" : "daemon is not running" });
   const failedRuns = store.countRuns("failed");
   checks.push(failedRuns === 0 ? { id: "loop-runs", status: "ok", message: "no failed loop runs recorded" } : { id: "loop-runs", status: "warn", message: `${failedRuns} failed loop run(s) recorded` });
+  const deployment = buildDeploymentStatus();
+  const schedulerState = deployment.schedulerState;
+  checks.push({
+    id: "scheduler-state",
+    status: deployment.deploymentMode === "local" || deployment.controlPlane.configured ? "ok" : "warn",
+    message: `scheduler state authority=${schedulerState.authority} local=${schedulerState.localStore.role} remote=${schedulerState.remoteStore.backend}`,
+    detail: [
+      `route_state=${schedulerState.routeAdmission.stateStore}`,
+      `active_statuses=${schedulerState.routeAdmission.activeStatuses.join(",")}`,
+      `gates=${schedulerState.routeAdmission.gates.join(",")}`,
+      `artifacts=${schedulerState.localStore.runArtifacts}`,
+      `remote_artifacts=${schedulerState.remoteStore.objectArtifacts}`,
+      `remote_apply=${String(schedulerState.remoteStore.applySupported)}`
+    ].join(" ")
+  });
   for (const loop of store.listLoops({ status: "active" })) {
     try {
       if (loop.target.type === "workflow") {

package/docs/DEPLOYMENT_MODES.md

@@ -68,7 +68,7 @@ loops import ./loops-export.json --apply
 Human status output is intentionally compact:
 
 ```text
-deploymentMode=local active source=default truth=local_sqlite local=authoritative control_plane=none
+deploymentMode=local active source=default truth=local_sqlite local=authoritative scheduler=local_sqlite control_plane=none
 ```
 
 JSON uses these field names:
@@ -85,6 +85,22 @@ JSON uses these field names:
   presence signal.
 - `controlPlane.apiUrl`: a display-safe URL without credentials, query string,
   or fragment.
+- `schedulerState.localStore`: always names the local SQLite store and local
+  run artifact files. In `local` mode this store is authoritative; in
+  non-local modes it is a cache, offline spool, and audit copy.
+- `schedulerState.remoteStore`: names the remote scheduler contract:
+  `api_control_plane_contract`, `postgres_contract`,
+  `hosted_control_plane_contract`, `unconfigured`, or `none`. Remote apply is
+  `false` in this public package until a control-plane host wires a full
+  storage adapter.
+- `schedulerState.remoteStore.objectArtifacts`: `object_store_contract` means
+  remote artifact/object storage is a control-plane contract. The public package
+  does not create or mutate S3 buckets, AWS resources, or hosted credentials.
+- `schedulerState.routeAdmission`: names the active route-state store and the
+  bounded gates (`max_dispatch`, `max_active`, `max_active_per_project`,
+  `max_active_per_project_group`, `max_active_scope`, and `max_per_profile`).
+  Live active counts use admitted/running work items; dry-runs do not open or
+  migrate the live store to compute counts.
 
 `loops-api` is a separate process in the same public package. It is not a
 separate package at this stage because self-hosted users and the hosted service
@@ -150,6 +166,12 @@ would generate new ids, so it is not a no-loss migration. Local SQLite remains
 authoritative until a safe import is applied; in non-local modes it may remain
 a cache, offline spool, and audit copy.
 
+`LOOPS_DATABASE_URL` selects the self-hosted Postgres scheduler-state contract,
+but it does not make the standalone CLI mutate a remote database by itself.
+Remote execution still flows through a configured control-plane API and runner
+protocol. `loops-runner` needs `LOOPS_API_URL` or `HASNA_LOOPS_API_URL` to claim
+work; a database URL alone is migration/readiness configuration.
+
 `loops self-hosted runner-register` is also preview-only unless `--apply` is
 present. The dry run prints the runner id, machine id, labels, and
 capabilities that would be posted, without exposing tokens.

package/docs/USAGE.md

@@ -25,6 +25,16 @@ planes:
   status only, and requires `LOOPS_CLOUD_API_URL` plus `LOOPS_CLOUD_TOKEN` or
   `HASNA_LOOPS_CLOUD_TOKEN` before status can report ready.
 
+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
@@ -674,11 +684,12 @@ idempotency key before rendering worktree plans or checking route limits. In
 dry-run mode, throttle counts are not evaluated because opening the live loop
 store can create or migrate the local database.
 Terminal routed work items such as failed, dead-letter, cancelled, or succeeded
-history remain deduped until an operator runs `loops routes requeue
-<work-item-id> --reason "<cause fixed>"`; a later drain should not create
-another worker just because the previous workflow ended. 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.
+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.
 
 When a sandboxed Codewith/Codex worker must update app stores outside the repo
 worktree, pass those stores explicitly with `--add-dir` or template `addDirs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",