session-relay Rust port (steps 1-6) + knowledge-format lint & citations

.github/AGENTS.md

@@ -1,12 +1,16 @@
 # CI workflows (.github/)
 
-`workflows/ci.yml` runs `node scripts/ci.mjs` — the exact same gate as local — in one job on GitHub. All validators are Node `.mjs`; the job needs Node + pnpm (`corepack enable`, then `pnpm install --frozen-lockfile`) for the `yaml` package and the lockfile-pinned `claude-code` binary, and adds `node_modules/.bin` to PATH so `ci.mjs` finds `claude`.
+`workflows/ci.yml` runs `node scripts/ci.mjs` — the exact same gate as local — in one job on GitHub. All validators are Node `.mjs`; the job needs Node + pnpm (`corepack enable`, then `pnpm install --frozen-lockfile`) for the `yaml` package and the lockfile-pinned `claude-code` binary, and adds `node_modules/.bin` to PATH so `ci.mjs` finds `claude`. The validate job also provisions Rust for the session-relay host leg (guarded: no-op until `plugins/session-relay/rust/rust-toolchain.toml` exists; rustup is preinstalled on the runner image, so no third-party toolchain action).
+
+## build-binaries.yml — the session-relay binary producer
+
+`workflows/build-binaries.yml` builds the four static `relay` binaries (2-runner matrix: Apple-Silicon `macos-latest` → both darwin arches; `ubuntu-latest` → both linux-musl arches) and uploads them as artifacts. **`workflow_dispatch` only — never tag-triggered**: binaries must be committed into `plugins/session-relay/bin/` *before* `release.mjs` tags HEAD (the tag push is the gate; it verifies what is in-tree, it cannot produce it). It is dispatchable only once the file exists on the default branch. No third-party toolchain action — both runner images preinstall rustup, and the pinned compiler comes from `rust-toolchain.toml`.
 
 ## Trigger model
 
 Only three events trigger CI:
 - `pull_request` to main → gate merges
-- `push` of tags matching `docks--v*` → gate releases (`release.mjs` waits for this)
+- `push` of tags matching `*--v*` — any `<plugin>--v<version>` release tag (`docks--v*`, `session-relay--v*`, …) → gate releases (`release.mjs` waits for this; a plugin-specific glob here once left session-relay releases un-gated)
 - `workflow_dispatch` → manual
 
 <constraint>

.github/workflows/build-binaries.yml

@@ -0,0 +1,69 @@
+name: build-binaries
+
+# Produces the four session-relay `relay` binaries as artifacts (rust-port plan).
+#
+#   macos-latest (Apple Silicon)  → aarch64-apple-darwin (native) + x86_64-apple-darwin (cross target)
+#   ubuntu-latest                 → x86_64-unknown-linux-musl + aarch64-unknown-linux-musl (static)
+#
+# workflow_dispatch ONLY — deliberately NOT tag-triggered. Binaries must be
+# committed into plugins/session-relay/bin/ BEFORE release.mjs tags HEAD:
+# the tag push is the release gate, so it can only verify what is already
+# in-tree, never produce it. Flow: dispatch here → download artifacts →
+# commit into bin/ (mode 100755) + SHA256SUMS → release.mjs bumps + tags.
+#
+# Notes:
+#   - Dispatchable only once this file exists on the DEFAULT branch.
+#   - No third-party toolchain action: both runner images preinstall rustup
+#     (runner-images Ubuntu2404 + macos-15-arm64 readmes, verified 2026-07-01);
+#     `rustup toolchain install` reads plugins/session-relay/rust/rust-toolchain.toml.
+#   - Will fail (by design) until the crate lands (rust-port plan step 3).
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: "build (${{ matrix.runner }})"
+    strategy:
+      matrix:
+        include:
+          - runner: macos-latest
+            targets: "aarch64-apple-darwin x86_64-apple-darwin"
+          - runner: ubuntu-latest
+            targets: "x86_64-unknown-linux-musl aarch64-unknown-linux-musl"
+    runs-on: ${{ matrix.runner }}
+    defaults:
+      run:
+        working-directory: plugins/session-relay/rust
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: "linux only: musl C toolchain + aarch64 cross-linker"
+        if: runner.os == 'Linux'
+        working-directory: .
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends musl-tools gcc-aarch64-linux-gnu
+      - name: "install the pinned toolchain (rust-toolchain.toml) + this runner's targets"
+        run: |
+          rustup toolchain install
+          rustup target add ${{ matrix.targets }}
+      - name: "build each target (--locked; release profile lives in Cargo.toml)"
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER: aarch64-linux-gnu-gcc
+        run: |
+          mkdir -p ../bin-out
+          for t in ${{ matrix.targets }}; do
+            cargo build --release --locked --target "$t"
+            cp "target/$t/release/relay" "../bin-out/relay-$t"
+          done
+      - name: "per-runner checksums (transit cross-check; the committed SHA256SUMS is regenerated in bin/)"
+        working-directory: plugins/session-relay/bin-out
+        run: shasum -a 256 relay-* | tee "SHA256SUMS-${{ matrix.runner }}.part"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: relay-${{ matrix.runner }}
+          path: |
+            plugins/session-relay/bin-out/relay-*
+            plugins/session-relay/bin-out/SHA256SUMS-*.part
+          if-no-files-found: error

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ on:
     branches: [main]
   push:
     tags:
-      - 'docks--v*'
+      - '*--v*'   # any <plugin>--v<version> release tag (docks--v*, session-relay--v*, ...)
   workflow_dispatch:
 
 # Least privilege: the single validator job is read-only.
@@ -38,5 +38,11 @@ jobs:
         run: node node_modules/@anthropic-ai/claude-code/install.cjs
       - name: "add node_modules/.bin to PATH (so ci.mjs finds the pinned claude)"
         run: echo "$GITHUB_WORKSPACE/node_modules/.bin" >> "$GITHUB_PATH"
+      - name: "provision Rust for the session-relay host leg (no-op until the crate lands; rustup is preinstalled on the image)"
+        run: |
+          if [ -f plugins/session-relay/rust/rust-toolchain.toml ]; then
+            sudo apt-get update && sudo apt-get install -y --no-install-recommends musl-tools
+            (cd plugins/session-relay/rust && rustup toolchain install && rustup target add x86_64-unknown-linux-musl)
+          fi
       - name: "run the full gate (ci.mjs) — guards, scores, manifests, plugin validate, scaffold, shellcheck"
         run: node scripts/ci.mjs

.gitignore

@@ -4,3 +4,4 @@
 .idea/
 .vscode/
 node_modules/
+plugins/session-relay/rust/target/