@onlooker-community/ecosystem 0.29.1 → 0.29.2

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.2",
   "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.2",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.2",
   "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/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 });
+  }
+});