@onlooker-community/ecosystem 0.19.0 → 0.21.0

package/test/bats/curator-session-start.bats

@@ -0,0 +1,316 @@
+#!/usr/bin/env bats
+#
+# Exercises the curator SessionStart hook end-to-end against a synthetic
+# typed memory store. Verifies the four cheap-tier finding kinds, dedup
+# on repeated scans, and the SessionStart surfacer's pointer rendering.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/curator"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO/scripts"
+  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/curator-test.git
+
+  # Seed a real file that the path-broken check should NOT flag.
+  printf 'live\n' > "${PROJECT_REPO}/scripts/live.py"
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/curator-project-key.sh"
+  PROJECT_KEY=$(curator_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  CURATOR_DIR="${ONLOOKER_DIR}/curator/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  # Memory store at a predictable path. Bypass the ${CLAUDE_PROJECT_ENCODED}
+  # template by overriding memory_store_path to an absolute path in the
+  # project settings file.
+  MEM_DIR="${TEST_HOME}/.claude/projects/test-project/memory"
+  mkdir -p "$MEM_DIR" "${PROJECT_REPO}/.claude"
+  jq -n --arg path "$MEM_DIR" \
+    '{
+      curator: {
+        enabled: true,
+        memory_store_path: $path,
+        date_check: { date_grace_period_days: 7 }
+      }
+    }' > "${PROJECT_REPO}/.claude/settings.json"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/curator-session-start.sh"
+}
+
+_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "sess-curator-test" \
+    '{cwd: $cwd, source: "startup", session_id: $sid}'
+}
+
+_seed_memory() {
+  local name="$1" type="$2" body="$3"
+  local file="${MEM_DIR}/${name}"
+  printf -- '---\nname: %s\ndescription: test\ntype: %s\n---\n\n%s\n' \
+    "$name" "$type" "$body" > "$file"
+}
+
+_write_index() {
+  local entries="$1"   # newline-separated `- [Title](file.md) — hook` lines
+  printf '%b\n' "$entries" > "${MEM_DIR}/MEMORY.md"
+}
+
+@test "session-start no-ops when curator is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  _seed_memory "feedback_stale.md" "feedback" "Decayed 2025-01-01 reference."
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q 'curator' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "session-start emits scan events with empty memory store" {
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+
+  grep -q '"event_type":"curator.scan.started"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"curator.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.findings_new == 0 and .payload.outcome == "ok"' >/dev/null
+}
+
+@test "session-start flags a date past the grace period" {
+  _seed_memory "project_freeze.md" "project" \
+    "Merge freeze begins 2026-03-05 for mobile release cut."
+  _write_index '- [Freeze](project_freeze.md) — merge freeze date'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  grep '"event_type":"curator.finding.date_decayed"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.memory_file == "project_freeze.md" and
+             .payload.matched_phrase == "2026-03-05" and
+             .payload.days_past > 7' >/dev/null
+
+  # Finding persisted on disk.
+  ls "${CURATOR_DIR}/findings"/*.json | grep -q '\.json$'
+
+  # Surfacer rendered the pointer.
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Curator: 1 open finding"* ]]
+  [[ "$ctx" == *"date-decayed"* ]]
+  [[ "$ctx" == *"/curator review"* ]]
+}
+
+@test "session-start flags a broken path reference" {
+  _seed_memory "reference_legacy.md" "reference" \
+    "See scripts/legacy_ingest.py for the old pipeline shape."
+  _write_index '- [Legacy](reference_legacy.md) — old pipeline'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  grep '"event_type":"curator.finding.path_broken"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.memory_file == "reference_legacy.md" and
+             .payload.broken_path == "scripts/legacy_ingest.py"' >/dev/null
+
+  # Live file (scripts/live.py) does NOT produce a finding.
+  ! grep '"event_type":"curator.finding.path_broken"' "$ONLOOKER_EVENTS_LOG" \
+    | grep -q 'live.py' || false
+}
+
+@test "session-start flags MEMORY.md pointing at a missing file" {
+  _write_index '- [Ghost](feedback_ghost.md) — never existed'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  grep '"event_type":"curator.finding.broken_index"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.referenced_file == "feedback_ghost.md"' >/dev/null
+}
+
+@test "session-start flags orphaned memory file" {
+  # File on disk, no MEMORY.md reference.
+  _seed_memory "user_orphan.md" "user" "Some orphaned context."
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  grep '"event_type":"curator.finding.orphaned_memory"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.memory_file == "user_orphan.md"' >/dev/null
+}
+
+@test "session-start dedupes findings on repeated scans" {
+  _seed_memory "project_freeze.md" "project" "Date 2025-01-01 in the past."
+  _write_index '- [Freeze](project_freeze.md) — old date'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local first_count
+  first_count=$(ls "${CURATOR_DIR}/findings"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  [ "$first_count" -ge 1 ]
+
+  # Second scan — the same finding should not produce a new file.
+  rm -f "$ONLOOKER_EVENTS_LOG"
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local second_count
+  second_count=$(ls "${CURATOR_DIR}/findings"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  [ "$second_count" -eq "$first_count" ]
+
+  # scan.complete reports findings_new == 0 on the dedup'd pass.
+  grep '"event_type":"curator.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.findings_new == 0' >/dev/null
+}
+
+@test "surfacer pluralizes finding count" {
+  _seed_memory "project_a.md" "project" "Date 2025-01-01"
+  _seed_memory "project_b.md" "project" "Date 2024-06-30"
+  _write_index "$(printf '%s\n%s' \
+    '- [A](project_a.md) — a' \
+    '- [B](project_b.md) — b')"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"2 open findings"* ]]
+}
+
+@test "MEMORY.md path-traversal entries are recorded as broken_index, never read" {
+  # Seed a sentinel file outside the memory dir that the parser must
+  # NEVER touch. The escape attempt below points at a path that would
+  # resolve to this file if filename sanitization were missing.
+  local outside_dir="${TEST_HOME}/.claude/projects"
+  local sentinel="${outside_dir}/sentinel.txt"
+  printf 'untouched\n' > "$sentinel"
+
+  # Linux's stat uses `-c FORMAT` and ignores `-f`; macOS uses `-f FORMAT`
+  # and does not accept `-c`. Try Linux first (CI runs on Ubuntu); fall
+  # back to BSD/macOS form for local runs.
+  _file_mtime() {
+    stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null
+  }
+  local sentinel_mtime_before
+  sentinel_mtime_before=$(_file_mtime "$sentinel")
+  [ -n "$sentinel_mtime_before" ]
+
+  # MEMORY.md tries to escape with `../sentinel.txt` and an absolute path.
+  _write_index "$(printf '%s\n%s\n%s' \
+    '- [Escape](../sentinel.txt) — traversal attempt' \
+    '- [Abs](/tmp/curator-abs-attempt.md) — absolute path attempt' \
+    '- [Normal](real.md) — clean reference')"
+  _seed_memory "real.md" "project" "Normal body."
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # Both unsafe entries surface as broken_index findings.
+  grep '"event_type":"curator.finding.broken_index"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.referenced_file == "../sentinel.txt")' >/dev/null
+  grep '"event_type":"curator.finding.broken_index"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.referenced_file == "/tmp/curator-abs-attempt.md")' >/dev/null
+
+  # The clean reference resolves as expected (no broken_index for it).
+  ! grep '"event_type":"curator.finding.broken_index"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.referenced_file == "real.md")' >/dev/null
+
+  # The sentinel file wasn't read (mtime unchanged) and content intact.
+  local sentinel_mtime_after
+  sentinel_mtime_after=$(_file_mtime "$sentinel")
+  [ "$sentinel_mtime_before" = "$sentinel_mtime_after" ]
+  grep -q 'untouched' "$sentinel"
+}
+
+@test "path_broken does not fire on URLs or absolute paths in memory bodies" {
+  _seed_memory "reference_urls.md" "reference" "$(cat <<'BODY'
+See https://example.com/foo.py for upstream context.
+Also /usr/bin/python3.11 is the system python on macOS.
+But scripts/legacy_ingest.py is the broken in-repo path.
+BODY
+)"
+  _write_index '- [Refs](reference_urls.md) — mixed refs'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # The in-repo broken path still fires.
+  grep '"event_type":"curator.finding.path_broken"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.broken_path == "scripts/legacy_ingest.py")' >/dev/null
+
+  # Neither the URL host nor the absolute path produce a finding.
+  ! grep '"event_type":"curator.finding.path_broken"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.broken_path | contains("example.com"))' >/dev/null
+  ! grep '"event_type":"curator.finding.path_broken"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.broken_path | contains("python3.11"))' >/dev/null
+}
+
+@test "surfacer counts multiple same-kind findings correctly" {
+  # Two date_decayed findings: with the group_by-without-sort bug, the
+  # summary would render as "1 date-decayed, 1 date-decayed" because
+  # ULID-ordered findings can interleave kinds. The sort_by(.kind) fix
+  # makes the summary aggregate correctly to "2 date-decayed".
+  _seed_memory "project_a.md" "project" "Stale date 2025-01-01"
+  _seed_memory "project_b.md" "project" "Older date 2024-06-30"
+  _write_index "$(printf '%s\n%s' \
+    '- [A](project_a.md) — a' \
+    '- [B](project_b.md) — b')"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"2 date-decayed"* ]]
+  # The buggy output would have looked like "1 date-decayed, 1 date-decayed".
+  [[ "$ctx" != *"1 date-decayed, 1 date-decayed"* ]]
+}
+
+@test "cheap_checks.enabled=false skips the scan and emits skip_reason disabled" {
+  printf '%s\n' \
+    '{"curator":{"enabled":true,"memory_store_path":"'"$MEM_DIR"'","cheap_checks":{"enabled":false}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+
+  _seed_memory "project_stale.md" "project" "Decayed 2025-01-01"
+  _write_index '- [S](project_stale.md) — s'
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # scan.complete uses skip_reason: disabled.
+  grep '"event_type":"curator.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "skipped" and .payload.skip_reason == "disabled"' >/dev/null
+
+  # No findings were written, even though the date would have matched.
+  [ ! -d "${CURATOR_DIR}/findings" ] || [ -z "$(ls -A "${CURATOR_DIR}/findings" 2>/dev/null)" ]
+
+  # No per-finding events emitted.
+  ! grep -q '"event_type":"curator.finding.date_decayed"' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "surfacer truncates context past max_pointer_chars" {
+  printf '%s\n' \
+    '{"curator":{"enabled":true,"memory_store_path":"'"$MEM_DIR"'","surfacer":{"max_pointer_chars":40}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+
+  _seed_memory "project_a.md" "project" "Date 2025-01-01"
+  _seed_memory "project_b.md" "project" "Date 2024-06-30"
+  _write_index "$(printf '%s\n%s' \
+    '- [A](project_a.md) — a' \
+    '- [B](project_b.md) — b')"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx ctx_len
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  # Grapheme-aware length so the trailing "…" doesn't confuse a
+  # byte-counting bash check.
+  ctx_len=$(python3 -c 'import sys; print(len(sys.argv[1]))' "$ctx")
+  [ "$ctx_len" -le 40 ]
+  [[ "$ctx" == *"…"* ]]
+}

package/test/bats/librarian-session-end.bats

@@ -0,0 +1,182 @@
+#!/usr/bin/env bats
+#
+# Exercises the librarian SessionEnd scan pipeline end-to-end with a stub
+# `claude` CLI. Verifies:
+#   - Disabled config: no proposals, no events.
+#   - Empty archivist dir: scan.started + scan.complete{outcome: empty}
+#     emitted, watermark advances.
+#   - Synthetic artifacts that pass durability filter and classifier:
+#     proposals land on disk with the expected provenance and scan events
+#     report the correct counts.
+#   - Durability-filtered artifacts (no marker phrase) emit
+#     candidate.dropped events.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  # Stand up a fake project repo so project-key resolution succeeds.
+  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/librarian-scan-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  ARCHIVIST_DIR="${ONLOOKER_DIR}/archivist/${PROJECT_KEY}"
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  # Project-scoped settings.json that enables librarian.
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  # Stub `claude` CLI on PATH. Returns a deterministic classifier response
+  # based on the artifact's summary contents.
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+# Read the prompt from stdin and decide which classifier response to emit.
+prompt=$(cat)
+if [[ "$prompt" == *"prefer-functional-stub"* ]]; then
+  printf '%s' '{"type":"feedback","title":"Prefer functional patterns","body":"User prefers functional patterns over class-based.\n\n**Why:** Stated explicitly during code review.\n**How to apply:** Default to plain functions and composition.","confidence":0.84}'
+elif [[ "$prompt" == *"compliance-stub"* ]]; then
+  printf '%s' '{"type":"project","title":"Auth rewrite is compliance driven","body":"Auth middleware rewrite is driven by legal/compliance requirements around session token storage.\n\n**Why:** Compliance ask, not tech debt cleanup.\n**How to apply:** Favor compliance posture over ergonomics when scoping.","confidence":0.91}'
+elif [[ "$prompt" == *"low-conf-stub"* ]]; then
+  printf '%s' '{"type":"user","title":"User edits","body":"User edits files.","confidence":0.4}'
+else
+  printf '%s' '{"type":null,"title":"","body":"","confidence":0.2}'
+fi
+STUB
+  chmod +x "${STUB_BIN}/claude"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-end.sh"
+}
+
+# Helper: write an archivist artifact for the project.
+_seed_artifact() {
+  local kind="$1" id="$2" summary="$3" detail="$4" created_at="${5:-2026-06-01T12:00:00Z}"
+  local dir="${ARCHIVIST_DIR}/${kind}"
+  mkdir -p "$dir"
+  jq -n \
+    --arg id "$id" --arg kind "${kind%s}" \
+    --arg project_key "$PROJECT_KEY" \
+    --arg summary "$summary" --arg detail "$detail" \
+    --arg created_at "$created_at" --arg session_id "sess-1" \
+    '{ id: $id, kind: $kind, project_key: $project_key, source: "local",
+       created_at: $created_at, updated_at: $created_at,
+       summary: $summary, detail: $detail, files: [], session_id: $session_id }' \
+    > "${dir}/${id}.json"
+}
+
+_hook_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "sess-end-test" \
+    '{cwd: $cwd, session_id: $sid, hook_event_name: "SessionEnd"}'
+}
+
+@test "session-end is a no-op when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  # No proposals written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+  # No events emitted.
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q 'librarian' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "session-end emits empty scan when archivist has nothing" {
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # scan.started fired with artifact_count_in_window = 0.
+  grep -q '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 0' >/dev/null
+
+  # scan.complete fired with outcome=empty and zero counts.
+  grep -q '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped == 0' >/dev/null
+
+  # Watermark advanced for next scan.
+  [ -f "${LIBRARIAN_DIR}/last_scan.json" ]
+  jq -e '.scanned_at | test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T")' "${LIBRARIAN_DIR}/last_scan.json" >/dev/null
+}
+
+@test "session-end proposes promotion for marker-phrase + classifier success" {
+  # Seed two promotable artifacts and one filter-rejected one.
+  _seed_artifact "decisions" "01PROPOSEEFEEDBACK00000000" \
+    "User prefers functional patterns prefer-functional-stub" \
+    "User explicitly said: always prefer plain functions over classes when adding new code in the api layer."
+
+  _seed_artifact "decisions" "01PROPOSEEPROJECT000000000" \
+    "Compliance-driven auth rewrite compliance-stub" \
+    "The reason for the auth middleware rewrite is legal compliance, not tech debt; remember this when sizing scope."
+
+  _seed_artifact "open_questions" "01FILTERREJECTED000000000" \
+    "ad hoc question" \
+    "this short text contains no marker phrase and should be filtered out before the classifier runs"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # Two proposals on disk.
+  proposals=("${LIBRARIAN_DIR}/proposals"/*.json)
+  [ "${#proposals[@]}" -eq 2 ]
+
+  # Both carry provenance back to their source artifact.
+  for p in "${proposals[@]}"; do
+    jq -e '.status == "pending" and .conflict_state == "none"' "$p" >/dev/null
+    jq -e '.proposed.type | IN("user", "feedback", "project", "reference")' "$p" >/dev/null
+    jq -e '.proposed.classifier_confidence >= 0.6' "$p" >/dev/null
+    jq -e '(.source_artifact_ids | length) > 0' "$p" >/dev/null
+  done
+
+  # scan.started reported the right window size (2 marker matches + 1 filtered = 3).
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 3' >/dev/null
+
+  # candidate.proposed fired twice with correct types.
+  proposed_types=$(grep '"event_type":"librarian.candidate.proposed"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -r '.payload.memory_type' | sort | paste -sd, -)
+  [ "$proposed_types" = "feedback,project" ]
+
+  # candidate.dropped fired for the marker-missing artifact.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "filter_marker_missing")' >/dev/null
+
+  # scan.complete with ok outcome and accurate counts.
+  scan_complete=$(grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG")
+  echo "$scan_complete" | jq -e '.payload.outcome == "ok" and .payload.candidates_proposed == 2 and .payload.candidates_dropped >= 1' >/dev/null
+}
+
+@test "session-end drops candidates below confidence floor" {
+  _seed_artifact "decisions" "01LOWCONFCANDIDATE0000000" \
+    "low-conf-stub trigger" \
+    "always prefer some thing because reasons that show a marker phrase but the stub returns low confidence"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # No proposal written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+
+  # candidate.dropped fired with low_confidence reason.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "low_confidence")' >/dev/null
+
+  # scan.complete reports empty outcome (zero proposals).
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped >= 1' >/dev/null
+}

package/test/bats/librarian-session-start.bats

@@ -0,0 +1,136 @@
+#!/usr/bin/env bats
+#
+# Tests the librarian SessionStart surfacer. Verifies:
+#   - Disabled config: empty additionalContext, exit 0.
+#   - No git context: empty additionalContext, exit 0.
+#   - Empty proposal queue + skip_inject_when_zero=true: empty context.
+#   - Pending proposals: one-line pointer with the count and pluralization.
+#   - Overflow: counts above max_pending_for_inject render as "<cap>+".
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  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/librarian-surfacer-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-start.sh"
+}
+
+_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" \
+    '{cwd: $cwd, source: "startup", session_id: "sess-start-test"}'
+}
+
+# Helper: drop a proposal file with the given status into the queue.
+_seed_proposal() {
+  local id="$1" status="${2:-pending}"
+  mkdir -p "${LIBRARIAN_DIR}/proposals"
+  jq -n --arg id "$id" --arg status "$status" \
+    '{
+      id: $id,
+      created_at: "2026-06-01T00:00:00Z",
+      source_artifact_ids: [],
+      source_session_ids: [],
+      proposed: { type: "feedback", filename: ($id + ".md"),
+                  title: "t", body: "b", classifier_confidence: 0.8 },
+      conflict_state: "none",
+      conflict_with: [],
+      status: $status
+    }' > "${LIBRARIAN_DIR}/proposals/${id}.json"
+}
+
+@test "surfacer emits empty context when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  _seed_proposal "01PROPOSALA000000000000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  echo "$output" | jq -e '.hookSpecificOutput.hookEventName == "SessionStart"' >/dev/null
+}
+
+@test "surfacer emits empty context when there is no git context" {
+  local non_git="${BATS_TEST_TMPDIR}/no-git"
+  mkdir -p "$non_git"
+  local input
+  input=$(jq -cn --arg cwd "$non_git" '{cwd: $cwd, source: "startup", session_id: "s"}')
+
+  run bash -c "printf '%s' '$input' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer emits empty context when no proposals are pending" {
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer surfaces one-line pointer when proposals exist (plural)" {
+  _seed_proposal "01PROPOSAL11111111111111A"
+  _seed_proposal "01PROPOSAL11111111111111B"
+  _seed_proposal "01PROPOSAL11111111111111C"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3 pending memory promotion proposals"* ]]
+  [[ "$ctx" == *"/librarian review"* ]]
+}
+
+@test "surfacer pluralizes singular vs plural correctly" {
+  _seed_proposal "01PROPOSALSINGULAR0000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 1 pending memory promotion proposal"* ]]
+  [[ "$ctx" != *"proposals."* ]]
+}
+
+@test "surfacer ignores accepted/rejected proposals when counting pending" {
+  _seed_proposal "01PROPOSALACCEPTED000000" "accepted"
+  _seed_proposal "01PROPOSALREJECTED000000" "rejected"
+  _seed_proposal "01PROPOSALPENDING0000000" "pending"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"1 pending memory promotion proposal"* ]]
+}
+
+@test "surfacer caps display at max_pending_for_inject + '+'" {
+  # Override max to 3 via a project settings overlay.
+  printf '%s\n' '{"librarian":{"enabled":true,"surfacer":{"max_pending_for_inject":3}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+  for i in A B C D E; do
+    _seed_proposal "01PROPOSALCAP$i$i$i$i$i$i$i$i$i$i$i$i"
+  done
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3+ pending memory promotion proposals"* ]]
+}