@hasna/loops 0.3.60 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog
+
+All notable changes to OpenLoops (npm `@hasna/loops`, repo `hasna/loops`) are
+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.0 (2026-07-02)
+
+Audit-hardening release: write-path secret scrubbing, process-group reaping,
+gated schema migrations, storage garbage collection, and a consolidated
+CLI/MCP/SDK surface with deprecation aliases.
+
+### Security
+
+- Write-path secret scrubbing (`src/lib/redact.ts`): persisted run/step
+  errors, goal evidence, raw model responses, and run envelopes pass through
+  `scrubSecrets`/`scrubSecretsDeep` before storage. Recognized credential
+  shapes — Anthropic `sk-ant-*`, OpenAI `sk-proj-*`, AWS `AKIA*`, GitHub
+  `ghp_*`/`github_pat_*`, Slack `xox?-*`, PEM private key blocks, and generic
+  `KEY="..."` assignments with high-entropy values — are replaced with
+  `[SCRUBBED]`. Scrubbing is idempotent and bounded for large (256KB+)
+  payloads.
+- MCP shell removal: `loops_create_command` now takes a structured
+  `command` + `args` argv only. The former `shell` boolean is rejected
+  (schema `z.never()`) instead of being silently stripped — shell loops
+  remain a human decision via the CLI. Mutation tools stay double-gated
+  behind `LOOPS_MCP_ALLOW_MUTATIONS=true` plus per-call confirmation.
+- Archived-loop guards centralized in the store: `updateLoop` throws a coded
+  `LoopArchivedError` for archived loops (except the explicit unarchive
+  path), so CLI, MCP, SDK, daemon, and scheduler all share one enforcement
+  point instead of per-surface checks.
+- Executor-enforced git worktrees: when a target carries worktree metadata,
+  the executor prepares/verifies and enters the worktree before spawning the
+  child (locally and on remote machine dispatch), records the entered
+  worktree, and `worktreeMode=required` fails closed instead of falling back
+  to the original checkout.
+- Coded error classes (`src/lib/errors.ts`): `LoopNotFoundError`,
+  `LoopArchivedError`, `AmbiguousNameError`, `ValidationError`, each with a
+  stable `.code` so callers branch on codes instead of message text.
+
+### Reliability
+
+- Run lease re-acquisition: runners heartbeat their lease
+  (`heartbeatRunLease`, every `leaseMs/3` capped at 60s) and the store
+  records the child process identity (`recordRunProcess` with pid/pgid/
+  process start fingerprint) so recovery can tell live runs from dead ones.
+- Orphan reaping: after startup and periodic lease recovery, the daemon
+  signals the process groups of abandoned runs (SIGTERM, then SIGKILL after
+  a grace period) using the pid/pgid + start-time fingerprints returned by
+  `recoverExpiredRunLeases`; unfingerprinted pids are never trusted or
+  signaled.
+- Retry backoff with jitter: exponential
+  `retryDelayMs * 2^(attempt-1) * (0.5 + random)`, capped at 6h;
+  rate-limit/auth failures back off 4x harder.
+- Circuit breaker: after 5 consecutive final failures (default,
+  configurable/disableable) the loop auto-pauses with a health-visible
+  skipped marker run explaining the trip; `loops resume` re-arms it and
+  requires a fresh failure streak before tripping again.
+- Default idle watchdog for agent targets: agent runs that set neither
+  `timeoutMs` nor `idleTimeoutMs` now time out after 30 minutes without
+  observable progress (4 hours for buffered agents); override with
+  `idleTimeoutMs` or `LOOPS_AGENT_IDLE_TIMEOUT_MS`. Timeouts kill the
+  child's entire process group, not just the direct child.
+- Daemon logging: every line is timestamped `[ISO8601] [loops-daemon] ...`,
+  and `daemon.log` rotates at 50MB.
+
+### Storage
+
+- Gated schema migrations: migrations are tracked in `schema_migrations` and
+  the database stamps `PRAGMA user_version` (now 6). Older 0.4.x+ binaries
+  refuse to open a newer database instead of silently misreading it;
+  baseline 0.3.x migrations are re-applied idempotently to converge drifted
+  databases (including the known live fork with orphan
+  `loops.metadata_json`/`loop_runs.source` columns).
+- `Store.pruneHistory({ maxAgeDays?, keepPerLoop?, dryRun? })` deletes old
+  terminal run history in bounded batches and returns a deletion summary;
+  exposed as the new `loops gc` command (dry-run by default, `--apply` to
+  execute) which also rotates database backups, checkpoints the WAL, and
+  removes stray temp files.
+- Online backups via `VACUUM INTO` (`src/lib/backup.ts`):
+  `backupDatabase({ reason, keep = 3 })` with a per-reason 1h debounce and
+  retention pruning; destructive CLI operations (rename, name-hygiene apply)
+  snapshot the database first.
+- Bounded run envelopes (`src/lib/run-envelope.ts`): persisted stdout/stderr
+  excerpts are capped (2048 chars per excerpt) and scrubbed, keeping run
+  rows small and secret-free.
+- Time-sortable ids: `genId()` now returns a 128-bit ULID-like id — 48-bit
+  millisecond timestamp prefix + 80 random bits, 32 lowercase hex chars —
+  so primary keys sort by creation time while staying compatible with
+  existing TEXT keys.
+
+### CLI / MCP / SDK
+
+- CLI: new `loops gc`; `routes` is the canonical event-routing surface.
+  Deprecated aliases retained for one release cycle: `loops events
+  handle|drain ...` (use `loops routes create|drain`), `loops templates
+  create` (use `loops workflows create --template <id>`), and `loops goal
+  status` (merged into `loops goal show`). Internal debloat consolidated
+  ~1,900 lines of template code and moved route/template plumbing into
+  `src/lib/route/` and `src/lib/template-kit.ts` without removing any
+  non-deprecated command.
+- MCP: tools renamed to a canonical `loops_*` namespace (e.g. `loop_runs` →
+  `loops_runs`, `workflow_read` → `loops_workflow_read`); every legacy name
+  is still registered as a deprecated alias. New read-only tools:
+  `loops_health`, `loops_diagnose`, `loops_daemon_status`,
+  `loops_workflow_run_inspect`; new guarded mutations: `loops_stop`,
+  `loops_archive`, `loops_unarchive`. A golden-schema test
+  (`src/mcp/golden-schema.test.ts`) pins the exported tool schemas.
+- SDK: `LoopsClient.list()` accepts status/limit/archived filters;
+  `runs(idOrName?, { status?, limit? })` resolves names and returns `[]` for
+  unknown loops (v0.3.x-compatible polling); new `doctor()` and `health()`
+  reports; `pause`/`resume`/`stop` surface the store's coded
+  `LoopArchivedError`.
+- Root export (`@hasna/loops`) is now a curated, documented API surface
+  (SDK client, MCP factory, coded errors, domain types, doctor/health
+  helpers) instead of `export *` of internals.
+- Packaging: `@hasna/machines` moved to `optionalDependencies`; `prepare`
+  only builds when `dist/` is missing; `CHANGELOG.md` ships in the npm
+  package; full Apache-2.0 license text restored in `LICENSE`; CI workflow
+  added (`.github/workflows/ci.yml`).
+
+### BREAKING / UPGRADE NOTES
+
+- **Database version stamp — plan downgrades before upgrading.** The first
+  0.4.0 process to open a loops database applies migration 0006 and stamps
+  `PRAGMA user_version = 6`. Migrations are additive (no columns dropped),
+  and 0.3.x binaries do not check `user_version`, so rollback generally
+  works — but downgrading after 0.4.0 has written process-identity data is
+  unsupported and untested. Take a copy of `loops.db` (or rely on the
+  automatic `VACUUM INTO` backups) before upgrading shared machines.
+- **Root import surface narrowed.** `@hasna/loops` no longer re-exports
+  every internal symbol. If you imported undocumented internals from the
+  package root, switch to the curated exports or the `./sdk`, `./mcp`, or
+  `./storage` subpaths. `./storage` (raw `Store`) remains internal plumbing
+  and may change without notice.
+- **Coded errors replace message-matching.** SDK/store mutations on
+  archived or missing loops now throw `LoopArchivedError` /
+  `LoopNotFoundError` (with `.code`) instead of plain `Error`s with ad-hoc
+  messages. Update any `error.message.includes(...)` checks.
+- **`LoopsClient.runs()` signature changed** from `runs(loopId?)` to
+  `runs(idOrName?, filters?)`; it now resolves loop names and returns `[]`
+  when the loop does not exist.
+- **`genId()` no longer takes a length argument** and always returns 32
+  chars. Existing shorter ids remain valid; code that assumed 12-char ids
+  must not.
+- **MCP `loop_create_command` requests that include `shell` are rejected**
+  with a validation error instead of the flag being ignored. Remove the
+  field and pass argv-style `command` + `args`.
+- **MCP tool names changed** to `loops_*`; legacy names (`loop_runs`,
+  `loop_pause`, `workflow_read`, ...) still work as deprecated aliases but
+  will be removed in a future minor. Re-list tools and migrate callers.
+- **CLI deprecations** (aliases still work, removal planned): `loops events
+  handle|drain` → `loops routes create|drain`; `loops templates create` →
+  `loops workflows create --template <id>`; `loops goal status` → `loops
+  goal show`.
+- **Agent loops can now time out by default.** Previously an agent target
+  with no `timeoutMs` could hang forever; it now idle-times-out after 30
+  minutes without progress (4h for buffered agents). Long-running agents
+  must set `timeoutMs`/`idleTimeoutMs` explicitly or export
+  `LOOPS_AGENT_IDLE_TIMEOUT_MS`.
+- **The daemon reaps abandoned process groups.** Inline/external runners
+  must keep the `<surface>:<pid>` runner-id shape and record process
+  identity through the scheduler so a starting daemon can see the owner is
+  alive; runs claimed without fingerprints are re-queued on lease expiry
+  (their processes are never signaled without a verified fingerprint).
+- **Failing loops auto-pause.** After 5 consecutive final failures the
+  circuit breaker pauses the loop with a `circuit breaker open` marker run;
+  fix the cause and `loops resume` the loop. Monitoring that expects
+  endless retries should watch for these markers.
+- **Bun is the only supported runtime** (`bun >= 1.0` on PATH even under
+  npm installs), and `@hasna/machines` is now an optional dependency —
+  installs without it simply disable remote-machine assignment.
+
+## 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
+- 0.3.54 (2026-06-29) feat: add prompt-file support for agent loops
+- 0.3.53 (2026-06-29) fix: refresh route invocation metadata safely
+- 0.3.52 (2026-06-29) feat: add full task lifecycle route template
+- 0.3.51 (2026-06-29) fix: harden custom template registry
+- 0.3.50 (2026-06-29) feat: add custom templates and loop rename
+- 0.3.49 (2026-06-29) fix: harden workflow route lifecycle
+- 0.3.48 (2026-06-29) fix: harden loop routing and recovery
+- 0.3.47 (2026-06-29) fix: validate agent loop options before storing
+- 0.3.46 (2026-06-29) fix: harden generic and cursor agent routes
+- 0.3.45 (2026-06-29) fix: allow routed task workflows to update app stores
+- 0.3.44 (2026-06-29) fix: harden loop readiness adapters
+- 0.3.43 (2026-06-28) fix: refresh stale generated route workflows
+- 0.3.42 (2026-06-28) chore: refresh loops cli release
+- 0.3.41 (2026-06-28) fix: give routed task agents exact todos project commands
+- 0.3.40 (2026-06-28) fix: migrate workflow run invocation indexes safely
+- 0.3.39 (2026-06-28) chore: release loops 0.3.39
+- 0.3.38 (2026-06-28) docs: require worktrees for routed repo tasks
+- 0.3.37 (2026-06-28) docs: require worktrees in routed examples
+- 0.3.36 (2026-06-28) fix: treat configured project path as fallback
+- 0.3.35 (2026-06-28) fix: prefer task repository paths for routing
+- 0.3.34 (2026-06-28) fix: infer task repo paths during drain
+- 0.3.33 (2026-06-28) feat: compact todos drain output
+- 0.3.32 (2026-06-28) fix: read todos drain queues from file
+- 0.3.31 (2026-06-28) fix: handle large todos drain queues
+- 0.3.30 (2026-06-28) fix: dedupe task routes across prefixes
+- 0.3.29 (2026-06-28) feat: filter drained tasks by project path
+- 0.3.28 (2026-06-28) feat: drain ready todos task workflows
+- 0.3.27 (2026-06-28) feat: throttle task event workflows
+- 0.3.26 (2026-06-27) feat: add safe auto routing for loop tasks (includes Cursor Agent CLI adapter fix, PR #10)
+- 0.3.25 (2026-06-27) fix: redact routed health evidence
+- 0.3.24 (2026-06-27) feat: add runtime loop preflight
+- 0.3.23 (2026-06-27) feat: preflight event workflows
+- 0.3.22 (2026-06-27) feat: preflight loop creation
+- 0.3.21 (2026-06-27) fix: rotate routed loop findings and tighten task routing
+- 0.3.20 (2026-06-27) feat: route loop hygiene findings to todos
+- 0.3.19 (2026-06-27) fix: back up loop database before name hygiene apply
+- 0.3.18 (2026-06-27) fix: harden loop hygiene routing gates
+- 0.3.17 (2026-06-27) feat: add loop health and hygiene abstractions
+- 0.3.16 (2026-06-27) chore: release loops 0.3.16 (includes gated todos task routing eligibility and loop health expectations)
+- 0.3.15 (2026-06-27) feat: archive loops and route task events through account pools
+- 0.3.14 (2026-06-26) chore: release loops 0.3.14 (includes deduped todos task event routing)
+- 0.3.13 (2026-06-26) feat: event-driven workflow templates
+- 0.3.12 (2026-06-25) fix: invoke Cursor agent subcommand
+- 0.3.11 (2026-06-25) chore: release 0.3.11 (includes fix(store): make additive column migrations idempotent)
+- 0.3.10 (2026-06-24) feat: run daemon loop jobs concurrently
+- 0.3.9 (2026-06-24) fix: strict goal response schemas
+- 0.3.8 (2026-06-22) feat: derive CLI version from package metadata
+- 0.3.7 (2026-06-22) feat: add transcript-driven loop workflow
+- 0.3.6 (2026-06-21) feat: add AI SDK goal orchestration
+- 0.3.5 (2026-06-20) fix: avoid login shell for remote machine loops
+- 0.3.4 (2026-06-20) feat: add OpenMachines loop assignment
+- 0.3.3 (2026-06-20) fix: harden OpenLoops daemon ownership and redaction
+- 0.3.2 (2026-06-19) feat: add codewith auth profiles and run-now exit codes
+- 0.3.1 (2026-06-19) fix: loops daemon path and output bugs
+- 0.3.0 (2026-06-19) release: loops workflow hardening
+
+## 0.2.0 (2026-06-19)
+
+- feat: add workflows and account-routed execution
+
+## 0.1.0 (2026-06-19)
+
+- feat: build OpenLoops CLI daemon

package/LICENSE

@@ -1,17 +1,201 @@
-Apache License
-Version 2.0, January 2004
-https://www.apache.org/licenses/
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright 2026 Hasna
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+   1. Definitions.
 
-    https://www.apache.org/licenses/LICENSE-2.0
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hasna
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,6 +2,11 @@
 
 OpenLoops is a local CLI and daemon for persistent loops and workflows: scheduled or recurring work that survives process restarts and records every run.
 
+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`, and `loops-mcp`.
+
 It supports deterministic command loops, JSON-defined workflows, and guarded CLI adapters for headless coding agents:
 
 - `claude`
@@ -13,7 +18,12 @@ It supports deterministic command loops, JSON-defined workflows, and guarded CLI
 
 ## Install
 
-From npm:
+**OpenLoops requires the [Bun](https://bun.sh) runtime (`bun >= 1.0`).** The
+`loops`, `loops-daemon`, 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):
 
 ```bash
 npm install -g @hasna/loops
@@ -197,7 +207,9 @@ non-secret routing/configuration data.
 
 ## Goals
 
-Add `--goal` to wrap a command, agent, or workflow loop in an AI-SDK orchestration layer. OpenLoops asks the configured model to create a flat DAG plan, executes ready nodes by calling the underlying target, then runs an adversarial achievement audit before marking the goal complete.
+Add `--goal` to wrap a command, agent, or workflow loop in an AI-SDK orchestration layer. OpenLoops asks the configured model to create a flat DAG plan, then executes ready plan nodes by re-running the underlying target once per node. Each node run is parameterized with that node's objective: agent prompts get the goal and node objective appended, and every wrapped process receives `LOOPS_GOAL_NODE_KEY` and `LOOPS_GOAL_NODE_OBJECTIVE` in its environment. An adversarial achievement audit runs before the goal is marked complete.
+
+The goal `autoExecute` mode is honored: `off` plans and persists the DAG without executing any nodes (the run reports the persisted plan), while `readyOnly` (the default) and `aiDirected` run the dependency-driven execution loop over ready nodes.
 
 ```bash
 export OPENROUTER_API_KEY=...
@@ -213,7 +225,7 @@ loops create agent repo-fixer \
   --goal-max-turns 5
 ```
 
-Goal planning and validation use the Vercel AI SDK with `@openrouter/ai-sdk-provider`. Set `OPENROUTER_API_KEY`; optionally set `LOOPS_GOAL_BASE_URL` to point at a local gateway compatible with OpenRouter. Goal context is passed to wrapped commands and agents as `LOOPS_GOAL_ID`, `LOOPS_GOAL_OBJECTIVE`, and `LOOPS_GOAL_NODE_KEY`.
+Goal planning and validation use the Vercel AI SDK with `@openrouter/ai-sdk-provider`. Set `OPENROUTER_API_KEY`; optionally set `LOOPS_GOAL_BASE_URL` to point at a local gateway compatible with OpenRouter. Goal context is passed to wrapped commands and agents as `LOOPS_GOAL_ID`, `LOOPS_GOAL_OBJECTIVE`, `LOOPS_GOAL_NODE_KEY`, and `LOOPS_GOAL_NODE_OBJECTIVE`.
 
 If a resumed goal plan has no runnable nodes, failed run output includes a
 structured `diagnostics` object with the concrete blocker and `owner`
@@ -660,59 +672,15 @@ write OpenLoops 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.
 
-Proposed SDK shape:
+The canonical `WorkflowUpsertRequest` / `WorkflowUpsertResult` shapes and their
+required semantics (dry-run/preflight/commit modes, `idempotencyKey` +
+`specHash` idempotency, dispatch behavior, and redaction-before-persistence)
+are specified in `docs/AUTOMATION_RUNTIME_DESIGN.md`; this README intentionally
+does not duplicate that spec.
 
-```ts
-type WorkflowUpsertRequest = {
-  idempotencyKey: string;
-  source: { kind: "action" | "automation" | "event"; id: string; dedupeKey?: string };
-  subject: { kind: "repo" | "task" | "pr" | "run"; id?: string; path?: string; url?: string };
-  workflow: { name: string; description?: string; steps: WorkflowStepInput[] };
-  loop: { name: string; schedule: { type: "once"; at: string }; machine?: LoopMachineRef };
-  route?: { projectPath?: string; projectGroup?: string; concurrencyGroup?: string };
-  execution?: AutomationExecutionPolicy;
-  mode?: "dry-run" | "preflight" | "commit";
-  dispatch?: "schedule" | "run-now" | "none";
-};
-
-type WorkflowUpsertResult = {
-  ok: boolean;
-  dryRun: boolean;
-  idempotencyKey: string;
-  specHash: string;
-  refs: {
-    workflowId?: string;
-    loopId?: string;
-    invocationId?: string;
-    workItemId?: string;
-    runId?: string;
-    manifestPath?: string;
-  };
-  action: "created" | "updated" | "reused" | "rejected";
-  preflight?: { ok: boolean; checks: unknown[]; error?: string };
-};
-```
-
-Required semantics:
-
-- `mode="dry-run"` validates, canonicalizes, hashes, and returns the same JSON
-  shape without mutating OpenLoops state.
-- `mode="preflight"` additionally checks provider binaries, machine routing,
-  accounts/auth profiles, prompt files, and workflow target compatibility before
-  commit.
-- `mode="commit"` is idempotent on `idempotencyKey` plus `specHash`: identical
-  requests return existing refs; changed specs create a new workflow version or
-  one-shot loop while preserving previous run history.
-- `dispatch="schedule"` stores a one-shot loop for the daemon; `run-now` claims
-  an immediate manual slot; `none` only materializes refs for another owner to
-  trigger later.
-- All persisted output is redacted before storage, and returned refs are enough
-  for the caller to inspect, cancel, replay, or resolve the run without querying
-  SQLite directly.
-
-See `docs/AUTOMATION_RUNTIME_DESIGN.md` for the planned DLQ/dead-letter
-lifecycle, including `loops dlq list/show/replay/resolve`, idempotent replay
-keys, and compatibility rules for `@hasna/actions`.
+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`.
 
 The same design doc also defines the planned strict automation execution mode:
 minimal env inheritance, scoped secret refs, enforced allowlists,
@@ -879,4 +847,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, prefer disposable worktrees and explicit prompts that name allowed write scope.
+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.