@onlooker-community/ecosystem 0.17.0 → 0.18.0

package/.claude-plugin/marketplace.json

@@ -98,6 +98,19 @@
       "license": "MIT",
       "keywords": ["documentation", "intent", "decisions", "tradeoffs", "why", "context"],
       "tags": ["documentation", "memory"]
+    },
+    {
+      "name": "counsel",
+      "source": "./plugins/counsel",
+      "description": "Weekly synthesis and recommendations from your full observability stack. Reads all plugin event logs, identifies patterns, surfaces improvement opportunities, and injects a structured brief at session start when the last brief is stale. Turns disparate logs into a coaching signal. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["synthesis", "recommendations", "observability", "coaching", "patterns", "weekly"],
+      "tags": ["observability", "coaching"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Observability substrate for Claude Code. Provides the shared ~/.onlooker/ storage root, 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,10 +1,11 @@
 {
-  ".": "0.17.0",
+  ".": "0.18.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
   "plugins/cartographer": "0.2.0",
   "plugins/governor": "0.2.0",
   "plugins/compass": "0.2.0",
-  "plugins/scribe": "0.2.0"
+  "plugins/scribe": "0.2.0",
+  "plugins/counsel": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.18.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.17.0...ecosystem-v0.18.0) (2026-06-02)
+
+
+### Features
+
+* **counsel:** weekly observability synthesis and coaching brief :robot: ([#51](https://github.com/onlooker-community/ecosystem/issues/51)) ([6364586](https://github.com/onlooker-community/ecosystem/commit/63645863cf3a1d7bbf0353aacb9b71e4f977dd56))
+
 ## [0.17.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.16.0...ecosystem-v0.17.0) (2026-06-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -26,7 +26,7 @@
     "test": "npm run test:bats && npm run test:schema",
     "test:bats": "bats test/bats",
     "test:schema": "node --test test/node/*.test.mjs",
-    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh",
+    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",

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

@@ -0,0 +1,14 @@
+{
+  "name": "counsel",
+  "version": "0.2.0",
+  "description": "Weekly synthesis and recommendations from the full observability stack. Reads all plugin event logs, produces a structured improvement brief, and injects it at session start when the last brief is stale.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": [],
+  "agents": []
+}

package/plugins/counsel/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.1.0...counsel-v0.2.0) (2026-06-02)
+
+
+### Features
+
+* **counsel:** weekly observability synthesis and coaching brief :robot: ([#51](https://github.com/onlooker-community/ecosystem/issues/51)) ([6364586](https://github.com/onlooker-community/ecosystem/commit/63645863cf3a1d7bbf0353aacb9b71e4f977dd56))

package/plugins/counsel/config.json

@@ -0,0 +1,20 @@
+{
+  "counsel": {
+    "enabled": true,
+    "synthesis_interval_days": 7,
+    "lookback_days": 30,
+    "evaluator": {
+      "model": "claude-haiku-4-5-20251001",
+      "timeout": 90,
+      "max_tokens": 4096,
+      "temperature": 0.4
+    },
+    "capture": {
+      "min_events": 10,
+      "events_chars_max": 60000
+    },
+    "output": {
+      "brief_max_chars": 3000
+    }
+  }
+}

package/plugins/counsel/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/counsel-session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Counsel SessionStart hook — weekly improvement brief injection.
+#
+# Fires at session start. If the last brief for this project is older than
+# synthesis_interval_days (default: 7), runs a Haiku synthesis pass over the
+# full event log and injects the resulting brief as additionalContext.
+#
+# Skip conditions (all silent):
+#   - counsel.enabled is false
+#   - no project key (non-git directory)
+#   - brief is still fresh
+#   - fewer than min_events events in the lookback window
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits hookSpecificOutput JSON on stdout (even when context is empty).
+#   - Errors are written to stderr only.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/counsel-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-config.sh"
+# shellcheck source=../lib/counsel-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-events.sh"
+# shellcheck source=../lib/counsel-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+# shellcheck source=../lib/counsel-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-ulid.sh"
+# shellcheck source=../lib/counsel-reader.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+# shellcheck source=../lib/counsel-synthesize.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-synthesize.sh"
+# shellcheck source=../lib/counsel-brief.sh
+source "${PLUGIN_ROOT}/scripts/lib/counsel-brief.sh"
+
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '
+		{
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: $ctx
+			}
+		}
+	'
+}
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+REPO_ROOT=$(counsel_project_repo_root "$CWD")
+counsel_config_load "$REPO_ROOT"
+
+if ! counsel_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+PROJECT_KEY=$(counsel_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+_generate_rc=0
+OUTPUT_PATH=$(counsel_generate_brief "$SESSION_ID" "$CWD") || _generate_rc=$?
+
+if [[ $_generate_rc -ne 0 ]]; then
+	# rc=2 means stale check passed (brief is fresh) or too few events — silent skip.
+	[[ $_generate_rc -ne 2 ]] && printf 'counsel-session-start: brief generation failed for session %s\n' "$SESSION_ID" >&2
+	_emit ""
+	exit 0
+fi
+
+if [[ -z "$OUTPUT_PATH" || ! -f "$OUTPUT_PATH" ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Load the brief content and apply the configured char budget.
+BRIEF_MAX_CHARS=$(counsel_config_get '.counsel.output.brief_max_chars')
+[[ -z "$BRIEF_MAX_CHARS" || "$BRIEF_MAX_CHARS" == "null" ]] && BRIEF_MAX_CHARS="3000"
+
+BRIEF_CONTENT=$(head -c "$BRIEF_MAX_CHARS" "$OUTPUT_PATH" 2>/dev/null) || BRIEF_CONTENT=""
+
+if [[ -z "$BRIEF_CONTENT" ]]; then
+	_emit ""
+	exit 0
+fi
+
+CONTEXT="Counsel — weekly improvement brief (auto-generated from your onlooker event log):
+
+${BRIEF_CONTENT}
+
+(Counsel injected this brief for project key ${PROJECT_KEY}. Set counsel.enabled=false to disable.)"
+
+_emit "$CONTEXT"
+exit 0

package/plugins/counsel/scripts/lib/counsel-brief.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Brief orchestrator for Counsel.
+#
+# Checks whether a fresh brief is needed, runs the full synthesis pipeline,
+# writes a Markdown brief to ~/.onlooker/counsel/<project-key>/briefs/,
+# and emits counsel.brief.generated.
+#
+# Exposes:
+#   counsel_brief_is_stale <project_key> <interval_days>
+#     Returns 0 if a new brief should be generated, 1 if the existing one is fresh.
+#
+#   counsel_generate_brief <session_id> <cwd>
+#     Runs the full pipeline. Echoes the output path on success.
+#     Returns 2 if skipped (not stale or too few events).
+#     Returns 1 on hard failure.
+
+# shellcheck source=./counsel-reader.sh
+# shellcheck source=./counsel-synthesize.sh
+# shellcheck source=./counsel-events.sh
+# shellcheck source=./counsel-project-key.sh
+# (caller must source these before counsel-brief.sh)
+
+_counsel_latest_brief_path() {
+	local briefs_dir="${1:-}"
+	[[ -d "$briefs_dir" ]] || return 1
+	# Briefs are named YYYY-WW.md; newest sorts last lexicographically.
+	local latest
+	latest=$(ls -1 "$briefs_dir"/*.md 2>/dev/null | sort | tail -1)
+	[[ -n "$latest" ]] || return 1
+	printf '%s' "$latest"
+}
+
+_counsel_brief_mtime_epoch() {
+	local path="${1:-}"
+	[[ -f "$path" ]] || { printf '0'; return 0; }
+	if [[ "$(uname)" == "Darwin" ]]; then
+		stat -f '%m' "$path" 2>/dev/null || printf '0'
+	else
+		stat -c '%Y' "$path" 2>/dev/null || printf '0'
+	fi
+}
+
+counsel_brief_is_stale() {
+	local project_key="${1:-}"
+	local interval_days="${2:-7}"
+
+	local briefs_dir
+	briefs_dir=$(counsel_project_dir "$project_key")
+
+	local latest_path
+	latest_path=$(_counsel_latest_brief_path "$briefs_dir") || { return 0; }
+
+	local mtime now age_days
+	mtime=$(_counsel_brief_mtime_epoch "$latest_path")
+	now=$(date +%s 2>/dev/null) || now=0
+	age_days=$(( (now - mtime) / 86400 ))
+
+	[[ "$age_days" -ge "$interval_days" ]]
+}
+
+_counsel_format_brief() {
+	local brief_json="${1:-}"
+	local period_start="${2:-}"
+	local period_end="${3:-}"
+	local event_count="${4:-0}"
+
+	local summary patterns_json recs_json wins_json watch_json
+	summary=$(printf '%s' "$brief_json" | jq -r '.summary // ""' 2>/dev/null) || summary=""
+	patterns_json=$(printf '%s' "$brief_json" | jq -c '.patterns // []' 2>/dev/null) || patterns_json="[]"
+	recs_json=$(printf '%s' "$brief_json" | jq -c '.recommendations // []' 2>/dev/null) || recs_json="[]"
+	wins_json=$(printf '%s' "$brief_json" | jq -c '.wins // []' 2>/dev/null) || wins_json="[]"
+	watch_json=$(printf '%s' "$brief_json" | jq -c '.watch // []' 2>/dev/null) || watch_json="[]"
+
+	local timestamp
+	timestamp=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || timestamp="unknown"
+
+	{
+		printf '# Counsel Brief: %s — %s\n\n' "$period_start" "$period_end"
+		[[ -n "$summary" ]] && printf '> %s\n\n' "$summary"
+
+		printf '## Recommendations\n\n'
+		local rec_count
+		rec_count=$(printf '%s' "$recs_json" | jq 'length' 2>/dev/null) || rec_count=0
+		if [[ "$rec_count" -gt 0 ]]; then
+			local i
+			for ((i = 0; i < rec_count; i++)); do
+				local title rationale priority
+				title=$(printf '%s' "$recs_json" | jq -r ".[$i].title // \"\"" 2>/dev/null) || title=""
+				rationale=$(printf '%s' "$recs_json" | jq -r ".[$i].rationale // \"\"" 2>/dev/null) || rationale=""
+				priority=$(printf '%s' "$recs_json" | jq -r ".[$i].priority // \"medium\"" 2>/dev/null) || priority="medium"
+				[[ -z "$title" ]] && continue
+				printf '### [%s] %s\n\n' "$priority" "$title"
+				[[ -n "$rationale" ]] && printf '%s\n\n' "$rationale"
+			done
+		else
+			printf '*No recommendations this period.*\n\n'
+		fi
+
+		printf '## Patterns Observed\n\n'
+		local pat_count
+		pat_count=$(printf '%s' "$patterns_json" | jq 'length' 2>/dev/null) || pat_count=0
+		if [[ "$pat_count" -gt 0 ]]; then
+			printf '%s' "$patterns_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None identified.*\n\n'
+		fi
+
+		printf '## Wins\n\n'
+		local win_count
+		win_count=$(printf '%s' "$wins_json" | jq 'length' 2>/dev/null) || win_count=0
+		if [[ "$win_count" -gt 0 ]]; then
+			printf '%s' "$wins_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*None noted.*\n\n'
+		fi
+
+		printf '## Watch\n\n'
+		local watch_count
+		watch_count=$(printf '%s' "$watch_json" | jq 'length' 2>/dev/null) || watch_count=0
+		if [[ "$watch_count" -gt 0 ]]; then
+			printf '%s' "$watch_json" | jq -r '.[]' 2>/dev/null | while IFS= read -r item; do
+				[[ -n "$item" ]] && printf '- %s\n' "$item"
+			done
+			printf '\n'
+		else
+			printf '*Nothing flagged.*\n\n'
+		fi
+
+		printf '---\n'
+		printf '*Generated by counsel · %s · %d events analyzed*\n' "$timestamp" "$event_count"
+	}
+}
+
+counsel_generate_brief() {
+	local session_id="${1:-}"
+	local cwd="${2:-}"
+
+	[[ -z "$session_id" ]] && return 1
+
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+
+	# Resolve config values.
+	local interval_days lookback_days model timeout_s max_tokens temperature chars_max min_events
+	interval_days=$(counsel_config_get '.counsel.synthesis_interval_days')
+	[[ -z "$interval_days" || "$interval_days" == "null" ]] && interval_days="7"
+	lookback_days=$(counsel_config_get '.counsel.lookback_days')
+	[[ -z "$lookback_days" || "$lookback_days" == "null" ]] && lookback_days="30"
+	model=$(counsel_config_get '.counsel.evaluator.model')
+	[[ -z "$model" || "$model" == "null" ]] && model="claude-haiku-4-5-20251001"
+	timeout_s=$(counsel_config_get '.counsel.evaluator.timeout')
+	[[ -z "$timeout_s" || "$timeout_s" == "null" ]] && timeout_s="90"
+	max_tokens=$(counsel_config_get '.counsel.evaluator.max_tokens')
+	[[ -z "$max_tokens" || "$max_tokens" == "null" ]] && max_tokens="4096"
+	temperature=$(counsel_config_get '.counsel.evaluator.temperature')
+	[[ -z "$temperature" || "$temperature" == "null" ]] && temperature="0.4"
+	chars_max=$(counsel_config_get '.counsel.capture.events_chars_max')
+	[[ -z "$chars_max" || "$chars_max" == "null" ]] && chars_max="60000"
+	min_events=$(counsel_config_get '.counsel.capture.min_events')
+	[[ -z "$min_events" || "$min_events" == "null" ]] && min_events="10"
+
+	local project_key
+	project_key=$(counsel_project_key "$cwd")
+
+	# Stale check.
+	if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
+		return 2
+	fi
+
+	# Read events.
+	local events_text
+	events_text=$(counsel_read_events "$lookback_days" "$chars_max")
+
+	local event_count
+	event_count=$(counsel_count_events "$events_text")
+
+	if [[ "$event_count" -lt "$min_events" ]]; then
+		return 2
+	fi
+
+	# Run synthesis.
+	local brief_json
+	brief_json=$(counsel_synthesize "$events_text" "$model" "$timeout_s" "$max_tokens" "$temperature") || {
+		printf 'counsel_generate_brief: synthesis failed for session %s\n' "$session_id" >&2
+		return 1
+	}
+
+	# Compute period bounds.
+	local period_start period_end
+	period_end=$(date '+%Y-%m-%d' 2>/dev/null) || period_end="unknown"
+	if [[ "$(uname)" == "Darwin" ]]; then
+		period_start=$(date -v "-${lookback_days}d" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+	else
+		period_start=$(date -d "-${lookback_days} days" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+	fi
+
+	# Determine sources consulted.
+	local sources_json
+	sources_json=$(counsel_sources_from_events "$events_text")
+
+	# Write brief.
+	local briefs_dir output_path
+	if [[ -n "$project_key" ]]; then
+		briefs_dir=$(counsel_project_dir "$project_key")
+	else
+		briefs_dir="${onlooker_dir}/counsel/unknown/briefs"
+	fi
+
+	mkdir -p "$briefs_dir" 2>/dev/null || {
+		printf 'counsel_generate_brief: cannot create briefs dir %s\n' "$briefs_dir" >&2
+		return 1
+	}
+
+	local week_label
+	week_label=$(date '+%G-%V' 2>/dev/null) || week_label=$(date '+%Y-%U' 2>/dev/null) || week_label="unknown"
+	local filename="${week_label}.md"
+	output_path="${briefs_dir}/${filename}"
+
+	local doc
+	doc=$(_counsel_format_brief "$brief_json" "$period_start" "$period_end" "$event_count")
+
+	printf '%s\n' "$doc" > "$output_path" 2>/dev/null || {
+		printf 'counsel_generate_brief: failed to write %s\n' "$output_path" >&2
+		return 1
+	}
+
+	# Emit counsel.brief.generated.
+	local rec_count
+	rec_count=$(printf '%s' "$brief_json" | jq '.recommendations | length' 2>/dev/null) || rec_count=0
+
+	local payload
+	payload=$(jq -n \
+		--arg ps "$period_start" \
+		--arg pe "$period_end" \
+		--argjson rc "$rec_count" \
+		--argjson src "$sources_json" \
+		'{period_start: $ps, period_end: $pe, recommendation_count: $rc, sources_consulted: $src}') || payload=""
+
+	[[ -n "$payload" ]] && counsel_emit_event "counsel.brief.generated" "$payload" || true
+
+	printf '%s' "$output_path"
+}

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Config resolution for Counsel.
+#
+# Three-layer merge, latest wins:
+#   1. plugins/counsel/config.json   (plugin defaults)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   counsel_config_load <repo_root>    # populates _COUNSEL_CONFIG (JSON)
+#   counsel_config_get <jq-path>       # echoes string value (empty if unset)
+#   counsel_config_get_json <jq-path>  # echoes JSON value (null if unset)
+#   counsel_config_enabled             # 0 if counsel.enabled is true
+
+_COUNSEL_CONFIG="{}"
+
+counsel_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ counsel: (.counsel // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_COUNSEL_CONFIG="$merged"
+}
+
+counsel_config_get() {
+	local path="$1"
+	printf '%s' "$_COUNSEL_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+counsel_config_get_json() {
+	local path="$1"
+	printf '%s' "$_COUNSEL_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+counsel_config_enabled() {
+	local v
+	v=$(counsel_config_get '.counsel.enabled')
+	[[ "$v" == "true" ]]
+}

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Canonical counsel.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema before being
+# appended to $ONLOOKER_EVENTS_LOG (defaults to $ONLOOKER_DIR/logs/onlooker-events.jsonl).
+#
+# Usage:
+#   counsel_emit_event "counsel.brief.generated" '{"period_start":"...","period_end":"...","recommendation_count":3}'
+
+_COUNSEL_PLUGIN_NAME="counsel"
+
+_counsel_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
+}
+
+_counsel_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'
+}
+
+counsel_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_counsel_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_counsel_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_COUNSEL_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}' \
+		2>/dev/null) || return 1
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t counsel-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/counsel-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_COUNSEL_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'counsel_emit_event: 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/counsel/scripts/lib/counsel-project-key.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Project key derivation for Counsel.
+#
+# Mirrors the tribunal/scribe project-key scheme so plugins partition storage
+# identically. A project key is a stable 12-char hex identifier derived from
+# the git remote URL (preferred) or repo root path (fallback).
+
+_counsel_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+counsel_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+counsel_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+counsel_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(counsel_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_counsel_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(counsel_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_counsel_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}
+
+counsel_project_dir() {
+	local project_key="${1:-}"
+	[[ -z "$project_key" ]] && return 1
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/counsel/${project_key}/briefs"
+}

package/plugins/counsel/scripts/lib/counsel-reader.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Event log reader for Counsel.
+#
+# Reads $ONLOOKER_EVENTS_LOG and returns a filtered, summarized view of
+# the last N days suitable for passing to the synthesis prompt.
+#
+# Exposes:
+#   counsel_read_events <lookback_days> <chars_max>
+#     Echoes a structured text summary of events, or empty string on failure.
+#
+#   counsel_sources_from_events <events_json>
+#     Echoes a JSON array of CounselSource strings present in the event batch.
+
+# Maps event_type prefixes to CounselSource values.
+_counsel_source_for_type() {
+	local event_type="${1:-}"
+	case "$event_type" in
+		tribunal.*)     printf 'tribunal_verdicts' ;;
+		echo.*)         printf 'echo_regressions' ;;
+		sentinel.*)     printf 'sentinel_audit' ;;
+		warden.*)       printf 'warden_audit' ;;
+		oracle.*)       printf 'oracle_calibrations' ;;
+		meridian.*)     printf 'meridian_reliance' ;;
+		*)              printf 'onlooker_events' ;;
+	esac
+}
+
+counsel_read_events() {
+	local lookback_days="${1:-30}"
+	local chars_max="${2:-60000}"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	[[ -f "$log_path" ]] || { printf ''; return 0; }
+
+	# Compute cutoff as an ISO 8601 date string. ISO 8601 strings are
+	# lexicographically sortable, so string comparison is safe for filtering.
+	local cutoff_ts
+	if [[ "$(uname)" == "Darwin" ]]; then
+		cutoff_ts=$(date -v "-${lookback_days}d" -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| cutoff_ts=""
+	else
+		cutoff_ts=$(date -d "-${lookback_days} days" -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| cutoff_ts=""
+	fi
+
+	# Filter to events within the lookback window. If cutoff_ts is empty (date
+	# command unavailable) fall through and include all events.
+	local summary
+	# -rc: compact output keeps each object on one line (JSONL-shaped), which
+	# downstream counsel_count_events and counsel_sources_from_events require.
+	summary=$(jq -rc --arg cutoff "$cutoff_ts" '
+		select(.timestamp != null) |
+		select($cutoff == "" or .timestamp >= $cutoff) |
+		{
+			type:      .event_type,
+			plugin:    (.plugin // "unknown"),
+			ts:        .timestamp,
+			session:   (.session_id // ""),
+			payload:   (.payload // {})
+		}
+	' "$log_path" 2>/dev/null | head -c "$chars_max") || summary=""
+
+	printf '%s' "$summary"
+}
+
+counsel_sources_from_events() {
+	local events_text="${1:-}"
+	[[ -z "$events_text" ]] && { printf '["onlooker_events"]'; return 0; }
+
+	local sources=()
+	local seen_tribunal=0 seen_echo=0 seen_sentinel=0 seen_warden=0 seen_oracle=0 seen_meridian=0 seen_other=0
+
+	while IFS= read -r line; do
+		[[ -z "$line" ]] && continue
+		local etype
+		etype=$(printf '%s' "$line" | jq -r '.type // ""' 2>/dev/null) || continue
+		case "$etype" in
+			tribunal.*)  seen_tribunal=1 ;;
+			echo.*)      seen_echo=1 ;;
+			sentinel.*)  seen_sentinel=1 ;;
+			warden.*)    seen_warden=1 ;;
+			oracle.*)    seen_oracle=1 ;;
+			meridian.*)  seen_meridian=1 ;;
+			*)           seen_other=1 ;;
+		esac
+	done <<< "$events_text"
+
+	[[ "$seen_other" -eq 1 ]]    && sources+=("\"onlooker_events\"")
+	[[ "$seen_tribunal" -eq 1 ]] && sources+=("\"tribunal_verdicts\"")
+	[[ "$seen_echo" -eq 1 ]]     && sources+=("\"echo_regressions\"")
+	[[ "$seen_sentinel" -eq 1 ]] && sources+=("\"sentinel_audit\"")
+	[[ "$seen_warden" -eq 1 ]]   && sources+=("\"warden_audit\"")
+	[[ "$seen_oracle" -eq 1 ]]   && sources+=("\"oracle_calibrations\"")
+	[[ "$seen_meridian" -eq 1 ]] && sources+=("\"meridian_reliance\"")
+
+	if [[ "${#sources[@]}" -eq 0 ]]; then
+		printf '["onlooker_events"]'
+		return 0
+	fi
+
+	local joined
+	joined=$(IFS=,; printf '%s' "${sources[*]}")
+	printf '[%s]' "$joined"
+}
+
+counsel_count_events() {
+	local events_text="${1:-}"
+	[[ -z "$events_text" ]] && { printf '0'; return 0; }
+	local count=0
+	while IFS= read -r line; do
+		[[ -n "$line" ]] && count=$((count + 1))
+	done <<< "$events_text"
+	printf '%s' "$count"
+}

package/plugins/counsel/scripts/lib/counsel-synthesize.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Synthesis pass for Counsel.
+#
+# Runs a single Haiku call over the event summary to produce a structured
+# improvement brief. The brief is returned as a JSON object.
+#
+# Exposes:
+#   counsel_synthesize <events_text> <model> <timeout_s> <max_tokens> <temperature>
+#     Echoes a JSON object on success, empty string on failure.
+#     JSON shape:
+#       {
+#         "summary":         string,
+#         "patterns":        [string],
+#         "recommendations": [{title, rationale, priority:"high"|"medium"|"low"}],
+#         "wins":            [string],
+#         "watch":           [string]
+#       }
+
+_COUNSEL_SYNTHESIS_PROMPT='You are an engineering coach analyzing an AI agent observability log. You have been given a structured dump of plugin events from the onlooker ecosystem over the past several weeks. Your job is to synthesize patterns, surface improvement opportunities, and highlight what is working well.
+
+Focus on:
+- Recurring failure modes or blocked gates (tribunal, sentinel, warden)
+- Prompt regression trends (echo plugin)
+- Budget or resource pressure patterns (governor plugin)
+- Quality trends over time
+- What the team is consistently doing well
+
+Return a JSON object with exactly these keys:
+{
+  "summary": "2-3 sentence executive summary of the period",
+  "patterns": ["observed pattern — what is happening and how often"],
+  "recommendations": [
+    {
+      "title": "short action title",
+      "rationale": "1-2 sentences explaining why this matters",
+      "priority": "high"
+    }
+  ],
+  "wins": ["thing that is working well — be specific"],
+  "watch": ["trend to monitor — not urgent but worth watching"]
+}
+
+Rules:
+- All fields are required; use empty arrays [] if no items found
+- recommendations must have priority: "high", "medium", or "low"
+- Keep each item to 1-2 sentences
+- Return ONLY the JSON object — no prose, no markdown fences, no explanation
+- If there is insufficient data to draw conclusions, say so in summary and return empty arrays
+
+'
+
+counsel_synthesize() {
+	local events_text="${1:-}"
+	local model="${2:-claude-haiku-4-5-20251001}"
+	local timeout_s="${3:-90}"
+	local max_tokens="${4:-4096}"
+	local temperature="${5:-0.4}"
+
+	[[ -z "$events_text" ]] && return 1
+
+	if ! command -v claude >/dev/null 2>&1; then
+		printf 'counsel_synthesize: claude CLI not found\n' >&2
+		return 1
+	fi
+
+	local prompt_file
+	prompt_file=$(mktemp -t counsel-synth.XXXXXX 2>/dev/null) || prompt_file="/tmp/counsel-synth.$$"
+	trap 'rm -f "$prompt_file"' RETURN
+
+	{
+		printf '%s' "$_COUNSEL_SYNTHESIS_PROMPT"
+		printf '<event_log>\n'
+		printf '%s\n' "$events_text"
+		printf '</event_log>\n'
+	} > "$prompt_file"
+
+	local claude_args=(-p --max-turns 1 --model "$model" --max-tokens "$max_tokens")
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	[[ -z "$response" ]] && return 1
+
+	# Strip markdown fences if present.
+	local clean
+	clean=$(printf '%s' "$response" \
+		| sed -e 's/^```json[[:space:]]*//' -e 's/^```[[:space:]]*//' -e 's/[[:space:]]*```$//')
+
+	if ! printf '%s' "$clean" | jq -e \
+		'.summary and (.patterns | type == "array") and (.recommendations | type == "array") and (.wins | type == "array") and (.watch | type == "array")' \
+		>/dev/null 2>&1; then
+		printf 'counsel_synthesize: response missing required keys\n' >&2
+		return 1
+	fi
+
+	printf '%s' "$clean"
+}

package/plugins/counsel/scripts/lib/counsel-ulid.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Counsel brief IDs.
+
+_COUNSEL_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_counsel_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_COUNSEL_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+counsel_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_counsel_ulid_encode "$now_ms" 10)
+	hi_part=$(_counsel_ulid_encode "$rand_hi" 8)
+	lo_part=$(_counsel_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/release-please-config.json

@@ -126,6 +126,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/counsel": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "counsel",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/counsel-project-key.bats

@@ -0,0 +1,82 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/counsel"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+}
+
+@test "non-git directory returns empty key" {
+  local d="${BATS_TEST_TMPDIR}/non-git"
+  mkdir -p "$d"
+  run counsel_project_key "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "git repo without remote falls back to repo-root hash" {
+  local d="${BATS_TEST_TMPDIR}/local-only-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name "Test"
+
+  local k1
+  k1=$(counsel_project_key "$d")
+  [ -n "$k1" ]
+  [ "${#k1}" -eq 12 ]
+
+  local k2
+  k2=$(counsel_project_key "$d")
+  [ "$k1" = "$k2" ]
+}
+
+@test "git repo with remote uses remote hash, ignores local path" {
+  local a="${BATS_TEST_TMPDIR}/clone-a"
+  local b="${BATS_TEST_TMPDIR}/clone-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+    git -C "$d" remote add origin git@github.com:org/proj.git
+  done
+
+  local ka kb
+  ka=$(counsel_project_key "$a")
+  kb=$(counsel_project_key "$b")
+  [ -n "$ka" ]
+  [ "$ka" = "$kb" ]
+}
+
+@test "different remotes yield different keys" {
+  local a="${BATS_TEST_TMPDIR}/proj-a"
+  local b="${BATS_TEST_TMPDIR}/proj-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+  done
+  git -C "$a" remote add origin git@github.com:org/proj-a.git
+  git -C "$b" remote add origin git@github.com:org/proj-b.git
+
+  local ka kb
+  ka=$(counsel_project_key "$a")
+  kb=$(counsel_project_key "$b")
+  [ -n "$ka" ]
+  [ -n "$kb" ]
+  [ "$ka" != "$kb" ]
+}
+
+@test "counsel_project_dir includes project key in path" {
+  local key="abc123def456"
+  run counsel_project_dir "$key"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"counsel/${key}/briefs" ]]
+}

package/test/bats/counsel-reader.bats

@@ -0,0 +1,132 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/counsel"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+}
+
+# ---------------------------------------------------------------------------
+# counsel_count_events
+# ---------------------------------------------------------------------------
+
+@test "count_events returns 0 for empty input" {
+  run counsel_count_events ""
+  [ "$status" -eq 0 ]
+  [ "$output" = "0" ]
+}
+
+@test "count_events counts non-blank lines" {
+  local text
+  text=$(printf '%s\n%s\n%s\n' '{"type":"a"}' '{"type":"b"}' '{"type":"c"}')
+  run counsel_count_events "$text"
+  [ "$status" -eq 0 ]
+  [ "$output" = "3" ]
+}
+
+# ---------------------------------------------------------------------------
+# counsel_sources_from_events
+# ---------------------------------------------------------------------------
+
+@test "sources_from_events returns onlooker_events for unknown types" {
+  local text='{"type":"scribe.distill.complete"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"onlooker_events"* ]]
+}
+
+@test "sources_from_events detects tribunal events" {
+  local text='{"type":"tribunal.gate.blocked"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"tribunal_verdicts"* ]]
+}
+
+@test "sources_from_events detects echo events" {
+  local text='{"type":"echo.regression.detected"}'
+  run counsel_sources_from_events "$text"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"echo_regressions"* ]]
+}
+
+@test "sources_from_events returns onlooker_events for empty input" {
+  run counsel_sources_from_events ""
+  [ "$status" -eq 0 ]
+  [ "$output" = '["onlooker_events"]' ]
+}
+
+# ---------------------------------------------------------------------------
+# counsel_read_events — file-based
+# ---------------------------------------------------------------------------
+
+@test "read_events returns empty when log does not exist" {
+  export ONLOOKER_EVENTS_LOG="${BATS_TEST_TMPDIR}/no-log.jsonl"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "read_events returns empty for empty log" {
+  local log="${BATS_TEST_TMPDIR}/empty-log.jsonl"
+  touch "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "read_events filters events within lookback window" {
+  local log="${BATS_TEST_TMPDIR}/events.jsonl"
+  # Use a timestamp far in the future to ensure it passes any lookback filter.
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"scribe.distill.complete\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+  run counsel_read_events "30" "60000"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"scribe.distill.complete"* ]]
+}
+
+@test "read_events output is JSONL-shaped: one object per line" {
+  local log="${BATS_TEST_TMPDIR}/multi-events.jsonl"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    "{\"event_type\":\"echo.regression.detected\",\"timestamp\":\"${ts}\",\"session_id\":\"s2\",\"payload\":{}}" \
+    "{\"event_type\":\"scribe.distill.complete\",\"timestamp\":\"${ts}\",\"session_id\":\"s3\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+
+  local events
+  events=$(counsel_read_events "30" "60000")
+
+  # count_events must see exactly 3 records, not inflated by pretty-printing.
+  run counsel_count_events "$events"
+  [ "$status" -eq 0 ]
+  [ "$output" = "3" ]
+}
+
+@test "read_events output preserves source types for sources_from_events" {
+  local log="${BATS_TEST_TMPDIR}/source-events.jsonl"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  printf '%s\n' \
+    "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s1\",\"payload\":{}}" \
+    > "$log"
+  export ONLOOKER_EVENTS_LOG="$log"
+
+  local events
+  events=$(counsel_read_events "30" "60000")
+
+  run counsel_sources_from_events "$events"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"tribunal_verdicts"* ]]
+}