@onlooker-community/ecosystem 0.28.1 → 0.29.0

package/plugins/inspector/docs/design.md

@@ -0,0 +1,286 @@
+# Inspector — Design
+
+**Layer:** verification / execution
+**Hook surface:** `PostToolUse` for `Write`, `Edit`, `MultiEdit`
+**Status:** initial design — first implementation under this doc
+
+Inspector is the per-edit lint and typecheck gate. Every time the agent writes
+to a file, inspector runs the project's configured checks on **just that file**
+and surfaces the result back to the agent before its next turn. The agent sees
+its own type errors immediately and self-corrects, instead of claiming success
+on broken code and getting caught later by [assayer] or a human reviewer.
+
+## What inspector is — and isn't
+
+- **Inspector is not proctor.** Proctor (planned) runs the project's full
+  verification command (`npm test`, `mise run check`, …) at `Stop`. Inspector
+  runs only on touched files, only on `PostToolUse`. Cheaper, fires far more
+  often, narrower scope.
+- **Inspector is not assayer.** Assayer (shipped) parses the agent's final
+  message for testable claims ("the build passes", "I ran the tests") and
+  cross-checks them against actual exit codes in the transcript. Assayer catches
+  the agent *lying* about claims. Inspector ensures the agent has *accurate
+  ground truth* to make claims from. They compose: inspector emits real
+  pass/fail signals; assayer can later confirm the agent's claims line up with
+  those signals.
+- **Inspector is not a build system.** It does not chain dependencies, cache
+  intermediate results, or share state across invocations beyond timeouts. It
+  runs the configured check, captures the result, emits an event, exits. If
+  configuration says "run tsc on a single file," it does that — even though
+  tsc's per-file mode loses project context. Choosing the right command for a
+  given language is the user's job; inspector executes what it is told.
+
+## Hook flow
+
+```
+PostToolUse(Write|Edit|MultiEdit)
+  → inspector-post-write.sh
+    → resolve touched file from tool_input.file_path
+    → load merged config (plugin defaults < home < repo)
+    → if disabled OR excluded path OR no extension match → emit .skipped, exit 0
+    → for each configured check matching the extension:
+        → expand ${file}, ${file_relative}, ${repo_root} in the command
+        → run with per-check timeout
+        → emit inspector.check.passed / .failed / .skipped
+    → exit 0 (never blocks the tool call)
+```
+
+The hook always exits 0. Inspector is advisory — it never blocks the agent's
+write. It surfaces what it found in the additional-context channel of the
+PostToolUse hook reply so the agent sees the result on its next turn.
+
+## Configuration
+
+The minimum useful configuration is a map from file extension to a list of
+commands to run. Each command is an argv array; `${file}` substitutes the
+canonical absolute path to the touched file.
+
+```jsonc
+{
+  "inspector": {
+    "enabled": false,
+    "timeout_seconds_per_check": 10,
+    "total_timeout_seconds": 30,
+    "exclude_paths": ["node_modules", ".git", "vendor", "dist", "build",
+                       ".next", "__pycache__", ".venv"],
+    "checks": {
+      ".ts":  [{ "name": "biome",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "argv": ["tsc",   "--noEmit"] }],
+      ".tsx": [{ "name": "biome",      "argv": ["biome", "check", "${file}"] },
+               { "name": "tsc",        "argv": ["tsc",   "--noEmit"] }],
+      ".py":  [{ "name": "ruff",       "argv": ["ruff",  "check", "${file}"] }],
+      ".sh":  [{ "name": "shellcheck", "argv": ["shellcheck", "${file}"] }]
+    }
+  }
+}
+```
+
+Merging follows the standard ecosystem precedence (plugin defaults < home <
+repo). Each layer can fully replace `checks` for a given extension by setting
+the array; deep-merge of individual entries within an extension is intentionally
+not supported — it makes the override behavior unpredictable.
+
+`config.json` ships with `enabled: false` to match the rest of the ecosystem.
+The first PR that ships inspector also adds an opt-in path in the README.
+
+## Path handling
+
+- `file_path` is resolved via `realpath` where available, falling back to
+  `readlink -f`, falling back to the raw input.
+- The file must be inside the current repo root (`git rev-parse --show-toplevel`
+  from `cwd`). Out-of-tree writes are skipped — inspector is per-project.
+- `exclude_paths` is matched against the file's path relative to the repo root.
+  Match semantics are *containment* (`vendor/foo.ts` matches `vendor`), not
+  glob. Compass uses globs; inspector uses containment because the use case is
+  "skip this whole directory tree."
+
+## Per-check execution
+
+Each check runs in the repo root (`cwd`) with the following environment:
+
+- inherited PATH plus any `mise`-shimmed bins (already set up at session start)
+- `INSPECTOR_FILE` — absolute path to the touched file
+- `INSPECTOR_FILE_RELATIVE` — relative to repo root
+- `INSPECTOR_REPO_ROOT` — the repo root
+- `INSPECTOR_PROJECT_KEY` — the project key
+
+`timeout_seconds_per_check` is enforced via the `timeout` command (or a
+fallback bash trap on systems that lack it). On timeout, inspector emits
+`inspector.check.skipped` with `reason: "timeout"`.
+
+If the command's first argv entry is not on PATH, inspector emits
+`inspector.check.skipped` with `reason: "tool_missing"`. This is the dominant
+"new project, lint not installed yet" case and must be quiet — no error in the
+hook output, just the skipped event in the log.
+
+## What the agent sees
+
+The hook's stdout (the additional-context channel for PostToolUse hooks)
+contains a compact, one-line-per-finding summary:
+
+```
+inspector: src/cart.ts
+  ✗ biome (3 issues)
+      src/cart.ts:42:5 — Unused variable 'subtotal'
+      src/cart.ts:51:3 — Missing return type annotation
+      src/cart.ts:64:9 — Unreachable code
+  ✗ tsc (1 error)
+      src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'
+```
+
+On clean runs, inspector either emits nothing to stdout (the silent case) or a
+single confirmation line, controlled by `inspector.show_clean_runs`
+(default `false`). Default silence avoids token spam on every edit.
+
+Output capture per check is bounded by `inspector.output_excerpt_max_bytes`
+(default 4096) — beyond that, inspector truncates with a `…[truncated]` marker
+both in the agent-facing output and in the event payload.
+
+## tsc and other whole-project checks
+
+TypeScript's typecheck is project-scoped: `tsc --noEmit` checks every file in
+the project, not just the touched one. Inspector cannot meaningfully run "tsc
+on a single file" — `tsc --noEmit src/foo.ts` runs in a degraded mode that
+loses project context (imports, references, lib types).
+
+The right behavior is to run `tsc --noEmit -p tsconfig.json` (full project)
+and filter the output to errors that mention the touched file. The first
+implementation runs the full project tsc and post-filters. This is more
+expensive than the lint case but cached by tsc's incremental compilation
+(`tsBuildInfoFile`). Users who care about latency can disable the tsc check
+per-project.
+
+Other languages with similar whole-project semantics (mypy, cargo check,
+golangci-lint) follow the same pattern: run the project-wide command, filter
+results to the touched file. Users opt into these in `config.json` because the
+cost is higher than per-file lint.
+
+## Events
+
+All four events are registered in `@onlooker-community/schema` under
+`plugins-verification.json`.
+
+### `inspector.check.passed`
+
+Emitted once per check that passed cleanly.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",            // Write | Edit | MultiEdit
+  "check_name": "biome",
+  "check_kind": "lint",           // lint | typecheck
+  "argv": ["biome", "check", "/abs/path/to/src/cart.ts"],
+  "duration_ms": 124
+}
+```
+
+### `inspector.check.failed`
+
+Emitted once per check that returned a non-zero exit code.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "check_name": "tsc",
+  "check_kind": "typecheck",
+  "argv": ["tsc", "--noEmit"],
+  "duration_ms": 980,
+  "exit_code": 2,
+  "issue_count": 3,
+  "output_excerpt": "src/cart.ts:42:5 — Type 'string | undefined' is not assignable to 'string'\n…"
+}
+```
+
+`issue_count` is best-effort: inspector parses common output formats (one
+issue per non-empty line, ignoring obvious headers/footers) where possible
+and falls back to `null` when the format is unknown.
+
+### `inspector.check.skipped`
+
+Emitted when a check did not run.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "check_name": "tsc",            // optional — absent for whole-file skips
+  "reason": "tool_missing"        // tool_missing | disabled | excluded_path
+                                  //   | no_extension_match | timeout
+                                  //   | not_in_repo | total_budget_exhausted
+}
+```
+
+### `inspector.run.completed`
+
+Emitted once per hook invocation, after all per-check events for that file.
+
+```jsonc
+{
+  "file_path": "/abs/path/to/src/cart.ts",
+  "file_path_relative": "src/cart.ts",
+  "tool_name": "Edit",
+  "checks_run": 2,
+  "checks_passed": 0,
+  "checks_failed": 2,
+  "checks_skipped": 0,
+  "duration_ms": 1104
+}
+```
+
+Downstream consumers that just want "did this edit produce broken code?" read
+`inspector.run.completed` and check `checks_failed > 0`. Consumers that want
+per-tool detail subscribe to `inspector.check.*`.
+
+## Project-key derivation
+
+Same algorithm as the rest of the ecosystem:
+
+```
+SHA256("remote:" + git remote get-url origin) → first 12 hex chars
+  → fall back to SHA256("root:" + git rev-parse --show-toplevel)[:12]
+  → fall back to SHA256("cwd:" + pwd)[:12]
+```
+
+Implemented in `plugins/inspector/scripts/lib/inspector-project-key.sh`,
+mirroring the equivalent helper in cartographer.
+
+## Failure modes and fail-soft behavior
+
+Inspector is advisory. It never blocks the tool call. Specifically:
+
+- Missing tool on PATH → `.skipped` event, no agent-facing output
+- Timeout → `.skipped` event, agent sees `inspector: src/foo.ts — biome timed out`
+- Hook script error → exit 0 with no event (last-resort; logged to
+  `~/.onlooker/inspector/<project>/hook.log`)
+- Schema validation error → logged to stderr, hook continues
+- Concurrent invocation → no lock; each check runs independently. tsc's own
+  incremental cache handles concurrent invocations safely
+
+The "exit 0 with no event" path is the only case where inspector goes silent.
+This is deliberate: inspector is a noticeably new behavior surface; bugs in the
+hook script must not block writes.
+
+## Open questions
+
+These are deferred to a follow-up ADR after first real-world use.
+
+1. **Output filtering for whole-project checks.** Filtering tsc/mypy output to
+   the touched file is necessary for "only what you broke just now" UX. But
+   compile errors in unrelated files often *are* caused by this edit (a removed
+   export breaks five importers). Showing only the touched-file errors hides
+   real damage; showing all errors floods the channel. Tentative: show only
+   touched-file errors by default; add `inspector.show_collateral_errors`
+   config knob if requests come in.
+2. **Caching.** Repeated edits to the same file within seconds will re-run all
+   checks. Worth caching at the level of "skip identical file content"? Not
+   for v1.
+3. **Parallel checks.** Checks for the same file run sequentially today. Worth
+   parallelizing? Not for v1 — most lints finish in <500ms and bash-level
+   parallelism with timeouts is fiddly.
+
+[assayer]: ../../assayer/docs/design.md

package/plugins/inspector/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/inspector-post-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/inspector/scripts/hooks/inspector-post-write.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# inspector-post-write.sh — PostToolUse hook for Write / Edit / MultiEdit.
+#
+# Runs the project's configured lint and typecheck commands on just the
+# touched file. Emits inspector.check.* and inspector.run.completed events.
+# Surfaces a compact summary on stdout for the agent's next turn.
+# Always exits 0 — inspector is advisory.
+
+set -uo pipefail
+
+# Recursion guard — prevents inspector from re-triggering itself if a check
+# command happens to write to a watched file via its own tooling.
+[[ "${INSPECTOR_NESTED:-0}" == "1" ]] && exit 0
+export INSPECTOR_NESTED=1
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/inspector-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/inspector-run.sh"
+
+HOOK_INPUT=$(cat)
+CWD=$(printf '%s' "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+_HOOK_SESSION_ID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$HOOK_INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+export _HOOK_SESSION_ID
+
+# Bail on missing input — never block the tool call.
+[[ -z "$CWD" ]] && exit 0
+case "$TOOL_NAME" in
+	Write|Edit|MultiEdit) ;;
+	*) exit 0 ;;
+esac
+export INSPECTOR_TOOL_NAME="$TOOL_NAME"
+
+# Resolve touched file from tool input.
+TOOL_TARGET=$(printf '%s' "$HOOK_INPUT" \
+	| jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+[[ -z "$TOOL_TARGET" ]] && exit 0
+
+# Canonicalize.
+if command -v realpath &>/dev/null; then
+	CANONICAL=$(realpath "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+elif command -v readlink &>/dev/null; then
+	CANONICAL=$(readlink -f "$TOOL_TARGET" 2>/dev/null) || CANONICAL="$TOOL_TARGET"
+else
+	CANONICAL="$TOOL_TARGET"
+fi
+export INSPECTOR_FILE="$CANONICAL"
+
+REPO_ROOT=$(inspector_project_repo_root "$CWD")
+export INSPECTOR_REPO_ROOT="$REPO_ROOT"
+
+# Project-key derivation — always succeeds (falls back to cwd hash).
+PROJECT_KEY=$(inspector_project_key "$CWD")
+export INSPECTOR_PROJECT_KEY="$PROJECT_KEY"
+
+# File must live under repo root.
+if [[ "$CANONICAL" != "$REPO_ROOT"/* && "$CANONICAL" != "$REPO_ROOT" ]]; then
+	export INSPECTOR_FILE_RELATIVE="$CANONICAL"
+	inspector_config_load "$REPO_ROOT"
+	inspector_config_enabled || exit 0
+	inspector_emit_whole_file_skipped "not_in_repo"
+	exit 0
+fi
+export INSPECTOR_FILE_RELATIVE="${CANONICAL#"$REPO_ROOT"/}"
+
+inspector_config_load "$REPO_ROOT"
+
+if ! inspector_config_enabled; then
+	# Silent skip — do not even emit an event when disabled. Disabled means
+	# "this plugin is dormant," not "this file was uninteresting."
+	exit 0
+fi
+
+# Excluded path containment check.
+EXCLUDES=$(inspector_config_exclude_paths)
+if [[ -n "$EXCLUDES" && "$EXCLUDES" != "null" && "$EXCLUDES" != "[]" ]]; then
+	if jq -e --arg rel "$INSPECTOR_FILE_RELATIVE" \
+		'any(.[]; . as $p | $rel | startswith($p + "/") or . == $p or (("/" + $rel) | contains("/" + $p + "/")))' \
+		<<<"$EXCLUDES" >/dev/null 2>&1; then
+		inspector_emit_whole_file_skipped "excluded_path"
+		exit 0
+	fi
+fi
+
+# Look up checks for this file's extension. Use the *longest* matching suffix
+# so `.test.ts` matches before `.ts`. For now this is a simple two-step:
+# first the multi-dot suffix, then the simple extension.
+FILE_BASE=$(basename "$CANONICAL")
+EXT_LONG=""
+EXT_SHORT=""
+if [[ "$FILE_BASE" == *.*.* ]]; then
+	EXT_LONG=".${FILE_BASE#*.}"
+fi
+if [[ "$FILE_BASE" == *.* ]]; then
+	EXT_SHORT=".${FILE_BASE##*.}"
+fi
+
+CHECKS="[]"
+if [[ -n "$EXT_LONG" ]]; then
+	CANDIDATE=$(inspector_config_checks_for_extension "$EXT_LONG")
+	if [[ -n "$CANDIDATE" && "$CANDIDATE" != "[]" ]]; then
+		CHECKS="$CANDIDATE"
+	fi
+fi
+if [[ "$CHECKS" == "[]" && -n "$EXT_SHORT" ]]; then
+	CANDIDATE=$(inspector_config_checks_for_extension "$EXT_SHORT")
+	if [[ -n "$CANDIDATE" && "$CANDIDATE" != "[]" ]]; then
+		CHECKS="$CANDIDATE"
+	fi
+fi
+
+if [[ "$CHECKS" == "[]" ]]; then
+	inspector_emit_whole_file_skipped "no_extension_match"
+	exit 0
+fi
+
+# Execute. Always exit 0 regardless of check outcomes.
+inspector_run "$CHECKS" || true
+
+exit 0

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# inspector-config.sh — load and query Inspector configuration.
+#
+# Merges three layers in precedence order (later wins):
+#   1. plugins/inspector/config.json    (plugin defaults)
+#   2. ~/.claude/settings.json          (.inspector subtree)
+#   3. <repo>/.claude/settings.json     (.inspector subtree)
+#
+# Usage:
+#   inspector_config_load <repo_root>
+#   inspector_config_enabled
+#   inspector_config_get ".inspector.timeout_seconds_per_check"
+#   inspector_config_get_json ".inspector.exclude_paths"
+#   inspector_config_checks_for_extension ".ts"
+
+_INSPECTOR_CONFIG=""
+_INSPECTOR_PLUGIN_CONFIG=""
+
+inspector_config_load() {
+	local repo_root="${1:-}"
+	local plugin_dir
+	plugin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+	local plugin_config="$plugin_dir/config.json"
+
+	_INSPECTOR_PLUGIN_CONFIG="{}"
+	if [[ -f "$plugin_config" ]]; then
+		_INSPECTOR_PLUGIN_CONFIG=$(cat "$plugin_config")
+	fi
+
+	local home_settings="{}"
+	if [[ -f "$HOME/.claude/settings.json" ]]; then
+		home_settings=$(cat "$HOME/.claude/settings.json")
+	fi
+
+	local repo_settings="{}"
+	if [[ -n "$repo_root" && -f "$repo_root/.claude/settings.json" ]]; then
+		repo_settings=$(cat "$repo_root/.claude/settings.json")
+	fi
+
+	_INSPECTOR_CONFIG=$(jq -n \
+		--argjson plugin "$_INSPECTOR_PLUGIN_CONFIG" \
+		--argjson home "$home_settings" \
+		--argjson repo "$repo_settings" \
+		'$plugin * {"inspector": (($plugin.inspector // {}) * ($home.inspector // {}) * ($repo.inspector // {}))}')
+}
+
+inspector_config_get() {
+	local path="${1:-}"
+	printf '%s' "$_INSPECTOR_CONFIG" | jq -r "$path // empty" 2>/dev/null
+}
+
+inspector_config_get_json() {
+	local path="${1:-}"
+	printf '%s' "$_INSPECTOR_CONFIG" | jq -c "$path // empty" 2>/dev/null
+}
+
+inspector_config_enabled() {
+	local v
+	v=$(inspector_config_get '.inspector.enabled')
+	[[ "$v" == "true" ]]
+}
+
+inspector_config_show_clean_runs() {
+	local v
+	v=$(inspector_config_get '.inspector.show_clean_runs')
+	[[ "$v" == "true" ]]
+}
+
+inspector_config_timeout_per_check() {
+	local v
+	v=$(inspector_config_get '.inspector.timeout_seconds_per_check')
+	printf '%s' "${v:-10}"
+}
+
+inspector_config_total_timeout() {
+	local v
+	v=$(inspector_config_get '.inspector.total_timeout_seconds')
+	printf '%s' "${v:-30}"
+}
+
+inspector_config_output_excerpt_max_bytes() {
+	local v
+	v=$(inspector_config_get '.inspector.output_excerpt_max_bytes')
+	printf '%s' "${v:-4096}"
+}
+
+inspector_config_exclude_paths() {
+	inspector_config_get_json '.inspector.exclude_paths // []'
+}
+
+# Emits a JSON array of {name, argv, kind} objects for the given file extension
+# (including the leading dot). Returns an empty array when no checks are
+# configured for the extension.
+inspector_config_checks_for_extension() {
+	local ext="${1:-}"
+	[[ -z "$ext" ]] && { printf '[]'; return; }
+	printf '%s' "$_INSPECTOR_CONFIG" | jq -c --arg ext "$ext" '
+		(.inspector.checks // {}) as $checks
+		| ($checks[$ext] // [])
+		| map(
+			if type == "array" then
+				{ name: (.[0] // "check"), argv: ., kind: "lint" }
+			else
+				{ name: (.name // "check"), argv: (.argv // []), kind: (.kind // "lint") }
+			end
+		)
+	' 2>/dev/null || printf '[]'
+}

package/plugins/inspector/scripts/lib/inspector-events.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# inspector-events.sh — emit inspector.* events to the canonical event log.
+#
+# Thin wrapper around onlooker-event.mjs. Validation failures are logged to
+# stderr and do not abort the caller — Inspector is advisory.
+#
+# Usage:
+#   inspector_emit_event "inspector.check.passed" '{"file_path":"...","tool_name":"Edit",...}'
+
+_INSPECTOR_PLUGIN_NAME="inspector"
+
+_inspector_event_js_path() {
+	if [[ -n "${_ONLOOKER_EVENT_JS:-}" && -f "$_ONLOOKER_EVENT_JS" ]]; then
+		printf '%s' "$_ONLOOKER_EVENT_JS"
+		return 0
+	fi
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local candidates=(
+		"${plugin_root}/scripts/lib/onlooker-event.mjs"
+		"${plugin_root}/../../scripts/lib/onlooker-event.mjs"
+	)
+	local c
+	for c in "${candidates[@]}"; do
+		[[ -f "$c" ]] && { printf '%s' "$c"; return 0; }
+	done
+	return 1
+}
+
+_inspector_session_id() {
+	if [[ -n "${_HOOK_SESSION_ID:-}" ]]; then
+		printf '%s' "$_HOOK_SESSION_ID"
+		return 0
+	fi
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+	printf 'unknown'
+}
+
+inspector_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_inspector_event_js_path) || {
+		printf 'inspector-events: cannot locate onlooker-event.mjs\n' >&2
+		return 1
+	}
+
+	local session_id
+	session_id=$(_inspector_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_INSPECTOR_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{"plugin":$plugin,"session_id":$sid,"event_type":$type,"payload":$payload}')
+
+	local stderr_file
+	stderr_file=$(mktemp -t inspector-event-err.XXXXXX 2>/dev/null) \
+		|| stderr_file="/tmp/inspector-event-err.$$"
+
+	local event
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_INSPECTOR_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'inspector-events: schema validation failed for %s\n' "$event_type" >&2
+		[[ -s "$stderr_file" ]] && cat "$stderr_file" >&2
+		rm -f "$stderr_file"
+		return 1
+	}
+	rm -f "$stderr_file"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	mkdir -p "$(dirname "$log_path")" 2>/dev/null || return 1
+	printf '%s\n' "$event" >>"$log_path"
+}

package/plugins/inspector/scripts/lib/inspector-project-key.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# inspector-project-key.sh — stable 12-char hex project key.
+#
+# Derives a key that survives repo renames, clones, and worktrees.
+# Algorithm:
+#   1. git remote get-url origin → sha256("remote:" + url)[0:12]
+#   2. Fallback: git rev-parse --show-toplevel → sha256("root:" + path)[0:12]
+#   3. Non-git: sha256("cwd:" + pwd)[0:12]
+#
+# Usage:
+#   key=$(inspector_project_key <cwd>)
+#   root=$(inspector_project_repo_root <cwd>)
+
+_inspector_sha256_first12() {
+	local input="$1"
+	if command -v sha256sum &>/dev/null; then
+		printf '%s' "$input" | sha256sum | cut -c1-12
+	elif command -v shasum &>/dev/null; then
+		printf '%s' "$input" | shasum -a 256 | cut -c1-12
+	else
+		printf '%s' "$input" | python3 -c \
+			'import sys,hashlib; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:12])'
+	fi
+}
+
+inspector_project_repo_root() {
+	local cwd="${1:-$(pwd)}"
+	local root
+	root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null) && printf '%s' "$root" && return 0
+	printf '%s' "$cwd"
+}
+
+inspector_project_remote_url() {
+	local cwd="${1:-$(pwd)}"
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+inspector_project_key() {
+	local cwd="${1:-$(pwd)}"
+	local remote
+	remote=$(inspector_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_inspector_sha256_first12 "remote:${remote}"
+		return 0
+	fi
+
+	local root
+	root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)
+	if [[ -n "$root" ]]; then
+		_inspector_sha256_first12 "root:${root}"
+		return 0
+	fi
+
+	_inspector_sha256_first12 "cwd:${cwd}"
+}