@onlooker-community/ecosystem 0.15.2 → 0.17.0

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

@@ -0,0 +1,14 @@
+{
+  "name": "governor",
+  "version": "0.2.0",
+  "description": "Resource governance and budget enforcement for the Onlooker ecosystem. Tracks per-session token and cost spend, gates Task spawns before they exceed a configurable budget ceiling, and emits governor.* events for audit. Named for the steam-engine governor — a device that regulates output. 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/governor/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/governor-v0.1.0...governor-v0.2.0) (2026-05-26)
+
+
+### Features
+
+* **governor:** resource governance and budget enforcement plugin :rocket: ([#43](https://github.com/onlooker-community/ecosystem/issues/43)) ([04e6d70](https://github.com/onlooker-community/ecosystem/commit/04e6d7051f27db752bb121d389d65b4d8ade04ad))
+
+## [0.1.0] - 2026-05-25
+
+### Added
+
+- Initial plugin scaffold: `config.json`, `plugin.json`, `hooks.json`
+- `governor-config.sh` — three-layer config resolution (plugin defaults → user settings → repo settings)
+- `governor-events.sh` — canonical `governor.*` event emission via ecosystem `onlooker-event.mjs`
+- `governor-ledger.sh` — JSONL ledger read/write with `portable-lock.sh` atomic guard
+- `governor-estimate.sh` — tier-table token estimation with configurable safety margin
+- `governor-session-start.sh` — SessionStart hook: setup storage, load budget contract, sweep stale locks, check global policy hash
+- `governor-pre-tool-use.sh` — PreToolUse hook on Task: pre-call gate via check-and-reserve with `portable-lock.sh`
+- `governor-post-tool-use.sh` — PostToolUse hook on Task: record call duration and estimated tokens to JSONL ledger
+- `governor-stop.sh` — Stop hook: emit `governor.session.complete` with cumulative spend summary

package/plugins/governor/config.json

@@ -0,0 +1,19 @@
+{
+  "plugin_name": "governor",
+  "storage_path": "~/.onlooker",
+  "governor": {
+    "enabled": false,
+    "enforcement": "soft",
+    "global_policy_path": "~/.onlooker/governance/global-policy.yaml",
+    "session": {
+      "tokens_default": 100000,
+      "cost_usd_default": 1.0,
+      "reserve_pct": 10
+    },
+    "estimation": {
+      "safety_margin": 1.3,
+      "hard_stop_margin": 1.5,
+      "method": "tier_table"
+    }
+  }
+}

package/plugins/governor/hooks/hooks.json

@@ -0,0 +1,48 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/governor-session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/governor-pre-tool-use.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/governor-post-tool-use.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/governor-stop.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/governor/scripts/hooks/governor-post-tool-use.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Governor PostToolUse hook (matcher: Task).
+#
+# Records each completed Task call in the JSONL ledger. Validates whether
+# the PostToolUse payload includes actual usage counts (Q1 from issue #40).
+#
+# Hook contract:
+#   - Always exits 0. Recording failure must never block the session.
+#   - Skips silently when governor.enabled is false.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/governor-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+# shellcheck source=../lib/governor-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+# shellcheck source=../lib/governor-estimate.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-estimate.sh"
+# shellcheck source=../lib/governor-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-ledger.sh"
+
+_done() { exit 0; }
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+[[ -z "$SESSION_ID" ]] && SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+governor_config_load "$CWD"
+
+if ! governor_config_enabled; then
+	_done
+fi
+
+# -----------------------------------------------------------------------
+# Extract hook fields.
+# -----------------------------------------------------------------------
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""
+TOOL_INPUT=$(printf '%s' "$INPUT" | jq -c '.tool_input // {}' 2>/dev/null) || TOOL_INPUT="{}"
+TOOL_RESPONSE=$(printf '%s' "$INPUT" | jq -c '.tool_response // {}' 2>/dev/null) || TOOL_RESPONSE="{}"
+DURATION_MS=$(printf '%s' "$INPUT" | jq -r '.duration_ms // 0' 2>/dev/null) || DURATION_MS=0
+
+# Check if actual usage counts are present (Q1 validation).
+ACTUAL_INPUT_TOKENS=$(printf '%s' "$TOOL_RESPONSE" \
+	| jq -r '.usage.input_tokens // .usage.input_tokens_total // empty' 2>/dev/null) \
+	|| ACTUAL_INPUT_TOKENS=""
+ACTUAL_OUTPUT_TOKENS=$(printf '%s' "$TOOL_RESPONSE" \
+	| jq -r '.usage.output_tokens // .usage.output_tokens_total // empty' 2>/dev/null) \
+	|| ACTUAL_OUTPUT_TOKENS=""
+
+# Estimate tokens from the input we sent.
+ESTIMATED_TOKENS=$(governor_estimate_tokens "$TOOL_INPUT")
+ESTIMATED_COST=$(governor_estimate_cost "$ESTIMATED_TOKENS")
+ESTIMATION_METHOD=$(governor_estimate_method)
+
+# Build the completion ledger record.
+# estimated_tokens is negated to cancel the reservation written by PreToolUse.
+# actual_tokens (when present) complete the two-phase accounting so the running
+# total converges to real spend: N_est + (-N_est) + N_act = N_act.
+AGENT_TYPE="${TOOL_NAME:-Task}"
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null) || TS="1970-01-01T00:00:00Z"
+NEG_ESTIMATED=$(( -ESTIMATED_TOKENS ))
+
+RECORD=$(jq -n \
+	--arg ts "$TS" \
+	--arg sid "$SESSION_ID" \
+	--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+	--arg at "$AGENT_TYPE" \
+	--argjson est "$NEG_ESTIMATED" \
+	--argjson cost "$ESTIMATED_COST" \
+	--argjson dur "$DURATION_MS" \
+	'{
+		ts: $ts,
+		session_id: $sid,
+		agent_id: $aid,
+		agent_type: $at,
+		estimated_tokens: $est,
+		cost_usd_estimated: $cost,
+		duration_ms: $dur
+	}' 2>/dev/null) || RECORD="{}"
+
+# Compute actual total once; used for both the ledger record and the event payload.
+ACTUAL_TOTAL=""
+if [[ -n "$ACTUAL_INPUT_TOKENS" && -n "$ACTUAL_OUTPUT_TOKENS" ]]; then
+	ACTUAL_TOTAL=$(( ACTUAL_INPUT_TOKENS + ACTUAL_OUTPUT_TOKENS ))
+	RECORD=$(printf '%s' "$RECORD" | jq \
+		--argjson actual "$ACTUAL_TOTAL" \
+		'. + {actual_tokens: $actual}' 2>/dev/null) || true
+fi
+
+governor_ledger_append "$SESSION_ID" "$RECORD" || true
+
+# Build the governor.call.recorded payload.
+CALL_PAYLOAD=$(jq -n \
+	--arg sid "$SESSION_ID" \
+	--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+	--arg at "$AGENT_TYPE" \
+	--argjson est "$ESTIMATED_TOKENS" \
+	--argjson cost "$ESTIMATED_COST" \
+	--argjson dur "$DURATION_MS" \
+	'{
+		session_id: $sid,
+		agent_id: $aid,
+		agent_type: $at,
+		estimated_tokens: $est,
+		cost_usd_estimated: $cost,
+		duration_ms: $dur
+	}' 2>/dev/null) || CALL_PAYLOAD="{}"
+
+if [[ -n "$ACTUAL_TOTAL" ]]; then
+	ESTIMATION_ERROR=""
+	if (( ACTUAL_TOTAL > 0 )); then
+		ESTIMATION_ERROR=$(awk \
+			"BEGIN { printf \"%.2f\", (($ESTIMATED_TOKENS - $ACTUAL_TOTAL) / $ACTUAL_TOTAL) * 100 }" \
+			2>/dev/null) || ESTIMATION_ERROR=""
+	fi
+	CALL_PAYLOAD=$(printf '%s' "$CALL_PAYLOAD" | jq \
+		--argjson actual "$ACTUAL_TOTAL" \
+		--arg err "${ESTIMATION_ERROR:-}" \
+		'. + {actual_tokens: $actual, tokens_returned_to_pool: 0}
+		 + (if $err != "" then {estimation_error_pct: ($err | tonumber)} else {} end)' \
+		2>/dev/null) || true
+fi
+
+governor_emit_event "governor.call.recorded" "$CALL_PAYLOAD" || true
+
+_done

package/plugins/governor/scripts/hooks/governor-pre-tool-use.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# Governor PreToolUse hook (matcher: Task).
+#
+# Gates Task spawns before they exceed the session budget. Uses
+# portable-lock.sh for an atomic check-and-reserve so concurrent spawns
+# cannot both pass a budget check simultaneously.
+#
+# Decision logic:
+#   - Estimate tokens for the spawn.
+#   - Read current consumed tokens from the JSONL ledger.
+#   - Allow if (consumed + estimated) <= budget_tokens.
+#   - Emit governor.gate.checked with decision and reason.
+#   - In "soft" enforcement: always allow, only emit the event.
+#   - In "hard" enforcement: block by returning {"decision": "block"} on
+#     stdout with exit 0 (Claude Code PreToolUse block protocol).
+#
+# Hook contract:
+#   - Exit 0 always.
+#   - To block: write {"decision": "block", "reason": "..."} to stdout.
+#   - To allow: write nothing (or {"decision": "allow"}) to stdout.
+#   - Skips silently when governor.enabled is false.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/governor-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+# shellcheck source=../lib/governor-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+# shellcheck source=../lib/governor-estimate.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-estimate.sh"
+# shellcheck source=../lib/governor-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-ledger.sh"
+
+_allow() { exit 0; }
+
+_block() {
+	local reason="${1:-budget_exceeded}"
+	printf '{"decision":"block","reason":"%s"}\n' "$reason"
+	exit 0
+}
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+[[ -z "$SESSION_ID" ]] && SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+governor_config_load "$CWD"
+
+if ! governor_config_enabled; then
+	_allow
+fi
+
+# -----------------------------------------------------------------------
+# Read config.
+# -----------------------------------------------------------------------
+ENFORCEMENT=$(governor_config_enforcement)
+TOKENS_BUDGET=$(governor_config_get '.governor.session.tokens_default')
+TOKENS_BUDGET="${TOKENS_BUDGET:-100000}"
+SAFETY_MARGIN=$(governor_config_get '.governor.estimation.safety_margin')
+SAFETY_MARGIN="${SAFETY_MARGIN:-1.3}"
+HARD_STOP_MARGIN=$(governor_config_get '.governor.estimation.hard_stop_margin')
+HARD_STOP_MARGIN="${HARD_STOP_MARGIN:-1.5}"
+
+# Respect env-var budget overrides set by orchestrating agents.
+if [[ -n "${ONLOOKER_SESSION_BUDGET_TOKENS:-}" ]]; then
+	TOKENS_BUDGET="$ONLOOKER_SESSION_BUDGET_TOKENS"
+fi
+
+TOOL_INPUT=$(printf '%s' "$INPUT" | jq -c '.tool_input // {}' 2>/dev/null) || TOOL_INPUT="{}"
+AGENT_TYPE=$(printf '%s' "$INPUT" | jq -r '.tool_name // "Task"' 2>/dev/null) || AGENT_TYPE="Task"
+
+# -----------------------------------------------------------------------
+# Estimate tokens for this spawn.
+# -----------------------------------------------------------------------
+ESTIMATED_TOKENS=$(governor_estimate_tokens "$TOOL_INPUT" "$SAFETY_MARGIN")
+ESTIMATED_COST=$(governor_estimate_cost "$ESTIMATED_TOKENS")
+ESTIMATION_METHOD=$(governor_estimate_method)
+
+# -----------------------------------------------------------------------
+# Atomic check-and-reserve via the ledger lock.
+# -----------------------------------------------------------------------
+LEDGER_PATH=$(governor_ledger_path "$SESSION_ID")
+GATE_LOCK="${LEDGER_PATH}.gate.lock"
+
+DECISION="allow"
+REASON=""
+TOKENS_CONSUMED=0
+
+if lock_acquire "$GATE_LOCK" 3; then
+	TOKENS_CONSUMED=$(governor_ledger_total_tokens "$SESSION_ID")
+	PROJECTED=$(( TOKENS_CONSUMED + ESTIMATED_TOKENS ))
+
+	# Hard stop: unconditionally block when projected exceeds budget * hard_stop_margin.
+	HARD_STOP_THRESHOLD=$(awk "BEGIN { printf \"%d\", int($TOKENS_BUDGET * $HARD_STOP_MARGIN) }" 2>/dev/null) \
+		|| HARD_STOP_THRESHOLD=$(( TOKENS_BUDGET * 2 ))
+
+	if (( PROJECTED > HARD_STOP_THRESHOLD )); then
+		DECISION="block"
+		REASON="ceiling_exceeded"
+	elif (( PROJECTED > TOKENS_BUDGET )); then
+		DECISION="block"
+		REASON="budget_exceeded"
+	fi
+
+	# Write reservation inside the gate lock so concurrent spawns see in-flight cost.
+	if [[ "$DECISION" == "allow" ]]; then
+		TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null) || TS="1970-01-01T00:00:00Z"
+		RESERVATION=$(jq -n \
+			--arg ts "$TS" \
+			--arg sid "$SESSION_ID" \
+			--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+			--arg at "$AGENT_TYPE" \
+			--argjson est "$ESTIMATED_TOKENS" \
+			--argjson cost "$ESTIMATED_COST" \
+			'{
+				ts: $ts,
+				session_id: $sid,
+				agent_id: $aid,
+				agent_type: $at,
+				estimated_tokens: $est,
+				cost_usd_estimated: $cost,
+				record_type: "reservation"
+			}' 2>/dev/null) || RESERVATION="{}"
+		governor_ledger_write_direct "$LEDGER_PATH" "$RESERVATION" || true
+	fi
+
+	lock_release "$GATE_LOCK"
+else
+	# Could not acquire gate lock — treat as block to be safe in hard mode.
+	DECISION="block"
+	REASON="lock_timeout"
+fi
+
+TOKENS_AVAILABLE=$(( TOKENS_BUDGET - TOKENS_CONSUMED ))
+(( TOKENS_AVAILABLE < 0 )) && TOKENS_AVAILABLE=0
+
+# -----------------------------------------------------------------------
+# Emit governor.gate.checked.
+# -----------------------------------------------------------------------
+GATE_PAYLOAD=$(jq -n \
+	--arg sid "$SESSION_ID" \
+	--arg aid "${CLAUDE_SESSION_ID:-unknown}" \
+	--arg at "$AGENT_TYPE" \
+	--arg dec "$DECISION" \
+	--argjson est "$ESTIMATED_TOKENS" \
+	--argjson avail "$TOKENS_AVAILABLE" \
+	--arg method "$ESTIMATION_METHOD" \
+	--argjson margin "$SAFETY_MARGIN" \
+	'{
+		session_id: $sid,
+		agent_id: $aid,
+		agent_type: $at,
+		decision: $dec,
+		estimated_tokens: $est,
+		tokens_available: $avail,
+		estimation_method: $method,
+		safety_margin: $margin
+	}' 2>/dev/null) || GATE_PAYLOAD="{}"
+
+if [[ -n "$REASON" ]]; then
+	GATE_PAYLOAD=$(printf '%s' "$GATE_PAYLOAD" \
+		| jq --arg r "$REASON" '. + {reason: $r}' 2>/dev/null) \
+		|| true
+fi
+
+governor_emit_event "governor.gate.checked" "$GATE_PAYLOAD" || true
+
+# -----------------------------------------------------------------------
+# Enforce decision.
+# -----------------------------------------------------------------------
+# ceiling_exceeded always blocks regardless of enforcement mode.
+# budget_exceeded and lock_timeout only block in hard enforcement mode.
+if [[ "$DECISION" == "block" ]]; then
+	if [[ "$REASON" == "ceiling_exceeded" || "$ENFORCEMENT" == "hard" ]]; then
+		_block "${REASON:-budget_exceeded}"
+	fi
+fi
+
+_allow

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Governor SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when governor.enabled is false.
+#   2. Create governance storage directories.
+#   3. Sweep stale lock files left by crashed prior sessions.
+#   4. Check global-policy.yaml exists (warn if missing, don't block).
+#   5. Emit governor.lock.stale_cleared for each stale lock removed.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - 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)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/governor-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+# shellcheck source=../lib/governor-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-events.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; }
+
+governor_config_load "$CWD"
+
+if ! governor_config_enabled; then
+	_done
+fi
+
+# -----------------------------------------------------------------------
+# 1. Ensure storage directories exist.
+# -----------------------------------------------------------------------
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+GOVERNANCE_DIR="${ONLOOKER_DIR}/governance"
+LEDGER_DIR="${GOVERNANCE_DIR}/ledgers"
+mkdir -p "$LEDGER_DIR" 2>/dev/null || true
+
+# -----------------------------------------------------------------------
+# 2. Sweep stale lock directories.
+#    A lock dir is "stale" if it is older than 60 seconds.
+#    We only clean .lock.d directories under the ledgers directory.
+# -----------------------------------------------------------------------
+STALE_AGE=60
+
+if [[ -d "$LEDGER_DIR" ]]; then
+	while IFS= read -r -d '' lockdir; do
+		[[ -d "$lockdir" ]] || continue
+
+		lock_age=0
+		if command -v stat >/dev/null 2>&1; then
+			# macOS stat: -f %m; GNU stat: -c %Y
+			mtime=$(stat -f '%m' "$lockdir" 2>/dev/null) \
+				|| mtime=$(stat -c '%Y' "$lockdir" 2>/dev/null) \
+				|| mtime=0
+			now=$(date +%s 2>/dev/null) || now=0
+			lock_age=$(( now - mtime ))
+		fi
+
+		if (( lock_age >= STALE_AGE )); then
+			rmdir "$lockdir" 2>/dev/null || true
+			cleared_payload=$(jq -n \
+				--arg lp "$lockdir" \
+				--argjson age "$lock_age" \
+				'{
+					lock_path: $lp,
+					lock_age_seconds: $age,
+					pid_verified_dead: false
+				}' 2>/dev/null) || cleared_payload="{}"
+			governor_emit_event "governor.lock.stale_cleared" "$cleared_payload" || true
+		fi
+	done < <(find "$LEDGER_DIR" -maxdepth 2 -name '*.lock.d' -print0 2>/dev/null)
+fi
+
+# -----------------------------------------------------------------------
+# 3. Global policy file check (advisory only).
+# -----------------------------------------------------------------------
+POLICY_PATH=$(governor_config_get '.governor.global_policy_path')
+POLICY_PATH="${POLICY_PATH/#\~/$HOME}"
+
+if [[ -n "$POLICY_PATH" && ! -f "$POLICY_PATH" ]]; then
+	printf 'governor: global-policy.yaml not found at %s — running without global ceiling\n' \
+		"$POLICY_PATH" >&2
+fi
+
+_done

package/plugins/governor/scripts/hooks/governor-stop.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Governor Stop hook.
+#
+# Fires at session end. Emits governor.session.complete with cumulative
+# spend totals from the JSONL ledger.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks Stop.
+#   - Skips silently when governor.enabled is false.
+#   - Errors from ledger reads are swallowed; emits best-effort totals.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/portable-lock.sh"
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/governor-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-config.sh"
+# shellcheck source=../lib/governor-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-events.sh"
+# shellcheck source=../lib/governor-ledger.sh
+source "${PLUGIN_ROOT}/scripts/lib/governor-ledger.sh"
+
+_done() { exit 0; }
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+[[ -z "$SESSION_ID" ]] && SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+governor_config_load "$CWD"
+
+if ! governor_config_enabled; then
+	_done
+fi
+
+# -----------------------------------------------------------------------
+# Read session totals from the ledger.
+# -----------------------------------------------------------------------
+TOTAL_TOKENS=$(governor_ledger_total_tokens "$SESSION_ID")
+TOTAL_COST=$(governor_ledger_total_cost "$SESSION_ID")
+TOTAL_CALLS=$(governor_ledger_call_count "$SESSION_ID")
+LEDGER_POISONED=$(governor_ledger_is_poisoned "$SESSION_ID" && printf 'true' || printf 'false')
+
+TOKENS_BUDGET=$(governor_config_get '.governor.session.tokens_default')
+TOKENS_BUDGET="${TOKENS_BUDGET:-100000}"
+COST_BUDGET=$(governor_config_get '.governor.session.cost_usd_default')
+COST_BUDGET="${COST_BUDGET:-1.0}"
+
+if [[ -n "${ONLOOKER_SESSION_BUDGET_TOKENS:-}" ]]; then
+	TOKENS_BUDGET="$ONLOOKER_SESSION_BUDGET_TOKENS"
+fi
+
+UNDER_BUDGET="true"
+TOTAL_TOKENS_INT=$(printf '%s' "${TOTAL_TOKENS:-0}" | grep -oE '^[0-9]+' || printf '0')
+TOKENS_BUDGET_INT=$(printf '%s' "${TOKENS_BUDGET:-0}" | grep -oE '^[0-9]+' || printf '0')
+(( TOTAL_TOKENS_INT > TOKENS_BUDGET_INT )) && UNDER_BUDGET="false"
+
+# Also check the cost dimension (float comparison via awk).
+if [[ "$UNDER_BUDGET" == "true" ]]; then
+	COST_OVER=$(awk "BEGIN { print (${TOTAL_COST:-0} > ${COST_BUDGET:-1.0}) ? 1 : 0 }" 2>/dev/null) || COST_OVER=0
+	[[ "$COST_OVER" == "1" ]] && UNDER_BUDGET="false"
+fi
+
+SESSION_PAYLOAD=$(jq -n \
+	--argjson total_cost "${TOTAL_COST:-0}" \
+	--argjson budget_usd "${COST_BUDGET:-1.0}" \
+	--argjson under "$( [[ "$UNDER_BUDGET" == "true" ]] && printf 'true' || printf 'false')" \
+	--arg sid "$SESSION_ID" \
+	--argjson total_tokens "${TOTAL_TOKENS_INT:-0}" \
+	--argjson total_calls "${TOTAL_CALLS:-0}" \
+	--argjson dur 0 \
+	--argjson calls_blocked 0 \
+	--argjson calls_warned 0 \
+	--argjson poisoned "$( [[ "$LEDGER_POISONED" == "true" ]] && printf 'true' || printf 'false')" \
+	'{
+		total_cost_usd: $total_cost,
+		budget_usd: $budget_usd,
+		under_budget: $under,
+		session_id: $sid,
+		total_tokens: $total_tokens,
+		total_api_calls: $total_calls,
+		duration_ms: $dur,
+		calls_blocked: $calls_blocked,
+		calls_warned: $calls_warned,
+		ledger_poisoned: $poisoned
+	}' 2>/dev/null) || SESSION_PAYLOAD="{}"
+
+governor_emit_event "governor.session.complete" "$SESSION_PAYLOAD" || true
+
+_done