@onlooker-community/ecosystem 0.29.1 → 0.29.3

package/.claude/skills/writing-tests/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: writing-tests
+description: How to write tests in the Onlooker ecosystem repo — bats integration tests for hooks and the node:test schema suite. Use when adding or changing anything under test/, when writing a new hook or plugin that needs tests, or when deciding which shared helper to reach for instead of hand-rolling setup, dates, CLI stubs, project keys, or event-log assertions. Steers toward test/helpers/setup.bash and each plugin's own libs so tests stay isolated and never become time bombs.
+---
+
+# Writing tests
+
+This repo has two test suites. Use the right one for what you're testing, and lean on the shared helpers below — most fragility in this codebase has come from tests hand-rolling things a helper already does.
+
+- **bats** (`test/bats/*.bats`) — bash hooks and end-to-end plugin behavior. This is where almost all tests live.
+- **node:test** (`test/node/*.test.mjs`) — schema mapping, manifest, and reference validation. Pure data-in/data-out, no hooks.
+
+## Run the suite
+
+```bash
+npm test               # bats + node schema suite (what most changes need)
+npm run test:bats      # just bats  (bats test/bats)
+npm run test:schema    # just node  (node --test test/node/*.test.mjs)
+npm run test:ci        # shellcheck + bats + schema + biome + manifest/reference lint
+```
+
+Run a single bats file while iterating: `bats test/bats/<name>.bats`. `bats` comes from mise (it is on `PATH`), not `npx`.
+
+## Golden rules
+
+1. Every bats test starts by isolating the filesystem — source `setup.bash` and call `setup_test_env`. Never touch the real `$HOME` or `~/.onlooker`.
+2. Always reference `$ONLOOKER_DIR` / `$ONLOOKER_EVENTS_LOG`, never a literal `~/.onlooker`.
+3. Never hardcode a date that feeds a relative window. Use `relative_iso_days_ago`.
+4. Resolve project keys, emit events, and generate ULIDs through the plugin's own libs — don't reimplement them.
+5. Assert behavior through the **event log** and on-disk artifacts, the same surfaces real consumers read.
+
+## bats tests
+
+### Isolate the environment first
+
+Every test file's `setup()` sources the shared helper and calls `setup_test_env`, which repoints `HOME`, `ONLOOKER_DIR`, `CLAUDE_HOME`, and `CLAUDE_PLUGIN_ROOT` into `$BATS_TEST_TMPDIR` and severs git from your global config:
+
+```bash
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/<plugin>"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+}
+```
+
+If your hook needs the resolved Onlooker paths (`$ONLOOKER_EVENTS_LOG`, the session/metrics dirs) materialized, call `load_validate_path` instead — it runs `setup_test_env`, sources `scripts/lib/validate-path.sh`, and `mkdir -p`s the standard directories.
+
+`setup_test_env` exports (read `test/helpers/setup.bash` for the authoritative list):
+
+| Variable | Points at |
+|----------|-----------|
+| `HOME` | `$BATS_TEST_TMPDIR/home` (isolated) |
+| `ONLOOKER_DIR` | `$HOME/.onlooker` |
+| `ONLOOKER_EVENTS_LOG` | `$ONLOOKER_DIR/logs/onlooker-events.jsonl` (after `validate-path.sh` is sourced) |
+| `CLAUDE_HOME` | `$HOME/.claude` |
+| `REPO_ROOT` | the repo root (set when `setup.bash` is sourced) |
+
+### Dates: use `relative_iso_days_ago`, never a literal
+
+A hardcoded ISO date is a **time bomb** when the code under test computes a window from "now" (for example librarian's "now − `bootstrap_lookback_days`" scan window). The fixture passes today and silently fails once wall-clock now drifts past the threshold. Date such fixtures relative to now:
+
+```bash
+# yesterday, UTC — comfortably inside a 14-day lookback window
+created_at=$(relative_iso_days_ago 1)
+```
+
+`relative_iso_days_ago N` lives in `test/helpers/setup.bash` and returns an ISO-8601 UTC timestamp N days in the past (0 = now, negative = future). It uses `python3` for portable date math, since `date -d` (GNU) and `date -v` (BSD/macOS) disagree. For a plain "now" timestamp, `date -u +%Y-%m-%dT%H:%M:%SZ` is fine and portable; only the *offset* math needs the helper.
+
+### Resolve project keys through the plugin lib
+
+Artifacts are partitioned by a project key. Don't recompute the SHA — source the plugin's `*-project-key.sh` and call its function (`<plugin>_project_key <repo-root>`):
+
+```bash
+source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+ARTIFACT_DIR="${ONLOOKER_DIR}/<plugin>/${PROJECT_KEY}"
+```
+
+For key resolution to succeed the test needs a git context — stand up a throwaway repo in `setup()`:
+
+```bash
+PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+mkdir -p "$PROJECT_REPO"
+git -C "$PROJECT_REPO" init -q
+git -C "$PROJECT_REPO" config user.email t@example.com
+git -C "$PROJECT_REPO" config user.name "Test"
+git -C "$PROJECT_REPO" remote add origin git@github.com:org/fixture.git
+```
+
+### Stub the `claude` CLI on `PATH`
+
+Hooks that classify or judge shell out to `claude`. Stub it deterministically — branch on the prompt so each case returns a known response — and prepend the stub dir to `PATH`:
+
+```bash
+STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+mkdir -p "$STUB_BIN"
+cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+prompt=$(cat)
+if [[ "$prompt" == *"some-marker"* ]]; then
+  printf '%s' '{"type":"feedback","title":"...","body":"...","confidence":0.84}'
+else
+  printf '%s' '{"type":null,"title":"","body":"","confidence":0.2}'
+fi
+STUB
+chmod +x "${STUB_BIN}/claude"
+export PATH="${STUB_BIN}:${PATH}"
+```
+
+Same pattern stubs any external CLI a hook depends on (`curl`, `git`, …). Keep the responses minimal but schema-valid.
+
+### Build hook input with `jq`
+
+Hooks read a JSON payload on stdin. Build it with `jq -cn` and feed it in — don't hand-concatenate JSON strings:
+
+```bash
+_hook_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "sess-test" \
+    '{cwd: $cwd, session_id: $sid, hook_event_name: "SessionEnd"}'
+}
+
+run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+[ "$status" -eq 0 ]   # hooks must always exit 0 — they never block the session
+```
+
+### Assert against the event log
+
+Plugins communicate through the canonical JSONL event bus, so that's where you assert. Grep for the event type, then check the payload with `jq -e`:
+
+```bash
+grep '"event_type":"<plugin>.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+  | jq -e '.payload.outcome == "ok" and .payload.candidates_proposed == 2' >/dev/null
+```
+
+To assert an emitted line is a **schema-valid** envelope (not just present), pipe it through the canonical validator rather than eyeballing fields:
+
+```bash
+tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+  | ONLOOKER_DIR="$ONLOOKER_DIR" node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+```
+
+Production code must emit only through `scripts/lib/onlooker-event.mjs` (often via a plugin wrapper like `librarian_emit` / `assayer_emit_event`) — never by writing the log directly. New event types must be registered in `@onlooker-community/schema` before they validate.
+
+### Seed fixtures and generate IDs
+
+Write fixtures with `jq -n` into the plugin's project-keyed directory, and generate IDs with the plugin's `*-ulid.sh` (ULIDs, not UUIDs — a repo-wide convention). A typical artifact seeder:
+
+```bash
+_seed_artifact() {
+  local kind="$1" id="$2" summary="$3" detail="$4" created_at="${5:-$(relative_iso_days_ago 1)}"
+  mkdir -p "${ARTIFACT_DIR}/${kind}"
+  jq -n --arg id "$id" --arg summary "$summary" --arg detail "$detail" \
+        --arg created_at "$created_at" \
+    '{ id: $id, created_at: $created_at, updated_at: $created_at,
+       summary: $summary, detail: $detail }' \
+    > "${ARTIFACT_DIR}/${kind}/${id}.json"
+}
+```
+
+## Anti-patterns
+
+Don't hand-roll these — each has bitten the suite before:
+
+- **Hardcoded dates in window-sensitive fixtures.** Use `relative_iso_days_ago`. A literal like `2026-06-01T12:00:00Z` aged out of librarian's lookback window and broke two tests the day wall-clock now crossed it.
+- **Literal `~/.onlooker` or `$HOME`.** Always `$ONLOOKER_DIR` and the `validate-path.sh` exports, so the isolated temp home is honored.
+- **Reimplementing the project key, ULID, or event envelope.** Source the plugin lib (`*-project-key.sh`, `*-ulid.sh`) and emit through `onlooker-event.mjs`.
+- **Concatenating JSON by hand.** Build payloads and hook input with `jq -n` / `jq -cn --arg`.
+- **Asserting on log lines with `grep` substring matches alone** when you mean "valid event" — validate the envelope with `onlooker-event.mjs validate`.
+- **Expecting a hook to exit non-zero.** Hooks fail soft and exit 0; assert on emitted events or absent side effects, not exit codes.
+
+## Node tests
+
+`test/node/*.test.mjs` use the built-in `node:test` runner and `node:assert/strict` — no external framework. They cover schema mapping (`schema-events.test.mjs`), manifest validation (`check-manifests.test.mjs`), and cross-references (`check-references.test.mjs`), driven by fixtures under `test/fixtures/`.
+
+```javascript
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+test('maps PostToolUse Read to tool.file.read', () => {
+  const mapped = mapHookInputToCanonical(loadFixture('post-tool-use-read.json'), { plugin: 'onlooker' });
+  assert.equal(mapped.valid, true);
+  assert.equal(mapped.event.event_type, 'tool.file.read');
+});
+```
+
+Prefer adding a fixture under `test/fixtures/` and asserting the mapping over inlining large JSON literals. Run with `npm run test:schema`.
+
+## Adding tests for a new plugin
+
+1. Create `test/bats/<plugin>-<surface>.bats` (e.g. `<plugin>-session-end.bats`).
+2. `setup()`: source `setup.bash`, call `setup_test_env`, set `PLUGIN_ROOT` / `CLAUDE_PLUGIN_ROOT`, stand up a fixture git repo, resolve the project key via the plugin lib.
+3. Stub `claude` (and any other CLI) on `PATH` if the hook shells out.
+4. Drive the hook with `jq`-built input; assert on `$ONLOOKER_EVENTS_LOG` and on-disk artifacts.
+5. Date any window-sensitive fixture with `relative_iso_days_ago`.
+6. Run `npm run test:ci` before opening the PR — it adds shellcheck and the manifest/reference linters on top of the tests.

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.29.1",
+  "version": "0.29.3",
   "description": "Observability substrate for Claude Code. Provides the shared $ONLOOKER_DIR storage root (default $HOME/.onlooker), canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
   "author": {
     "name": "Onlooker Community",

package/.release-please-manifest.json

@@ -1,5 +1,5 @@
 {
-  ".": "0.29.1",
+  ".": "0.29.3",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -13,7 +13,7 @@
   "plugins/curator": "0.1.0",
   "plugins/historian": "0.2.0",
   "plugins/assayer": "1.0.0",
-  "plugins/bursar": "0.1.0",
+  "plugins/bursar": "0.1.1",
   "plugins/lineage": "0.1.0",
   "plugins/inspector": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.29.3](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.29.2...ecosystem-v0.29.3) (2026-06-24)
+
+
+### Performance Improvements
+
+* **bursar:** collapse process forks in SessionEnd hot path :relieved: ([#101](https://github.com/onlooker-community/ecosystem/issues/101)) ([7a426fe](https://github.com/onlooker-community/ecosystem/commit/7a426fe359785eca35ea1ad61523b05fda79e0da))
+
+## [0.29.2](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.29.1...ecosystem-v0.29.2) (2026-06-21)
+
+
+### Bug Fixes
+
+* **emitter:** make emission dependency-free and fail-open :relieved: ([#99](https://github.com/onlooker-community/ecosystem/issues/99)) ([0dda7f8](https://github.com/onlooker-community/ecosystem/commit/0dda7f803ed2dfa28561bd8d9e4193b2b18e5bbf))
+
 ## [0.29.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.29.0...ecosystem-v0.29.1) (2026-06-15)
 
 

package/CLAUDE.md

@@ -73,7 +73,7 @@ See `plugins/compass/docs/adr/001-evaluate-prompts-in-context.md` for the full d
 2. Use `scripts/lib/onlooker-event.mjs` for all event emission — never write directly to the JSONL log.
 3. Store runtime artifacts under `${ONLOOKER_DIR:-$HOME/.onlooker}/<name>/<project-key>/`. Always use `$ONLOOKER_DIR` — never hardcode `~/.onlooker` — so the test suite's isolated temp home is respected.
 4. Derive the project key via `tribunal_project_key` (or equivalent) — first 12 hex chars of SHA256(`remote:<origin-url>`), falling back to SHA256(`root:<repo-root>`) for repos without a remote. See `plugins/tribunal/scripts/lib/tribunal-project-key.sh`.
-5. Register event types in `@onlooker-community/schema` before emitting them (the emitter validates the envelope).
+5. Register event types in `@onlooker-community/schema` before emitting them. The runtime emitter is dependency-free and **fails open**: it validates against the schema package only when that package is resolvable (dev, CI, tests) and emits unconditionally otherwise, because installed marketplace plugins ship no `node_modules`. Schema drift is caught in CI against the published schemas at `schema.onlooker.dev`. See [ADR-005](docs/adr/005-runtime-emitter-fails-open.md).
 6. Fail-soft when `~/.onlooker/` is absent — plugins must not block a session they were not invited to.
 
 ## Development

package/docs/adr/002-centralized-jsonl-event-log.md

@@ -1,7 +1,8 @@
 # ADR-002: Centralized JSONL Event Log with Schema Validation
 
 **Status:** Accepted  
-**Date:** 2026-05-24
+**Date:** 2026-05-24  
+**Amended by:** [ADR-005](005-runtime-emitter-fails-open.md) — runtime validation was moved off the hot path; the emitter now fails open. The "schema validation at write time" rationale below holds only for dev/CI, not installed plugins.
 
 ## Context
 

package/docs/adr/005-runtime-emitter-fails-open.md

@@ -0,0 +1,46 @@
+# ADR-005: The Runtime Emitter Is Dependency-Free and Fails Open
+
+**Status:** Accepted  
+**Date:** 2026-06-20  
+**Amends:** [ADR-002](002-centralized-jsonl-event-log.md)
+
+## Context
+
+The canonical emitter `scripts/lib/onlooker-event.mjs` built each event envelope and **validated it against `@onlooker-community/schema` before printing it** (ADR-002: "schema validation at write time prevents silent corruption"). `@onlooker-community/schema` was a runtime `dependency`, and it pulls in `ajv` + `ajv-formats`. The package also reads its JSON schema files from disk at import time.
+
+This assumed `node_modules` would be present wherever a hook runs. It is not. **Claude Code installs a marketplace plugin by cloning the marketplace repo; it never runs `npm install`.** `node_modules/` is git-ignored, so the installed plugin ships none. Every emission therefore ran:
+
+```
+node scripts/lib/onlooker-event.mjs emit
+  └─ import '@onlooker-community/schema'  →  ERR_MODULE_NOT_FOUND  →  exit 1
+```
+
+The bash side of each hook kept working (hook-health, per-session trackers need no node), so hooks looked healthy while **every event was silently dropped**. In one observed case `~/.onlooker/logs/onlooker-events.jsonl` received nothing for 18 days. Fail-closed validation, intended to prevent "silent corruption," instead produced total silent loss — a strictly worse failure than the one it guarded against.
+
+Mechanisms considered to make the dependency available in the install: vendor a committed `node_modules`, bundle the emitter + `ajv` into one file with esbuild, or a self-healing `SessionStart` hook that runs `npm install`. Each ships or fetches a validator with the plugin and carries cost (repo bloat, a build step, or a network dependency on every fresh install).
+
+## Decision
+
+**The runtime emitter has zero external dependencies and fails open.** Validation is best-effort, not a gate:
+
+- `createEvent` (envelope assembly) and the event-type constants are **inlined** into `onlooker-event.mjs` — pure `node:` stdlib, no package import.
+- Validation is attempted via a lazy `await import('@onlooker-community/schema')`. When the package resolves (dev, CI, tests) the emitter validates and **rejects** invalid events. When it does not resolve (installed plugins) the emitter **emits anyway**.
+- `@onlooker-community/schema` moves from `dependencies` to `devDependencies`.
+- A CI test (`test/node/schema-published.test.mjs`) validates representative emitter output against the canonical schemas **published at `https://schema.onlooker.dev`** — the contract downstream consumers actually enforce. It skips when the endpoint is unreachable.
+
+## Rationale
+
+**Observability must not be fragile.** A telemetry pipeline that deletes everything when a dependency is missing — or when a payload drifts from the schema — is worse than one that records a slightly-off event. For an observability substrate, fail-open is the correct default: capture the signal, surface problems out-of-band.
+
+**Best-effort keeps the dev-time guard.** The same lazy import that degrades gracefully in production still gates strictly wherever the validator is installed. The negative tests across the plugins ("emission fails loudly on a bogus event_type") keep passing because CI runs with dev dependencies present. We lose nothing in the loop that catches mistakes, and gain resilience where mistakes are unrecoverable.
+
+**Validation belongs where it can act, not on the hot path.** A hook firing on every tool call cannot meaningfully respond to a validation failure except by dropping data. CI can: a red test blocks the release. Moving the authoritative check to CI — against the *published* schemas, not just the pinned npm copy — catches drift between what the emitter produces and what the deployed contract accepts.
+
+**No artifact to ship or fetch.** Dependency-free is simpler than vendoring a `node_modules`, bundling with esbuild, or bootstrapping `npm install` at session start. There is nothing to keep in sync, nothing to build, and the install works offline.
+
+## Consequences
+
+- The JSONL log may, in an installed plugin, contain an event that violates the schema if a payload builder drifts. Downstream consumers (the onlooker agent, the backend) validate on ingest; CI catches drift before release. This is the accepted cost of fail-open.
+- `node` is still required to emit (the emitter is JS), but **no npm packages are**. Hooks that shell out to `onlooker-event.mjs` work on a fresh clone with nothing installed.
+- The `validate` CLI subcommand and `onlooker_validate_event` still require the dev dependency; they are used only by the test suite, never on a runtime hook path.
+- `test:schema` now makes a network call to `schema.onlooker.dev`. It skips cleanly offline, so local and air-gapped runs are unaffected; CI with egress exercises the live contract.

package/docs/architecture.md

@@ -22,7 +22,7 @@ flowchart TB
         echo --> emitter
         cartographer --> emitter
 
-        emitter -->|"schema-validated<br/>event envelope"| log
+        emitter -->|"event envelope<br/>(validated in dev/CI)"| log
         log -.->|"append-only JSONL"| log
     end
 ```
@@ -34,7 +34,7 @@ The `ecosystem` plugin (repo root) is not optional — it provides the infrastru
 | Component | What it does |
 |-----------|-------------|
 | `~/.onlooker/` directory | Shared storage root, created by the Onlooker installer. All plugins store artifacts here under their own sub-path. |
-| `scripts/lib/onlooker-event.mjs` | Canonical event builder. Accepts a JSON payload on stdin, validates it against `@onlooker-community/schema`, and prints the validated envelope to stdout. Callers capture the output and append it to the JSONL log. |
+| `scripts/lib/onlooker-event.mjs` | Canonical event builder. Accepts a JSON payload on stdin and prints a canonical envelope to stdout; callers capture it and append to the JSONL log. **Dependency-free and fail-open**: it validates against `@onlooker-community/schema` only when that package is resolvable (dev/CI) and emits unconditionally otherwise, so a fresh marketplace install — which ships no `node_modules` — never loses telemetry. See [ADR-005](adr/005-runtime-emitter-fails-open.md). |
 | `scripts/lib/onlooker-schema.sh` | Bash convenience wrapper around `onlooker-event.mjs`. Provides `onlooker_event_from_hook` (builds an envelope via `node`) and `onlooker_append_event` (appends a pre-built envelope to the log). Node is still required. |
 | `scripts/lib/validate-path.sh` | Sets canonical `$ONLOOKER_*` environment variables (log path, tracker dirs, etc.) so every hook uses consistent paths. |
 | Session trackers | `SessionStart`, `SessionEnd`, `PreCompact`, `PostCompact`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, and `WorktreeRemove` hooks that emit `session.*`, `tool.*`, `turn.*` events for the observability layer. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.29.1",
+  "version": "0.29.3",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -18,9 +18,6 @@
   "bin": {
     "onlooker-install": "install.sh"
   },
-  "dependencies": {
-    "@onlooker-community/schema": "^2.9.0"
-  },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
     "test": "npm run test:bats && npm run test:schema",
@@ -45,6 +42,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
+    "@onlooker-community/schema": "^2.9.0",
     "globals": "^17.6.0",
     "markdownlint-cli": "^0.48.0"
   }

package/plugins/bursar/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bursar",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Multi-session, per-project budget accounting for the Onlooker ecosystem. Rolls each session's spend into a per-project ledger on SessionEnd and surfaces \"this project burned $X this week\" at SessionStart. Where governor regulates a single session, bursar is the cross-session rollup: it reads governor.session.complete off the shared event bus and emits bursar.* events for audit. Named for the officer who keeps the accounts. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/bursar/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.1](https://github.com/onlooker-community/ecosystem/compare/bursar-v0.1.0...bursar-v0.1.1) (2026-06-24)
+
+
+### Performance Improvements
+
+* **bursar:** collapse process forks in SessionEnd hot path :relieved: ([#101](https://github.com/onlooker-community/ecosystem/issues/101)) ([7a426fe](https://github.com/onlooker-community/ecosystem/commit/7a426fe359785eca35ea1ad61523b05fda79e0da))
+
 ## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/bursar-v0.0.1...bursar-v0.1.0) (2026-06-12)
 
 

package/plugins/bursar/scripts/hooks/bursar-session-end.sh

@@ -33,11 +33,12 @@ source "${PLUGIN_ROOT}/scripts/lib/bursar-project-key.sh"
 source "${PLUGIN_ROOT}/scripts/lib/bursar-ledger.sh"
 
 INPUT=$(cat)
-SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
-CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
 
 _done() { exit 0; }
 
+# Parse session_id and cwd in a single jq pass (one fork, not two).
+{ IFS= read -r SESSION_ID; IFS= read -r CWD; } < <(printf '%s' "$INPUT" | jq -r '.session_id // "", .cwd // ""' 2>/dev/null)
+
 [[ -z "$SESSION_ID" ]] && _done
 
 ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
@@ -47,11 +48,13 @@ TRACKER="${ONLOOKER_DIR}/session-trackers/${SESSION_ID}"
 
 # -----------------------------------------------------------------------
 # Resolve project key + cwd: breadcrumb → substrate tracker → live cwd.
+# The breadcrumb (dropped at SessionStart) usually carries both, which lets us
+# skip the git + shasum project-key derivation entirely in the common case.
 # -----------------------------------------------------------------------
 PROJECT_KEY=""
 if [[ -f "$BREADCRUMB" ]]; then
-	PROJECT_KEY=$(jq -r '.project_key // ""' "$BREADCRUMB" 2>/dev/null) || PROJECT_KEY=""
-	[[ -z "$CWD" ]] && CWD=$(jq -r '.cwd // ""' "$BREADCRUMB" 2>/dev/null)
+	{ IFS= read -r PROJECT_KEY; IFS= read -r bc_cwd; } < <(jq -r '.project_key // "", .cwd // ""' "$BREADCRUMB" 2>/dev/null)
+	[[ -z "$CWD" ]] && CWD="$bc_cwd"
 fi
 if [[ -z "$CWD" && -f "$TRACKER" ]]; then
 	CWD=$(jq -r '.cwd // ""' "$TRACKER" 2>/dev/null) || CWD=""
@@ -74,66 +77,74 @@ COST=""
 TOKENS=""
 CALLS=""
 
-# Reads event-log lines on stdin; echoes the latest matching session.complete payload.
-_latest_governor_payload() {
+# Reads event-log lines on stdin; emits one TSV line "cost<TAB>tokens<TAB>calls"
+# for the latest governor.session.complete matching this session (empty if none).
+# grep pre-filters so jq only parses the handful of matching lines, and the
+# field extraction happens in the same jq pass that selects the latest match —
+# replacing the prior select + three separate jq extractions.
+_latest_governor_spend() {
 	grep -F '"governor.session.complete"' 2>/dev/null \
-		| jq -c --arg sid "$SESSION_ID" \
-			'select(.event_type == "governor.session.complete" and .payload.session_id == $sid) | .payload' \
-			2>/dev/null \
-		| tail -n 1
+		| jq -rs --arg sid "$SESSION_ID" '
+			[ .[]
+			  | select(.event_type == "governor.session.complete" and .payload.session_id == $sid)
+			  | .payload ]
+			| if length == 0 then empty
+			  else (.[-1] | [(.total_cost_usd // ""), (.total_tokens // ""), (.total_api_calls // "")] | @tsv)
+			  end' \
+			2>/dev/null
 }
 
 if [[ -f "$LOG" ]]; then
 	# The matching event was emitted seconds ago (governor's final Stop), so it is
 	# almost always near the tail. Scan a recent slice first to keep this hook
 	# fast as the global log grows; fall back to the full file only on a miss.
-	SPEND=$(tail -n 2000 "$LOG" 2>/dev/null | _latest_governor_payload)
-	[[ -z "$SPEND" ]] && SPEND=$(_latest_governor_payload < "$LOG")
+	SPEND=$(tail -n 2000 "$LOG" 2>/dev/null | _latest_governor_spend)
+	[[ -z "$SPEND" ]] && SPEND=$(_latest_governor_spend < "$LOG")
 	if [[ -n "$SPEND" ]]; then
 		GOV_PRESENT="true"
-		COST=$(printf '%s' "$SPEND" | jq -r '.total_cost_usd // empty' 2>/dev/null) || COST=""
-		TOKENS=$(printf '%s' "$SPEND" | jq -r '.total_tokens // empty' 2>/dev/null) || TOKENS=""
-		CALLS=$(printf '%s' "$SPEND" | jq -r '.total_api_calls // empty' 2>/dev/null) || CALLS=""
+		IFS=$'\t' read -r COST TOKENS CALLS <<<"$SPEND"
 	fi
 fi
 
 MODEL=""
 [[ -f "$TRACKER" ]] && MODEL=$(jq -r '.model // ""' "$TRACKER" 2>/dev/null)
 
+# One date fork yields both the epoch and the RFC3339 stamp (was two).
+{ IFS= read -r NOW_EPOCH; IFS= read -r NOW_ISO; } < <(date -u +'%s%n%Y-%m-%dT%H:%M:%SZ' 2>/dev/null)
+[[ -z "$NOW_EPOCH" ]] && NOW_EPOCH=0
+
 # -----------------------------------------------------------------------
-# Build the record and the event payload, attaching spend fields only when
-# governor supplied them.
+# Build the ledger record AND the (smaller) event payload in a single jq pass.
+# Spend fields are passed as strings and coerced with tonumber so an empty value
+# is simply omitted — replacing the per-field add_fields() helper that forked a
+# jq for every field, twice. The event payload is the record minus the
+# ledger-only ts/ts_epoch fields.
 # -----------------------------------------------------------------------
-add_fields() {
-	# Echoes the input JSON ($1) with cost/tokens/calls/model merged in.
-	local base="$1"
-	[[ -n "$COST" ]] && base=$(printf '%s' "$base" | jq --argjson v "$COST" '. + {cost_usd: $v}' 2>/dev/null)
-	[[ -n "$TOKENS" ]] && base=$(printf '%s' "$base" | jq --argjson v "$TOKENS" '. + {tokens: $v}' 2>/dev/null)
-	[[ -n "$CALLS" ]] && base=$(printf '%s' "$base" | jq --argjson v "$CALLS" '. + {api_calls: $v}' 2>/dev/null)
-	[[ -n "$MODEL" ]] && base=$(printf '%s' "$base" | jq --arg v "$MODEL" '. + {model: $v}' 2>/dev/null)
-	printf '%s' "$base"
-}
-
-RECORD=$(jq -n \
-	--arg ts "$(bursar_now_iso)" \
-	--argjson te "$(bursar_now_epoch)" \
+{ IFS= read -r RECORD; IFS= read -r EV; } < <(jq -rn \
+	--arg ts "$NOW_ISO" \
+	--argjson te "$NOW_EPOCH" \
 	--arg sid "$SESSION_ID" \
 	--arg pk "$PROJECT_KEY" \
 	--argjson gp "$GOV_PRESENT" \
-	'{ts: $ts, ts_epoch: $te, session_id: $sid, project_key: $pk, governor_present: $gp}' 2>/dev/null)
-RECORD=$(add_fields "$RECORD")
+	--arg cost "$COST" \
+	--arg tokens "$TOKENS" \
+	--arg calls "$CALLS" \
+	--arg model "$MODEL" \
+	'
+	( {ts: $ts, ts_epoch: $te, session_id: $sid, project_key: $pk, governor_present: $gp}
+	  + (if $cost   != "" then {cost_usd:  ($cost   | tonumber)} else {} end)
+	  + (if $tokens != "" then {tokens:    ($tokens | tonumber)} else {} end)
+	  + (if $calls  != "" then {api_calls: ($calls  | tonumber)} else {} end)
+	  + (if $model  != "" then {model: $model} else {} end)
+	) as $record
+	| ($record | tojson), ($record | del(.ts, .ts_epoch) | tojson)
+	' 2>/dev/null)
 
 # Only claim the session was recorded — and only drop the breadcrumb — once the
 # ledger upsert actually succeeds. A failed write (lock timeout, mv failure)
 # must keep the breadcrumb so the session→project attribution survives for a
 # later attempt rather than being lost behind a false "recorded" event.
 if [[ -n "$RECORD" ]] && bursar_ledger_record "$PROJECT_KEY" "$RECORD"; then
-	EV=$(jq -n \
-		--arg pk "$PROJECT_KEY" \
-		--arg sid "$SESSION_ID" \
-		--argjson gp "$GOV_PRESENT" \
-		'{project_key: $pk, session_id: $sid, governor_present: $gp}' 2>/dev/null)
-	EV=$(add_fields "$EV")
 	[[ -n "$EV" ]] && bursar_emit_event "bursar.session.recorded" "$EV" "$SESSION_ID" || true
 
 	rm -f "$BREADCRUMB" 2>/dev/null || true

package/plugins/bursar/scripts/lib/bursar-config.sh

@@ -21,40 +21,43 @@ bursar_config_load() {
 	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
 	local home_dir="${HOME:-}"
 
-	local merged="{}"
-	local file
+	# Read each layer's raw text with the no-fork `$(<file)` builtin (NOT `cat`),
+	# then deep-merge all three layers in a SINGLE jq invocation. The dominant
+	# cost in the SessionEnd hook is jq process startup, not the merge itself, so
+	# this collapses what was one-jq-per-file (up to 6 forks) down to one.
+	local default_txt="" home_txt="" repo_txt=""
+	local default_file="${plugin_root}/config.json"
+	local home_file="${home_dir}/.claude/settings.json"
+	local repo_file=""
+	[[ -n "$repo_root" ]] && repo_file="${repo_root}/.claude/settings.json"
 
-	file="${plugin_root}/config.json"
-	if [[ -f "$file" ]]; then
-		local defaults
-		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
-		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
-			|| merged="$defaults"
-	fi
+	[[ -f "$default_file" ]] && default_txt="$(<"$default_file")"
+	[[ -f "$home_file" ]] && home_txt="$(<"$home_file")"
+	[[ -n "$repo_file" && -f "$repo_file" ]] && repo_txt="$(<"$repo_file")"
 
-	local repo_settings=""
-	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
-
-	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
-		[[ -n "$file" && -f "$file" ]] || continue
-		local overlay
-		overlay=$(jq '{ bursar: (.bursar // {}) }' "$file" 2>/dev/null) || continue
-		[[ -z "$overlay" ]] && continue
-		local attempt
-		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
-			def deepmerge($a; $b):
-				if ($a|type) == "object" and ($b|type) == "object" then
-					reduce (($a|keys) + ($b|keys) | unique)[] as $k
-						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
-				elif $b == null then $a
-				else $b end;
-			deepmerge($a; $b)
-		' 2>/dev/null) && [[ -n "$attempt" ]]; then
-			merged="$attempt"
-		fi
-	done
-
-	_BURSAR_CONFIG="$merged"
+	# Precedence (latest wins): defaults < home settings < repo settings. The
+	# defaults file is merged whole; settings files contribute only their .bursar
+	# key. `fromjson? // {}` parses each layer defensively — a missing or malformed
+	# file degrades to {} rather than aborting the merge (matches the prior
+	# per-file fallback).
+	_BURSAR_CONFIG=$(jq -n \
+		--arg d "$default_txt" \
+		--arg h "$home_txt" \
+		--arg r "$repo_txt" \
+		'
+		def deepmerge($a; $b):
+			if ($a|type) == "object" and ($b|type) == "object" then
+				reduce (($a|keys) + ($b|keys) | unique)[] as $k
+					({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+			elif $b == null then $a
+			else $b end;
+		($d | fromjson? // {}) as $defaults
+		| (($h | fromjson? // {}) | {bursar: (.bursar // {})}) as $home
+		| (($r | fromjson? // {}) | {bursar: (.bursar // {})}) as $repo
+		| deepmerge(deepmerge($defaults; $home); $repo)
+		' 2>/dev/null) || _BURSAR_CONFIG="{}"
+	[[ -z "$_BURSAR_CONFIG" ]] && _BURSAR_CONFIG="{}"
+	return 0
 }
 
 bursar_config_get() {

package/plugins/bursar/scripts/lib/bursar-ledger.sh

@@ -55,12 +55,13 @@ bursar_ledger_record() {
 	local record="${2:-}"
 	[[ -z "$project_key" || -z "$record" ]] && return 1
 
-	local sid
-	sid=$(printf '%s' "$record" | jq -r '.session_id // empty' 2>/dev/null) || sid=""
-	[[ -z "$sid" ]] && return 1
-
-	local record_compact
-	record_compact=$(printf '%s' "$record" | jq -c . 2>/dev/null) || return 1
+	# Pull the session_id and the compacted record out in a single jq pass:
+	# line 1 is the key, line 2 is the line we will write.
+	local sid record_compact
+	{ IFS= read -r sid; IFS= read -r record_compact; } < <(
+		printf '%s' "$record" | jq -r '.session_id // empty, tojson' 2>/dev/null
+	)
+	[[ -z "$sid" || -z "$record_compact" ]] && return 1
 
 	local dir ledger_path lock_path
 	dir=$(bursar_ledger_dir "$project_key")

package/scripts/lib/onlooker-event.mjs

@@ -6,20 +6,24 @@
 import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-  createEvent,
-  SKILL_INVOKED,
-  TASK_COMPLETE,
-  TASK_START,
-  TOOL_AGENT_COMPLETE,
-  TOOL_AGENT_SPAWN,
-  TOOL_FILE_EDIT,
-  TOOL_FILE_READ,
-  TOOL_FILE_WRITE,
-  TOOL_SHELL_EXEC,
-  TOOL_WEB_FETCH,
-  validate,
-} from '@onlooker-community/schema';
+
+// Canonical event-type constants, inlined rather than imported from
+// @onlooker-community/schema so this emitter has ZERO runtime dependencies.
+// Claude Code installs plugins by cloning the marketplace repo and never runs
+// `npm install`, so an installed plugin has no node_modules — a runtime import
+// of the schema package fails with ERR_MODULE_NOT_FOUND and silently kills all
+// telemetry. The full contract still lives in @onlooker-community/schema; it is
+// now a devDependency used to validate emitter output in CI (see tryValidate).
+const SKILL_INVOKED = 'skill.invoked';
+const TASK_START = 'task.start';
+const TASK_COMPLETE = 'task.complete';
+const TOOL_AGENT_COMPLETE = 'tool.agent.complete';
+const TOOL_AGENT_SPAWN = 'tool.agent.spawn';
+const TOOL_FILE_EDIT = 'tool.file.edit';
+const TOOL_FILE_READ = 'tool.file.read';
+const TOOL_FILE_WRITE = 'tool.file.write';
+const TOOL_SHELL_EXEC = 'tool.shell.exec';
+const TOOL_WEB_FETCH = 'tool.web.fetch';
 
 export function ensureMachineId(onlookerDir) {
   const path = join(onlookerDir, 'machine_id');
@@ -55,21 +59,52 @@ export function buildCanonicalEvent({
   cost_usd,
   token_count,
 }) {
-  const event = createEvent({
+  // Envelope assembly inlined from @onlooker-community/schema's createEvent so
+  // emission needs no external package. The schema is the source of truth for
+  // this shape; CI validates against it (see test/node/schema-*.test.mjs).
+  const event = {
+    id: randomUUID(),
+    schema_version: '1.0',
     runtime,
-    adapter_id,
     plugin,
     machine_id: ensureMachineId(onlookerDir),
+    timestamp: new Date().toISOString(),
     session_id,
+    sequence: nextSequence(onlookerDir),
     event_type,
     payload,
-    cost_usd,
-    token_count,
-  });
-  event.sequence = nextSequence(onlookerDir);
+    redacted: false,
+  };
+  if (adapter_id !== undefined) event.adapter_id = adapter_id;
+  if (cost_usd !== undefined) event.cost_usd = cost_usd;
+  if (token_count !== undefined) event.token_count = token_count;
   return event;
 }
 
+/**
+ * Best-effort schema validation.
+ *
+ * @onlooker-community/schema is a devDependency, so it resolves in dev, CI, and
+ * tests — where we DO want emitter output gated against the contract (this is
+ * what the negative tests across the plugins rely on) — but is absent in an
+ * installed marketplace plugin. When it is absent we fail OPEN: build and emit
+ * anyway, so schema drift can never silently kill telemetry the way a hard
+ * runtime dependency did. Drift is caught in CI, which validates emitter output
+ * against the published schemas at https://schema.onlooker.dev.
+ *
+ * Returns { available: false } when no validator is installed, otherwise the
+ * { valid, errors? } result from the schema package.
+ */
+async function tryValidate(event) {
+  let schema;
+  try {
+    schema = await import('@onlooker-community/schema');
+  } catch {
+    return { available: false };
+  }
+  return { available: true, ...schema.validate(event) };
+}
+
 function summarizeText(value, maxLen = 1000) {
   if (value == null) return undefined;
   const text = String(value).replace(/\s+/g, ' ').trim();
@@ -219,11 +254,7 @@ export function mapSkillHookInput(hookInput, options) {
     payload,
   });
 
-  const result = validate(event);
-  if (!result.valid) {
-    return { valid: false, errors: result.errors, event_type: SKILL_INVOKED };
-  }
-  return { valid: true, event: result.event };
+  return { valid: true, event };
 }
 
 /**
@@ -269,11 +300,7 @@ export function mapTaskHookInput(hookInput, options) {
     payload,
   });
 
-  const result = validate(event);
-  if (!result.valid) {
-    return { valid: false, errors: result.errors, event_type: eventType };
-  }
-  return { valid: true, event: result.event };
+  return { valid: true, event };
 }
 
 /**
@@ -322,11 +349,7 @@ export function mapWorktreeHookInput(hookInput, options) {
     payload,
   });
 
-  const result = validate(event);
-  if (!result.valid) {
-    return { valid: false, errors: result.errors, event_type: TOOL_SHELL_EXEC };
-  }
-  return { valid: true, event: result.event };
+  return { valid: true, event };
 }
 
 /**
@@ -444,11 +467,7 @@ export function mapHookInputToCanonical(hookInput, options) {
     payload,
   });
 
-  const result = validate(event);
-  if (!result.valid) {
-    return { valid: false, errors: result.errors, event_type: eventType };
-  }
-  return { valid: true, event: result.event };
+  return { valid: true, event };
 }
 
 function readStdin() {
@@ -468,12 +487,16 @@ async function main() {
   if (command === 'validate') {
     const raw = await readStdin();
     const parsed = JSON.parse(raw || '{}');
-    const result = validate(parsed);
-    if (!result.valid) {
-      console.error(JSON.stringify(result.errors, null, 2));
+    const check = await tryValidate(parsed);
+    if (!check.available) {
+      console.error('@onlooker-community/schema is not installed; cannot validate');
+      process.exit(1);
+    }
+    if (!check.valid) {
+      console.error(JSON.stringify(check.errors, null, 2));
       process.exit(1);
     }
-    console.log(JSON.stringify(result.event));
+    console.log(JSON.stringify(parsed));
     return;
   }
 
@@ -484,8 +507,11 @@ async function main() {
     if (!mapped) {
       process.exit(0);
     }
-    if (!mapped.valid) {
-      console.error(JSON.stringify(mapped.errors, null, 2));
+    // Best-effort: reject when a validator is present (dev/CI), fail open in
+    // installed plugins so the event is still emitted.
+    const check = await tryValidate(mapped.event);
+    if (check.available && !check.valid) {
+      console.error(JSON.stringify(check.errors, null, 2));
       process.exit(1);
     }
     console.log(JSON.stringify(mapped.event));
@@ -509,12 +535,14 @@ async function main() {
       event_type: params.event_type,
       payload: params.payload,
     });
-    const result = validate(event);
-    if (!result.valid) {
-      console.error(JSON.stringify(result.errors, null, 2));
+    // Best-effort: reject when a validator is present (dev/CI), fail open in
+    // installed plugins so the event is still emitted.
+    const check = await tryValidate(event);
+    if (check.available && !check.valid) {
+      console.error(JSON.stringify(check.errors, null, 2));
       process.exit(1);
     }
-    console.log(JSON.stringify(result.event));
+    console.log(JSON.stringify(event));
     return;
   }
 

package/test/bats/librarian-session-end.bats

@@ -65,10 +65,10 @@ STUB
 
   # On its first scan the hook has no watermark and falls back to a relative
   # "now - bootstrap_lookback_days" window (default 14 days). Fixtures must be
-  # dated inside that window or the scan sees nothing. Compute a recent
-  # timestamp at runtime — a hardcoded date silently ages out of the window
-  # and turns these tests into a time bomb. One day back keeps a wide margin.
-  FIXTURE_CREATED_AT=$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")
+  # dated inside that window or the scan sees nothing, so date them relative to
+  # now — one day back keeps a wide margin. See relative_iso_days_ago in
+  # test/helpers/setup.bash for why a hardcoded date is a time bomb here.
+  FIXTURE_CREATED_AT=$(relative_iso_days_ago 1)
 }
 
 # Helper: write an archivist artifact for the project.

package/test/helpers/setup.bash

@@ -31,6 +31,29 @@ setup_test_env() {
   unset XDG_CONFIG_HOME
 }
 
+# Produce an ISO-8601 UTC timestamp offset from "now" by N days into the past.
+# Positive N = N days ago, 0 = now, negative N = N days in the future.
+#
+# Use this for any fixture whose date must fall inside a relative window the
+# code computes from "now" (e.g. a "now - lookback_days" scan window). A
+# hardcoded ISO date silently ages out of such a window and turns the test
+# into a time bomb that passes today and fails on some future date. Always
+# date those fixtures relative to now.
+#
+# Uses python3 (already a hook dependency) for portable date math — `date -d`
+# vs `date -v` diverges between GNU and BSD/macOS.
+#
+# Usage: created_at=$(relative_iso_days_ago 1)   # yesterday, UTC
+relative_iso_days_ago() {
+  local days="${1:-0}"
+  python3 -c '
+import datetime, sys
+delta = datetime.timedelta(days=int(sys.argv[1]))
+now = datetime.datetime.now(datetime.timezone.utc)
+print((now - delta).strftime("%Y-%m-%dT%H:%M:%SZ"))
+' "$days"
+}
+
 # Source validate-path.sh with test env vars already set.
 load_validate_path() {
   setup_test_env

package/test/node/schema-published.test.mjs

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import _addFormats from 'ajv-formats';
+import { buildCanonicalEvent } from '../../scripts/lib/onlooker-event.mjs';
+
+// The runtime emitter is dependency-free and fails open (it never drops events
+// in an installed plugin — see scripts/lib/onlooker-event.mjs). This test is the
+// other half of that contract: it proves the emitter's output still conforms to
+// the canonical schemas PUBLISHED at https://schema.onlooker.dev — the contract
+// downstream consumers (the onlooker agent, the backend) actually validate
+// against. Schema drift that would silently pass at runtime is caught here.
+//
+// Network-resilient: when the published endpoint is unreachable (offline dev,
+// CI without egress) the test skips rather than failing red.
+
+const addFormats = _addFormats.default ?? _addFormats;
+const BASE = 'https://schema.onlooker.dev/schemas';
+
+async function fetchJson(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
+  if (!res.ok) throw new Error(`${url} -> HTTP ${res.status}`);
+  return res.json();
+}
+
+// Representative events the emitter produces, paired with the payload schema
+// file each event family maps to.
+const SAMPLES = [
+  {
+    event_type: 'session.start',
+    payloadFile: 'session.json',
+    payload: { working_directory: '/tmp', git_branch: 'main' },
+  },
+  { event_type: 'session.prompt', payloadFile: 'session.json', payload: { turn_number: 2, input_summary: 'hello' } },
+  { event_type: 'tool.shell.exec', payloadFile: 'tool.json', payload: { command: 'ls -la', exit_code: 0 } },
+  {
+    event_type: 'skill.invoked',
+    payloadFile: 'skill.json',
+    payload: { skill_name: 'commit', invocation_source: 'tool' },
+  },
+  { event_type: 'task.start', payloadFile: 'task.json', payload: { task_summary: 'implement the thing' } },
+];
+
+test('emitter output conforms to the published schemas at schema.onlooker.dev', async (t) => {
+  let envelope;
+  const payloadDocs = new Map();
+  try {
+    envelope = await fetchJson(`${BASE}/event.v1.json`);
+    for (const file of new Set(SAMPLES.map((s) => s.payloadFile))) {
+      payloadDocs.set(file, await fetchJson(`${BASE}/payload/${file}`));
+    }
+  } catch (err) {
+    t.skip(`published schemas unreachable (${err.message}); skipping live-contract check`);
+    return;
+  }
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validateEnvelope = ajv.compile(envelope);
+
+  const tmp = mkdtempSync(join(tmpdir(), 'onlooker-published-'));
+  try {
+    for (const sample of SAMPLES) {
+      const event = buildCanonicalEvent({
+        onlookerDir: tmp,
+        plugin: 'onlooker',
+        session_id: 'published-contract-test',
+        event_type: sample.event_type,
+        payload: sample.payload,
+      });
+
+      assert.ok(
+        validateEnvelope(event),
+        `published envelope rejected ${sample.event_type}: ${ajv.errorsText(validateEnvelope.errors)}`,
+      );
+
+      const def = payloadDocs.get(sample.payloadFile)?.$defs?.[sample.event_type];
+      assert.ok(def, `published payload/${sample.payloadFile} has no $defs entry for ${sample.event_type}`);
+
+      const validatePayload = ajv.compile(def);
+      assert.ok(
+        validatePayload(event.payload),
+        `published payload schema rejected ${sample.event_type}: ${ajv.errorsText(validatePayload.errors)}`,
+      );
+    }
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});