@onlooker-community/ecosystem 0.22.0 → 0.23.0

package/plugins/historian/scripts/lib/historian-retriever.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Similarity-search retriever for Historian.
+#
+# Given a query embedding and a project key, walks every JSONL chunk
+# record under ~/.onlooker/historian/<key>/sessions/, computes cosine
+# similarity between the query vector and each chunk's `embedding`
+# field, and returns the top-K candidates above a similarity floor.
+#
+# Chunks indexed before the embedder shipped don't have an `embedding`
+# field; the retriever silently skips them rather than treating them as
+# zero-similarity. They'll join the index after the next SessionEnd
+# indexing pass.
+
+# Aggregate every chunk record for the project. Returns a JSON array.
+historian_retriever_load_all_chunks() {
+	local key="$1"
+	[[ -z "$key" ]] && { echo '[]'; return 0; }
+
+	local dir
+	dir=$(historian_sessions_dir "$key")
+	[[ -d "$dir" ]] || { echo '[]'; return 0; }
+
+	# Walk every *.jsonl, emit one JSON array. Use python3 to avoid the
+	# `jq -s` quirks around very large inputs and to control the chunk
+	# shape (drop the embedding from filtering candidates but keep it
+	# for the math).
+	python3 - "$dir" <<'PY'
+import json, os, sys
+dir_path = sys.argv[1]
+out = []
+try:
+    for name in sorted(os.listdir(dir_path)):
+        if not name.endswith(".jsonl"):
+            continue
+        path = os.path.join(dir_path, name)
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    out.append(rec)
+        except OSError:
+            continue
+except FileNotFoundError:
+    pass
+print(json.dumps(out))
+PY
+}
+
+# Compute top-K cosine-similarity matches against the query embedding.
+#
+# The chunks are streamed from disk one line at a time so memory and
+# argv stay bounded as the per-project store grows. Earlier versions
+# passed the full chunks array as an argv string, which would trip the
+# OS ARG_MAX limit somewhere around tens of thousands of chunks; this
+# form never holds more than one chunk in memory at a time.
+#
+# Usage: historian_retriever_search <sessions_dir>
+#                                   <query_embedding_json>
+#                                   <top_k> <min_similarity>
+#                                   <max_age_days> <current_session_id>
+#
+# Output: JSON array sorted by similarity descending, length <= top_k.
+# Each entry: {
+#   chunk_id, session_id, similarity, age_days, body_redacted,
+#   chunk_index, start_turn_index, end_turn_index, source
+# }
+historian_retriever_search() {
+	local sessions_dir="${1:-}"
+	local query="${2:-[]}"
+	local top_k="${3:-5}"
+	local min_sim="${4:-0.55}"
+	local max_age_days="${5:-180}"
+	local current_session="${6:-}"
+
+	if [[ -z "$sessions_dir" || ! -d "$sessions_dir" ]]; then
+		echo '[]'
+		return 0
+	fi
+
+	python3 - "$sessions_dir" "$top_k" "$min_sim" "$max_age_days" "$current_session" "$query" <<'PY'
+import datetime, json, math, os, sys
+
+sessions_dir = sys.argv[1]
+top_k = int(sys.argv[2])
+min_sim = float(sys.argv[3])
+max_age_days = int(sys.argv[4])
+current_session = sys.argv[5]
+query = json.loads(sys.argv[6] or "null")
+
+
+def cosine(a, b):
+    if not a or not b or len(a) != len(b):
+        return None
+    dot = 0.0
+    na = 0.0
+    nb = 0.0
+    for x, y in zip(a, b):
+        dot += x * y
+        na += x * x
+        nb += y * y
+    if na <= 0.0 or nb <= 0.0:
+        return None
+    return dot / (math.sqrt(na) * math.sqrt(nb))
+
+
+def parse_iso(s):
+    if not s:
+        return None
+    try:
+        return datetime.datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ").replace(
+            tzinfo=datetime.timezone.utc
+        )
+    except ValueError:
+        return None
+
+
+if not isinstance(query, list) or not query:
+    print("[]")
+    sys.exit(0)
+
+now = datetime.datetime.now(datetime.timezone.utc)
+scored = []
+
+
+def consider(chunk):
+    sid = chunk.get("session_id", "")
+    # Exclude chunks from the session that is currently asking for
+    # context; a session retrieving its own chunks is a degenerate case.
+    if current_session and sid == current_session:
+        return
+    embedding = chunk.get("embedding")
+    if not isinstance(embedding, list) or not embedding:
+        return
+    sim = cosine(query, embedding)
+    if sim is None or sim < min_sim:
+        return
+    created = parse_iso(chunk.get("created_at"))
+    if created is None:
+        age_days = -1
+    else:
+        age_days = (now - created).days
+        if max_age_days > 0 and age_days > max_age_days:
+            return
+    scored.append(
+        {
+            "chunk_id": chunk.get("chunk_id"),
+            "session_id": sid,
+            "similarity": round(sim, 4),
+            "age_days": age_days,
+            "body_redacted": chunk.get("body_redacted", ""),
+            "chunk_index": chunk.get("chunk_index"),
+            "start_turn_index": chunk.get("start_turn_index"),
+            "end_turn_index": chunk.get("end_turn_index"),
+            "source": chunk.get("source", "local"),
+        }
+    )
+
+
+try:
+    names = sorted(os.listdir(sessions_dir))
+except OSError:
+    names = []
+
+for name in names:
+    if not name.endswith(".jsonl"):
+        continue
+    path = os.path.join(sessions_dir, name)
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    chunk = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                consider(chunk)
+    except OSError:
+        continue
+
+scored.sort(key=lambda c: c["similarity"], reverse=True)
+print(json.dumps(scored[:top_k]))
+PY
+}

package/plugins/historian/scripts/lib/historian-storage.sh

@@ -108,3 +108,50 @@ historian_storage_reset_session() {
 	[[ -f "$path" ]] || return 0
 	: > "$path"
 }
+
+# ============================================================================
+# Retrieval watermarks (per-session, scoped to the project key)
+# ============================================================================
+
+# Path used to hold the per-session retrieval state (count + last_ms) so
+# the rate gate persists across UserPromptSubmit invocations within a
+# single session. We key on (project, session) so cross-session retrieval
+# limits don't leak. The state file uses `last_ms` — an epoch-millisecond
+# timestamp of the last retrieval the rate gate let through — and the
+# cooldown gate compares (now_ms - last_ms) against cooldown_seconds.
+historian_retrieval_state_path() {
+	local key="$1"
+	local session_id="$2"
+	local safe
+	safe=$(printf '%s' "$session_id" | tr -cd '[:alnum:]._-')
+	[[ -z "$safe" ]] && safe="unknown"
+	printf '%s/retrieval-state/%s.json' "$(historian_project_dir "$key")" "$safe"
+}
+
+# Read the JSON document at the watermark path. Returns {"count":0,
+# "last_ms":0} when the file is absent or unreadable.
+historian_retrieval_state_read() {
+	local key="$1"
+	local session_id="$2"
+	local path
+	path=$(historian_retrieval_state_path "$key" "$session_id")
+	if [[ -f "$path" ]]; then
+		jq -c '. // {count:0, last_ms:0}' "$path" 2>/dev/null \
+			|| printf '%s' '{"count":0,"last_ms":0}'
+	else
+		printf '%s' '{"count":0,"last_ms":0}'
+	fi
+}
+
+# Bump the count and update last_ms.
+historian_retrieval_state_write() {
+	local key="$1"
+	local session_id="$2"
+	local count="$3"
+	local last_ms="$4"
+	local path
+	path=$(historian_retrieval_state_path "$key" "$session_id")
+	mkdir -p "$(dirname "$path")" 2>/dev/null
+	jq -cn --argjson count "$count" --argjson last_ms "$last_ms" \
+		'{ count: $count, last_ms: $last_ms }' > "$path" 2>/dev/null
+}

package/scripts/hooks/memory-recall-tracker.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# Onlooker Memory Recall Tracker
+# Invoked by SessionStart (matcher: *) when a session boots, resumes, or
+# restarts after compaction. Emits one canonical `memory.recalled` event
+# per typed-memory file present at the project's per-checkout memory
+# store path. This approximates the substrate signal "these memories are
+# now in the model's context for the session about to begin".
+#
+# Curator's usage tracker (and any future plugin that reasons about how
+# often a memory is in scope) depends on this. The signal is coarse —
+# per-session-load rather than per-recall — but actionable in aggregate.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - No-ops when there is no project memory store, no git context, or
+#     when the source is `compact` (compaction is metadata-only; the
+#     same memories remain in scope, so re-emitting would double-count).
+
+set -uo pipefail # No -e: never block session startup
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/validate-path.sh
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+# shellcheck source=../lib/onlooker-schema.sh
+source "$SCRIPT_DIR/../lib/onlooker-schema.sh"
+
+# Standard hook health instrumentation. hook_register sets up the timer;
+# hook_set_context exports _HOOK_SESSION_ID + _HOOK_EVENT_NAME so failures
+# attach to the right session in ~/.onlooker/logs/hook-health.jsonl;
+# hook_success / hook_failure close the health record.
+hook_register "memory-recall-tracker" "Memory Recall Tracker" "Emits memory.recalled per typed memory file present at SessionStart"
+
+INPUT=$(cat 2>/dev/null || true)
+hook_set_context "$INPUT" "SessionStart"
+
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+SOURCE=$(printf '%s' "$INPUT" | jq -r '.source // "startup"' 2>/dev/null) || SOURCE="startup"
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+# Compaction reloads the session with the same memories still in scope.
+# Re-emitting on each compaction would inflate usage counts; skip.
+if [[ "$SOURCE" == "compact" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve project_key. Mirrors the SHA256-of-remote-URL + common-dir
+# fallback every memory plugin uses (see plugins/librarian/scripts/lib/
+# librarian-project-key.sh and friends): if there's no origin remote,
+# anchor the key on git --git-common-dir rather than --show-toplevel so
+# two worktrees of the same local-only repo share a key.
+# ---------------------------------------------------------------------------
+
+_memory_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
+}
+
+_memory_repo_root_via_common_dir() {
+	local cwd="$1"
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+	# git-common-dir may be relative; resolve relative to cwd.
+	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
+		# common_dir is typically the .git dir of the main repo; its
+		# parent is the canonical repo root (shared across worktrees).
+		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"
+}
+
+PROJECT_KEY=""
+if git -C "$CWD" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+	REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null || true)
+	if [[ -n "$REMOTE" ]]; then
+		PROJECT_KEY=$(_memory_sha256_first12 "remote:${REMOTE}")
+	else
+		ROOT=$(_memory_repo_root_via_common_dir "$CWD")
+		if [[ -n "$ROOT" ]]; then
+			PROJECT_KEY=$(_memory_sha256_first12 "root:${ROOT}")
+		fi
+	fi
+fi
+
+if [[ -z "$PROJECT_KEY" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve the per-project typed-memory store at
+# ~/.claude/projects/<encoded>/memory/. Claude Code encodes the project
+# path by replacing path separators with `-` and prepending a leading `-`.
+# Prefer $CLAUDE_PROJECT_ENCODED when the harness has populated it; fall
+# back to deriving from CWD.
+# ---------------------------------------------------------------------------
+
+ENCODED="${CLAUDE_PROJECT_ENCODED:-}"
+if [[ -z "$ENCODED" ]]; then
+	# Encode the absolute cwd: drop leading slash, swap remaining `/` for
+	# `-`, prepend the leading `-`.
+	ABS_CWD=$(cd "$CWD" 2>/dev/null && pwd -P) || ABS_CWD=""
+	if [[ -n "$ABS_CWD" ]]; then
+		ENCODED=$(printf '%s' "$ABS_CWD" | sed -E 's#/#-#g')
+	fi
+fi
+
+MEMORY_DIR="${CLAUDE_HOME}/projects/${ENCODED}/memory"
+if [[ -z "$ENCODED" || ! -d "$MEMORY_DIR" ]]; then
+	hook_success
+	exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Walk every *.md file (excluding MEMORY.md itself, which is the index, not
+# a memory). For each, parse the YAML frontmatter's `type` field. Skip
+# files whose type isn't one of the four valid enum values — emitting
+# anything else would fail schema validation and the event would be
+# silently dropped.
+# ---------------------------------------------------------------------------
+
+_extract_type() {
+	local path="$1"
+	[[ -f "$path" ]] || return 0
+	# Parse frontmatter type via awk + sed (no python dep, no yq dep).
+	awk '
+		NR == 1 && /^---/ { in_fm = 1; next }
+		in_fm && /^---/ { exit }
+		in_fm
+	' "$path" 2>/dev/null \
+		| sed -nE 's/^type:[[:space:]]*(.*)$/\1/p' \
+		| head -1 \
+		| tr -d '"' \
+		| tr -d "'"
+}
+
+position=0
+for file in "$MEMORY_DIR"/*.md; do
+	[[ -f "$file" ]] || continue
+	fname=$(basename "$file")
+	[[ "$fname" == "MEMORY.md" ]] && continue
+
+	memory_type=$(_extract_type "$file")
+	case "$memory_type" in
+		user|feedback|project|reference)
+			;;
+		*)
+			# Untyped or unknown-typed memories don't fit the schema's
+			# enum. Skip silently rather than tank schema validation.
+			continue
+			;;
+	esac
+
+	payload=$(jq -cn \
+		--arg project_key "$PROJECT_KEY" \
+		--arg memory_file "$fname" \
+		--arg memory_type "$memory_type" \
+		--argjson recall_position "$position" \
+		'{
+			project_key: $project_key,
+			memory_file: $memory_file,
+			memory_type: $memory_type,
+			recall_position: $recall_position
+		}')
+
+	# Use the canonical ecosystem plugin name (matches the
+	# `${ONLOOKER_PLUGIN_NAME:-onlooker}` default that scripts/lib/
+	# onlooker-emit.sh and onlooker-event.mjs both fall back to). Other
+	# substrate-level emissions land under "onlooker" too, so this stays
+	# consistent with the existing event stream.
+	local_plugin="${ONLOOKER_PLUGIN_NAME:-onlooker}"
+
+	params=$(jq -cn \
+		--arg plugin "$local_plugin" \
+		--arg sid "$SESSION_ID" \
+		--arg type "memory.recalled" \
+		--argjson payload "$payload" \
+		'{ plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload }')
+
+	event_json=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="$ONLOOKER_DIR" ONLOOKER_PLUGIN_NAME="$local_plugin" \
+		  node "$_ONLOOKER_EVENT_JS" emit 2>/dev/null) || event_json=""
+	[[ -z "$event_json" ]] && continue
+
+	onlooker_append_event "$event_json" || true
+	position=$((position + 1))
+done
+
+hook_success
+exit 0

package/test/bats/historian-prompt-submit.bats

@@ -0,0 +1,236 @@
+#!/usr/bin/env bats
+#
+# Exercises the historian UserPromptSubmit retrieval pipeline end-to-end
+# against a synthetic ollama daemon (a fake `curl` binary on PATH that
+# returns predictable embeddings keyed on sentinel substrings in the
+# prompt). Indexing happens via the real SessionEnd hook against the
+# same stub, so the test exercises both halves of the embedder
+# integration.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/historian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/historian-retrieval-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/historian-project-key.sh"
+  PROJECT_KEY=$(historian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  HIST_DIR="${ONLOOKER_DIR}/historian/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/curl" <<'STUB'
+#!/usr/bin/env bash
+# Mini curl stub for historian bats tests.
+# Parses just enough of the curl arg shape to find the URL and the -d
+# payload. Returns deterministic embeddings keyed on sentinel substrings
+# in the prompt.
+url=""
+payload=""
+prev=""
+for arg in "$@"; do
+  case "$prev" in
+    -d|--data|--data-raw)
+      payload="$arg"; prev=""; continue ;;
+    --max-time|-o|-H|--header)
+      prev=""; continue ;;
+  esac
+  case "$arg" in
+    -d|--data|--data-raw|--max-time|-o|-H|--header)
+      prev="$arg" ;;
+    -*)
+      ;;
+    *)
+      [[ -z "$url" ]] && url="$arg" ;;
+  esac
+done
+
+# An env var toggles the probe success so the same stub serves the
+# "embedder unavailable" test case.
+if [[ "${HISTORIAN_STUB_OLLAMA_AVAILABLE:-1}" == "0" ]]; then
+  exit 7
+fi
+
+if [[ "$url" == */api/tags ]]; then
+  exit 0
+fi
+
+if [[ "$url" == */api/embeddings ]]; then
+  prompt=$(printf '%s' "$payload" | jq -r '.prompt // ""' 2>/dev/null)
+  case "$prompt" in
+    *redash*) printf '{"embedding":[1,0,0]}' ;;
+    *kafka*)  printf '{"embedding":[0,1,0]}' ;;
+    *postgres*) printf '{"embedding":[0,0,1]}' ;;
+    *) printf '{"embedding":[0.5,0.5,0.5]}' ;;
+  esac
+  exit 0
+fi
+
+exit 1
+STUB
+  chmod +x "${STUB_BIN}/curl"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  TRANSCRIPT="${BATS_TEST_TMPDIR}/transcript.jsonl"
+  SESSION_ID="sess-retrieval"
+
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' \
+    '{"historian":{"enabled":true,"indexing":{"min_transcript_chars_to_index":50,"chunk_target_chars":400,"chunk_overlap_chars":50},"retrieval":{"cooldown_seconds":60,"max_retrievals_per_session":5,"min_prompt_chars":40,"min_similarity":0.55,"max_age_days":365}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+
+  INDEX_HOOK="${PLUGIN_ROOT}/scripts/hooks/historian-session-end.sh"
+  RETRIEVE_HOOK="${PLUGIN_ROOT}/scripts/hooks/historian-prompt-submit.sh"
+}
+
+_index_input() {
+  local sid="${1:-$SESSION_ID}"
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "$sid" --arg transcript "$TRANSCRIPT" \
+    '{cwd:$cwd, session_id:$sid, transcript_path:$transcript, hook_event_name:"SessionEnd"}'
+}
+
+_retrieve_input() {
+  local prompt="$1" sid="${2:-current}"
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "$sid" --arg prompt "$prompt" \
+    '{cwd:$cwd, session_id:$sid, prompt:$prompt, hook_event_name:"UserPromptSubmit"}'
+}
+
+_append_text_turn() {
+  local role="$1" text="$2"
+  jq -cn --arg role "$role" --arg text "$text" \
+    '{role:$role, content:$text}' >> "$TRANSCRIPT"
+}
+
+_index_session() {
+  local sid="$1"
+  shift
+  : > "$TRANSCRIPT"
+  while [ $# -gt 0 ]; do
+    _append_text_turn "user" "$1"; shift
+    [ $# -gt 0 ] && { _append_text_turn "assistant" "$1"; shift; }
+  done
+  bash -c "printf '%s' '$(_index_input "$sid")' | '$INDEX_HOOK'" >/dev/null
+}
+
+@test "retrieval no-op when historian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  run bash -c "printf '%s' '$(_retrieve_input "a prompt long enough to clear the floor and trigger retrieval but historian is off")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q '"historian.retrieval' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "retrieval skipped when prompt is shorter than min_prompt_chars" {
+  run bash -c "printf '%s' '$(_retrieve_input "tiny")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "short_prompt"' >/dev/null
+}
+
+@test "indexing embeds chunks when ollama is up" {
+  _index_session "$SESSION_ID" \
+    "We are debugging a redash dashboard problem with timezone offsets and saved query parameters this morning." \
+    "Sure — the latest version always passes UTC because of a chart migration we did last week."
+
+  local jsonl="${HIST_DIR}/sessions/${SESSION_ID}.jsonl"
+  [ -f "$jsonl" ]
+  jq -e '.embedding | type == "array" and length == 3' "$jsonl" >/dev/null
+}
+
+@test "retrieval surfaces a matching past chunk" {
+  # Index a past session containing a "redash" topic.
+  _index_session "past-1" \
+    "We are debugging a redash dashboard problem with timezone offsets and saved query parameters this morning." \
+    "Sure — the latest version always passes UTC because of a chart migration we did last week."
+
+  # New session, same project, query about redash → should match.
+  run bash -c "printf '%s' '$(_retrieve_input "Hitting another redash dashboard timezone issue on the same saved query parameters again today")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Historian: a past chunk looks similar"* ]]
+  [[ "$ctx" == *"redash"* ]]
+
+  grep '"event_type":"historian.retrieval.surfaced"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.similarity >= 0.55 and .payload.source_session_id == "past-1"' >/dev/null
+}
+
+@test "retrieval returns empty when no chunk clears the similarity floor" {
+  # Past session about kafka — query about postgres falls below the
+  # 0.55 floor (the embedding vectors are orthogonal in the stub).
+  _index_session "past-2" \
+    "Investigating kafka consumer lag on the ingest pipeline today after the rebalance event yesterday." \
+    "Looks like the rebalance left a stale offset; manual reset cleared it."
+
+  run bash -c "printf '%s' '$(_retrieve_input "Working on a postgres migration plan today for our settings tables to add new columns safely")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty"' >/dev/null
+}
+
+@test "retrieval skipped on cooldown" {
+  _index_session "past-3" \
+    "Yet another redash dashboard query that we had to fix the timezone on this morning to make the report run again." \
+    "ok"
+
+  # First retrieval surfaces something.
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem again on the saved query parameters this morning afternoon")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  grep -q '"event_type":"historian.retrieval.surfaced"' "$ONLOOKER_EVENTS_LOG"
+
+  rm -f "$ONLOOKER_EVENTS_LOG"
+
+  # Immediate second retrieval (same session) hits the cooldown gate
+  # (60s) and gets skipped without calling the embedder.
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem follow-up just a moment after the previous prompt cleared")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "cooldown"' >/dev/null
+}
+
+@test "retrieval skipped when the embedder is unreachable" {
+  _index_session "past-4" \
+    "Yet another redash dashboard query that we had to fix the timezone on this morning to make the report run again." \
+    "ok"
+
+  # Turn off the stub so the probe fails.
+  HISTORIAN_STUB_OLLAMA_AVAILABLE=0 \
+    run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone problem long enough to clear the prompt floor for retrieval")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+
+  grep -q '"event_type":"historian.embedder.unavailable"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "embedder_unavailable"' >/dev/null
+}
+
+@test "retrieval excludes chunks from the current session id" {
+  # Index the same session id we'll then query from — should be excluded.
+  _index_session "current" \
+    "Working on a redash dashboard right now in this very session of the test framework that we are running." \
+    "ok"
+
+  run bash -c "printf '%s' '$(_retrieve_input "redash dashboard timezone trouble inside this very session of the test framework")' | '$RETRIEVE_HOOK'"
+  [ "$status" -eq 0 ]
+
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  grep '"event_type":"historian.retrieval.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty"' >/dev/null
+}