@onlooker-community/ecosystem 0.26.0 → 0.27.0

package/.claude-plugin/marketplace.json

@@ -189,6 +189,19 @@
       "license": "MIT",
       "keywords": ["verification", "claims", "exit-codes", "honesty", "testing", "transcript"],
       "tags": ["verification", "testing"]
+    },
+    {
+      "name": "bursar",
+      "source": "./plugins/bursar",
+      "description": "Multi-session, per-project budget accounting. Rolls each session's spend into a per-project ledger on SessionEnd and surfaces \"this project burned $X this week\" at SessionStart. Where governor regulates a single session, bursar is the cross-session rollup: it reads governor.session.complete off the shared event bus and degrades to a session count when governor is absent. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["budget", "cost", "rollup", "multi-session", "accounting", "audit"],
+      "tags": ["governance", "observability"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "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.26.0",
+  ".": "0.27.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -7,10 +7,11 @@
   "plugins/governor": "0.2.1",
   "plugins/compass": "0.2.0",
   "plugins/scribe": "0.2.1",
-  "plugins/counsel": "0.3.0",
+  "plugins/counsel": "0.3.1",
   "plugins/warden": "0.2.0",
   "plugins/librarian": "0.2.0",
   "plugins/curator": "0.1.0",
   "plugins/historian": "0.2.0",
-  "plugins/assayer": "1.0.0"
+  "plugins/assayer": "1.0.0",
+  "plugins/bursar": "0.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.27.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.26.1...ecosystem-v0.27.0) (2026-06-12)
+
+
+### Features
+
+* **bursar:** introduce multi-session budget rollup plugin ([#81](https://github.com/onlooker-community/ecosystem/issues/81)) ([b11e687](https://github.com/onlooker-community/ecosystem/commit/b11e687744bab70a94025c46c4aaa58fb7ea97f4))
+
+## [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)
 
 

package/CLAUDE.md

@@ -11,6 +11,7 @@ ecosystem/                    ← substrate plugin (always-on observability)
 
 plugins/
   archivist/                  ← session memory across context truncation
+  bursar/                     ← multi-session, per-project budget rollup (governor's cross-session view)
   cartographer/               ← instruction-file auditor (CLAUDE.md, AGENTS.md, rules/)
   compass/                    ← pre-write alignment gate (design phase)
   echo/                       ← prompt-change regression detection
@@ -38,6 +39,7 @@ scripts/lib/onlooker-event.mjs  ← canonical event builder; all plugins route t
 | tribunal | Stop + skill invocation | Post-task quality gate; also invokable via `/tribunal` |
 | warden | PostToolUse (WebFetch, Read), PreToolUse (Write, Edit, MultiEdit, Bash), SessionStart + skill invocation | Scans ingested content for injection; closes a content gate that blocks write-class tools until cleared via `/warden` |
 | assayer | Stop | Verifies the agent's final-message claims against actual command results in the transcript; advisory |
+| bursar | SessionStart, SessionEnd | Rolls each session's spend into a per-project ledger on SessionEnd; surfaces "this project burned $X this week" at SessionStart. Governor is per-session; bursar is the cross-session rollup |
 
 Plugins communicate by emitting events to the JSONL log — they do not call each other directly. All plugins depend on the ecosystem substrate; no plugin depends on another plugin directly.
 

package/docs/architecture.md

@@ -56,6 +56,10 @@ Plugins communicate by **emitting events**, not by calling each other directly.
 
 Findings are stored in `~/.onlooker/cartographer/<project-key>/findings/` and delivered at-least-once (deduplicated on `payload.finding_hash`). The audit runs as a detached background process; your session is never blocked.
 
+### Bursar
+
+[Bursar](../plugins/bursar) is the clearest example of one plugin consuming another's output **through the bus rather than by direct coupling**. Governor tracks spend per session and emits `governor.session.complete`; bursar reads those events at `SessionEnd`, rolls each session's totals into a per-project ledger under `~/.onlooker/bursar/projects/<project-key>/`, and surfaces "this project burned $X this week" at the next `SessionStart`. It never imports governor's code — if governor is disabled the events simply aren't there, and bursar degrades to a session count. This is the dependency model working as intended: the cross-session rollup is a separate, independently installable plugin that observes governor's event stream.
+
 ### Plugin dependency model
 
 All plugins depend on `ecosystem`. No plugin depends on another plugin at runtime. This means:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -19,14 +19,14 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^2.6.0"
+    "@onlooker-community/schema": "^2.7.0"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
     "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 plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh plugins/assayer/scripts/hooks/*.sh plugins/assayer/scripts/lib/*.sh plugins/cartographer/scripts/hooks/*.sh plugins/cartographer/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 plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh plugins/assayer/scripts/hooks/*.sh plugins/assayer/scripts/lib/*.sh plugins/cartographer/scripts/hooks/*.sh plugins/cartographer/scripts/lib/*.sh plugins/bursar/scripts/hooks/*.sh plugins/bursar/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/bursar/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "bursar",
+  "version": "0.1.0",
+  "description": "Multi-session, per-project budget accounting for the Onlooker ecosystem. Rolls each session's spend into a per-project ledger on SessionEnd and surfaces \"this project burned $X this week\" at SessionStart. Where governor regulates a single session, bursar is the cross-session rollup: it reads governor.session.complete off the shared event bus and emits bursar.* events for audit. Named for the officer who keeps the accounts. Builds on the Onlooker ecosystem plugin.",
+  "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/bursar/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/bursar-v0.0.1...bursar-v0.1.0) (2026-06-12)
+
+
+### Features
+
+* **bursar:** introduce multi-session budget rollup plugin ([#81](https://github.com/onlooker-community/ecosystem/issues/81)) ([b11e687](https://github.com/onlooker-community/ecosystem/commit/b11e687744bab70a94025c46c4aaa58fb7ea97f4))
+
+## Changelog

package/plugins/bursar/README.md

@@ -0,0 +1,100 @@
+# Bursar
+
+Multi-session, per-project budget accounting for the Onlooker ecosystem.
+
+Bursar rolls each session's spend into a per-project ledger when the session ends, and surfaces "this project burned $X this week" at the next session start. Named for the officer who keeps an institution's accounts, it answers a question [`governor`](../governor) cannot: not "is *this* session over budget?" but "what has *this project* cost me lately?"
+
+Where governor regulates a single session, bursar is the cross-session rollup. The two do not call each other — bursar reads governor's per-session totals off the shared event bus (`governor.session.complete`) and degrades gracefully when governor is not running.
+
+Bursar is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | Matcher | What Bursar does |
+|------|---------|------------------|
+| `SessionStart` | `*` | Derives the project key from the session `cwd`, writes a breadcrumb so `SessionEnd` can attribute spend, then sums the per-project ledger over the active window and surfaces the total as `additionalContext`. Emits `bursar.rollup.surfaced` (or `bursar.rollup.skipped` when there is nothing in the window). |
+| `SessionEnd` | `*` | Resolves the ending session's project key (breadcrumb → substrate session tracker → live cwd), reads the session's spend from the latest `governor.session.complete` on the event bus, upserts one record into the per-project ledger, and emits `bursar.session.recorded`. |
+
+### Attributing a session to a project
+
+`SessionEnd`'s hook payload only reliably carries `session_id`, so bursar cannot derive a project key from a `cwd` at that point. Instead, `SessionStart` — which *does* receive `cwd` — derives the [project key](../tribunal/scripts/lib/tribunal-project-key.sh) (SHA256 of the git origin URL, or the repo root for remote-less repos) and stashes a breadcrumb at `$ONLOOKER_DIR/bursar/sessions/<session-id>.json`. `SessionEnd` reads it back, falling back to the substrate session tracker's recorded `cwd`, then to the live `cwd`.
+
+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.
+
+### Reading spend off the bus
+
+On `SessionEnd`, bursar scans `~/.onlooker/logs/onlooker-events.jsonl` for the **last** `governor.session.complete` matching the session — governor re-emits cumulatively, so the final one carries the session's totals. It records `total_cost_usd`, `total_tokens`, and `total_api_calls`. When no such event exists (governor disabled or absent), the session is still recorded with `governor_present: false` and no cost, and the surfaced message degrades to a session count.
+
+## Activation
+
+Bursar is **off by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "bursar": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`. While disabled, every hook skips silently and no ledger is written.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "bursar": {
+    "enabled": false,
+    "window": "rolling_7d",
+    "week_start": "monday",
+    "surface_at_session_start": true,
+    "min_cost_to_surface_usd": 0
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for any recording, surfacing, or event emission to run. |
+| `window` | `"rolling_7d"` | Rollup window. `"rolling_7d"` sums the trailing 7×24h; `"calendar_week"` sums from the most recent week start. |
+| `week_start` | `"monday"` | First day of the calendar week — `"monday"` or `"sunday"`. Only consulted when `window` is `"calendar_week"`. |
+| `surface_at_session_start` | `true` | When `false`, bursar still records sessions and writes breadcrumbs but prints nothing at `SessionStart`. |
+| `min_cost_to_surface_usd` | `0` | Suppress the `SessionStart` message when the windowed total is below this dollar amount. |
+
+Config resolves in three layers, latest wins: plugin `config.json` → `~/.claude/settings.json` → `<repo>/.claude/settings.json`.
+
+## Storage layout
+
+```text
+~/.onlooker/bursar/
+├── projects/
+│   └── <project-key>/
+│       ├── sessions.jsonl        # one record per session (project key sanitized to [a-zA-Z0-9-_])
+│       └── sessions.jsonl.lock   # upsert lock
+└── sessions/
+    └── <session-id>.json         # SessionStart→SessionEnd breadcrumb (removed once recorded)
+```
+
+Each ledger line is a JSON record: `{ ts, ts_epoch, session_id, project_key, cost_usd?, tokens?, api_calls?, governor_present, model? }`. `ts_epoch` (seconds) is stored alongside the RFC3339 `ts` so windowing is a portable numeric compare with no date parsing. Cost fields are omitted when governor was not running for the session.
+
+Bursar honors `$ONLOOKER_DIR`; it never hardcodes `~/.onlooker`, so the test suite's isolated temp home is respected.
+
+## Events emitted
+
+Bursar emits the canonical `bursar.*` event surface from [`@onlooker-community/schema`](https://github.com/onlooker-community/schema) v2.7.0+. All events land in `~/.onlooker/logs/onlooker-events.jsonl` and are validated against the schema before write.
+
+| Event | When |
+|-------|------|
+| `bursar.session.recorded` | At `SessionEnd`, after a session's spend is upserted into the project ledger. Carries `project_key`, `session_id`, `governor_present`, and — when governor supplied them — `cost_usd`, `tokens`, `api_calls`, `model`. |
+| `bursar.rollup.surfaced` | At `SessionStart`, when a windowed total is shown. Carries `project_key`, `window`, `window_start`, `total_cost_usd`, `session_count`, `total_tokens`, and `sessions_with_cost`. |
+| `bursar.rollup.skipped` | At `SessionStart`, when nothing is surfaced because the window is empty. Carries `reason` and `project_key`. |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- The [`governor`](../governor) plugin enabled, to populate the dollar figures bursar rolls up. Without it, bursar still reports session counts.
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `awk` for fractional cost arithmetic and token formatting (standard on macOS and most Linux distributions).

package/plugins/bursar/config.json

@@ -0,0 +1,11 @@
+{
+  "plugin_name": "bursar",
+  "storage_path": "~/.onlooker",
+  "bursar": {
+    "enabled": false,
+    "window": "rolling_7d",
+    "week_start": "monday",
+    "surface_at_session_start": true,
+    "min_cost_to_surface_usd": 0
+  }
+}

package/plugins/bursar/hooks/hooks.json

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

package/plugins/bursar/scripts/hooks/bursar-session-end.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# Bursar SessionEnd hook.
+#
+# Fires when a session ends. Responsibilities:
+#   1. Skip silently when bursar.enabled is false.
+#   2. Resolve the project key for the ending session (breadcrumb first, then
+#      the substrate session-tracker cwd, then the current cwd).
+#   3. Read this session's spend from the shared event bus — the latest
+#      governor.session.complete for this session_id. When governor is absent
+#      the session is still recorded, with cost unknown (governor_present:false).
+#   4. Upsert the session's spend into the per-project rollup ledger.
+#   5. Emit bursar.session.recorded and drop the breadcrumb.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session termination.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+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/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+# shellcheck source=../lib/bursar-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-config.sh"
+# shellcheck source=../lib/bursar-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-events.sh"
+# shellcheck source=../lib/bursar-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-project-key.sh"
+# shellcheck source=../lib/bursar-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-ledger.sh"
+
+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=""
+
+_done() { exit 0; }
+
+[[ -z "$SESSION_ID" ]] && _done
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+SAFE_SID=$(printf '%s' "$SESSION_ID" | tr -c 'a-zA-Z0-9-' '_')
+BREADCRUMB="${ONLOOKER_DIR}/bursar/sessions/${SAFE_SID}.json"
+TRACKER="${ONLOOKER_DIR}/session-trackers/${SESSION_ID}"
+
+# -----------------------------------------------------------------------
+# Resolve project key + cwd: breadcrumb → substrate tracker → live cwd.
+# -----------------------------------------------------------------------
+PROJECT_KEY=""
+if [[ -f "$BREADCRUMB" ]]; then
+	PROJECT_KEY=$(jq -r '.project_key // ""' "$BREADCRUMB" 2>/dev/null) || PROJECT_KEY=""
+	[[ -z "$CWD" ]] && CWD=$(jq -r '.cwd // ""' "$BREADCRUMB" 2>/dev/null)
+fi
+if [[ -z "$CWD" && -f "$TRACKER" ]]; then
+	CWD=$(jq -r '.cwd // ""' "$TRACKER" 2>/dev/null) || CWD=""
+fi
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+
+bursar_config_load "$CWD"
+bursar_config_enabled || _done
+
+[[ -z "$PROJECT_KEY" ]] && PROJECT_KEY=$(bursar_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done
+
+# -----------------------------------------------------------------------
+# Read this session's spend off the shared event bus: the last
+# governor.session.complete carries the session's cumulative totals.
+# -----------------------------------------------------------------------
+LOG="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR}/logs/onlooker-events.jsonl}"
+GOV_PRESENT="false"
+COST=""
+TOKENS=""
+CALLS=""
+
+# Reads event-log lines on stdin; echoes the latest matching session.complete payload.
+_latest_governor_payload() {
+	grep -F '"governor.session.complete"' 2>/dev/null \
+		| jq -c --arg sid "$SESSION_ID" \
+			'select(.event_type == "governor.session.complete" and .payload.session_id == $sid) | .payload' \
+			2>/dev/null \
+		| tail -n 1
+}
+
+if [[ -f "$LOG" ]]; then
+	# The matching event was emitted seconds ago (governor's final Stop), so it is
+	# almost always near the tail. Scan a recent slice first to keep this hook
+	# fast as the global log grows; fall back to the full file only on a miss.
+	SPEND=$(tail -n 2000 "$LOG" 2>/dev/null | _latest_governor_payload)
+	[[ -z "$SPEND" ]] && SPEND=$(_latest_governor_payload < "$LOG")
+	if [[ -n "$SPEND" ]]; then
+		GOV_PRESENT="true"
+		COST=$(printf '%s' "$SPEND" | jq -r '.total_cost_usd // empty' 2>/dev/null) || COST=""
+		TOKENS=$(printf '%s' "$SPEND" | jq -r '.total_tokens // empty' 2>/dev/null) || TOKENS=""
+		CALLS=$(printf '%s' "$SPEND" | jq -r '.total_api_calls // empty' 2>/dev/null) || CALLS=""
+	fi
+fi
+
+MODEL=""
+[[ -f "$TRACKER" ]] && MODEL=$(jq -r '.model // ""' "$TRACKER" 2>/dev/null)
+
+# -----------------------------------------------------------------------
+# Build the record and the event payload, attaching spend fields only when
+# governor supplied them.
+# -----------------------------------------------------------------------
+add_fields() {
+	# Echoes the input JSON ($1) with cost/tokens/calls/model merged in.
+	local base="$1"
+	[[ -n "$COST" ]] && base=$(printf '%s' "$base" | jq --argjson v "$COST" '. + {cost_usd: $v}' 2>/dev/null)
+	[[ -n "$TOKENS" ]] && base=$(printf '%s' "$base" | jq --argjson v "$TOKENS" '. + {tokens: $v}' 2>/dev/null)
+	[[ -n "$CALLS" ]] && base=$(printf '%s' "$base" | jq --argjson v "$CALLS" '. + {api_calls: $v}' 2>/dev/null)
+	[[ -n "$MODEL" ]] && base=$(printf '%s' "$base" | jq --arg v "$MODEL" '. + {model: $v}' 2>/dev/null)
+	printf '%s' "$base"
+}
+
+RECORD=$(jq -n \
+	--arg ts "$(bursar_now_iso)" \
+	--argjson te "$(bursar_now_epoch)" \
+	--arg sid "$SESSION_ID" \
+	--arg pk "$PROJECT_KEY" \
+	--argjson gp "$GOV_PRESENT" \
+	'{ts: $ts, ts_epoch: $te, session_id: $sid, project_key: $pk, governor_present: $gp}' 2>/dev/null)
+RECORD=$(add_fields "$RECORD")
+
+# Only claim the session was recorded — and only drop the breadcrumb — once the
+# ledger upsert actually succeeds. A failed write (lock timeout, mv failure)
+# must keep the breadcrumb so the session→project attribution survives for a
+# later attempt rather than being lost behind a false "recorded" event.
+if [[ -n "$RECORD" ]] && bursar_ledger_record "$PROJECT_KEY" "$RECORD"; then
+	EV=$(jq -n \
+		--arg pk "$PROJECT_KEY" \
+		--arg sid "$SESSION_ID" \
+		--argjson gp "$GOV_PRESENT" \
+		'{project_key: $pk, session_id: $sid, governor_present: $gp}' 2>/dev/null)
+	EV=$(add_fields "$EV")
+	[[ -n "$EV" ]] && bursar_emit_event "bursar.session.recorded" "$EV" "$SESSION_ID" || true
+
+	rm -f "$BREADCRUMB" 2>/dev/null || true
+fi
+
+_done

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Bursar SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when bursar.enabled is false.
+#   2. Derive the project key from the session cwd and stash a breadcrumb
+#      (project_key + cwd) so SessionEnd can attribute spend even though the
+#      SessionEnd payload only reliably carries session_id.
+#   3. Surface "this project burned $X this week" by summing the per-project
+#      ledger over the configured window and emitting it as SessionStart
+#      additionalContext.
+#   4. Emit bursar.rollup.surfaced (or bursar.rollup.skipped) for audit.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - Only the additionalContext JSON is written to stdout; errors go to stderr.
+
+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/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+# shellcheck source=../lib/bursar-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-config.sh"
+# shellcheck source=../lib/bursar-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-events.sh"
+# shellcheck source=../lib/bursar-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-project-key.sh"
+# shellcheck source=../lib/bursar-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/bursar-ledger.sh"
+
+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=""
+
+_done() { exit 0; }
+
+bursar_config_load "$CWD"
+bursar_config_enabled || _done
+
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+PROJECT_KEY=$(bursar_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done   # not a recognizable project — nothing to attribute
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+
+# -----------------------------------------------------------------------
+# Breadcrumb: lets SessionEnd resolve the project key without re-deriving
+# from a cwd it may not have.
+# -----------------------------------------------------------------------
+if [[ -n "$SESSION_ID" ]]; then
+	BREADCRUMB_DIR="${ONLOOKER_DIR}/bursar/sessions"
+	mkdir -p "$BREADCRUMB_DIR" 2>/dev/null || true
+	safe_sid=$(printf '%s' "$SESSION_ID" | tr -c 'a-zA-Z0-9-' '_')
+	jq -n --arg pk "$PROJECT_KEY" --arg cwd "$CWD" --arg ts "$(bursar_now_iso)" \
+		'{project_key: $pk, cwd: $cwd, started_at: $ts}' \
+		>"${BREADCRUMB_DIR}/${safe_sid}.json" 2>/dev/null || true
+fi
+
+# -----------------------------------------------------------------------
+# Surface the rolling total (opt-out via bursar.surface_at_session_start).
+# -----------------------------------------------------------------------
+bursar_config_surface_enabled || _done
+
+WINDOW=$(bursar_config_window)
+WEEK_START=$(bursar_config_week_start)
+CUTOFF=$(bursar_window_cutoff_epoch "$WINDOW" "$WEEK_START")
+TOTALS=$(bursar_window_totals "$PROJECT_KEY" "$CUTOFF")
+
+SESSION_COUNT=$(printf '%s' "$TOTALS" | jq -r '.session_count // 0' 2>/dev/null) || SESSION_COUNT=0
+TOTAL_COST=$(printf '%s' "$TOTALS" | jq -r '.total_cost_usd // 0' 2>/dev/null) || TOTAL_COST=0
+TOTAL_TOKENS=$(printf '%s' "$TOTALS" | jq -r '.total_tokens // 0' 2>/dev/null) || TOTAL_TOKENS=0
+SESSIONS_WITH_COST=$(printf '%s' "$TOTALS" | jq -r '.sessions_with_cost // 0' 2>/dev/null) || SESSIONS_WITH_COST=0
+
+# Nothing recorded yet in the window.
+if [[ "${SESSION_COUNT:-0}" -eq 0 ]]; then
+	skipped=$(jq -n --arg pk "$PROJECT_KEY" '{reason: "no_data", project_key: $pk}' 2>/dev/null) || skipped='{"reason":"no_data"}'
+	bursar_emit_event "bursar.rollup.skipped" "$skipped" "$SESSION_ID" || true
+	_done
+fi
+
+# Below the noise threshold — record nothing on screen.
+MIN_COST=$(bursar_config_min_cost)
+if [[ "$(awk -v c="$TOTAL_COST" -v m="$MIN_COST" 'BEGIN { print (c < m) ? 1 : 0 }')" == "1" ]]; then
+	_done
+fi
+
+WINDOW_LABEL="in the last 7 days"
+[[ "$WINDOW" == "calendar_week" ]] && WINDOW_LABEL="this week"
+COST_FMT=$(awk -v c="$TOTAL_COST" 'BEGIN { printf "%.2f", c }')
+TOKENS_FMT=$(bursar_fmt_tokens "$TOTAL_TOKENS")
+SESS_NOUN=$([[ "${SESSION_COUNT:-0}" -eq 1 ]] && printf 'session' || printf 'sessions')
+
+# Key the "enable governor" prompt on cost *coverage*, not on the dollar total:
+# governor can legitimately report $0.00 for a window, and that should still
+# render as a tracked total rather than a nudge to enable governor.
+if [[ "${SESSIONS_WITH_COST:-0}" -eq 0 ]]; then
+	MSG="Bursar: ${SESSION_COUNT} ${SESS_NOUN} in this project ${WINDOW_LABEL}. Enable governor for \$ cost tracking."
+elif [[ "${SESSIONS_WITH_COST:-0}" -lt "${SESSION_COUNT:-0}" ]]; then
+	MSG="Bursar: this project burned \$${COST_FMT} across ${SESSIONS_WITH_COST} of ${SESSION_COUNT} sessions ${WINDOW_LABEL} (~${TOKENS_FMT} tokens); enable governor in the rest for full cost tracking."
+else
+	MSG="Bursar: this project burned \$${COST_FMT} across ${SESSION_COUNT} ${SESS_NOUN} ${WINDOW_LABEL} (~${TOKENS_FMT} tokens)."
+fi
+
+WINDOW_START_ISO=$(bursar_epoch_to_iso "$CUTOFF")
+surfaced=$(jq -n \
+	--arg pk "$PROJECT_KEY" \
+	--arg w "$WINDOW" \
+	--argjson cost "$TOTAL_COST" \
+	--argjson sc "$SESSION_COUNT" \
+	--argjson tok "$TOTAL_TOKENS" \
+	--argjson swc "$SESSIONS_WITH_COST" \
+	--arg ws "$WINDOW_START_ISO" \
+	'{
+		project_key: $pk,
+		window: $w,
+		total_cost_usd: $cost,
+		session_count: $sc,
+		total_tokens: $tok,
+		sessions_with_cost: $swc
+	}
+	+ (if $ws != "" then {window_start: $ws} else {} end)' 2>/dev/null) || surfaced=""
+[[ -n "$surfaced" ]] && bursar_emit_event "bursar.rollup.surfaced" "$surfaced" "$SESSION_ID" || true
+
+jq -cn --arg ctx "$MSG" '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
+
+_done