@onlooker-community/ecosystem 0.26.1 → 0.27.0

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Config resolution for bursar.
+#
+# Reads three layers, latest wins:
+#   1. plugins/bursar/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   bursar_config_load <repo_root>     # populates _BURSAR_CONFIG (JSON)
+#   bursar_config_get <jq-path>        # echoes string value (empty if unset)
+#   bursar_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   bursar_config_enabled              # 0 if bursar.enabled is true
+#   bursar_config_window               # echoes "rolling_7d" or "calendar_week"
+#   bursar_config_week_start           # echoes "monday" or "sunday"
+
+_BURSAR_CONFIG="{}"
+
+bursar_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 '{ bursar: (.bursar // {}) }' "$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
+
+	_BURSAR_CONFIG="$merged"
+}
+
+bursar_config_get() {
+	local path="$1"
+	printf '%s' "$_BURSAR_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+bursar_config_get_json() {
+	local path="$1"
+	printf '%s' "$_BURSAR_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+bursar_config_enabled() {
+	local v
+	v=$(bursar_config_get '.bursar.enabled')
+	[[ "$v" == "true" ]]
+}
+
+bursar_config_surface_enabled() {
+	# Use the JSON getter, not bursar_config_get: jq's `//` treats a literal
+	# `false` as empty, which would mask an explicit opt-out. The JSON getter
+	# returns the raw `false`/`true`/`null` so the default-on behavior holds.
+	local v
+	v=$(bursar_config_get_json '.bursar.surface_at_session_start')
+	# Default to surfacing unless explicitly set to false.
+	[[ "$v" != "false" ]]
+}
+
+bursar_config_window() {
+	local v
+	v=$(bursar_config_get '.bursar.window')
+	case "$v" in
+		calendar_week) printf 'calendar_week' ;;
+		*) printf 'rolling_7d' ;;
+	esac
+}
+
+bursar_config_week_start() {
+	local v
+	v=$(bursar_config_get '.bursar.week_start')
+	case "$v" in
+		sunday) printf 'sunday' ;;
+		*) printf 'monday' ;;
+	esac
+}
+
+bursar_config_min_cost() {
+	local v
+	v=$(bursar_config_get '.bursar.min_cost_to_surface_usd')
+	printf '%s' "${v:-0}"
+}

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Canonical bursar.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema (>= 2.7.0,
+# which registers the bursar.* event types) before being appended to
+# ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Usage:
+#   bursar_emit_event "bursar.session.recorded" '{"project_key":"...",...}' "$SESSION_ID"
+
+_BURSAR_PLUGIN_NAME="bursar"
+
+_bursar_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
+}
+
+_bursar_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'
+}
+
+# Emit a single bursar.* event. Returns 0 on success, non-zero on failure.
+# Usage: bursar_emit_event <event_type> <payload_json> [session_id]
+bursar_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	local session_id="${3:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+	[[ -z "$session_id" ]] && session_id=$(_bursar_session_id)
+
+	local event_js
+	event_js=$(_bursar_event_js_path) || return 1
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_BURSAR_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 bursar-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/bursar-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_BURSAR_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'bursar_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/bursar/scripts/lib/bursar-ledger.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Per-project, multi-session rollup ledger for bursar.
+#
+# Where governor keeps a per-session ledger under
+# ~/.onlooker/governance/ledgers/<session-id>.jsonl, bursar keeps one ledger
+# per project under:
+#
+#   $ONLOOKER_DIR/bursar/projects/<project_key>/sessions.jsonl
+#
+# Each line is one session's spend, recorded once on SessionEnd:
+#
+#   { ts, ts_epoch, session_id, project_key,
+#     cost_usd?, tokens?, api_calls?, governor_present, model? }
+#
+# cost/tokens/api_calls are omitted when governor was not running for the
+# session (governor_present:false) — bursar degrades to a session count.
+#
+# Records are keyed by session_id: re-recording a session replaces its line
+# rather than appending, so a SessionEnd that fires more than once is
+# idempotent.
+#
+# ts_epoch (seconds) is stored alongside the RFC3339 ts so window filtering is
+# a portable numeric jq compare with no date parsing.
+#
+# Requires portable-lock.sh to be sourced beforehand.
+
+BURSAR_LEDGER_LOCK_TIMEOUT=5
+
+bursar_ledger_dir() {
+	local project_key="${1:-unknown}"
+	local safe_key
+	safe_key=$(printf '%s' "$project_key" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/bursar/projects/%s' "${ONLOOKER_DIR:-${HOME}/.onlooker}" "$safe_key"
+}
+
+bursar_ledger_path() {
+	printf '%s/sessions.jsonl' "$(bursar_ledger_dir "$1")"
+}
+
+# Current wall-clock helpers (portable across macOS/Linux).
+bursar_now_epoch() { date +%s 2>/dev/null || printf '0'; }
+bursar_now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf ''; }
+
+bursar_epoch_to_iso() {
+	local e="${1:-0}"
+	date -u -r "$e" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+		|| date -u -d "@$e" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+		|| printf ''
+}
+
+# Upsert a session record into the project ledger, keyed by session_id.
+# Usage: bursar_ledger_record "$project_key" "$record_json"
+bursar_ledger_record() {
+	local project_key="${1:-}"
+	local record="${2:-}"
+	[[ -z "$project_key" || -z "$record" ]] && return 1
+
+	local sid
+	sid=$(printf '%s' "$record" | jq -r '.session_id // empty' 2>/dev/null) || sid=""
+	[[ -z "$sid" ]] && return 1
+
+	local record_compact
+	record_compact=$(printf '%s' "$record" | jq -c . 2>/dev/null) || return 1
+
+	local dir ledger_path lock_path
+	dir=$(bursar_ledger_dir "$project_key")
+	ledger_path="${dir}/sessions.jsonl"
+	lock_path="${ledger_path}.lock"
+	mkdir -p "$dir" 2>/dev/null || return 1
+
+	if ! lock_acquire "$lock_path" "$BURSAR_LEDGER_LOCK_TIMEOUT"; then
+		return 1
+	fi
+
+	local tmp
+	tmp=$(mktemp "${dir}/.sessions.XXXXXX" 2>/dev/null) || { lock_release "$lock_path"; return 1; }
+
+	if [[ -f "$ledger_path" ]]; then
+		# Keep every line whose session_id differs from the one being recorded.
+		jq -c --arg sid "$sid" 'select(.session_id != $sid)' "$ledger_path" 2>/dev/null >>"$tmp"
+	fi
+	printf '%s\n' "$record_compact" >>"$tmp"
+
+	mv "$tmp" "$ledger_path" 2>/dev/null || { rm -f "$tmp"; lock_release "$lock_path"; return 1; }
+	lock_release "$lock_path"
+	return 0
+}
+
+# Compute the inclusive lower-bound epoch for the active window.
+# Usage: bursar_window_cutoff_epoch <rolling_7d|calendar_week> <monday|sunday>
+bursar_window_cutoff_epoch() {
+	local window="${1:-rolling_7d}"
+	local week_start="${2:-monday}"
+	local now
+	now=$(bursar_now_epoch)
+
+	if [[ "$window" == "calendar_week" ]]; then
+		# Local midnight today, computed portably from H/M/S (no GNU/BSD-only flags).
+		local h m s secs_today today_midnight dow days_since
+		h=$(date +%H 2>/dev/null) || h=0
+		m=$(date +%M 2>/dev/null) || m=0
+		s=$(date +%S 2>/dev/null) || s=0
+		secs_today=$(( 10#$h * 3600 + 10#$m * 60 + 10#$s ))
+		today_midnight=$(( now - secs_today ))
+
+		dow=$(date +%u 2>/dev/null) || dow=1   # 1=Mon .. 7=Sun
+		if [[ "$week_start" == "sunday" ]]; then
+			days_since=$(( dow % 7 ))           # Sun(7)->0, Mon(1)->1 .. Sat(6)->6
+		else
+			days_since=$(( dow - 1 ))           # Mon(1)->0 .. Sun(7)->6
+		fi
+		printf '%d' "$(( today_midnight - days_since * 86400 ))"
+	else
+		printf '%d' "$(( now - 604800 ))"       # rolling trailing 7 days
+	fi
+}
+
+# Aggregate spend over the window. Prints a JSON object:
+#   {total_cost_usd, total_tokens, session_count, sessions_with_cost}
+# Usage: bursar_window_totals "$project_key" "$cutoff_epoch"
+bursar_window_totals() {
+	local project_key="${1:-}"
+	local cutoff="${2:-0}"
+	local ledger_path
+	ledger_path=$(bursar_ledger_path "$project_key")
+
+	if [[ ! -f "$ledger_path" ]]; then
+		printf '{"total_cost_usd":0,"total_tokens":0,"session_count":0,"sessions_with_cost":0}'
+		return 0
+	fi
+
+	jq -s --argjson cutoff "$cutoff" '
+		[ .[] | select((.ts_epoch // 0) >= $cutoff) ] as $w
+		| {
+			total_cost_usd: ([ $w[] | (.cost_usd // 0) ] | add // 0),
+			total_tokens: ([ $w[] | (.tokens // 0) ] | add // 0),
+			session_count: ($w | length),
+			sessions_with_cost: ([ $w[] | select(.cost_usd != null) ] | length)
+		}
+	' "$ledger_path" 2>/dev/null \
+		|| printf '{"total_cost_usd":0,"total_tokens":0,"session_count":0,"sessions_with_cost":0}'
+}
+
+# Human-friendly token count: 1234567 -> "1.2M", 42000 -> "42k", 800 -> "800".
+bursar_fmt_tokens() {
+	local n="${1:-0}"
+	awk -v n="$n" 'BEGIN {
+		if (n >= 1000000) printf "%.1fM", n/1000000;
+		else if (n >= 1000) printf "%.0fk", n/1000;
+		else printf "%d", n;
+	}'
+}

package/plugins/bursar/scripts/lib/bursar-project-key.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Project key derivation for bursar.
+#
+# Mirrors the archivist/tribunal project-key scheme so the plugins partition
+# storage identically. A project key is a stable 12-char hex identifier that
+# survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works.
+
+_bursar_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
+}
+
+bursar_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.
+bursar_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"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty string.
+bursar_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(bursar_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_bursar_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(bursar_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_bursar_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for bursar 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.
+
+_BURSAR_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_bursar_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_BURSAR_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+bursar_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=$(_bursar_ulid_encode "$now_ms" 10)
+	hi_part=$(_bursar_ulid_encode "$rand_hi" 8)
+	lo_part=$(_bursar_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/bursar/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 bursar plugin so the per-project ledger's atomic upserts
+# keep working when bursar is installed standalone from the marketplace: the
+# cache layout (~/.claude/plugins/cache/<owner>/bursar/<version>/) does not
+# include the ecosystem repo's top-level scripts/lib/. Without a local copy,
+# lock_acquire would be undefined and the SessionEnd upsert could clobber a
+# concurrent writer. This mirrors the per-plugin vendoring of bursar-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/release-please-config.json

@@ -222,6 +222,22 @@
           "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"
+        }
+      ]
     }
   },
   "$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 ]
+}