@onlooker-community/ecosystem 0.26.1 → 0.28.0

package/plugins/lineage/scripts/lib/lineage-record.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Build and append lineage change records.
+#
+# Storage: $ONLOOKER_DIR/lineage/<project-key>/changes.jsonl — append-only, one
+# change per line. Each record:
+#   { change_id, ts, ts_epoch, session_id, turn?, tool, operation, file_path,
+#     lines_added, lines_removed, bytes, edit_count, content_sha256,
+#     added_snippets[], transcript_path }
+#
+# The bus event (lineage.change.recorded) carries metadata + content_sha256
+# only; the added content lives here in the per-project ledger, where the
+# /lineage query content-anchors a line back to the change that introduced it.
+#
+# Requires lineage-redact.sh and portable-lock.sh sourced beforehand.
+
+lineage_record_dir() {
+	local key="${1:-unknown}"
+	local safe
+	safe=$(printf '%s' "$key" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/lineage/%s' "${ONLOOKER_DIR:-${HOME}/.onlooker}" "$safe"
+}
+
+lineage_record_path() { printf '%s/changes.jsonl' "$(lineage_record_dir "$1")"; }
+
+lineage_now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf ''; }
+lineage_now_epoch() { date +%s 2>/dev/null || printf '0'; }
+
+lineage_sha256() {
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$1" | shasum -a 256 2>/dev/null | cut -d' ' -f1
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$1" | sha256sum 2>/dev/null | cut -d' ' -f1
+	else
+		printf ''
+	fi
+}
+
+# Line count of a text blob (0 for empty). `grep -c ''` counts every line,
+# including a final line with no trailing newline.
+_lineage_count_lines() {
+	[[ -z "$1" ]] && { printf '0'; return 0; }
+	printf '%s' "$1" | grep -c '' 2>/dev/null || printf '0'
+}
+
+# Tool → operation enum (create|overwrite|edit|multi_edit). Write is recorded as
+# a coarse "create"; the create/overwrite distinction is not reliably knowable
+# at PostToolUse and does not affect the provenance answer.
+_lineage_operation() {
+	case "$1" in
+		Edit) printf 'edit' ;;
+		MultiEdit) printf 'multi_edit' ;;
+		Write) printf 'create' ;;
+		*) printf 'edit' ;;
+	esac
+}
+
+# Added / removed content extracted from the tool_input JSON, per tool.
+_lineage_added() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.new_string // ""' 2>/dev/null ;;
+		Write) printf '%s' "$ti" | jq -r '.content // ""' 2>/dev/null ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.new_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+_lineage_removed() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.old_string // ""' 2>/dev/null ;;
+		Write) printf '' ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.old_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+# Build a change record JSON (pure — no I/O). Echoes the record.
+# Usage: lineage_build_record <change_id> <ts> <ts_epoch> <session_id> <turn>
+#          <tool> <file_path> <tool_input_json> <max_chars> <do_redact> <transcript_path>
+lineage_build_record() {
+	local change_id="$1" ts="$2" ts_epoch="$3" session_id="$4" turn="$5"
+	local tool="$6" file_path="$7" ti="$8" max_chars="$9" do_redact="${10}" transcript_path="${11}"
+
+	local added removed added_red lines_added lines_removed bytes digest op edit_count
+	added=$(_lineage_added "$tool" "$ti")
+	removed=$(_lineage_removed "$tool" "$ti")
+	lines_added=$(_lineage_count_lines "$added")
+	lines_removed=$(_lineage_count_lines "$removed")
+	bytes=$(printf '%s' "$added" | wc -c | tr -d ' ')
+	digest=$(lineage_sha256 "$added")
+	op=$(_lineage_operation "$tool")
+	edit_count=$(printf '%s' "$ti" | jq -r 'if .edits then (.edits | length) else 1 end' 2>/dev/null) || edit_count=1
+	added_red=$(printf '%s' "$added" | lineage_redact "$max_chars" "$do_redact")
+
+	jq -n \
+		--arg cid "$change_id" --arg ts "$ts" --argjson te "${ts_epoch:-0}" \
+		--arg sid "$session_id" --arg tool "$tool" --arg op "$op" \
+		--arg fp "$file_path" --arg snip "$added_red" --arg tp "$transcript_path" \
+		--argjson la "${lines_added:-0}" --argjson lr "${lines_removed:-0}" \
+		--argjson by "${bytes:-0}" --arg digest "$digest" \
+		--argjson ec "${edit_count:-1}" --arg turn "$turn" \
+		'{
+			change_id: $cid, ts: $ts, ts_epoch: $te,
+			session_id: $sid, tool: $tool, operation: $op, file_path: $fp,
+			lines_added: $la, lines_removed: $lr, bytes: $by,
+			edit_count: $ec, content_sha256: $digest,
+			added_snippets: [$snip], transcript_path: $tp
+		}
+		+ (if $turn != "" then {turn: ($turn | tonumber)} else {} end)' 2>/dev/null
+}
+
+# Append a record to the project ledger under its write lock.
+# Usage: lineage_append <project_key> <record_json>
+lineage_append() {
+	local key="$1" record="$2"
+	[[ -z "$key" || -z "$record" ]] && return 1
+
+	local dir path lock rec_compact
+	dir=$(lineage_record_dir "$key")
+	path="${dir}/changes.jsonl"
+	lock="${path}.lock"
+	mkdir -p "$dir" 2>/dev/null || return 1
+
+	rec_compact=$(printf '%s' "$record" | jq -c . 2>/dev/null) || return 1
+
+	if lock_acquire "$lock" 5; then
+		printf '%s\n' "$rec_compact" >> "$path" 2>/dev/null
+		local ok=$?
+		lock_release "$lock"
+		return "$ok"
+	fi
+	return 1
+}

package/plugins/lineage/scripts/lib/lineage-redact.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Secret redaction + size capping for lineage change snippets.
+#
+# Mirrors the conservative secret patterns in historian-sanitizer.sh (false
+# positives acceptable; false negatives are the failure mode that matters).
+# The heavy lifting runs in an inline python3 block — the same pattern
+# historian uses — because portable case-insensitive regex across BSD/GNU sed
+# is not worth the fragility on a path that handles user code.
+
+# Redact secret-shaped substrings from stdin, then cap to <max_chars>.
+# Usage: printf '%s' "$content" | lineage_redact <max_chars> <redact:true|false>
+lineage_redact() {
+	local max_chars="${1:-4000}"
+	local do_redact="${2:-true}"
+	# Pass the program via -c (not a heredoc on stdin): -c keeps stdin free for
+	# the piped content, so sys.stdin.read() actually receives it.
+	local _prog
+	_prog=$(cat <<'PY'
+import re
+import sys
+
+max_chars = int(sys.argv[1] or "4000")
+do_redact = sys.argv[2] != "false"
+text = sys.stdin.read()
+
+if do_redact:
+    patterns = [
+        re.compile(r"\bAKIA[0-9A-Z]{16}\b"),            # AWS access key id
+        re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),  # GitHub tokens
+        re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}\b"),   # Anthropic API keys
+        re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),         # OpenAI-style keys
+        re.compile(r"(?i:Bearer)\s+[A-Za-z0-9._\-+/=]{20,}"),  # bearer tokens
+    ]
+    for pat in patterns:
+        text = pat.sub("[REDACTED:secret]", text)
+    # KEY=value or "key": "value" where the key name implies a secret;
+    # preserve the key, redact the value.
+    kv = re.compile(
+        r'([A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD)[A-Za-z0-9_]*"?\s*[:=]\s*"?)\S+',
+        re.IGNORECASE,
+    )
+    text = kv.sub(lambda m: m.group(1) + "[REDACTED:secret]", text)
+
+if len(text) > max_chars:
+    text = text[:max_chars] + "… [truncated %d chars]" % (len(text) - max_chars)
+
+sys.stdout.write(text)
+PY
+)
+	python3 -c "$_prog" "$max_chars" "$do_redact"
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for lineage record ids.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+#
+# Copied from plugins/tribunal/scripts/lib/tribunal-ulid.sh and renamed; the
+# ecosystem ships one *_ulid helper per plugin rather than a shared one.
+
+_LINEAGE_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_lineage_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_LINEAGE_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+lineage_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=$(_lineage_ulid_encode "$now_ms" 10)
+	hi_part=$(_lineage_ulid_encode "$rand_hi" 8)
+	lo_part=$(_lineage_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/lineage/scripts/lib/portable-lock.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# portable-lock.sh — vendored copy of the ecosystem substrate's portable lock.
+#
+# Vendored into the lineage plugin so the per-project ledger's atomic upserts
+# keep working when lineage is installed standalone from the marketplace: the
+# cache layout (~/.claude/plugins/cache/<owner>/lineage/<version>/) does not
+# include the ecosystem repo's top-level scripts/lib/. Without a local copy,
+# lock_acquire would be undefined and concurrent PostToolUse appends (e.g.
+# from parallel subagents) could clobber the change ledger. This mirrors the
+# per-plugin vendoring of lineage-ulid.sh and friends.
+# Keep in sync with scripts/lib/portable-lock.sh at the repo root.
+#
+# 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 concurrent writes to $ONLOOKER_DIR silently clobber each other.
+#
+# 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/plugins/lineage/skills/lineage/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: lineage
+description: Answer "why does this line exist?" — trace a file, or a specific line, back to the change, prompt, agent, and session that produced it. Reads lineage's per-project change ledger and joins it to the transcripts historian preserves. Modes — /lineage <file> (change history), /lineage <file>:<line> or --line N (single-line provenance), /lineage <file> --grep <text> (content search), /lineage --status (ledger stats). Use when the user asks who/what/why introduced code in a file, or invokes /lineage.
+---
+
+# Lineage Skill
+
+`/lineage` reads the per-project change ledger that the PostToolUse hook records
+and resolves each change's originating prompt by joining to historian's durable
+session transcripts (falling back to the live transcript). It answers
+"why does this line exist?" without an LLM call — pure read, join, and render.
+
+## Setup
+
+Run once. 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/portable-lock.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-redact.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-record.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-query.sh"
+
+REPO_ROOT=$(lineage_project_repo_root "$(pwd)")
+lineage_config_load "$REPO_ROOT"
+if ! lineage_config_enabled; then
+  echo "Lineage is disabled. Set lineage.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+PROJECT_KEY=$(lineage_project_key "$(pwd)")
+if [[ -z "$PROJECT_KEY" ]]; then
+  echo "No project key — lineage needs a git repository (remote or root) to scope its ledger."
+  exit 0
+fi
+PROMPT_SOURCE=$(lineage_config_prompt_source)
+QSID="${CLAUDE_SESSION_ID:-lineage-query}"
+```
+
+## Invocation Modes
+
+### `/lineage <file>` — change history (default)
+
+Set `FILE` to the path the user named, then run. (Repo-relative paths are
+resolved against the repo root.)
+
+```bash
+FILE="REPLACE_WITH_FILE"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+
+echo "## Lineage — change history for \`$FILE\`"
+count=0
+while IFS= read -r rec; do
+  [[ -z "$rec" ]] && continue
+  count=$((count + 1))
+  ts=$(jq -r '.ts' <<<"$rec"); sid=$(jq -r '.session_id' <<<"$rec")
+  turn=$(jq -r '.turn // ""' <<<"$rec"); tool=$(jq -r '.tool' <<<"$rec")
+  la=$(jq -r '.lines_added' <<<"$rec"); lr=$(jq -r '.lines_removed' <<<"$rec")
+  tp=$(jq -r '.transcript_path // ""' <<<"$rec")
+  resolved=$(lineage_resolve_prompt "$PROJECT_KEY" "$sid" "$turn" "$tp" "$PROMPT_SOURCE")
+  prompt=$(jq -r '.prompt' <<<"$resolved"); via=$(jq -r '.resolved_via' <<<"$resolved")
+  echo ""
+  echo "### ${ts} · ${tool} (+${la}/-${lr}) · session ${sid}${turn:+ · turn ${turn}}"
+  if [[ -n "$prompt" ]]; then
+    echo "Prompt context (${via}):"; echo ""
+    printf '%s\n' "$prompt" | head -c 600 | sed 's/^/> /'
+  else
+    echo "_Prompt unavailable (${via})._"
+  fi
+done < <(lineage_changes_for_file "$PROJECT_KEY" "$FILE")
+[[ "$count" -eq 0 ]] && { echo ""; echo "No recorded changes for this file (it may predate lineage)."; }
+
+lineage_emit_event "lineage.query.answered" \
+  "$(jq -nc --arg pk "$PROJECT_KEY" --arg f "$FILE" --argjson m "$count" \
+     '{project_key:$pk, file_path:$f, matches:$m}')" "$QSID" || true
+```
+
+### `/lineage <file>:<line>` (or `--line N`) — single-line provenance
+
+Set `FILE` and `LINE`, then run. Reads the current line's text and content-anchors
+it to the change that introduced it.
+
+```bash
+FILE="REPLACE_WITH_FILE"; LINE="REPLACE_WITH_LINE_NUMBER"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+
+line_text=$(sed -n "${LINE}p" "$FILE" 2>/dev/null)
+needle=$(printf '%s' "$line_text" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+echo "## Lineage — why does \`$FILE\`:${LINE} exist?"
+echo ""
+echo "Line ${LINE}: \`${line_text}\`"
+
+rec=$(lineage_match_line "$PROJECT_KEY" "$FILE" "$needle")
+via="none"; matches=0
+if [[ -z "$rec" ]]; then
+  echo ""
+  echo "No recorded change introduced this content (it may predate lineage, or the line moved since it was written)."
+else
+  matches=1
+  ts=$(jq -r '.ts' <<<"$rec"); sid=$(jq -r '.session_id' <<<"$rec")
+  turn=$(jq -r '.turn // ""' <<<"$rec"); tool=$(jq -r '.tool' <<<"$rec")
+  tp=$(jq -r '.transcript_path // ""' <<<"$rec")
+  resolved=$(lineage_resolve_prompt "$PROJECT_KEY" "$sid" "$turn" "$tp" "$PROMPT_SOURCE")
+  prompt=$(jq -r '.prompt' <<<"$resolved"); via=$(jq -r '.resolved_via' <<<"$resolved")
+  echo ""
+  echo "Introduced ${ts} by a ${tool} in session ${sid}${turn:+ (turn ${turn})}."
+  if [[ -n "$prompt" ]]; then
+    echo ""; echo "Prompt context (${via}):"; echo ""
+    printf '%s\n' "$prompt" | sed 's/^/> /'
+  else
+    echo "_Prompt unavailable (${via})._"
+  fi
+fi
+
+lineage_emit_event "lineage.query.answered" \
+  "$(jq -nc --arg pk "$PROJECT_KEY" --arg f "$FILE" --argjson m "$matches" \
+     --argjson ln "${LINE:-0}" --arg via "$via" \
+     '{project_key:$pk, file_path:$f, matches:$m, line:$ln, resolved_via:$via}')" "$QSID" || true
+```
+
+### `/lineage <file> --grep <text>` — content search
+
+Same as the line mode, but set `needle` to the user's search text instead of
+reading a line from the file:
+
+```bash
+FILE="REPLACE_WITH_FILE"; needle="REPLACE_WITH_TEXT"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+rec=$(lineage_match_line "$PROJECT_KEY" "$FILE" "$needle")
+# …render as in the line mode…
+```
+
+### `/lineage --status` — ledger stats
+
+```bash
+LEDGER=$(lineage_record_path "$PROJECT_KEY")
+echo "## Lineage status"
+echo "- Project key: ${PROJECT_KEY}"
+echo "- Ledger: ${LEDGER}"
+if [[ -f "$LEDGER" ]]; then
+  total=$(wc -l < "$LEDGER" | tr -d ' ')
+  files=$(jq -r '.file_path' "$LEDGER" 2>/dev/null | sort -u | grep -c '')
+  echo "- Changes recorded: ${total} across ${files} file(s)"
+else
+  echo "- No changes recorded yet. Make some Edit/Write changes with lineage enabled."
+fi
+```
+
+## Notes
+
+- Provenance is **content-anchored**: a line is matched to the change whose added
+  content contains it. If later edits moved or rewrote the line, the match is the
+  most recent change that introduced the matching text — not a git-blame-exact
+  mapping.
+- The prompt is resolved lazily: historian's preserved per-session chunks first
+  (durable across transcript cleanup), then the live `transcript_path`, then
+  "unavailable." Install and enable historian for the most reliable prompts.
+- Storage, project keying, and event emission match the other ecosystem plugins;
+  everything is scoped by project key and honors `$ONLOOKER_DIR`.

package/release-please-config.json

@@ -222,6 +222,38 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/bursar": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "bursar",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/lineage": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "lineage",
+      "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/bursar-config.bats

@@ -0,0 +1,79 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-config.sh"
+}
+
+@test "bursar is disabled by default" {
+	bursar_config_load ""
+	run bursar_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable bursar" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	bursar_config_load ""
+	run bursar_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	bursar_config_load "$repo"
+	run bursar_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "default window is rolling_7d" {
+	bursar_config_load ""
+	[ "$(bursar_config_window)" = "rolling_7d" ]
+}
+
+@test "window can be set to calendar_week" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"window":"calendar_week"}}' > "${HOME}/.claude/settings.json"
+	bursar_config_load ""
+	[ "$(bursar_config_window)" = "calendar_week" ]
+}
+
+@test "an invalid window falls back to rolling_7d" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"window":"yearly"}}' > "${HOME}/.claude/settings.json"
+	bursar_config_load ""
+	[ "$(bursar_config_window)" = "rolling_7d" ]
+}
+
+@test "default week_start is monday" {
+	bursar_config_load ""
+	[ "$(bursar_config_week_start)" = "monday" ]
+}
+
+@test "week_start can be set to sunday" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"week_start":"sunday"}}' > "${HOME}/.claude/settings.json"
+	bursar_config_load ""
+	[ "$(bursar_config_week_start)" = "sunday" ]
+}
+
+@test "surfacing is on by default and can be disabled" {
+	bursar_config_load ""
+	run bursar_config_surface_enabled
+	[ "$status" -eq 0 ]
+
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"surface_at_session_start":false}}' > "${HOME}/.claude/settings.json"
+	bursar_config_load ""
+	run bursar_config_surface_enabled
+	[ "$status" -ne 0 ]
+}

package/test/bats/bursar-events.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+# Validates that bursar.* events pass @onlooker-community/schema validation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-events.sh"
+
+	export CLAUDE_SESSION_ID="bats-bursar-session-$$"
+	PK="proj0123abcd"
+	SID="bats-bursar-sid-000"
+}
+
+_validate_latest_event() {
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ -n "$last" ] || return 1
+	printf '%s' "$last" | ONLOOKER_DIR="$ONLOOKER_DIR" \
+		node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+@test "bursar.session.recorded with governor present validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, governor_present:true,
+		  cost_usd:0.42, tokens:42000, api_calls:12, model:"claude-opus-4-8"}')
+	bursar_emit_event "bursar.session.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.session.recorded with governor absent validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, governor_present:false}')
+	bursar_emit_event "bursar.session.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.rollup.surfaced validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" \
+		'{project_key:$pk, window:"rolling_7d", total_cost_usd:3.17,
+		  session_count:8, total_tokens:310000, sessions_with_cost:7,
+		  window_start:"2026-06-05T00:00:00Z"}')
+	bursar_emit_event "bursar.rollup.surfaced" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.rollup.skipped validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" '{reason:"no_data", project_key:$pk}')
+	bursar_emit_event "bursar.rollup.skipped" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar_emit_event returns nonzero for an unknown event type" {
+	run bursar_emit_event "bursar.no_such_event" '{"project_key":"x"}' "$SID"
+	[ "$status" -ne 0 ]
+}