@osfactory/har 0.50.1 → 0.51.0

package/dist/index.js

@@ -69193,7 +69193,7 @@ function harnessExists(repoPath) {
 // src/harness/plugins.ts
 init_schema2();
 init_stages();
-var PLUGIN_IDS = ["playwright", "rocketsim"];
+var PLUGIN_IDS = ["playwright", "rocketsim", "kerno"];
 var PluginManifestFileSchema = external_exports.object({
   src: external_exports.string().min(1),
   dest: external_exports.string().min(1),

package/dist/templates/har-boilerplate/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -90,6 +90,7 @@ committed.
 ## Shipped plugins
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
-playwright` (web) or `har env add-plugin rocketsim` (iOS) installs one. A
+playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
+add-plugin kerno` (backend) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/har-boilerplate-cli/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -90,6 +90,7 @@ committed.
 ## Shipped plugins
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
-playwright` (web) or `har env add-plugin rocketsim` (iOS) installs one. A
+playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
+add-plugin kerno` (backend) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/har-boilerplate-ios/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -90,6 +90,7 @@ committed.
 ## Shipped plugins
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
-playwright` (web) or `har env add-plugin rocketsim` (iOS) installs one. A
+playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
+add-plugin kerno` (backend) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/plugins/kerno/.github/workflows/kerno.yml

@@ -0,0 +1,43 @@
+# Kerno backend validation (CI template).
+#
+# This is a starting scaffold, not a drop-in. The backend-validation stage needs three
+# things that are repo-specific, so wire them up before enabling this workflow:
+#   1. Docker available on the runner (Kerno runs scenarios in a sandbox container).
+#   2. Your app running and reachable at the SUT URL, with its database migrated/seeded.
+#   3. A Kerno agent bound to this checkout (`kerno init`) with a committed suite in .kerno/.
+#
+# The stage sources the HAR slot machinery (.har/harness.env, agent-slot.sh, .env.agent.<id>),
+# so the supported path is to run it inside a launched HAR slot. Adapt the "start app" and
+# "kerno init" steps for your stack. Remove `if: false` once wired up.
+name: Kerno backend validation
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  backend-validation:
+    if: false # ← remove after wiring up app startup + `kerno init` below
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install deps
+        run: npm ci
+      - name: Install Kerno CLI
+        run: npm install -g @kerno/cli
+      # - name: Start the app (adapt for your stack) and migrate/seed its database
+      #   run: ./.har/launch.sh 1 && <start your app in the slot>
+      # - name: Bind a Kerno agent to this checkout
+      #   run: kerno init
+      # - name: Run backend validation
+      #   run: ./.har/stages/backend-validation.sh 1
+      - name: Upload Kerno artifacts
+        if: success() || failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: backend-validation
+          path: .har/artifacts/backend-validation

package/dist/templates/plugins/kerno/.har/stages/KERNO.md

@@ -0,0 +1,115 @@
+# Kerno Backend Validation
+
+The `backend-validation` stage re-runs your committed [Kerno](https://kerno.io) scenario
+suite against the app running in an agent slot, deterministically and with no LLM in the
+loop. It turns the slot's isolated running app plus its per-slot database into a real
+backend-validation target, then leaves a pass/fail exit code and an evidence trail.
+
+Full verify (`verify --full`) runs this stage when `backend-validation` is listed in
+`verificationStages` (the plugin adds it for you).
+
+## How it works
+
+For the slot you name, the stage:
+
+1. Acquires a machine-wide lock so two slots never validate at once (see "One agent at a time").
+2. Preflights that a Kerno agent is running and bound to this worktree, that Docker is up, and
+   that a committed suite exists under `.kerno/scenarios/`.
+3. Points Kerno's target config at this slot over REST (the slot's SUT URL and, for greybox, its
+   per-slot database).
+4. Runs every endpoint's scenarios via `POST /scenarios/run` and reads the verdicts straight from
+   the HTTP response.
+5. Writes per-endpoint run responses and any fresh `report.json` files under
+   `.har/artifacts/backend-validation/`, and exits non-zero if any scenario is not `passed`.
+
+## Prerequisites
+
+- **Kerno CLI** installed: `npm install -g @kerno/cli`.
+- **Docker** running. Kerno executes each scenario inside a sandbox container.
+- **A Kerno agent bound to this worktree.** Run `kerno init` inside the agent slot's worktree so
+  Kerno's workspace path matches the slot. The stage never starts or rebinds the agent itself
+  (starting one would kill any other running Kerno agent, see below).
+- **A committed suite** under `.kerno/scenarios/endpoints/`. Validate re-runs an existing suite,
+  it never generates one. Ask your Kerno agent to generate scenarios first, then commit them.
+
+## One agent at a time
+
+Kerno runs a single agent per machine. Starting a second agent (via `kerno init`) kills any other
+running Kerno agent and can tear down its in-flight sandboxes. Because of that, this stage:
+
+- **Never spawns or rebinds** the agent. If none is bound to this worktree, it fails with an
+  instruction to run `kerno init` here.
+- **Serializes across slots** with a fail-fast lock at `~/.kerno/har-backend-validation.lock`. If a
+  second slot runs the stage while one is validating, the second fails fast rather than colliding.
+
+So backend validation runs one slot at a time. Frontend stages (Playwright, and so on) still run
+concurrently across slots.
+
+## Configuration the stage reads
+
+All values come from the slot's `.env.agent.<id>` (written by `launch.sh`) and `~/.kerno/agent.port`:
+
+| Value | Source | Used for |
+|-------|--------|----------|
+| `API_PORT` / `SUT_URL` | slot env | the SUT base URL Kerno tests (`http://localhost:$API_PORT`) |
+| `DATABASE_URL` / `DB_PORT` | slot env | greybox DB target (`agent_<id>`); omitted for black-box apps |
+| `KERNO_AGENT_PORT` or `~/.kerno/agent.port` | Kerno state | which local Kerno agent to call (default `8085`) |
+| `KERNO_APP_ID` (optional) | you | pin the application id when Kerno does not surface one (see below) |
+| `KERNO_SANDBOX_ENV` (optional) | you | extra env injected into the Kerno sandbox for your scenarios (see below) |
+
+Override the agent port with `KERNO_AGENT_PORT` if you run Kerno on a non-default port.
+
+### Scenario env (`KERNO_SANDBOX_ENV`)
+
+Some suites need runtime values, a test-user email, an API token, a feature flag, that
+the scenarios read from the sandbox environment. Pass them as newline- or
+semicolon-separated `KEY=VALUE` pairs; keys must be upper-snake-case. They are injected
+into the Kerno sandbox verbatim alongside the slot database.
+
+```bash
+KERNO_SANDBOX_ENV="KERNO_TEST_USER_EMAIL=dev@example.com;FEATURE_X=on" \
+  ./.har/stages/backend-validation.sh 1
+```
+
+For an authenticated suite, this is usually where the test user goes. The user must exist
+in the slot's seeded database, and the app must accept it (for example a dev-login provider
+enabled in the running app).
+
+If Kerno analyzed your app but did not classify it as HTTP-serving, it is omitted from
+the workspace's application list. The stage falls back to the analyzed module and logs a
+note, so validation still runs. To pin the id explicitly, set `KERNO_APP_ID` (find it via
+`kerno_get_applications`, under `unsupported_apps` when this happens).
+
+## Verdicts
+
+Overall pass requires every scenario across every endpoint to be `passed`. A `failed`, `blocked`,
+or `not_implemented` scenario fails the stage. `blocked` usually means the target or its DB was not
+reachable or a precondition could not be met, so check the run response in the artifacts.
+
+## Artifacts
+
+Under `.har/artifacts/backend-validation/`:
+
+- `<METHOD>_<path>.run.json` for each endpoint: the raw `POST /scenarios/run` response, including
+  per-scenario `verdict`, response status/body, and any `potentialBug`.
+- Copies of Kerno's own `report.json` files written during this run.
+
+## Running
+
+```bash
+# One slot
+./.har/stages/backend-validation.sh 1
+
+# As part of full verify
+./.har/verify.sh 1 --full
+```
+
+## Adapting per repo
+
+- **Auth and runtime env vars** your scenarios or SUT need at runtime belong in the Kerno config
+  (`kerno save-config` via your agent, or the `.kerno/config.yaml` dependency blocks). The stage sets
+  only the SUT URL and the slot DB.
+- **Black-box only** apps (no slot DB) are fine. Leave `DATABASE_URL`/`DB_PORT` unset in the slot and
+  the stage tests over HTTP only.
+- **Regenerate on new endpoints.** When you add an endpoint, ask your Kerno agent to generate its
+  scenarios and commit them, so the next validation covers it.

package/dist/templates/plugins/kerno/.har/stages/backend-validation.sh

@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+# Kerno deterministic backend/API scenario validation for an agent slot.
+# Re-runs the committed Kerno suite (.kerno/scenarios/) against the running slot
+# via the local Kerno agent's REST API. Outputs JSON to stdout, progress to stderr.
+#
+# Usage: ./.har/stages/backend-validation.sh <agent-id>
+# Prerequisite: ./.har/launch.sh <agent-id>, the app running in the slot, AND a Kerno
+#   agent started with `kerno init` in THIS worktree (Kerno allows ONE agent per machine).
+# See: ./.har/stages/KERNO.md for the full setup + adaptation guide.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
+# agent-slot.sh expects SCRIPT_DIR to be .har/ (slot registry lives there)
+SCRIPT_DIR="$HARNESS_DIR"
+
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: backend-validation.sh <agent-id>}"
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [backend-validation agent-$AGENT_ID] $*" >&2; }
+
+ARTIFACT_DIR="$REPO_ROOT/.har/artifacts/backend-validation"
+TOTAL_MS=0
+
+# Emit a result JSON envelope to stdout (used for both early failures and the final result).
+emit_result() {
+  local status="$1"; local message="${2:-}"
+  STATUS="$status" MSG="$message" AID="$AGENT_ID" TMS="$TOTAL_MS" SUT="${API_URL:-}" node -e "
+const out = {
+  status: process.env.STATUS,
+  stageId: 'backend-validation',
+  kind: 'test',
+  agent_id: Number(process.env.AID),
+  total_ms: Number(process.env.TMS || 0),
+  artifacts: [{ path: '.har/artifacts/backend-validation', kind: 'directory' }],
+};
+if (process.env.MSG) out.message = process.env.MSG;
+if (process.env.SUT) out.urls = [{ label: 'sut', url: process.env.SUT }];
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+}
+
+# ── Rule 2: machine-level lock (Kerno allows one agent at a time) ──────────────
+# Stock macOS bash 3.2 has no `flock` binary, so use an atomic mkdir lock with a
+# stale-PID check. Fail fast (never block) so a second slot can't stomp a live run.
+LOCK_DIR="$HOME/.kerno/har-backend-validation.lock"
+MARKER=""
+cleanup() {
+  [ -n "${LOCK_DIR:-}" ] && rm -rf "$LOCK_DIR" 2>/dev/null || true
+  [ -n "${MARKER:-}" ] && rm -f "$MARKER" 2>/dev/null || true
+}
+
+fail() {
+  log "✗ $*"
+  emit_result fail "$*"
+  exit 1
+}
+
+acquire_lock() {
+  mkdir -p "$HOME/.kerno" 2>/dev/null || true
+  if mkdir "$LOCK_DIR" 2>/dev/null; then echo "$$" > "$LOCK_DIR/pid"; return 0; fi
+  local other=""
+  [ -f "$LOCK_DIR/pid" ] && other="$(cat "$LOCK_DIR/pid" 2>/dev/null || true)"
+  if [ -n "$other" ] && kill -0 "$other" 2>/dev/null; then return 1; fi
+  # stale lock — reclaim once
+  rm -rf "$LOCK_DIR" 2>/dev/null || true
+  if mkdir "$LOCK_DIR" 2>/dev/null; then echo "$$" > "$LOCK_DIR/pid"; return 0; fi
+  return 1
+}
+
+if ! acquire_lock; then
+  # Do NOT trap-remove a lock we don't own.
+  fail "another Kerno validation is already in progress on this machine (lock: $LOCK_DIR). Kerno allows one agent at a time — retry after it finishes."
+fi
+trap cleanup EXIT
+
+# ── Resolve agent env + slot target ───────────────────────────────────────────
+ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+  echo "No .env.agent.${AGENT_ID} found." >&2
+  har_suggest_launch "$AGENT_ID" >&2
+  exit 1
+}
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+
+# SUT URL: prefer an explicit override, then the app's own SITE_URL (both the default
+# web profile and single-port apps like Next.js set SITE_URL to the running app), then a
+# port fallback (PORT for single-port apps, else API_PORT).
+APP_PORT="${PORT:-${API_PORT:-${FE_PORT:-}}}"
+API_URL="${SUT_URL:-${SITE_URL:-}}"
+if [ -z "$API_URL" ] && [ -n "$APP_PORT" ]; then
+  API_URL="http://localhost:${APP_PORT}"
+fi
+[ -n "$API_URL" ] || fail "Could not determine the slot SUT URL. Set SUT_URL, or ensure the slot env defines SITE_URL or PORT/API_PORT."
+
+# Slot database (greybox). The launch env file already exports DATABASE_URL for the
+# per-slot DB (agent_<id>); reconstruct it from DB_PORT only if absent. Omitted for
+# black-box (HTTP-only) apps that expose no slot DB.
+DB_URL="${DATABASE_URL:-}"
+if [ -z "$DB_URL" ] && [ -n "${DB_PORT:-}" ]; then
+  DB_URL="postgresql://postgres:password@localhost:${DB_PORT}/agent_${AGENT_ID}"
+fi
+
+# ── Discover the Kerno agent (never spawn it — spawning kills other agents) ────
+KERNO_PORT="${KERNO_AGENT_PORT:-}"
+if [ -z "$KERNO_PORT" ] && [ -f "$HOME/.kerno/agent.port" ]; then
+  KERNO_PORT="$(cat "$HOME/.kerno/agent.port" 2>/dev/null || true)"
+fi
+KERNO_PORT="${KERNO_PORT:-8085}"
+AGENT_URL="http://127.0.0.1:${KERNO_PORT}"
+
+# ── Rule 1: preflight — assume-and-verify, never spawn/rebind ──────────────────
+# The stage drives Kerno entirely over REST and never invokes the `kerno` CLI, so
+# reachability of the agent (not the CLI being on PATH) is the real requirement.
+command -v curl  >/dev/null 2>&1 || fail "curl is required but was not found on PATH."
+docker info >/dev/null 2>&1 || fail "Docker is not running. Kerno executes scenarios in a container — start Docker and retry."
+curl -sf "$AGENT_URL/health" >/dev/null 2>&1 || fail "No Kerno agent reachable at $AGENT_URL. Install the Kerno CLI (npm install -g @kerno/cli) and run 'kerno init' in this worktree first (Kerno allows one agent per machine). Override the port with KERNO_AGENT_PORT."
+
+WORKSPACES_JSON="$(curl -sf "$AGENT_URL/workspaces" 2>/dev/null || true)"
+[ -n "$WORKSPACES_JSON" ] || fail "Could not read Kerno workspaces from $AGENT_URL/workspaces."
+
+# Extract workspaceId, applicationId, and the bound workspace path from the first
+# (only) workspace. Field-by-field extraction avoids delimiter-splitting pitfalls when
+# a field (e.g. an absent applicationId) is empty.
+ws_field() { printf '%s' "$WORKSPACES_JSON" | node -e "$1" 2>/dev/null || true; }
+WID="$(ws_field 'const w=JSON.parse(require("fs").readFileSync(0,"utf8"))[0]||{};process.stdout.write(w.id||"")')"
+AID="$(ws_field 'const w=JSON.parse(require("fs").readFileSync(0,"utf8"))[0]||{};const a=(w.applications||[])[0];process.stdout.write(a&&a.id?a.id:"")')"
+WS_PATH="$(ws_field 'const w=JSON.parse(require("fs").readFileSync(0,"utf8"))[0]||{};process.stdout.write(w.path||"")')"
+PATH_MATCH="$(WSP="$WS_PATH" WD="$WORK_DIR" node -e 'const fs=require("fs");const r=p=>{try{return fs.realpathSync(p)}catch(e){return p||""}};const wsp=process.env.WSP||"";process.stdout.write(wsp&&r(wsp)===r(process.env.WD||"")?"1":"0")' 2>/dev/null || echo 0)"
+
+[ -n "${WID:-}" ] || fail "Kerno agent has no analyzed workspace yet. Run 'kerno init' in this worktree."
+if [ "${PATH_MATCH:-0}" != "1" ]; then
+  fail "Kerno agent is bound to '${WS_PATH:-unknown}', not this slot worktree ('$WORK_DIR'). Run 'kerno init' in this worktree first (Kerno allows one agent per machine)."
+fi
+
+# Resolve the applicationId. Precedence: explicit KERNO_APP_ID override, then the
+# workspace's HTTP/MCP-serving application (the normal case). If Kerno analyzed a
+# module but did not classify it as HTTP-serving, /workspaces omits it — fall back to
+# the module list Kerno leaks in a 404 body so validation still works, with a note.
+if [ -n "${KERNO_APP_ID:-}" ]; then
+  AID="$KERNO_APP_ID"
+elif [ -z "$AID" ]; then
+  PROBE="$(curl -s "$AGENT_URL/workspaces/$WID/applications/__har_kerno_probe__/config" 2>/dev/null || true)"
+  AID="$(printf '%s' "$PROBE" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>{const m=d.match(/has modules: \[([^\]]*)\]/);process.stdout.write(m&&m[1].trim()?m[1].split(",")[0].trim():"")})' 2>/dev/null || true)"
+  [ -n "$AID" ] && log "note: no HTTP-classified application in /workspaces; falling back to analyzed module '$AID' (Kerno may not have classified this app as HTTP-serving). Set KERNO_APP_ID to pin it."
+fi
+[ -n "${AID:-}" ] || fail "Kerno detected no usable application in this workspace. Set KERNO_APP_ID (see 'kerno_get_applications' → unsupported_apps for the id) or confirm the app was analyzed and a suite generated."
+
+# Suite must already exist — validate never generates.
+SCEN_DIR="$WORK_DIR/.kerno/scenarios/endpoints"
+SCEN_FILES="$(find "$SCEN_DIR" -name '*.scenario.ts' 2>/dev/null | sort)"
+[ -n "$SCEN_FILES" ] || fail "No Kerno scenario suite under .kerno/scenarios/endpoints/. Ask your Kerno agent to generate scenarios first — validate only re-runs an existing suite."
+
+# ── Point Kerno's config at this slot (REST PATCH — same writer as save_config) ──
+# The env map is injected verbatim into the sandbox. It carries the slot DB plus any
+# KERNO_SANDBOX_ENV the app's scenarios need at runtime (test-user email, tokens, flags),
+# as newline- or semicolon-separated KEY=VALUE pairs. Kerno treats the block name as
+# organisational only, so all values are injected regardless of the block.
+CONFIG_BODY="$(API_URL="$API_URL" DB_URL="$DB_URL" EXTRA="${KERNO_SANDBOX_ENV:-}" node -e '
+const body = { sut: { inputUrl: process.env.API_URL }, targetEnvironment: "local" };
+const env = {};
+if (process.env.DB_URL) env.DATABASE_URL = process.env.DB_URL;
+(process.env.EXTRA || "").split(/[;\n]+/).forEach((p) => {
+  const i = p.indexOf("=");
+  if (i < 1) return;
+  const k = p.slice(0, i).trim();
+  const v = p.slice(i + 1).trim();
+  if (/^[A-Z_][A-Z0-9_]*$/.test(k)) env[k] = v;
+});
+if (Object.keys(env).length) body.postgres = env;
+process.stdout.write(JSON.stringify(body));
+')"
+curl -sf -X PATCH "$AGENT_URL/workspaces/$WID/applications/$AID/config" \
+  -H 'content-type: application/json' -d "$CONFIG_BODY" >/dev/null 2>&1 \
+  || fail "Failed to set Kerno target config (PATCH /workspaces/$WID/applications/$AID/config)."
+
+log "Validating against SUT $API_URL${DB_URL:+ (greybox DB configured)}"
+log "Workspace: $WID  Application: $AID"
+
+# ── Enumerate unique endpoints (METHOD + path) from the on-disk suite ──────────
+# Each *.scenario.ts lives in .kerno/scenarios/endpoints/<METHOD>/<path>/ ; the
+# endpoint is that parent dir. No `mapfile` — stock macOS bash is 3.2.
+ENDPOINTS=""
+while IFS= read -r scen; do
+  [ -n "$scen" ] || continue
+  d="$(dirname "$scen")"
+  rel="${d#"$SCEN_DIR"/}"          # e.g. GET/api/health
+  method="${rel%%/*}"              # GET
+  rest="${rel#*/}"                 # api/health  (== rel when no sub-path)
+  if [ "$rest" = "$rel" ]; then rest=""; fi
+  path="/${rest}"; path="${path%/}"; [ -z "$path" ] && path="/"
+  ENDPOINTS="${ENDPOINTS}${method}	${path}
+"
+done <<< "$SCEN_FILES"
+ENDPOINTS="$(printf '%s' "$ENDPOINTS" | sort -u | sed '/^[[:space:]]*$/d')"
+
+# ── Run each endpoint (synchronous REST; the response is the source of truth) ──
+mkdir -p "$ARTIFACT_DIR"
+MARKER="$(mktemp)"                 # reference for "fresh" report.json (macOS find has -newer, not -newermt)
+START_TOTAL=$(now_ms)
+OVERALL_PASS=true
+ENDPOINT_RESULTS="[]"
+
+while IFS=$'\t' read -r method path; do
+  [ -n "$method" ] || continue
+  printf "  → %-6s %-40s" "$method" "$path" >&2
+
+  REQ_BODY="$(METHOD="$method" EPATH="$path" node -e 'process.stdout.write(JSON.stringify({method:process.env.METHOD,path:process.env.EPATH}))')"
+
+  set +e
+  RESP="$(curl -s -X POST "$AGENT_URL/workspaces/$WID/applications/$AID/scenarios/run" \
+    -H 'content-type: application/json' -d "$REQ_BODY" 2>/dev/null)"
+  CURL_EXIT=$?
+  set -e
+
+  if [ "$CURL_EXIT" != "0" ]; then
+    # Connection reset mid-run usually means the Kerno agent was killed (another
+    # agent booted). Surface it as a failure rather than a silent pass.
+    echo "✗ (agent unreachable)" >&2
+    SUMMARY="$(METHOD="$method" EPATH="$path" node -e 'process.stdout.write(JSON.stringify({method:process.env.METHOD,path:process.env.EPATH,ok:false,total:0,passed:0,error:"agent unreachable mid-run (curl exit '"$CURL_EXIT"')"}))')"
+    OVERALL_PASS=false
+  else
+    SAFE="$(printf '%s' "${method}_${path}" | tr '/ ' '__' | tr -cd 'A-Za-z0-9_.-')"
+    printf '%s\n' "$RESP" > "$ARTIFACT_DIR/${SAFE}.run.json"
+
+    SUMMARY="$(printf '%s' "$RESP" | METHOD="$method" EPATH="$path" node -e '
+const fs = require("fs");
+let raw = ""; try { raw = fs.readFileSync(0, "utf8"); } catch (e) {}
+let data; try { data = JSON.parse(raw); } catch (e) {
+  process.stdout.write(JSON.stringify({ method: process.env.METHOD, path: process.env.EPATH, ok: false, total: 0, passed: 0, error: "unparseable run response" }));
+  process.exit(0);
+}
+const results = Array.isArray(data.results) ? data.results : [];
+const passed = results.filter(r => r.verdict === "passed").length;
+const failing = results.filter(r => r.verdict !== "passed");
+const bugs = results.filter(r => r.potentialBug).map(r => ({ title: r.potentialBug.title, severity: r.potentialBug.severity || null, scenario: r.scenarioId }));
+const ok = results.length > 0 && failing.length === 0;
+process.stdout.write(JSON.stringify({
+  method: process.env.METHOD, path: process.env.EPATH, ok,
+  total: results.length, passed,
+  failing: failing.map(r => ({ scenario: r.scenarioId, verdict: r.verdict, status: r.responseStatus })),
+  bugs,
+}));
+')"
+
+    EP_OK="$(printf '%s' "$SUMMARY" | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));process.stdout.write(d.ok?"1":"0")' 2>/dev/null || echo 0)"
+    EP_PASS="$(printf '%s' "$SUMMARY" | node -e 'const d=JSON.parse(require("fs").readFileSync(0,"utf8"));process.stdout.write(String(d.passed)+"/"+String(d.total))' 2>/dev/null || echo "?")"
+    if [ "$EP_OK" = "1" ]; then
+      echo "✓ ($EP_PASS)" >&2
+    else
+      echo "✗ ($EP_PASS)" >&2
+      OVERALL_PASS=false
+    fi
+  fi
+
+  ENDPOINT_RESULTS="$(printf '%s' "$ENDPOINT_RESULTS" | SUMMARY="$SUMMARY" node -e 'const fs=require("fs");let a=JSON.parse(fs.readFileSync(0,"utf8"));a.push(JSON.parse(process.env.SUMMARY));process.stdout.write(JSON.stringify(a))')"
+done <<< "$ENDPOINTS"
+
+END_TOTAL=$(now_ms)
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+# ── Copy Kerno's own report.json files, but only ones written by THIS run ──────
+if [ -d "$WORK_DIR/.kerno" ]; then
+  while IFS= read -r rep; do
+    [ -n "$rep" ] || continue
+    rel="${rep#"$WORK_DIR"/}"
+    safe="$(printf '%s' "$rel" | tr '/ ' '__')"
+    cp "$rep" "$ARTIFACT_DIR/$safe" 2>/dev/null || true
+  done < <(find "$WORK_DIR/.kerno" -name 'report.json' -newer "$MARKER" 2>/dev/null || true)
+fi
+
+# ── Emit aggregated result ─────────────────────────────────────────────────────
+RESULTS="$ENDPOINT_RESULTS" AID="$AGENT_ID" TMS="$TOTAL_MS" SUT="$API_URL" node -e "
+const results = JSON.parse(process.env.RESULTS || '[]');
+const overall = results.length > 0 && results.every(r => r.ok);
+const scenarios = {
+  total: results.reduce((a, r) => a + (r.total || 0), 0),
+  passed: results.reduce((a, r) => a + (r.passed || 0), 0),
+};
+const bugs = results.reduce((a, r) => a.concat(r.bugs || []), []);
+const out = {
+  status: overall ? 'pass' : 'fail',
+  stageId: 'backend-validation',
+  kind: 'test',
+  agent_id: Number(process.env.AID),
+  total_ms: Number(process.env.TMS),
+  urls: [{ label: 'sut', url: process.env.SUT }],
+  scenarios,
+  endpoints: results,
+  bugs,
+  artifacts: [{ path: '.har/artifacts/backend-validation', kind: 'directory' }],
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+[ "$OVERALL_PASS" = "true" ] || exit 1

package/dist/templates/plugins/kerno/README.md

@@ -0,0 +1,67 @@
+# Kerno plugin
+
+Add deterministic backend/API validation to your harness with [Kerno](https://kerno.io).
+Kerno re-runs a committed scenario suite against the app running in an agent slot, using the
+slot's own database for greybox checks, and reports a pass/fail with a full evidence trail.
+
+```bash
+har env add-plugin kerno
+```
+
+## What this installs
+
+| File | Purpose |
+|------|---------|
+| `.har/stages/backend-validation.sh` | Stage runner. Re-runs the Kerno suite against the running slot over REST |
+| `.har/stages/KERNO.md` | Setup and adaptation guide: prerequisites, the one-agent rule, artifacts |
+| `tests/kerno/README.md` | This file |
+| `.github/workflows/kerno.yml` | Optional CI workflow (skip with `--skip-ci`) |
+
+## Workflow
+
+```
+        Code change
+             │
+       launch slot  +  app running
+             │
+   typecheck + unit-tests + lint
+             │
+     backend-validation  ◄── your committed .kerno/scenarios/
+             │
+          pass/fail  +  evidence
+```
+
+## Requirements
+
+- Kerno CLI: `npm install -g @kerno/cli`
+- Docker running (Kerno executes scenarios in a sandbox container)
+- A Kerno agent bound to the slot's worktree (`kerno init` inside it)
+- A committed suite under `.kerno/scenarios/` (validate re-runs, it does not generate)
+
+Kerno runs one agent per machine, so backend validation is serialized across slots by a
+fail-fast lock. See `.har/stages/KERNO.md` for the full explanation.
+
+## Quick start after install
+
+```bash
+# 1. Install the stage
+har env add-plugin kerno
+
+# 2. Install the Kerno CLI and bind an agent to the worktree
+npm install -g @kerno/cli
+kerno init                       # run inside the slot worktree
+
+# 3. Ensure a suite exists (ask your Kerno agent to generate one, then commit it)
+ls .kerno/scenarios/endpoints/
+
+# 4. Launch the slot and start your app
+./.har/launch.sh 1
+
+# 5. Run backend validation
+./.har/stages/backend-validation.sh 1
+
+# 6. Validate everything
+./.har/verify.sh 1 --full
+```
+
+Per-endpoint run responses and verdicts land in `.har/artifacts/backend-validation/`.

package/dist/templates/plugins/kerno/template.manifest.json

@@ -0,0 +1,46 @@
+{
+  "id": "kerno",
+  "stageId": "backend-validation",
+  "verificationStages": [
+    "typecheck",
+    "unit-tests",
+    "api-health",
+    "lint",
+    "backend-validation"
+  ],
+  "stage": {
+    "id": "backend-validation",
+    "kind": "test",
+    "description": "Kerno deterministic backend/API scenario validation against the running slot",
+    "script": "stages/backend-validation.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/backend-validation",
+        "kind": "directory",
+        "description": "Per-endpoint run responses, aggregated verdicts, and copied Kerno report.json files"
+      },
+      {
+        "path": ".har/artifacts/backend-validation/report.json",
+        "kind": "report"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/backend-validation.sh", "dest": ".har/stages/backend-validation.sh", "executable": true },
+    { "src": ".har/stages/KERNO.md", "dest": ".har/stages/KERNO.md" },
+    { "src": "README.md", "dest": "tests/kerno/README.md" }
+  ],
+  "optionalFiles": [
+    { "src": ".github/workflows/kerno.yml", "dest": ".github/workflows/kerno.yml", "skipFlag": "skipCi" }
+  ],
+  "nextSteps": [
+    "npm install -g @kerno/cli",
+    "kerno init                       # bind the single Kerno agent to THIS worktree",
+    "Ask your Kerno agent to generate a scenario suite (or ensure .kerno/scenarios/ is committed)",
+    "./.har/launch.sh 1               # then start your app in the slot",
+    "./.har/stages/backend-validation.sh 1",
+    "Open .har/artifacts/backend-validation/ for verdicts and per-endpoint run responses"
+  ],
+  "docsPath": ".har/stages/KERNO.md"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.50.1",
+  "version": "0.51.0",
   "description": "Open harness for reproducible multi-agent coding workflows",
   "keywords": [
     "har",