@onlooker-community/ecosystem 0.43.5 → 0.43.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.43.5",
+  "version": "0.43.6",
   "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.43.5",
+  ".": "0.43.6",
   "plugins/archivist": "0.3.2",
   "plugins/tribunal": "1.2.8",
   "plugins/echo": "0.3.2",
@@ -15,5 +15,5 @@
   "plugins/assayer": "1.1.4",
   "plugins/bursar": "0.3.1",
   "plugins/lineage": "0.2.3",
-  "plugins/inspector": "0.3.3"
+  "plugins/inspector": "0.3.4"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.43.6](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.43.5...ecosystem-v0.43.6) (2026-08-22)
+
+
+### Bug Fixes
+
+* **events:** drop safe_emit's hand-built envelope fallback :broom: ([#202](https://github.com/onlooker-community/ecosystem/issues/202)) ([bad684a](https://github.com/onlooker-community/ecosystem/commit/bad684a4f7c535d72f91ed2b1d4928a4dd9a10e8))
+* **inspector:** canonicalize the file and repo root the same way :mag: ([0f850e9](https://github.com/onlooker-community/ecosystem/commit/0f850e92d7e620e4d7e06f512ef81efe4255f316))
+
 ## [0.43.5](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.43.4...ecosystem-v0.43.5) (2026-08-22)
 
 

package/docs/architecture.md

@@ -93,9 +93,9 @@ Every observable event flows through `onlooker-event.mjs` before being written t
 
 The schema is versioned independently and published to npm. Plugin shell scripts invoke `onlooker-event.mjs` at runtime so schema validation always reflects the installed version.
 
-> **Note:** Every emission path that fires in normal operation routes through `onlooker-event.mjs`. `prompt_rule.*` was the last routine exception — `prompt_rules_emit` hand-built its envelope with `jq` and wrote straight to `$ONLOOKER_EVENTS_LOG`, so those lines carried none of the required `id`/`schema_version`/`runtime`/`machine_id`/`sequence` fields and added a `turn` field the envelope forbids. It now goes through the emitter like everything else.
+> **Note:** Every emission path in this repo routes through `onlooker-event.mjs`. Nothing hand-builds an envelope and appends it to the log. Two paths used to: `prompt_rules_emit` (ecosystem-aaz) and the `safe_emit` fallback in `scripts/lib/validate-path.sh` (ecosystem-0tm). Both wrote lines missing all five required `id`/`schema_version`/`runtime`/`machine_id`/`sequence` fields, plus fields the envelope forbids — `event.v1.json` is `additionalProperties: false`.
 >
-> One hand-built envelope remains, in the `safe_emit` fallback in `scripts/lib/validate-path.sh`. It is reached only when `$ONLOOKER_EMIT` is missing, which does not happen in a normal checkout or install, so it is latent rather than live — but if it ever fires it writes the same unvalidatable shape. Route new event types through the emitter rather than writing to the log directly: an envelope assembled anywhere else will drift from the schema without anything noticing.
+> Route a new event type the same way rather than writing to the log directly. The shape to copy is a `{plugin, session_id, event_type, payload}` params object piped to `onlooker-event.mjs emit`, whose output you append; the emitter owns envelope assembly so there is exactly one place for it to drift. When the emitter is unavailable, emit nothing and return non-zero — an unparseable line on the bus is worse than a missing one.
 
 ### Emission gates
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.43.5",
+  "version": "0.43.6",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",

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

@@ -1,6 +1,6 @@
 {
   "name": "inspector",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Per-edit lint and typecheck gate. Runs the project's configured checks on just the touched file after every Write / Edit / MultiEdit, so the agent sees its own type errors before claiming success. Cheaper than proctor (which runs project-wide verification at Stop); complements assayer (which catches the agent lying about claims). Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/inspector/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.4](https://github.com/onlooker-community/ecosystem/compare/inspector-v0.3.3...inspector-v0.3.4) (2026-08-22)
+
+
+### Bug Fixes
+
+* **inspector:** canonicalize the file and repo root the same way :mag: ([0f850e9](https://github.com/onlooker-community/ecosystem/commit/0f850e92d7e620e4d7e06f512ef81efe4255f316))
+
 ## [0.3.3](https://github.com/onlooker-community/ecosystem/compare/inspector-v0.3.2...inspector-v0.3.3) (2026-08-22)
 
 

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

@@ -40,14 +40,10 @@ 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
+# Canonicalize through the same helper the repo root uses. The containment
+# check below is a prefix match, so both sides have to be resolved the same
+# way — see inspector_canonical_path and ecosystem-foi.
+CANONICAL=$(inspector_canonical_path "$TOOL_TARGET")
 export INSPECTOR_FILE="$CANONICAL"
 
 REPO_ROOT=$(inspector_project_repo_root "$CWD")

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

@@ -23,11 +23,68 @@ _inspector_sha256_first12() {
 	fi
 }
 
+# Resolve a path to its physical form — symlinks expanded, no trailing slash.
+#
+# The hook decides whether a touched file lives inside the repo by prefix-
+# matching one canonicalized path against the other. Both sides MUST come
+# through this one function. They used to be canonicalized independently
+# (realpath for the file, `git rev-parse --show-toplevel` for the root), each
+# with its own fallback, and on macOS /var is a symlink to /private/var — so
+# whenever either mechanism fell back, the two sides landed in different
+# namespaces and the prefix match failed. The hook then reported not_in_repo
+# for a file plainly inside the repo, exiting 0 with no output. See
+# ecosystem-foi, where that surfaced as an intermittent test failure.
+#
+# The last resort is `cd` + `pwd -P`, a bash builtin that needs no external
+# tool, so this still returns a physical path when neither realpath nor a
+# GNU-style `readlink -f` is available.
+#
+# Usage: canonical=$(inspector_canonical_path "$some_path")
+inspector_canonical_path() {
+	local p="${1:-}"
+	[[ -z "$p" ]] && return 0
+
+	local out
+	if out=$(realpath "$p" 2>/dev/null) && [[ -n "$out" ]]; then
+		printf '%s' "$out"
+		return 0
+	fi
+	# BSD readlink has no -f, so this silently no-ops there and falls through.
+	if out=$(readlink -f "$p" 2>/dev/null) && [[ -n "$out" ]]; then
+		printf '%s' "$out"
+		return 0
+	fi
+
+	if [[ -d "$p" ]]; then
+		out=$(cd "$p" 2>/dev/null && pwd -P) && [[ -n "$out" ]] && {
+			printf '%s' "$out"
+			return 0
+		}
+	else
+		local dir base
+		dir=$(dirname "$p")
+		base=$(basename "$p")
+		out=$(cd "$dir" 2>/dev/null && pwd -P) && [[ -n "$out" ]] && {
+			printf '%s/%s' "$out" "$base"
+			return 0
+		}
+	fi
+
+	# Nothing resolved it — hand back the input rather than an empty string,
+	# so a caller comparing two of these still compares like with like.
+	printf '%s' "$p"
+}
+
 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"
+	# Canonicalize BOTH the git answer and the fallback. git already returns a
+	# physical path, so the first call is a no-op; the fallback is the caller's
+	# raw cwd, which is exactly the case that used to diverge.
+	root=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null) \
+		&& [[ -n "$root" ]] \
+		&& { inspector_canonical_path "$root"; return 0; }
+	inspector_canonical_path "$cwd"
 }
 
 inspector_project_remote_url() {

package/scripts/lib/validate-path.sh

@@ -530,11 +530,32 @@ turn_state_next_tool() {
   fi
 }
 
-# Safely emit dev-os event (validates emit script exists)
-# Automatically exports turn state if not already set, so every emission
-# gets hook_type/turn/tool_call_seq in the envelope without callers needing
-# to call turn_state_export() explicitly.
-# Usage: echo "$INPUT" | safe_emit "event_type" '{"key":"value"}'
+# Safely emit an Onlooker event through the canonical emitter.
+#
+# Automatically exports turn state if not already set, so a caller does not have
+# to call turn_state_export() itself. Note the turn rides in the PAYLOAD, as
+# turn_number, for the event types whose schema declares it — the envelope has
+# no turn field and is additionalProperties:false.
+#
+# Returns non-zero and writes NOTHING when $ONLOOKER_EMIT is unavailable.
+#
+# There used to be a fallback here that hand-built an envelope with jq and
+# appended it directly. Every line it wrote was unvalidatable: it omitted all
+# five required id/schema_version/runtime/machine_id/sequence fields, and added
+# four the envelope forbids outright (hook_type, tool_name, turn,
+# tool_call_seq). It was reached only when $ONLOOKER_EMIT was missing — a file
+# that ships next to this one, so it never fired in a normal checkout or
+# install — which is how it stayed broken and unnoticed. See ecosystem-0tm.
+#
+# Dropping it rather than teaching it to call the emitter is the same
+# fail-closed choice made for prompt_rules_emit in ecosystem-aaz: an
+# unparseable line on the bus is worse than a missing one, and a second way to
+# build an envelope is a second thing to drift.
+#
+# Callers must tolerate a non-zero return — hooks run under `set -e`, so use
+# `safe_emit ... || true` when the emission is advisory.
+#
+# Usage: safe_emit "event_type" '{"key":"value"}'
 safe_emit() {
   local event_type="$1"
   local payload="$2"
@@ -544,38 +565,8 @@ safe_emit() {
     turn_state_export "$_HOOK_SESSION_ID"
   fi
 
-  if validate_file_exists "$ONLOOKER_EMIT"; then
-    "$ONLOOKER_EMIT" "$event_type" "$payload"
-  else
-    # Fallback: write directly to events log with envelope enrichment.
-    # Uses env vars set by hook_set_context() — NOT stdin (already consumed).
-    ensure_file_exists "$ONLOOKER_EVENTS_LOG" || return 1
-    local timestamp session_id plugin_name hook_type tool_name turn tool_seq
-    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-    session_id="${_HOOK_SESSION_ID:-}"
-    if [[ -z "$session_id" ]]; then
-      session_id=$(echo "$payload" | jq -r '.session_id // "unknown"' 2>/dev/null) || session_id="unknown"
-    fi
-    plugin_name="${ONLOOKER_PLUGIN_NAME:-unknown}"
-    hook_type="${ONLOOKER_HOOK_TYPE:-}"
-    tool_name="${ONLOOKER_TOOL_NAME:-}"
-    turn="${ONLOOKER_TURN_NUMBER:-}"
-    tool_seq="${ONLOOKER_TURN_TOOL_SEQ:-}"
-    jq -cn \
-      --arg ts "$timestamp" \
-      --arg sid "$session_id" \
-      --arg plugin "$plugin_name" \
-      --arg type "$event_type" \
-      --arg hook_type "$hook_type" \
-      --arg tool_name "$tool_name" \
-      --arg turn "$turn" \
-      --arg tool_seq "$tool_seq" \
-      --argjson payload "$payload" \
-      '{timestamp: $ts, session_id: $sid, plugin: $plugin, event_type: $type, payload: $payload}
-      + (if $hook_type != "" then {hook_type: $hook_type} else {} end)
-      + (if $tool_name != "" then {tool_name: $tool_name} else {} end)
-      + (if $turn != "" then {turn: ($turn | tonumber)} else {} end)
-      + (if $tool_seq != "" then {tool_call_seq: ($tool_seq | tonumber)} else {} end)
-      ' >> "$ONLOOKER_EVENTS_LOG"
+  if ! validate_file_exists "$ONLOOKER_EMIT"; then
+    return 1
   fi
+  "$ONLOOKER_EMIT" "$event_type" "$payload"
 }

package/test/bats/inspector-post-write-hook.bats

@@ -155,3 +155,95 @@ EOF
 	# The last argv slot should now hold the resolved touched file path.
 	[[ "$(echo "$argv" | jq -r '.[-1]')" == *"src/sample.ts" ]]
 }
+
+# ── path canonicalization (ecosystem-foi) ────────────────────────────────────
+#
+# The hook decides "is this file inside the repo?" by prefix-matching the
+# canonicalized file path against the repo root. Those two paths used to be
+# canonicalized by INDEPENDENT mechanisms — realpath for the file, `git
+# rev-parse --show-toplevel` for the root — each with its own fallback. On
+# macOS /var is a symlink to /private/var, so whenever either mechanism fell
+# back, the two sides landed in different namespaces, the prefix match failed,
+# and the hook reported not_in_repo for a file plainly inside the repo: exit 0,
+# no agent output, one misleading .skipped event.
+#
+# That is the exact signature of the intermittent failure in ecosystem-foi,
+# where the hook exited 0 but emitted no file header. These tests force each
+# fallback deterministically instead of waiting for the flake.
+
+_stub_dir() {
+	local d="${BATS_TEST_TMPDIR}/stub-$1"
+	mkdir -p "$d"
+	printf '%s' "$d"
+}
+
+_failing_check_settings() {
+	cat <<'EOF' | _settings
+{"inspector":{"checks":{".ts":[
+	{"name":"broken","kind":"lint","argv":["sh","-c","echo 'src/sample.ts:1:1 - Bad'; exit 2"]}
+]}}}
+EOF
+}
+
+@test "the repo-root fallback still finds a file inside the repo when git fails" {
+	# git rev-parse failing sends inspector_project_repo_root to its $cwd
+	# fallback, which is the caller-supplied (unresolved) path.
+	_failing_check_settings
+	local stub
+	stub=$(_stub_dir git)
+	printf '#!/bin/sh\nexit 1\n' >"${stub}/git"
+	chmod +x "${stub}/git"
+
+	run bash -c "printf '%s' '$(_input)' | PATH='${stub}:$PATH' ONLOOKER_DIR='$ONLOOKER_DIR' CLAUDE_PLUGIN_ROOT='$PLUGIN_ROOT' bash '$HOOK'"
+	[ "$status" -eq 0 ] || return 1
+	[[ "$output" == *"inspector: src/sample.ts"* ]] || return 1
+	[ "$(_event_count inspector.check.failed)" = "1" ]
+}
+
+@test "the file is still found inside the repo when realpath is unavailable" {
+	# realpath failing leaves the file path unresolved while the repo root,
+	# coming from git, is resolved — the same mismatch from the other side.
+	_failing_check_settings
+	local stub
+	stub=$(_stub_dir realpath)
+	printf '#!/bin/sh\nexit 1\n' >"${stub}/realpath"
+	chmod +x "${stub}/realpath"
+
+	run bash -c "printf '%s' '$(_input)' | PATH='${stub}:$PATH' ONLOOKER_DIR='$ONLOOKER_DIR' CLAUDE_PLUGIN_ROOT='$PLUGIN_ROOT' bash '$HOOK'"
+	[ "$status" -eq 0 ] || return 1
+	[[ "$output" == *"inspector: src/sample.ts"* ]] || return 1
+	[ "$(_event_count inspector.check.failed)" = "1" ]
+}
+
+@test "a file genuinely outside the repo still reports not_in_repo" {
+	# The containment check must still say no when the answer really is no —
+	# canonicalizing both sides must not turn it into a rubber stamp.
+	_failing_check_settings
+	local outside="${BATS_TEST_TMPDIR}/outside.ts"
+	printf 'x\n' >"$outside"
+
+	run _run_hook "$(_input "$REPO" "Edit" "$outside")"
+	[ "$status" -eq 0 ] || return 1
+	[ -z "$output" ] || return 1
+	[ "$(jq -r 'select(.event_type=="inspector.check.skipped").payload.reason' "$ONLOOKER_EVENTS_LOG")" = "not_in_repo" ]
+}
+
+@test "canonicalization survives with neither realpath nor readlink -f" {
+	# The last resort is `cd` + `pwd -P`, a builtin. Without it, a box with no
+	# GNU coreutils would hit the same namespace mismatch through a third door,
+	# and no other test forces this branch.
+	_failing_check_settings
+	local stub
+	stub=$(_stub_dir noresolvers)
+	printf '#!/bin/sh\nexit 1\n' >"${stub}/realpath"
+	printf '#!/bin/sh\nexit 1\n' >"${stub}/readlink"
+	chmod +x "${stub}/realpath" "${stub}/readlink"
+
+	run bash -c "printf '%s' '$(_input)' | PATH='${stub}:$PATH' ONLOOKER_DIR='$ONLOOKER_DIR' CLAUDE_PLUGIN_ROOT='$PLUGIN_ROOT' bash '$HOOK'"
+	[ "$status" -eq 0 ] || return 1
+	[[ "$output" == *"inspector: src/sample.ts"* ]] || return 1
+	# file_path_relative must still be repo-relative, not an absolute path —
+	# that is what proves the prefix strip found the root, rather than the
+	# header printing off a coincidentally-passing comparison.
+	[ "$(jq -r 'select(.event_type=="inspector.check.failed").payload.file_path_relative' "$ONLOOKER_EVENTS_LOG")" = "src/sample.ts" ]
+}

package/test/bats/validate-path.bats

@@ -108,6 +108,52 @@ setup() {
     >/dev/null
 }
 
+@test "safe_emit's line validates as a canonical envelope, not just a lookalike" {
+  # The assertion above spot-checks four fields. A hand-built envelope can pass
+  # that while still being rejected by the schema, which is exactly how the
+  # fallback below stayed broken. Validate the whole line instead.
+  export _HOOK_SESSION_ID="emit-session"
+  safe_emit "tool.file.read" '{"path":"/tmp/example.txt","read_mode":"full"}'
+  tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+    | ONLOOKER_DIR="$ONLOOKER_DIR" node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+@test "safe_emit writes nothing when the emit script is missing" {
+  # The degraded path. It used to hand-build an envelope with jq that omitted
+  # every required id/schema_version/runtime/machine_id/sequence field and added
+  # four the schema forbids (hook_type, tool_name, turn, tool_call_seq), on an
+  # envelope that is additionalProperties:false. An unparseable line on the bus
+  # is worse than a missing one, so this path now writes nothing at all.
+  # See ecosystem-0tm.
+  export _HOOK_SESSION_ID="emit-session"
+  export ONLOOKER_HOOK_TYPE="PreToolUse"
+  export ONLOOKER_TOOL_NAME="Read"
+  export ONLOOKER_TURN_NUMBER=4
+  export ONLOOKER_TURN_TOOL_SEQ=2
+  export ONLOOKER_EMIT="${BATS_TEST_TMPDIR}/no-such-emit.sh"
+
+  : >"$ONLOOKER_EVENTS_LOG"
+  run safe_emit "tool.file.read" '{"path":"/tmp/example.txt","read_mode":"full"}'
+  [ "$status" -ne 0 ] || return 1
+  [ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "safe_emit's failure to emit never aborts the calling hook" {
+  # safe_emit is substrate: returning non-zero must be absorbable by a caller
+  # running under `set -e`, the shape every hook uses. Assert the caller
+  # survives and reaches its next statement.
+  export ONLOOKER_EMIT="${BATS_TEST_TMPDIR}/no-such-emit.sh"
+  run bash -c "
+    set -euo pipefail
+    source '${REPO_ROOT}/scripts/lib/validate-path.sh'
+    export ONLOOKER_EMIT='${BATS_TEST_TMPDIR}/no-such-emit.sh'
+    safe_emit 'tool.file.read' '{\"path\":\"/x\",\"read_mode\":\"full\"}' || true
+    echo REACHED
+  "
+  [ "$status" -eq 0 ] || return 1
+  [[ "$output" == *"REACHED"* ]]
+}
+
 # ----------------------------------------------------------------------------
 # Hook health instrumentation: hook_register / hook_success / hook_failure
 # ----------------------------------------------------------------------------