@onlooker-community/ecosystem 0.10.0 → 0.14.0

package/scripts/coverage/run-coverage.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Run the .mjs test suite with node's built-in --experimental-test-coverage,
+// parse the emitted table into structured JSON, and either pretty-print it
+// or hand it off as JSON for downstream tools (format-comment.mjs).
+//
+// The output table is fixed-format text; we parse it line-by-line rather
+// than depending on V8 coverage dumps so we don't need to handle binary
+// formats across node versions.
+//
+// Flags:
+//   --json   emit structured JSON
+//   --root   override repo root
+
+import { spawnSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function findRepoRoot(start) {
+  let cur = resolve(start);
+  while (cur !== '/') {
+    try {
+      statSync(join(cur, '.claude-plugin', 'marketplace.json'));
+      return cur;
+    } catch {}
+    cur = dirname(cur);
+  }
+  throw new Error(`no repo root above ${start}`);
+}
+
+function parseArgs(argv) {
+  const out = { json: false, root: null };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') out.json = true;
+    else if (argv[i] === '--root') out.root = argv[++i];
+  }
+  return out;
+}
+
+// Parse the human-readable coverage report node prints after a --test run.
+// Layout:
+//   ℹ start of coverage report
+//   ℹ ---------- (separator)
+//   ℹ file | line % | branch % | funcs % | uncovered lines
+//   ℹ ---------- (separator)
+//   ℹ <directory>
+//   ℹ  <subdir>
+//   ℹ   <file.mjs>  | 74.20 | 58.27 | 85.00 | 130-131 170 ...
+//   ℹ ---------- (separator)
+//   ℹ all files     | 78.55 | 57.38 | 87.18 |
+//   ℹ ---------- (separator)
+//   ℹ end of coverage report
+function parseCoverageOutput(text) {
+  const lines = text.split(/\r?\n/);
+  const files = [];
+  let overall = null;
+  let inReport = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/^ℹ\s?/, '').replace(/^[\sℹ]+/, '');
+    if (line.startsWith('start of coverage report')) {
+      inReport = true;
+      continue;
+    }
+    if (line.startsWith('end of coverage report')) {
+      inReport = false;
+      continue;
+    }
+    if (!inReport) continue;
+
+    // Skip separators and the header row.
+    if (line.startsWith('-')) continue;
+    if (line.includes('line %') && line.includes('branch %')) continue;
+
+    const cells = line.split('|').map((c) => c.trim());
+    // A real data row has 5 columns: file, line%, branch%, funcs%, uncovered.
+    if (cells.length < 5) continue;
+
+    const [file, linePct, branchPct, funcsPct, uncovered] = cells;
+    if (!file) continue;
+    // Directory rows have all-blank metric columns — skip them so we only
+    // surface per-file numbers + the all-files total.
+    if (!linePct || !branchPct || !funcsPct) continue;
+
+    const num = (s) => Number.parseFloat(s);
+    const entry = {
+      file,
+      line: num(linePct),
+      branch: num(branchPct),
+      funcs: num(funcsPct),
+      uncoveredLines: uncovered || '',
+    };
+    if (file === 'all files') {
+      overall = entry;
+    } else {
+      files.push(entry);
+    }
+  }
+
+  return { files, overall };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = args.root ? resolve(args.root) : findRepoRoot(here);
+
+  const testGlob = ['test/node'].map((d) => join(root, d, '*.test.mjs'));
+  const r = spawnSync(
+    'node',
+    [
+      '--experimental-test-coverage',
+      '--test-coverage-include=scripts/**/*.mjs',
+      '--test-coverage-exclude=test/**',
+      '--test',
+      ...testGlob,
+    ],
+    { encoding: 'utf8', cwd: root },
+  );
+
+  if (r.status !== 0) {
+    process.stderr.write(`tests failed (exit ${r.status})\n`);
+    process.stderr.write(r.stdout);
+    process.stderr.write(r.stderr);
+    process.exit(r.status ?? 1);
+  }
+
+  const report = parseCoverageOutput(r.stdout);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (!report.overall) {
+    process.stderr.write('could not parse coverage output\n');
+    process.stderr.write(r.stdout);
+    process.exit(1);
+  }
+
+  process.stdout.write(
+    `node coverage: line ${report.overall.line.toFixed(1)}%  branch ${report.overall.branch.toFixed(1)}%  funcs ${report.overall.funcs.toFixed(1)}%\n\n`,
+  );
+  for (const f of report.files) {
+    process.stdout.write(
+      `  line ${f.line.toFixed(0).padStart(3)}%  branch ${f.branch.toFixed(0).padStart(3)}%  ${f.file}\n`,
+    );
+  }
+}
+
+main();

package/scripts/hooks/agent-spawn-tracker.sh

@@ -64,9 +64,9 @@ BACKGROUND=$(jq -r '.tool_input.background // false' <<<"$INPUT")
 STATE_FILE="$ONLOOKER_DIR/agent-spawn-trackers.json"
 LOCKFILE="$STATE_FILE.lock"
 
-# Use flock for exclusive access
-exec 200>"$LOCKFILE"
-flock -w 5 200 || {
+# Acquire exclusive access via the portable lock helper (mkdir-based mutex,
+# works on macOS without util-linux).
+lock_acquire "$LOCKFILE" 5 || {
 	json_response "deny" "Failed to acquire lock"
 	hook_failure
 	exit 0
@@ -103,7 +103,7 @@ STATE=$(jq --arg sid "$SESSION_ID" '
 echo "$STATE" > "$STATE_FILE" 2>/dev/null || true
 
 # Release lock
-flock -u 200
+lock_release "$LOCKFILE"
 
 # Get current session stats
 SPAWN_COUNT=$(jq -r --arg sid "$SESSION_ID" '.sessions[$sid].spawns' <<<"$STATE")

package/scripts/hooks/prompt-rule-injector.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Onlooker Prompt Rule Injector
+# Invoked by UserPromptSubmit. Loads declarative prompt rules from
+#   ~/.onlooker/prompt-rules.json (global)
+#   <cwd>/.claude/prompt-rules.json (project, overrides global by id)
+# and injects guidance for rules whose POSIX-ERE pattern matches the prompt.
+# Each rule fires at most once per session per rule_id.
+#
+# Emits canonical-ish events to ~/.onlooker/logs/onlooker-events.jsonl:
+#   prompt_rule.matched — every match (including subsequent matches in-session)
+#   prompt_rule.applied — only when guidance is actually injected
+#
+# Usage:
+#   echo "$INPUT" | prompt-rule-injector.sh
+
+set -uo pipefail # No -e: never block prompt submission
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/validate-path.sh
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+# shellcheck source=../lib/prompt-rules.sh
+source "$SCRIPT_DIR/../lib/prompt-rules.sh"
+
+hook_register "prompt-rule-injector" "Prompt Rule Injector" "Injects declarative guidance when regex rules match prompts"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "UserPromptSubmit"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+[[ -z "$CWD" ]] && CWD="$PWD"
+
+turn_state_export "$SESSION_ID"
+
+CONFIG_FILE="${CLAUDE_PLUGIN_ROOT:-}/config.json"
+PER_TURN_MAX_CHARS=1200
+ENABLED=true
+if [[ -f "$CONFIG_FILE" ]]; then
+  # `// true` would coerce an explicit `false` to true; check the field explicitly.
+  ENABLED=$(jq -r 'if (.prompt_rules.enabled == false) then "false" else "true" end' "$CONFIG_FILE" 2>/dev/null) || ENABLED=true
+  PER_TURN_MAX_CHARS=$(jq -r '.prompt_rules.per_turn_max_chars // 1200' "$CONFIG_FILE" 2>/dev/null) || PER_TURN_MAX_CHARS=1200
+fi
+
+if [[ "$ENABLED" != "true" ]]; then
+  hook_success
+  exit 0
+fi
+
+RULES=$(prompt_rules_load_merged "$CWD")
+RULE_COUNT=$(echo "$RULES" | jq 'length' 2>/dev/null || echo 0)
+if [[ "$RULE_COUNT" -eq 0 ]]; then
+  hook_success
+  exit 0
+fi
+
+FIRED=$(prompt_rules_load_fired "$SESSION_ID")
+COMBINED_GUIDANCE=""
+COMBINED_LEN=0
+
+while IFS= read -r rule; do
+  [[ -z "$rule" ]] && continue
+  RULE_ID=$(echo "$rule" | jq -r '.id // empty')
+  PATTERN=$(echo "$rule" | jq -r '.pattern // empty')
+  GUIDANCE=$(echo "$rule" | jq -r '.guidance // empty')
+  MAX_CHARS=$(echo "$rule" | jq -r '.max_chars // 400')
+  # `// true` would coerce an explicit `false` to true (jq's // treats `false`
+  # like `null`); check the field explicitly so rules can opt out of fire-once.
+  FIRE_ONCE=$(echo "$rule" | jq -r 'if (.fire_once_per_session == false) then "false" else "true" end')
+
+  [[ -z "$RULE_ID" || -z "$PATTERN" || -z "$GUIDANCE" ]] && continue
+
+  if ! prompt_rules_pattern_matches "$PROMPT" "$PATTERN"; then
+    continue
+  fi
+
+  prompt_rules_emit "$SESSION_ID" "prompt_rule.matched" \
+    "$(jq -cn --arg id "$RULE_ID" '{rule_id: $id}')" || true
+
+  ALREADY_FIRED=$(echo "$FIRED" | jq --arg id "$RULE_ID" 'index($id) != null' 2>/dev/null)
+  if [[ "$FIRE_ONCE" == "true" && "$ALREADY_FIRED" == "true" ]]; then
+    continue
+  fi
+
+  if (( ${#GUIDANCE} > MAX_CHARS )); then
+    GUIDANCE="${GUIDANCE:0:$MAX_CHARS}"
+  fi
+
+  ADD_LEN=${#GUIDANCE}
+  # +2 accounts for the blank-line separator between guidance entries.
+  if (( COMBINED_LEN + ADD_LEN + 2 > PER_TURN_MAX_CHARS )); then
+    continue
+  fi
+
+  if [[ -n "$COMBINED_GUIDANCE" ]]; then
+    COMBINED_GUIDANCE="$COMBINED_GUIDANCE"$'\n\n'"$GUIDANCE"
+    COMBINED_LEN=$(( COMBINED_LEN + ADD_LEN + 2 ))
+  else
+    COMBINED_GUIDANCE="$GUIDANCE"
+    COMBINED_LEN=$ADD_LEN
+  fi
+
+  prompt_rules_mark_fired "$SESSION_ID" "$RULE_ID" || hook_failure "Failed to mark rule fired: $RULE_ID"
+  FIRED=$(prompt_rules_load_fired "$SESSION_ID")
+
+  prompt_rules_emit "$SESSION_ID" "prompt_rule.applied" \
+    "$(jq -cn --arg id "$RULE_ID" --argjson chars "$ADD_LEN" \
+      '{rule_id: $id, guidance_chars: $chars}')" || true
+done < <(echo "$RULES" | jq -c '.[]' 2>/dev/null)
+
+if [[ -n "$COMBINED_GUIDANCE" ]]; then
+  jq -n --arg ctx "$COMBINED_GUIDANCE" \
+    '{
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: $ctx
+      }
+    }'
+fi
+
+hook_success
+exit 0

package/scripts/lib/portable-lock.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see every PostToolUse history append silently fail.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}

package/scripts/lib/prompt-rules.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# Prompt-rule library — declarative regex-triggered guidance injection.
+#
+# Source after validate-path.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/validate-path.sh"
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/prompt-rules.sh"
+#
+# Rule schema (JSON file at ~/.onlooker/prompt-rules.json or <cwd>/.claude/prompt-rules.json):
+#   {
+#     "rules": [
+#       {
+#         "id": "rule-no-verify-warning",
+#         "pattern": "--no-verify",
+#         "guidance": "Skipping hooks usually masks the real issue.",
+#         "fire_once_per_session": true,
+#         "max_chars": 400,
+#         "enabled": true,
+#         "tags": ["safety"]
+#       }
+#     ]
+#   }
+#
+# Patterns are POSIX ERE (bash [[ =~ ]] semantics). `\b` is unsupported;
+# use `(^|[^a-zA-Z0-9_])foo([^a-zA-Z0-9_]|$)` for word-boundary behavior.
+
+export ONLOOKER_PROMPT_RULES_DIR="${ONLOOKER_PROMPT_RULES_DIR:-$ONLOOKER_DIR/prompt-rules}"
+export ONLOOKER_PROMPT_RULES_SESSIONS_DIR="$ONLOOKER_PROMPT_RULES_DIR/sessions"
+
+# Path to the global rules file.
+# Usage: path=$(prompt_rules_global_path)
+prompt_rules_global_path() {
+  printf '%s\n' "$ONLOOKER_DIR/prompt-rules.json"
+}
+
+# Path to the project-scoped rules file for a given cwd.
+# Usage: path=$(prompt_rules_project_path "$cwd")
+prompt_rules_project_path() {
+  local cwd="${1:-$PWD}"
+  printf '%s\n' "$cwd/.claude/prompt-rules.json"
+}
+
+# Path to the fired-marker file for a session.
+# Usage: path=$(prompt_rules_fired_path "$session_id")
+prompt_rules_fired_path() {
+  local session_id="${1:-unknown}"
+  printf '%s\n' "$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/$session_id.json"
+}
+
+# Print the merged rules JSON array. Project entries override global by id.
+# Disabled rules (enabled: false) are filtered out.
+# Usage: rules=$(prompt_rules_load_merged "$cwd")
+prompt_rules_load_merged() {
+  local cwd="${1:-$PWD}"
+  local global_path project_path
+  global_path=$(prompt_rules_global_path)
+  project_path=$(prompt_rules_project_path "$cwd")
+
+  local global_json='[]'
+  local project_json='[]'
+  if [[ -f "$global_path" ]]; then
+    global_json=$(jq -c '.rules // []' "$global_path" 2>/dev/null) || global_json='[]'
+  fi
+  if [[ -f "$project_path" ]]; then
+    project_json=$(jq -c '.rules // []' "$project_path" 2>/dev/null) || project_json='[]'
+  fi
+
+  jq -n \
+    --argjson g "$global_json" \
+    --argjson p "$project_json" \
+    '
+    # Coerce non-array inputs to []; drop entries without a string id so a
+    # single malformed rule cannot poison `map({(.id): .})` (which errors when
+    # `.id` is null or non-string).
+    def to_array(x): if (x | type) == "array" then x else [] end;
+    def sanitize(arr): to_array(arr) | map(select(type == "object" and (.id | type) == "string" and .id != ""));
+    def to_map(arr): (sanitize(arr) | map({(.id): .}) | add) // {};
+    (to_map($g) + to_map($p))
+    | to_entries
+    | map(.value)
+    | map(select(.enabled != false))
+    '
+}
+
+# Print the fired-id JSON array for a session.
+# Usage: fired=$(prompt_rules_load_fired "$session_id")
+prompt_rules_load_fired() {
+  local session_id="${1:-unknown}"
+  local path
+  path=$(prompt_rules_fired_path "$session_id")
+  if [[ -f "$path" ]]; then
+    jq -c '.fired_ids // []' "$path" 2>/dev/null || echo '[]'
+  else
+    echo '[]'
+  fi
+}
+
+# Mark a rule id as fired for a session. Idempotent.
+# Read-modify-write is wrapped in a portable file lock so concurrent
+# UserPromptSubmit hooks (or other writers) can't drop updates or corrupt
+# the marker file — same pattern as tool-history.sh.
+# Usage: prompt_rules_mark_fired "$session_id" "$rule_id"
+prompt_rules_mark_fired() {
+  local session_id="${1:-unknown}"
+  local rule_id="${2:-}"
+  [[ -z "$rule_id" ]] && return 1
+  local path
+  path=$(prompt_rules_fired_path "$session_id")
+  ensure_dir_exists "$(dirname "$path")" || return 1
+
+  local lockfile="${path}.lock"
+  lock_acquire "$lockfile" 5 || return 1
+
+  local current='[]'
+  if [[ -f "$path" ]]; then
+    current=$(jq -c '.fired_ids // []' "$path" 2>/dev/null) || current='[]'
+  fi
+  local next rc=0
+  next=$(jq -cn --argjson cur "$current" --arg id "$rule_id" \
+    '{fired_ids: ($cur + [$id] | unique)}')
+  printf '%s\n' "$next" > "$path" || rc=$?
+  lock_release "$lockfile"
+  return "$rc"
+}
+
+# Test whether a POSIX ERE pattern matches the given prompt.
+# Returns 0 on match, 1 otherwise (including empty or invalid pattern).
+# Invalid ERE patterns from user-edited rule files would otherwise leak a
+# "syntax error in regular expression" message to stderr and return status 2;
+# we treat that as a non-match so the hook stays quiet on bad input.
+# Usage: prompt_rules_pattern_matches "$prompt" "$pattern" && echo "hit"
+prompt_rules_pattern_matches() {
+  local prompt="$1"
+  local pattern="$2"
+  [[ -z "$pattern" ]] && return 1
+  { [[ "$prompt" =~ $pattern ]]; } 2>/dev/null
+  local rc=$?
+  # Bash returns 2 for a malformed regex; collapse to "no match".
+  if (( rc == 0 )); then
+    return 0
+  fi
+  return 1
+}
+
+# Append a prompt-rule event to the global events log.
+# These event types (prompt_rule.matched, prompt_rule.applied) are not yet
+# in @onlooker-community/schema; once added, swap to onlooker_append_event.
+# Usage: prompt_rules_emit "$session_id" "prompt_rule.matched" "$payload_json"
+prompt_rules_emit() {
+  local session_id="${1:-unknown}"
+  local event_type="${2:-}"
+  local payload_json="${3:-{\}}"
+  [[ -z "$event_type" ]] && return 1
+  ensure_file_exists "$ONLOOKER_EVENTS_LOG" || return 1
+
+  local timestamp plugin
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  plugin="${ONLOOKER_PLUGIN_NAME:-onlooker}"
+
+  jq -cn \
+    --arg ts "$timestamp" \
+    --arg sid "$session_id" \
+    --arg plugin "$plugin" \
+    --arg type "$event_type" \
+    --argjson payload "$payload_json" \
+    --arg turn "${ONLOOKER_TURN_NUMBER:-}" \
+    '{timestamp: $ts, session_id: $sid, plugin: $plugin, event_type: $type, payload: $payload}
+     + (if $turn != "" then {turn: ($turn | tonumber)} else {} end)
+    ' >> "$ONLOOKER_EVENTS_LOG"
+}
+
+# Print a human-readable table of merged rules with their fired status.
+# Usage: prompt_rules_list_table "$session_id" "$cwd"
+prompt_rules_list_table() {
+  local session_id="${1:-unknown}"
+  local cwd="${2:-$PWD}"
+
+  local rules fired global_path project_path
+  rules=$(prompt_rules_load_merged "$cwd")
+  fired=$(prompt_rules_load_fired "$session_id")
+  global_path=$(prompt_rules_global_path)
+  project_path=$(prompt_rules_project_path "$cwd")
+
+  local rule_count
+  rule_count=$(echo "$rules" | jq 'length' 2>/dev/null || echo 0)
+
+  printf 'Prompt rules (session: %s)\n' "$session_id"
+  printf '  global file:  %s%s\n' "$global_path" \
+    "$([[ -f "$global_path" ]] && printf '' || printf ' (missing)')"
+  printf '  project file: %s%s\n' "$project_path" \
+    "$([[ -f "$project_path" ]] && printf '' || printf ' (missing)')"
+  printf '  active rules: %s\n' "$rule_count"
+  printf '\n'
+
+  if [[ "$rule_count" -eq 0 ]]; then
+    printf '  (no rules)\n'
+    return 0
+  fi
+
+  echo "$rules" | jq -r --argjson fired "$fired" '
+    .[]
+    | . as $rule
+    | "  - id: \(.id)\n"
+      + "    pattern: \(.pattern)\n"
+      + "    fired: \(if ($fired | any(. == $rule.id)) then "yes" else "no" end)\n"
+      + "    guidance: \(.guidance)\n"
+  '
+}

package/scripts/lib/tool-history.sh

@@ -13,8 +13,9 @@ tool_history_build_record() {
 	onlooker_event_from_hook "$input_json"
 }
 
-# Append a canonical event to the session JSONL history (flock-protected).
-# Usage: tool_history_append "$SESSION_ID" "$event_json"
+# Append a canonical event to the session JSONL history (lock-protected).
+# Uses the portable mkdir-based mutex so the hook works on macOS as well as
+# Linux. Usage: tool_history_append "$SESSION_ID" "$event_json"
 tool_history_append() {
 	local session_id="${1:-}"
 	local record_json="${2:-}"
@@ -25,11 +26,9 @@ tool_history_append() {
 	ensure_dir_exists "$ONLOOKER_SESSION_HISTORY_DIR" || return 1
 
 	local lockfile="${history_file}.lock"
-	exec 202>"$lockfile"
-	if ! flock -w 5 202; then
-		return 1
-	fi
-
+	lock_acquire "$lockfile" 5 || return 1
 	printf '%s\n' "$record_json" >>"$history_file" 2>/dev/null
-	flock -u 202
+	local rc=$?
+	lock_release "$lockfile"
+	return "$rc"
 }

package/scripts/lib/validate-path.sh

@@ -22,6 +22,10 @@ export ONLOOKER_EVENTS_LOG="$ONLOOKER_DIR/logs/onlooker-events.jsonl"
 export ONLOOKER_HOOK_HEALTH_LOG="$ONLOOKER_DIR/logs/hook-health.jsonl"
 _VALIDATE_PATH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export ONLOOKER_EMIT="$_VALIDATE_PATH_DIR/onlooker-emit.sh"
+# Portable mutex (flock substitute) — every hook script that needs to write
+# shared state can call lock_acquire/lock_release after sourcing this file.
+# shellcheck source=portable-lock.sh
+source "$_VALIDATE_PATH_DIR/portable-lock.sh"
 unset _VALIDATE_PATH_DIR
 
 # ==============================================================================