@onlooker-community/ecosystem 0.14.0 → 0.15.1

package/plugins/cartographer/scripts/hooks/cartographer-session-start.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# cartographer-session-start.sh — SessionStart hook.
+#
+# Fast path: reads one JSON field, acquires a lock, and launches the audit
+# pipeline as a detached background process. Returns in under 2 seconds.
+#
+# Invariant: this script NEVER calls claude -p or traverses the filesystem.
+# All heavy work runs in run-audit.sh as an orphaned child.
+
+set -uo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh"
+
+# Parse hook input
+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)
+export _HOOK_SESSION_ID
+
+[[ -z "$CWD" ]] && exit 0
+
+REPO_ROOT=$(cartographer_project_repo_root "$CWD")
+cartographer_config_load "$REPO_ROOT"
+
+cartographer_config_enabled || exit 0
+
+PROJECT_KEY=$(cartographer_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}"
+CARTOGRAPHER_DIR="$ONLOOKER_DIR/cartographer/$PROJECT_KEY"
+mkdir -p "$CARTOGRAPHER_DIR"
+
+LOCK_FILE="$CARTOGRAPHER_DIR/audit.lock"
+STATE_FILE="$CARTOGRAPHER_DIR/last_audit_at"
+
+# Determine if an audit is due
+INTERVAL_HOURS=$(cartographer_config_audit_interval_hours)
+FIRST_RUN_TRIGGER="session_start_first_run"
+INTERVAL_TRIGGER="session_start_interval"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+	TRIGGER="$FIRST_RUN_TRIGGER"
+elif [[ -f "$STATE_FILE" ]]; then
+	LAST=$(cat "$STATE_FILE" 2>/dev/null || printf '0')
+	NOW=$(date +%s)
+	ELAPSED=$(( NOW - LAST ))
+	THRESHOLD=$(( INTERVAL_HOURS * 3600 ))
+	if [[ "$ELAPSED" -lt "$THRESHOLD" ]]; then
+		exit 0
+	fi
+	TRIGGER="$INTERVAL_TRIGGER"
+fi
+
+# Acquire lock non-blocking — skip if another session's audit is running.
+# portable-lock.sh uses atomic mkdir so no fd lifetime concerns.
+cartographer_lock_acquire "$LOCK_FILE" || exit 0
+
+# Launch the audit detached — hook must return immediately.
+# setsid detaches from the controlling terminal so SIGHUP on session close
+# does not kill the background audit (ADR-001). Falls back to nohup-only on
+# macOS where setsid requires coreutils.
+export CARTOGRAPHER_DIR
+export CARTOGRAPHER_TRIGGER="$TRIGGER"
+export CARTOGRAPHER_REPO_ROOT="$REPO_ROOT"
+export ONLOOKER_DIR
+
+if command -v setsid &>/dev/null; then
+	nohup setsid bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+else
+	nohup bash -c "
+	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
+	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
+	  cartographer_config_load \"$REPO_ROOT\"
+	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
+	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
+fi
+
+exit 0

package/plugins/cartographer/scripts/lib/cartographer-analyze.sh

@@ -0,0 +1,286 @@
+#!/usr/bin/env bash
+# cartographer-analyze.sh — LLM-assisted analysis of instruction files.
+#
+# Orchestrates four analysis phases:
+#   1. contradiction  — rules that cannot both be satisfied simultaneously
+#   2. stale_ref      — references to paths/tools that no longer exist
+#   3. dead_rule      — rules subsumed elsewhere or referencing removed workflows
+#   4. scope_collision — project rules duplicating or contradicting global rules
+#
+# Each phase calls `claude -p` and produces a JSON findings array.
+# Findings are normalized and returned for deduplication + storage.
+#
+# Usage:
+#   cartographer_analyze_contradiction  <files_json> <model> <max_tokens> <phase_timeout>
+#   cartographer_analyze_stale_ref      <files_json> <repo_root> <model> <max_tokens> <phase_timeout>
+#   cartographer_analyze_scope_collision <global_files_json> <project_files_json> <model> <max_tokens> <phase_timeout>
+#
+# Note: contradiction detection also flags dead_rule findings in a single LLM pass.
+#
+# Each function prints a JSON array of finding objects on stdout:
+#   [{type, severity, file_a, excerpt_a, file_b, excerpt_b, description, suggested_fix}]
+
+_CARTOGRAPHER_TIMEOUT_CMD=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || printf 'timeout')
+
+_cartographer_read_files_for_prompt() {
+	local files_json="$1"
+	local output=""
+	while IFS= read -r fpath; do
+		[[ -z "$fpath" || ! -f "$fpath" ]] && continue
+		output+=$'\n<FILE: '"$fpath"$'>\n'
+		output+=$(cat "$fpath")
+		output+=$'\n</FILE>\n'
+	done < <(printf '%s' "$files_json" | jq -r '.[]' 2>/dev/null)
+	printf '%s' "$output"
+}
+
+cartographer_analyze_contradiction() {
+	local files_json="$1"
+	local model="${2:-claude-haiku-4-5-20251001}"
+	local max_tokens="${3:-2048}"
+	local timeout_s="${4:-60}"
+
+	local corpus
+	corpus=$(_cartographer_read_files_for_prompt "$files_json")
+	[[ -z "$corpus" ]] && printf '[]' && return 0
+
+	local prompt
+	prompt=$(cat <<'PROMPT'
+You are an expert technical editor reviewing Claude Code instruction files for internal consistency.
+
+Your task: identify any CONTRADICTIONS — pairs of rules that cannot both be satisfied at the same time. A contradiction exists only when following rule A makes it impossible or directly inconsistent to follow rule B. Do not flag rules that are merely different or address different contexts.
+
+Also identify any DEAD RULES — rules that are fully redundant because a more specific rule elsewhere already covers exactly the same ground.
+
+Output ONLY a JSON array. Each element:
+{
+  "type": "contradiction" | "dead_rule",
+  "severity": "error" | "warning",
+  "file_a": "<absolute path>",
+  "excerpt_a": "<quoted text ≤150 chars>",
+  "file_b": "<absolute path>",
+  "excerpt_b": "<quoted text ≤150 chars>",
+  "description": "<one sentence explaining the conflict or redundancy>",
+  "suggested_fix": "<one sentence concrete action>"
+}
+
+Severity: "error" if following both rules would violate safety or produce incorrect output; "warning" otherwise.
+If no issues found, output: []
+PROMPT
+)
+
+	local full_prompt="${prompt}
+
+${corpus}"
+
+	local response
+	response=$(printf '%s' "$full_prompt" \
+		| $_CARTOGRAPHER_TIMEOUT_CMD "$timeout_s" claude -p \
+			--model "$model" \
+			--max-tokens "$max_tokens" \
+			2>/dev/null) || { printf '[]'; return 1; }
+
+	printf '%s' "$response" | python3 -c "
+import sys, json
+raw = sys.stdin.read()
+start = raw.find('[')
+end = raw.rfind(']') + 1
+if start < 0 or end <= start:
+    print('[]')
+else:
+    try:
+        arr = json.loads(raw[start:end])
+        print(json.dumps(arr))
+    except Exception:
+        print('[]')
+" 2>/dev/null || printf '[]'
+}
+
+cartographer_analyze_stale_ref() {
+	local files_json="$1"
+	local repo_root="$2"
+	local model="${3:-claude-haiku-4-5-20251001}"
+	local max_tokens="${4:-2048}"
+	local timeout_s="${5:-60}"
+
+	# bash pre-pass: extract path-like tokens and test on filesystem
+	local candidates=""
+	while IFS= read -r fpath; do
+		[[ -z "$fpath" || ! -f "$fpath" ]] && continue
+		local line_no=0
+		while IFS= read -r line; do
+			(( line_no++ ))
+			# extract tokens that look like relative/absolute paths
+			local tokens
+			tokens=$(printf '%s' "$line" | grep -oE '[./][a-zA-Z0-9_/.-]{3,}' 2>/dev/null || true)
+			while IFS= read -r tok; do
+				[[ -z "$tok" ]] && continue
+				# resolve relative to repo root
+				local resolved="$repo_root/$tok"
+				if [[ ! -e "$resolved" && ! -e "$tok" ]]; then
+					candidates+="FILE=$fpath LINE=$line_no TOKEN=$tok CONTEXT=$(printf '%s' "$line" | cut -c1-120)"$'\n'
+				fi
+			done < <(printf '%s\n' "$tokens")
+		done <"$fpath"
+	done < <(printf '%s' "$files_json" | jq -r '.[]' 2>/dev/null)
+
+	[[ -z "$candidates" ]] && printf '[]' && return 0
+
+	local prompt
+	prompt=$(cat <<'PROMPT'
+You are reviewing references extracted from Claude Code instruction files. Each reference could not be resolved on the filesystem.
+
+Classify each as:
+- "stale": a genuine reference to something that should exist but does not
+- "example": an illustrative or hypothetical path, not a real reference
+- "ambiguous": cannot tell from context
+
+Output ONLY a JSON array (only include items classified as "stale"):
+{
+  "type": "stale_ref",
+  "severity": "warning",
+  "file_a": "<path>",
+  "excerpt_a": "<the unresolvable reference token>",
+  "file_b": null,
+  "excerpt_b": null,
+  "description": "<one sentence>",
+  "suggested_fix": "<one sentence, or null>"
+}
+
+If none are stale, output: []
+PROMPT
+)
+	local full_prompt="${prompt}
+
+<CANDIDATES>
+${candidates}
+</CANDIDATES>"
+
+	local response
+	response=$(printf '%s' "$full_prompt" \
+		| $_CARTOGRAPHER_TIMEOUT_CMD "$timeout_s" claude -p \
+			--model "$model" \
+			--max-tokens "$max_tokens" \
+			2>/dev/null) || { printf '[]'; return 1; }
+
+	printf '%s' "$response" | python3 -c "
+import sys, json
+raw = sys.stdin.read()
+start = raw.find('[')
+end = raw.rfind(']') + 1
+if start < 0 or end <= start:
+    print('[]')
+else:
+    try:
+        arr = json.loads(raw[start:end])
+        print(json.dumps(arr))
+    except Exception:
+        print('[]')
+" 2>/dev/null || printf '[]'
+}
+
+cartographer_analyze_scope_collision() {
+	local global_json="$1"
+	local project_json="$2"
+	local model="${3:-claude-haiku-4-5-20251001}"
+	local max_tokens="${4:-2048}"
+	local timeout_s="${5:-60}"
+
+	local global_files project_files
+	global_files=$(_cartographer_read_files_for_prompt "$global_json")
+	project_files=$(_cartographer_read_files_for_prompt "$project_json")
+
+	[[ -z "$global_files" || -z "$project_files" ]] && printf '[]' && return 0
+
+	local prompt
+	prompt=$(cat <<'PROMPT'
+You are auditing Claude Code instruction files for scope collisions between global and project-level files.
+
+The GLOBAL file applies to all projects. The PROJECT files apply only to this project. Project rules override global rules when they conflict.
+
+Identify SCOPE COLLISIONS:
+1. Exact or near-exact duplications where the project rule adds nothing new
+2. Contradictions where it is unclear from context that the project is intentionally overriding the global
+
+Do NOT flag intentional, clearly-worded overrides like "For this project, use X instead of the global default Y".
+
+Output ONLY a JSON array:
+{
+  "type": "scope_collision",
+  "severity": "warning",
+  "file_a": "<global file path>",
+  "excerpt_a": "<global rule ≤150 chars>",
+  "file_b": "<project file path>",
+  "excerpt_b": "<project rule ≤150 chars>",
+  "description": "<one sentence>",
+  "suggested_fix": "<one sentence>"
+}
+
+If none found, output: []
+PROMPT
+)
+
+	local full_prompt="${prompt}
+
+<GLOBAL FILES>
+${global_files}
+</GLOBAL FILES>
+
+<PROJECT FILES>
+${project_files}
+</PROJECT FILES>"
+
+	local response
+	response=$(printf '%s' "$full_prompt" \
+		| $_CARTOGRAPHER_TIMEOUT_CMD "$timeout_s" claude -p \
+			--model "$model" \
+			--max-tokens "$max_tokens" \
+			2>/dev/null) || { printf '[]'; return 1; }
+
+	printf '%s' "$response" | python3 -c "
+import sys, json
+raw = sys.stdin.read()
+start = raw.find('[')
+end = raw.rfind(']') + 1
+if start < 0 or end <= start:
+    print('[]')
+else:
+    try:
+        arr = json.loads(raw[start:end])
+        print(json.dumps(arr))
+    except Exception:
+        print('[]')
+" 2>/dev/null || printf '[]'
+}
+
+# Compute the canonical finding hash (commutative across file_a/file_b).
+cartographer_finding_hash() {
+	local type="$1"
+	local file_a="$2"
+	local excerpt_a="$3"
+	local file_b="${4:-}"
+	local excerpt_b="${5:-}"
+
+	# Sort files so A→B and B→A produce the same hash
+	local sorted_files
+	if [[ "$file_a" < "$file_b" ]]; then
+		sorted_files="${file_a}:::${file_b}"
+	else
+		sorted_files="${file_b}:::${file_a}"
+	fi
+
+	# Normalize excerpts: strip leading/trailing whitespace, collapse internal runs
+	local norm_a norm_b
+	norm_a=$(printf '%s' "$excerpt_a" | tr -s ' \t\n' ' ' | sed 's/^ //;s/ $//')
+	norm_b=$(printf '%s' "$excerpt_b" | tr -s ' \t\n' ' ' | sed 's/^ //;s/ $//')
+
+	local input="${type}:${sorted_files}:${norm_a}:${norm_b}"
+	if command -v sha256sum &>/dev/null; then
+		printf '%s' "$input" | sha256sum | cut -c1-16
+	elif command -v shasum &>/dev/null; then
+		printf '%s' "$input" | shasum -a 256 | cut -c1-16
+	else
+		printf '%s' "$input" | python3 -c \
+			'import sys,hashlib; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:16])'
+	fi
+}

package/plugins/cartographer/scripts/lib/cartographer-collect.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# cartographer-collect.sh — discover all auditable instruction files under a repo root.
+#
+# Finds:
+#   - CLAUDE.md files (all depths up to max_depth)
+#   - AGENTS.md files (all depths up to max_depth)
+#   - .claude/rules/*.md files (global and repo-level)
+#
+# Applies exclude_paths (substring filter) to the collected list.
+#
+# Usage:
+#   cartographer_collect_files <repo_root> <exclude_paths_json> [max_depth]
+#   # prints one absolute path per line
+
+cartographer_collect_files() {
+	local repo_root="${1:?repo_root required}"
+	local exclude_json="${2:-[]}"
+	local max_depth="${3:-5}"
+
+	# Build find -not -path exclusions
+	local find_excludes=()
+	while IFS= read -r excl; do
+		[[ -z "$excl" ]] && continue
+		find_excludes+=(-not -path "*/${excl}/*")
+	done < <(printf '%s' "$exclude_json" | jq -r '.[]' 2>/dev/null)
+
+	# Discover CLAUDE.md and AGENTS.md
+	find "$repo_root" -maxdepth "$max_depth" \
+		\( -name "CLAUDE.md" -o -name "AGENTS.md" \) \
+		"${find_excludes[@]}" \
+		-type f 2>/dev/null
+
+	# Discover .claude/rules/*.md at repo level
+	if [[ -d "$repo_root/.claude/rules" ]]; then
+		find "$repo_root/.claude/rules" -maxdepth 2 -type f -name "*.md" 2>/dev/null
+	fi
+}
+
+cartographer_collect_global_files() {
+	# Global ~/.claude/CLAUDE.md and ~/.claude/rules/*.md
+	if [[ -f "$HOME/.claude/CLAUDE.md" ]]; then
+		printf '%s\n' "$HOME/.claude/CLAUDE.md"
+	fi
+	if [[ -d "$HOME/.claude/rules" ]]; then
+		find "$HOME/.claude/rules" -maxdepth 2 -type f -name "*.md" 2>/dev/null
+	fi
+}
+
+cartographer_file_content_hash() {
+	local path="$1"
+	[[ ! -f "$path" ]] && return 1
+	if command -v sha256sum &>/dev/null; then
+		sha256sum "$path" | cut -c1-16
+	elif command -v shasum &>/dev/null; then
+		shasum -a 256 "$path" | cut -c1-16
+	else
+		python3 -c "import sys,hashlib; print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest()[:16])" "$path"
+	fi
+}

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# cartographer-config.sh — load and query Cartographer configuration.
+#
+# Merges three layers in precedence order (later wins):
+#   1. plugins/cartographer/config.json  (plugin defaults)
+#   2. ~/.claude/settings.json           (.cartographer subtree)
+#   3. <repo>/.claude/settings.json      (.cartographer subtree)
+#
+# Usage:
+#   cartographer_config_load <repo_root>
+#   cartographer_config_get ".cartographer.enabled"
+#   cartographer_config_get_json ".cartographer.exclude_paths"
+
+_CARTOGRAPHER_CONFIG=""
+_CARTOGRAPHER_PLUGIN_CONFIG=""
+
+cartographer_config_load() {
+	local repo_root="${1:-}"
+	local plugin_dir
+	plugin_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+	local plugin_config="$plugin_dir/config.json"
+
+	_CARTOGRAPHER_PLUGIN_CONFIG="{}"
+	if [[ -f "$plugin_config" ]]; then
+		_CARTOGRAPHER_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
+
+	_CARTOGRAPHER_CONFIG=$(jq -n \
+		--argjson plugin "$_CARTOGRAPHER_PLUGIN_CONFIG" \
+		--argjson home "$home_settings" \
+		--argjson repo "$repo_settings" \
+		'$plugin * {"cartographer": (($plugin.cartographer // {}) * ($home.cartographer // {}) * ($repo.cartographer // {}))}')
+}
+
+cartographer_config_get() {
+	local path="${1:-}"
+	printf '%s' "$_CARTOGRAPHER_CONFIG" | jq -r "$path // empty" 2>/dev/null
+}
+
+cartographer_config_get_json() {
+	local path="${1:-}"
+	printf '%s' "$_CARTOGRAPHER_CONFIG" | jq -c "$path // empty" 2>/dev/null
+}
+
+cartographer_config_enabled() {
+	local v
+	v=$(cartographer_config_get '.cartographer.enabled')
+	[[ "$v" == "true" ]]
+}
+
+cartographer_config_model_extraction() {
+	local v
+	v=$(cartographer_config_get '.cartographer.extraction.model')
+	printf '%s' "${v:-claude-haiku-4-5-20251001}"
+}
+
+cartographer_config_model_synthesis() {
+	local v
+	v=$(cartographer_config_get '.cartographer.synthesis.model')
+	printf '%s' "${v:-claude-haiku-4-5-20251001}"
+}
+
+cartographer_config_phase_timeout() {
+	local v
+	v=$(cartographer_config_get '.cartographer.phase_timeout_seconds')
+	printf '%s' "${v:-60}"
+}
+
+cartographer_config_total_timeout() {
+	local v
+	v=$(cartographer_config_get '.cartographer.total_timeout_seconds')
+	printf '%s' "${v:-600}"
+}
+
+cartographer_config_audit_interval_hours() {
+	local v
+	v=$(cartographer_config_get '.cartographer.audit_interval_hours')
+	printf '%s' "${v:-24}"
+}
+
+cartographer_config_exclude_paths() {
+	cartographer_config_get_json '.cartographer.exclude_paths // ["node_modules",".git","vendor",".venv","dist",".next",".nuxt","build","__pycache__"]'
+}
+
+cartographer_config_max_output_tokens_extraction() {
+	local v
+	v=$(cartographer_config_get '.cartographer.extraction.max_output_tokens')
+	printf '%s' "${v:-2048}"
+}
+
+cartographer_config_max_output_tokens_synthesis() {
+	local v
+	v=$(cartographer_config_get '.cartographer.synthesis.max_output_tokens')
+	printf '%s' "${v:-2048}"
+}

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# cartographer-events.sh — emit cartographer.* events to the canonical event log.
+#
+# Thin wrapper around onlooker-event.mjs. Validation failures are logged to
+# stderr and do not abort the caller — Cartographer is advisory.
+#
+# Usage:
+#   cartographer_emit_event "cartographer.audit.complete" '{"audit_id":"...","new_finding_count":2}'
+
+_CARTOGRAPHER_PLUGIN_NAME="cartographer"
+
+_cartographer_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
+}
+
+_cartographer_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'
+}
+
+cartographer_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_cartographer_event_js_path) || {
+		printf 'cartographer-events: cannot locate onlooker-event.mjs\n' >&2
+		return 1
+	}
+
+	local session_id
+	session_id=$(_cartographer_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_CARTOGRAPHER_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 cartographer-event-err.XXXXXX 2>/dev/null) \
+		|| stderr_file="/tmp/cartographer-event-err.$$"
+
+	local event
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_CARTOGRAPHER_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'cartographer-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/cartographer/scripts/lib/cartographer-lock.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# cartographer-lock.sh — thin wrappers around the shared portable-lock.sh.
+#
+# portable-lock.sh uses atomic mkdir() which works on Linux, macOS, and any
+# POSIX local filesystem without requiring flock or any external utility.
+#
+# Usage:
+#   source cartographer-lock.sh
+#   cartographer_lock_acquire <lock_file>   # returns 0=acquired, 1=timeout
+#   cartographer_lock_release <lock_file>
+
+_CARTOGRAPHER_LOCK_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../../scripts/lib" && pwd)/portable-lock.sh"
+
+if [[ ! -f "$_CARTOGRAPHER_LOCK_LIB" ]]; then
+	printf '[cartographer-lock] ERROR: portable-lock.sh not found at %s\n' \
+		"$_CARTOGRAPHER_LOCK_LIB" >&2
+	exit 1
+fi
+
+# shellcheck source=../../../../scripts/lib/portable-lock.sh
+source "$_CARTOGRAPHER_LOCK_LIB"
+
+cartographer_lock_acquire() {
+	local lock_file="${1:?lock_file required}"
+	mkdir -p "$(dirname "$lock_file")" 2>/dev/null || true
+	# Non-blocking: pass timeout=0 so we return immediately if held.
+	lock_acquire "$lock_file" 0
+}
+
+cartographer_lock_release() {
+	local lock_file="${1:?lock_file required}"
+	lock_release "$lock_file"
+}
+
+cartographer_lock_is_held() {
+	local lock_file="${1:?lock_file required}"
+	[[ -d "${lock_file}.d" ]]
+}