@onlooker-community/ecosystem 0.25.1 → 0.26.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "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.25.1",
+  ".": "0.26.1",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -7,7 +7,7 @@
   "plugins/governor": "0.2.1",
   "plugins/compass": "0.2.0",
   "plugins/scribe": "0.2.1",
-  "plugins/counsel": "0.2.0",
+  "plugins/counsel": "0.3.1",
   "plugins/warden": "0.2.0",
   "plugins/librarian": "0.2.0",
   "plugins/curator": "0.1.0",

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.26.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.26.0...ecosystem-v0.26.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **counsel:** drop unsupported --max-tokens flag from claude synthesis call :relieved: ([#79](https://github.com/onlooker-community/ecosystem/issues/79)) ([ade85ce](https://github.com/onlooker-community/ecosystem/commit/ade85cecb3243781f47e14fea4990ce31e69e8f4))
+* **counsel:** stop pipefail from discarding all events on large logs :relieved: ([#78](https://github.com/onlooker-community/ecosystem/issues/78)) ([638347d](https://github.com/onlooker-community/ecosystem/commit/638347dec3b9df740b7a85c3e475fa2ffe5d054b))
+
+## [0.26.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.25.1...ecosystem-v0.26.0) (2026-06-11)
+
+
+### Features
+
+* **counsel:** add /counsel on-demand weekly-review command :rocket: ([#76](https://github.com/onlooker-community/ecosystem/issues/76)) ([8ce951c](https://github.com/onlooker-community/ecosystem/commit/8ce951cd5cb7b173f194f86c2960a31fb0d6889d))
+
 ## [0.25.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.25.0...ecosystem-v0.25.1) (2026-06-10)
 
 

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "counsel",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -9,6 +9,6 @@
   "homepage": "https://onlooker.dev",
   "repository": "https://github.com/onlooker-community/ecosystem",
   "license": "MIT",
-  "skills": [],
+  "skills": ["./skills/counsel"],
   "agents": []
 }

package/plugins/counsel/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.3.1](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.3.0...counsel-v0.3.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **counsel:** drop unsupported --max-tokens flag from claude synthesis call :relieved: ([#79](https://github.com/onlooker-community/ecosystem/issues/79)) ([ade85ce](https://github.com/onlooker-community/ecosystem/commit/ade85cecb3243781f47e14fea4990ce31e69e8f4))
+* **counsel:** stop pipefail from discarding all events on large logs :relieved: ([#78](https://github.com/onlooker-community/ecosystem/issues/78)) ([638347d](https://github.com/onlooker-community/ecosystem/commit/638347dec3b9df740b7a85c3e475fa2ffe5d054b))
+
+## [0.3.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.2.0...counsel-v0.3.0) (2026-06-11)
+
+
+### Features
+
+* **counsel:** add /counsel on-demand weekly-review command :rocket: ([#76](https://github.com/onlooker-community/ecosystem/issues/76)) ([8ce951c](https://github.com/onlooker-community/ecosystem/commit/8ce951cd5cb7b173f194f86c2960a31fb0d6889d))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/counsel-v0.1.0...counsel-v0.2.0) (2026-06-02)
 
 

package/plugins/counsel/README.md

@@ -18,6 +18,18 @@ Counsel partitions the event stream by source plugin, recognizing `tribunal`, `e
 
 The hook always exits 0 — it never blocks a session from starting. It skips silently when Counsel is disabled, the directory has no project key (non-git), the latest brief is still fresh, or fewer than `capture.min_events` events fall inside the lookback window.
 
+## On-demand brief — `/counsel`
+
+The SessionStart path only regenerates when the latest brief is stale. To run the weekly review immediately — regardless of freshness — invoke the `/counsel` skill. It forces a synthesis pass, writes the brief, emits `counsel.brief.generated`, and renders the result in the conversation instead of injecting it invisibly.
+
+| Invocation | What it does |
+|------------|--------------|
+| `/counsel` | Forces a fresh synthesis now (bypassing the staleness gate), writes `<YYYY-WW>.md`, and prints the brief. Re-running in the same ISO week overwrites that week's brief in place. |
+| `/counsel --show` | Renders the most recent brief already on disk. No LLM call, no events emitted. |
+| `/counsel --status` | Reports the latest brief's age, last-generated time, and whether it is stale. No LLM call. |
+
+The on-demand path bypasses only the staleness gate — output, events, storage layout, project keying, and the `capture.min_events` floor are identical to the SessionStart path. If too few events fall inside the lookback window, `/counsel` reports that rather than emitting a thin brief.
+
 ## Activation
 
 Counsel is **on by default**. Disable it per-project in `.claude/settings.json` (or globally in `~/.claude/settings.json`):

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

@@ -9,8 +9,10 @@
 #   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>
+#   counsel_generate_brief <session_id> <cwd> [force]
 #     Runs the full pipeline. Echoes the output path on success.
+#     When [force] is "1" or "force", the staleness gate is bypassed (used by
+#     the on-demand /counsel skill); the min_events gate always applies.
 #     Returns 2 if skipped (not stale or too few events).
 #     Returns 1 on hard failure.
 
@@ -101,7 +103,7 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
@@ -113,7 +115,7 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
@@ -125,14 +127,14 @@ _counsel_format_brief() {
 		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"
+				[[ -n "$item" ]] && printf -- '- %s\n' "$item"
 			done
 			printf '\n'
 		else
 			printf '*Nothing flagged.*\n\n'
 		fi
 
-		printf '---\n'
+		printf -- '---\n'
 		printf '*Generated by counsel · %s · %d events analyzed*\n' "$timestamp" "$event_count"
 	}
 }
@@ -140,6 +142,7 @@ _counsel_format_brief() {
 counsel_generate_brief() {
 	local session_id="${1:-}"
 	local cwd="${2:-}"
+	local force="${3:-0}"
 
 	[[ -z "$session_id" ]] && return 1
 
@@ -167,9 +170,11 @@ counsel_generate_brief() {
 	local project_key
 	project_key=$(counsel_project_key "$cwd")
 
-	# Stale check.
-	if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
-		return 2
+	# Stale check. On-demand invocations pass force to bypass it.
+	if [[ "$force" != "1" && "$force" != "force" ]]; then
+		if ! counsel_brief_is_stale "$project_key" "$interval_days"; then
+			return 2
+		fi
 	fi
 
 	# Read events.
@@ -190,14 +195,28 @@ counsel_generate_brief() {
 		return 1
 	}
 
-	# Compute period bounds.
-	local period_start period_end
-	period_end=$(date '+%Y-%m-%d' 2>/dev/null) || period_end="unknown"
+	# Compute period bounds. The brief heading shows calendar dates; the emitted
+	# event requires RFC 3339 date-time strings (schema format: date-time), so
+	# compute the timestamps first and derive the date-only strings from them.
+	# Prefer UTC; fall back to local time (still RFC 3339, just a different zone)
+	# if -u is unavailable. If even that fails the date subsystem is broken and
+	# the bounds stay empty — the emit below skips rather than send garbage.
+	local period_start_ts period_end_ts
+	period_end_ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+		|| period_end_ts=$(date '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+		|| period_end_ts=""
 	if [[ "$(uname)" == "Darwin" ]]; then
-		period_start=$(date -v "-${lookback_days}d" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+		period_start_ts=$(date -u -v "-${lookback_days}d" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=$(date -v "-${lookback_days}d" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=""
 	else
-		period_start=$(date -d "-${lookback_days} days" '+%Y-%m-%d' 2>/dev/null) || period_start="unknown"
+		period_start_ts=$(date -u -d "-${lookback_days} days" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=$(date -d "-${lookback_days} days" '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) \
+			|| period_start_ts=""
 	fi
+	local period_start period_end
+	period_end="${period_end_ts%%T*}"; [[ -z "$period_end" ]] && period_end="unknown"
+	period_start="${period_start_ts%%T*}"; [[ -z "$period_start" ]] && period_start="unknown"
 
 	# Determine sources consulted.
 	local sources_json
@@ -235,13 +254,19 @@ counsel_generate_brief() {
 
 	local payload
 	payload=$(jq -n \
-		--arg ps "$period_start" \
-		--arg pe "$period_end" \
+		--arg ps "$period_start_ts" \
+		--arg pe "$period_end_ts" \
 		--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
+	# Only emit when the period bounds are valid RFC 3339 date-times — emitting
+	# empty bounds would fail schema validation and silently drop the event.
+	if [[ -n "$payload" && -n "$period_start_ts" && -n "$period_end_ts" ]]; then
+		counsel_emit_event "counsel.brief.generated" "$payload" || true
+	else
+		printf 'counsel_generate_brief: skipped counsel.brief.generated (no valid period bounds)\n' >&2
+	fi
 
 	printf '%s' "$output_path"
 }

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

@@ -46,9 +46,15 @@ counsel_read_events() {
 	# Filter to events within the lookback window. If cutoff_ts is empty (date
 	# command unavailable) fall through and include all events.
 	local summary
+	# Run inside a subshell with pipefail disabled. head -c closes the pipe once
+	# chars_max bytes have arrived, which sends jq SIGPIPE; under the caller's
+	# `set -o pipefail` (the SessionStart hook and the /counsel skill both set it)
+	# that marks the whole pipeline failed, and the `|| summary=""` fallback would
+	# then discard *every* event on any log large enough to exceed chars_max.
+	# Disabling pipefail locally keeps the truncated output.
 	# -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" '
+	summary=$(set +o pipefail; jq -rc --arg cutoff "$cutoff_ts" '
 		select(.timestamp != null) |
 		select($cutoff == "" or .timestamp >= $cutoff) |
 		{

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

@@ -53,7 +53,11 @@ counsel_synthesize() {
 	local events_text="${1:-}"
 	local model="${2:-claude-haiku-4-5-20251001}"
 	local timeout_s="${3:-90}"
+	# shellcheck disable=SC2034  # accepted for call-site compatibility; the
+	# claude CLI print mode exposes no max-tokens/temperature flags, so neither
+	# is forwarded (see claude_args below).
 	local max_tokens="${4:-4096}"
+	# shellcheck disable=SC2034
 	local temperature="${5:-0.4}"
 
 	[[ -z "$events_text" ]] && return 1
@@ -74,7 +78,10 @@ counsel_synthesize() {
 		printf '</event_log>\n'
 	} > "$prompt_file"
 
-	local claude_args=(-p --max-turns 1 --model "$model" --max-tokens "$max_tokens")
+	# NOTE: `claude -p` does not accept --max-tokens (it errors with "unknown
+	# option") and has no temperature flag, so we pass neither. Output length is
+	# governed by the model/prompt; the synthesis prompt asks for terse JSON.
+	local claude_args=(-p --max-turns 1 --model "$model")
 
 	local response=""
 	if command -v timeout >/dev/null 2>&1; then

package/plugins/counsel/skills/counsel/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: counsel
+description: Run the weekly observability synthesis on demand and render the coaching brief in the conversation. Reads the onlooker event log, runs a single synthesis pass, writes the brief, and prints it — bypassing the SessionStart staleness gate. Use when the user explicitly invokes /counsel, or wants a fresh improvement brief right now instead of waiting for the next stale-brief regeneration. Supports --show (print the latest brief, no LLM call) and --status.
+---
+
+# Counsel Skill
+
+Counsel's SessionStart hook regenerates a weekly improvement brief only when the
+last one has gone stale (`synthesis_interval_days`, default 7) and injects it
+invisibly. This skill is the on-demand path: it forces a fresh synthesis right
+now and renders the brief into the conversation.
+
+## Setup
+
+Run this once at the start. It sources the plugin helpers, loads config, and
+resolves project context.
+
+```bash
+set -uo pipefail
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/counsel-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-ulid.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-reader.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-synthesize.sh"
+source "$PLUGIN_ROOT/scripts/lib/counsel-brief.sh"
+
+REPO_ROOT=$(counsel_project_repo_root "$(pwd)")
+counsel_config_load "$REPO_ROOT"
+
+if ! counsel_config_enabled; then
+  echo "Counsel is disabled. Set counsel.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+
+PROJECT_KEY=$(counsel_project_key "$(pwd)")
+if [[ -z "$PROJECT_KEY" ]]; then
+  echo "No project key — Counsel needs a git repository (remote or root) to scope briefs. Skipping."
+  exit 0
+fi
+BRIEFS_DIR=$(counsel_project_dir "$PROJECT_KEY")
+```
+
+## Invocation Modes
+
+### `/counsel` — run the weekly review now (default)
+
+Forces a synthesis pass regardless of brief freshness, writes the brief to
+`${ONLOOKER_DIR:-~/.onlooker}/counsel/<project-key>/briefs/<YYYY-WW>.md`, emits
+`counsel.brief.generated`, and renders the result. Re-running in the same ISO
+week overwrites that week's brief in place. (`$ONLOOKER_DIR` overrides the
+storage root; the test suite and non-default installs rely on it.)
+
+```bash
+SESSION_ID="${CLAUDE_SESSION_ID:-$(counsel_ulid)}"
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+LOOKBACK=$(counsel_config_get '.counsel.lookback_days'); LOOKBACK="${LOOKBACK:-30}"
+echo "Running Counsel synthesis over the last ${LOOKBACK} days of events…"
+
+_rc=0
+OUTPUT_PATH=$(counsel_generate_brief "$SESSION_ID" "$(pwd)" force) || _rc=$?
+
+if [[ "$_rc" -eq 2 ]]; then
+  min_events=$(counsel_config_get '.counsel.capture.min_events'); min_events="${min_events:-10}"
+  echo "Not enough events to synthesize a brief (fewer than ${min_events} in the lookback window). Use the ecosystem long enough to accumulate telemetry, then try again."
+  exit 0
+elif [[ "$_rc" -ne 0 || -z "$OUTPUT_PATH" || ! -f "$OUTPUT_PATH" ]]; then
+  echo "Counsel synthesis failed. Check that the \`claude\` CLI is on PATH and the onlooker log is readable."
+  exit 1
+fi
+```
+
+Then render the brief verbatim to the conversation:
+
+```bash
+echo "## Counsel weekly review (\`$(basename "$OUTPUT_PATH" .md)\`)"
+echo ""
+cat "$OUTPUT_PATH"
+echo ""
+echo "_Brief saved to ${OUTPUT_PATH}._"
+```
+
+### `/counsel --show` — print the latest brief (no LLM call)
+
+Renders the most recent brief already on disk. No synthesis, no events emitted.
+
+```bash
+LATEST=$(ls -1 "$BRIEFS_DIR"/*.md 2>/dev/null | sort | tail -1)
+if [[ -z "$LATEST" || ! -f "$LATEST" ]]; then
+  echo "No brief on disk yet for this project. Run \`/counsel\` to generate one."
+  exit 0
+fi
+echo "## Counsel brief (\`$(basename "$LATEST" .md)\`)"
+echo ""
+cat "$LATEST"
+```
+
+### `/counsel --status` — brief freshness
+
+Reports the latest brief's age, last-generated time, and path. No LLM call.
+
+```bash
+INTERVAL=$(counsel_config_get '.counsel.synthesis_interval_days'); INTERVAL="${INTERVAL:-7}"
+LATEST=$(ls -1 "$BRIEFS_DIR"/*.md 2>/dev/null | sort | tail -1)
+
+echo "## Counsel status"
+echo "- Project key: ${PROJECT_KEY}"
+echo "- Briefs dir:  ${BRIEFS_DIR}"
+echo "- Stale after: ${INTERVAL} days"
+
+if [[ -z "$LATEST" || ! -f "$LATEST" ]]; then
+  echo "- Latest brief: none yet (run \`/counsel\`)"
+  exit 0
+fi
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  mtime=$(stat -f '%m' "$LATEST" 2>/dev/null || echo 0)
+  human=$(date -r "$mtime" 2>/dev/null || echo "$mtime")
+else
+  mtime=$(stat -c '%Y' "$LATEST" 2>/dev/null || echo 0)
+  human=$(date -d "@$mtime" 2>/dev/null || echo "$mtime")
+fi
+now=$(date +%s 2>/dev/null || echo "$mtime")
+age_days=$(( (now - mtime) / 86400 ))
+
+echo "- Latest brief: $(basename "$LATEST") (generated ${human}, ${age_days}d ago)"
+if [[ "$age_days" -ge "$INTERVAL" ]]; then
+  echo "- Status: stale — SessionStart will regenerate, or run \`/counsel\` now."
+else
+  echo "- Status: fresh — run \`/counsel\` to force a regeneration anyway."
+fi
+```
+
+## Notes
+
+- The synthesis pass shells out to `claude -p` with the configured
+  `evaluator.model` (default Haiku) — see the plugin README for all config keys.
+- The on-demand path honors the same `capture.min_events` floor as the hook: if
+  too few events fall inside the lookback window, it reports that instead of
+  emitting a thin brief.
+- Output, events, storage layout, and project keying are identical to the
+  SessionStart path — this skill only bypasses the staleness gate.

package/test/bats/counsel-brief.bats

@@ -0,0 +1,167 @@
+#!/usr/bin/env bats
+
+# Exercises counsel_generate_brief's staleness gate and the force bypass the
+# on-demand /counsel skill relies on. The claude CLI is stubbed so synthesis is
+# deterministic and offline.
+
+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-config.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-events.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-project-key.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-ulid.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-reader.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-synthesize.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/counsel-brief.sh"
+
+  # A git work tree so counsel_project_key resolves to a stable root key.
+  WORK="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$WORK"
+  git -C "$WORK" init -q
+  git -C "$WORK" config user.email test@example.com
+  git -C "$WORK" config user.name test
+
+  counsel_config_load "$WORK"
+
+  # Stub the claude CLI: ignore stdin/args, emit a valid synthesis object whose
+  # summary carries a marker we can assert on in the written brief.
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+cat <<'JSON'
+{"summary":"SYNTH_MARKER weekly review","patterns":["pattern one"],"recommendations":[{"title":"do x","rationale":"because y","priority":"high"}],"wins":["win one"],"watch":["watch one"]}
+JSON
+STUB
+  chmod +x "${STUB_BIN}/claude"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  # Event log with comfortably more than min_events records in-window.
+  export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+  mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  : > "$ONLOOKER_EVENTS_LOG"
+  local i
+  for ((i = 0; i < 12; i++)); do
+    printf '%s\n' \
+      "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s${i}\",\"payload\":{}}" \
+      >> "$ONLOOKER_EVENTS_LOG"
+  done
+
+  PROJECT_KEY=$(counsel_project_key "$WORK")
+  BRIEFS_DIR=$(counsel_project_dir "$PROJECT_KEY")
+  mkdir -p "$BRIEFS_DIR"
+}
+
+# ---------------------------------------------------------------------------
+# Staleness gate (default, non-force path used by the SessionStart hook)
+# ---------------------------------------------------------------------------
+
+# counsel_generate_brief prints the brief path on stdout and diagnostics on
+# stderr; capture stdout only so $out is exactly the path.
+gen() {
+  GEN_STATUS=0
+  GEN_OUT=$(counsel_generate_brief "$@" 2>/dev/null) || GEN_STATUS=$?
+}
+
+@test "generate_brief writes a brief when none exists yet" {
+  gen "sess-1" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "generate_brief skips (rc=2) when the latest brief is still fresh" {
+  # A freshly written brief makes counsel_brief_is_stale return false.
+  printf '# old brief\n' > "${BRIEFS_DIR}/2099-01.md"
+  gen "sess-2" "$WORK"
+  [ "$GEN_STATUS" -eq 2 ]
+}
+
+# Bullet lists and the rule in the rendered brief must not be mangled by
+# printf treating a leading dash as an option.
+@test "rendered brief contains intact bullets and horizontal rule" {
+  gen "sess-bullets" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  grep -q '^- pattern one$' "$GEN_OUT"
+  grep -q '^- win one$' "$GEN_OUT"
+  grep -q '^---$' "$GEN_OUT"
+}
+
+# ---------------------------------------------------------------------------
+# Force bypass (on-demand /counsel skill path)
+# ---------------------------------------------------------------------------
+
+@test "force bypasses the staleness gate and regenerates a fresh brief" {
+  printf '# stale-looking but fresh-on-disk brief\n' > "${BRIEFS_DIR}/2099-01.md"
+
+  gen "sess-3" "$WORK" force
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "force accepts the literal \"1\" as well" {
+  printf '# fresh\n' > "${BRIEFS_DIR}/2099-01.md"
+  gen "sess-4" "$WORK" 1
+  [ "$GEN_STATUS" -eq 0 ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+}
+
+@test "force still respects the min_events floor" {
+  # Only a couple of events — below the default min_events of 10.
+  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\":{}}" \
+    > "$ONLOOKER_EVENTS_LOG"
+
+  gen "sess-5" "$WORK" force
+  [ "$GEN_STATUS" -eq 2 ]
+}
+
+# Regression: counsel.brief.generated must validate against the schema and land
+# in the event log. The period bounds are emitted as RFC 3339 date-time strings.
+@test "generated brief emits a schema-valid counsel.brief.generated event" {
+  gen "sess-evt" "$WORK"
+  [ "$GEN_STATUS" -eq 0 ]
+  run grep -c '"event_type":"counsel.brief.generated"' "$ONLOOKER_EVENTS_LOG"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+  # period_start must be a full date-time, not a bare calendar date.
+  run grep -o '"period_start":"[^"]*"' "$ONLOOKER_EVENTS_LOG"
+  [[ "$output" == *"T"*"Z"* ]]
+}
+
+# If date cannot produce timestamps the bounds are empty; rather than emit an
+# event that fails schema validation, the emit is skipped and the brief is
+# still written.
+@test "emit is skipped (never invalid) when date cannot produce bounds" {
+  local datestub="${BATS_TEST_TMPDIR}/datebin"
+  mkdir -p "$datestub"
+  printf '#!/usr/bin/env bash\nexit 1\n' > "${datestub}/date"
+  chmod +x "${datestub}/date"
+  PATH="${datestub}:${PATH}"
+
+  gen "sess-nodate" "$WORK" force
+  [ "$GEN_STATUS" -eq 0 ]
+  [ -f "$GEN_OUT" ]
+  grep -q "SYNTH_MARKER" "$GEN_OUT"
+  # No counsel.brief.generated event should have been appended.
+  run grep -c '"event_type":"counsel.brief.generated"' "$ONLOOKER_EVENTS_LOG"
+  [ "$output" -eq 0 ]
+}

package/test/bats/counsel-reader.bats

@@ -114,6 +114,34 @@ setup() {
   [ "$output" = "3" ]
 }
 
+@test "read_events survives caller pipefail when output exceeds chars_max" {
+  # Regression: head -c closes the pipe once chars_max bytes arrive, sending jq
+  # SIGPIPE. Under the caller's `set -o pipefail` (as the hook and skill run),
+  # the reader must still return the truncated output, not discard everything.
+  local log="${BATS_TEST_TMPDIR}/big-events.jsonl"
+  local ts
+  ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null) || ts="2099-01-01T00:00:00Z"
+  : > "$log"
+  local i
+  for ((i = 0; i < 60; i++)); do
+    printf '%s\n' \
+      "{\"event_type\":\"tribunal.gate.blocked\",\"timestamp\":\"${ts}\",\"session_id\":\"s${i}\",\"payload\":{\"k\":\"vvvvvvvvvvvvvvvvvvvvvvvvvvvvvv\"}}" \
+      >> "$log"
+  done
+  export ONLOOKER_EVENTS_LOG="$log"
+
+  # Tiny cap so head closes the pipe after the first event or two.
+  local out
+  set -o pipefail
+  out=$(counsel_read_events "30" "200")
+  set +o pipefail
+
+  [ -n "$out" ]
+  run counsel_count_events "$out"
+  [ "$status" -eq 0 ]
+  [ "$output" -ge 1 ]
+}
+
 @test "read_events output preserves source types for sources_from_events" {
   local log="${BATS_TEST_TMPDIR}/source-events.jsonl"
   local ts