Add iso-orchestrator package

Author: CharGrnmn

.github/workflows/ci.yml

@@ -50,6 +50,9 @@ jobs:
           - workspace: "@razroo/iso-route"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-orchestrator"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/iso-trace"
             node: "20.6.0"
             extra: ""
@@ -133,7 +136,7 @@ jobs:
         working-directory: packages/isolint
         run: node dist/cli/index.js lint . --fail-on error
 
-      - name: Pipeline integration (all seven packages)
+      - name: Pipeline integration (build/feedback toolchain)
         run: node examples/pipeline/build.mjs
 
       - name: iso wrapper dogfood integration

.github/workflows/iso-orchestrator-release.yml

@@ -0,0 +1,48 @@
+name: iso-orchestrator Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-orchestrator
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-orchestrator-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#iso-orchestrator-v}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Verify required CI passed for release commit
+        uses: ./.github/actions/verify-release-gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify package.json version matches release tag
+        run: npm run release:check-source -- "$VERSION"
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - name: Publish to npm (with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CLAUDE.md

@@ -1,6 +1,6 @@
 # iso — monorepo
 
-Workspaces monorepo (npm) housing seven Razroo tools that together make
+Workspaces monorepo (npm) housing eight Razroo tools that together make
 AI-agent harnesses *isomorphic* — the same authored source producing the
 same behavior across every coding harness (Cursor, Claude Code, Codex,
 OpenCode) and every model tier (frontier → 7B local).
@@ -44,6 +44,14 @@ cross-package compositions and the decouplings that are deliberate.
   sessions into a normalized event model for local observability. Zero
   upload. TypeScript.
 
+**Runtime control:**
+
+- `packages/iso-orchestrator` — `@razroo/iso-orchestrator`. Durable
+  workflow primitives for agent harnesses: resumable steps, keyed
+  mutexes, bounded parallel fan-out, and file-backed run state.
+  TypeScript, `tsc` → `dist/`. Tests via
+  `node --test --import tsx tests/*.test.ts`.
+
 ## Conventions
 
 - Each package owns its `package.json`, tests, README, LICENSE, and

INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-This repo ships seven packages that **work on their own** but are **designed
+This repo ships eight packages that **work on their own** but are **designed
 to compose**. The planned cross-package compositions listed here are already
 shipped, so this file now serves as:
 
@@ -86,7 +86,7 @@ missing user messages, redaction, and directory layout stability.
 
 ---
 
-## 5. `examples/pipeline/` ← exercise all seven packages — **DONE**
+## 5. `examples/pipeline/` ← exercise the shipped build/feedback toolchain end-to-end — **DONE**
 
 Shipped and expanded. `examples/pipeline/build.mjs` now drives the full
 chain (`agentmd lint + render → isolint lint → iso-route build

README.md

@@ -25,7 +25,7 @@ Today, writing agent instructions is fragmented on two axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 
-Seven packages solve that in one pipeline with a feedback loop:
+Eight packages solve that in one pipeline with a control layer and feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
   [`@razroo/agentmd`](./packages/agentmd) validates *structure*,
@@ -34,6 +34,9 @@ Seven packages solve that in one pipeline with a feedback loop:
   [`@razroo/iso-route`](./packages/iso-route) compiles *one model policy* into each harness's config.
 - **One wrapper** runs the whole build chain:
   [`@razroo/iso`](./packages/iso) chains the above into a single `iso build`.
+- **One orchestration library** handles durable runtime control:
+  [`@razroo/iso-orchestrator`](./packages/iso-orchestrator) provides resumable
+  steps, keyed mutexes, and bounded fan-out for side-effectful agent workflows.
 - **Two feedback tools** close the loop after deploy:
   [`@razroo/iso-eval`](./packages/iso-eval) scores *did the agent complete the task?* and
   [`@razroo/iso-trace`](./packages/iso-trace) parses production transcripts to show *what the agent actually did*.
@@ -155,6 +158,14 @@ the repo now supports a tighter loop:
   transcripts do not yet expose stable model metadata. Zero upload —
   everything is local reads and user-controlled output.
 
+- **[`packages/iso-orchestrator`](./packages/iso-orchestrator)** — `@razroo/iso-orchestrator`
+  Durable orchestration primitives for the runtime layer above a single
+  agent session. Persists workflow state to local disk, memoizes
+  load-bearing `step()` results, provides keyed mutexes for "same
+  entity" exclusion, and offers bounded `forEach()` fan-out so domain
+  packages can move invariants out of prompt prose and shell scripts.
+  Library-first today: no CLI, no harness-specific task-dispatch adapter.
+
 Each package is independently published on npm and works on its own.
 They're in one repo because they're designed to compose.
 
@@ -262,6 +273,7 @@ iso/
     ├── iso-harness/      # one source, every harness
     ├── iso/              # one command for the whole pipeline
     ├── iso-route/        # one model policy → per-harness config
+    ├── iso-orchestrator/ # durable runtime control above one agent session
     ├── iso-eval/         # behavioral eval on the produced harness
     └── iso-trace/        # parse + query real agent transcripts (observability)
 ```
@@ -313,7 +325,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **all seven packages end-to-end** in one `npm run
+that exercises **seven of the eight packages end-to-end** in one `npm run
 test:pipeline` invocation: `agentmd lint` + `render` → `isolint lint` →
 `iso-route build` (from a bundled `models.yaml` that extends the
 `standard` preset) → `iso-harness build` (which consumes iso-route's

package-lock.json

@@ -0,0 +1,13 @@
+# @razroo/iso-orchestrator
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release. Adds a library-first orchestration layer for agent harnesses
+  with file-backed workflow records, idempotent/resumable `step()` execution,
+  process-safe keyed mutexes, and bounded parallel `forEach()` fan-out.
+
+  The package is intentionally generic: it does not know about any particular
+  harness or task-dispatch surface yet, so domain packages can bring their own
+  adapters.

packages/iso-orchestrator/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razroo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.