@north-light/cli 0.3.437 → 0.3.438

package/docs/ci-runner.md

@@ -0,0 +1,58 @@
+# CI runners and the double-run gate
+
+Crouter's suite runs on macOS (see the header of `.github/workflows/test.yml`). GitHub-hosted `macos-latest` is billed per minute and a full run is ~50 billed minutes, so the suite can run on a self-hosted Mac instead, and the push to `main` does not re-run it for a tree that already passed.
+
+## Where the macOS jobs run: `CRTR_CI_RUNNER`
+
+Repository variable `CRTR_CI_RUNNER` selects `runs-on` for the `build`, `build-output` and `lane` jobs of `test.yml`:
+
+| Value | Runs on |
+| --- | --- |
+| unset, or anything other than `self-hosted` | GitHub-hosted `macos-latest` (billed) |
+| `self-hosted` | runners labelled `[self-hosted, macOS, crouter]` (the Mac mini) |
+
+```bash
+gh variable set CRTR_CI_RUNNER --body self-hosted -R Northlight-Systems/crouter     # use the mini
+gh variable delete CRTR_CI_RUNNER -R Northlight-Systems/crouter                      # fall back to macos-latest
+```
+
+It takes effect on the next run; no commit is needed. **If the mini is offline, jobs queue until it returns (they do not fall back by themselves) — delete the variable.** Cancel and re-run anything already queued. The variable also changes the shard matrix: `self-hosted` uses 2 unit + 3 integration + 3 seam shards (8 lane jobs, 3 runner instances), hosted uses 3 + 6 + 6 (15).
+
+A pull request from a fork always runs on `macos-latest`, whatever the variable says: a self-hosted runner must never execute fork code. The repository is private and forking is disabled today, so this only guards a later change.
+
+## The Mac mini runners
+
+`scripts/ci-runner/install.sh` installs N runner instances (default 3). The mini has 10 cores and 16 GB; a lane job runs up to 8 test files at once, each with a broker and tmux, so three concurrent jobs is the ceiling before the seam lane's timeouts become the failure.
+
+Isolation, per instance `~/ci-runners/crouter-N/`:
+
+- its own runner directory and `_work` checkout;
+- its own `HOME` (`~/ci-runners/crouter-N/home`), never the account's. The suite refuses to start if `$HOME/.crouter` exists, so the account's own crouter install (`~/.crouter`, the selected runtime, `~/.local/bin/crtr`, any running `crtrd`) is neither read nor written;
+- a minimal `PATH` (Homebrew + system) that does not include the account's crtr or npm globals;
+- `hook-job-started.sh` / `hook-job-completed.sh` (`ACTIONS_RUNNER_HOOK_JOB_*`), which kill every process whose environment or command line points into that instance's directory (brokers, `crtrd`, test tmux servers, orphaned node processes) and wipe `home/.crouter*` and `_temp`. They match only that instance's path, so one instance's cleanup cannot touch another's job or the account's processes.
+
+The tests bind unix sockets under per-test temp dirs and tmux servers under the per-test `HOME`, with no fixed TCP ports, so instances do not collide.
+
+### Service
+
+Each instance is a boot-time LaunchDaemon (survives reboot and logout, runs as `silasrhyneer`): `ai.northlight.ci-runner.crouter-1` … `-3`.
+
+```bash
+sudo launchctl kickstart -k system/ai.northlight.ci-runner.crouter-1      # restart one
+sudo launchctl print system/ai.northlight.ci-runner.crouter-1 | head       # state
+tail -f ~/ci-runners/crouter-1/runner.log                                    # log
+gh api repos/Northlight-Systems/crouter/actions/runners --jq '.runners[]|[.name,.status,.busy]|@tsv'
+```
+
+Installing and upgrading: get a registration token (`gh api -X POST repos/Northlight-Systems/crouter/actions/runners/registration-token --jq .token`), run `RUNNER_TOKEN=… scripts/ci-runner/install.sh 3` on the mini, then run the `sudo launchctl bootstrap` lines it prints. Prerequisites on the mini: `tmux`, `uv`, `git` (Homebrew); Node comes from `actions/setup-node`.
+
+## No double run on `main`
+
+`publish.yml` starts with a `gate` job. It reads the pushed commit's **git tree** and looks for a workflow artifact named `tested-tree-<tree>`. `test.yml`'s final `tested` job creates that artifact only after `build`, `build-output` and every `lane` shard pass, on every pull request run and on every run of Publish's own `tests` job.
+
+- Rebase-merging a PR whose tested merge ref has the same tree as the resulting `main` commit → artifact found → `tests` is skipped and `publish` proceeds.
+- A direct push to `main`, or a merge after `main` moved (a different tree from the one the PR run tested) → no artifact → the full suite runs exactly as before. A release commit (`chore: release …`, pushed by Publish itself) changes the tree, so a PR not updated since before the latest release runs the suite once on merge; update the branch to avoid it.
+- The gate can only skip; if the lookup errors it runs the suite. `publish` runs only when `tests` passed, or was skipped *because* the gate found a record. A failed or cancelled suite never publishes.
+- Branch protection is not enabled on `main` and the gate does not depend on it: the proof is the tree, not a required check. Artifacts are kept 30 days; older trees are simply re-tested.
+
+The OIDC constraint at the top of `publish.yml` is unchanged: every publishing job is still in that file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.437",
+  "version": "0.3.438",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -137,7 +137,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.437",
+    "@north-light/identity": "0.3.438",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.437",
+  "version": "0.3.438",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.437",
+  "version": "0.3.438",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "1.1.0",
         "@earendil-works/pi-coding-agent": "1.1.0",
         "@earendil-works/pi-tui": "1.1.0",
-        "@north-light/identity": "0.3.437",
+        "@north-light/identity": "0.3.438",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12095,17 +12095,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12113,20 +12113,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.437",
-        "@north-light/identity": "0.3.437"
+        "@north-light/api": "0.3.438",
+        "@north-light/identity": "0.3.438"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.437",
+      "version": "0.3.438",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.437",
-        "@north-light/identity": "0.3.437",
+        "@north-light/api": "0.3.438",
+        "@north-light/identity": "0.3.438",
         "jose": "^6.2.1"
       },
       "bin": {