@onlooker-community/ecosystem 0.19.0 → 0.21.0

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

@@ -0,0 +1,312 @@
+#!/usr/bin/env bash
+# Librarian SessionEnd scan.
+#
+# Reads archivist artifacts created since the last librarian scan, runs them
+# through the durability filter, classifies survivors via Haiku, and writes
+# proposals to the queue for review at next SessionStart.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session shutdown.
+#   - No-ops when librarian.enabled is not true.
+#   - No-ops when no project key (no git context) or no archivist artifacts.
+#   - Classifier failures degrade gracefully: the affected candidate is
+#     dropped, the rest of the scan proceeds.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# Source the ecosystem substrate so $ONLOOKER_DIR / $ONLOOKER_EVENTS_LOG
+# resolve correctly under the test harness's isolated temp home.
+_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"
+fi
+
+# shellcheck source=../lib/librarian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-config.sh"
+# shellcheck source=../lib/librarian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+# shellcheck source=../lib/librarian-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-ulid.sh"
+# shellcheck source=../lib/librarian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-storage.sh"
+# shellcheck source=../lib/librarian-emit.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-emit.sh"
+# shellcheck source=../lib/librarian-archivist-reader.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-archivist-reader.sh"
+# shellcheck source=../lib/librarian-durability.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-durability.sh"
+# shellcheck source=../lib/librarian-classifier.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-classifier.sh"
+
+INPUT=$(cat 2>/dev/null || true)
+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=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+librarian_config_load "$(librarian_project_repo_root "$CWD")"
+librarian_config_enabled || exit 0
+
+PROJECT_KEY=$(librarian_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+# Storage init + manifest refresh.
+librarian_storage_init "$PROJECT_KEY" || exit 0
+REMOTE_URL=$(librarian_project_remote_url "$CWD")
+REPO_ROOT=$(librarian_project_repo_root "$CWD")
+librarian_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+# ----------------------------------------------------------------------------
+# Determine the watermark. Empty means "first scan" — fall back to N days ago.
+# ----------------------------------------------------------------------------
+
+WATERMARK=$(librarian_storage_read_last_scan "$PROJECT_KEY")
+
+if [[ -z "$WATERMARK" ]]; then
+	BOOTSTRAP_DAYS=$(librarian_config_get '.librarian.scan.bootstrap_lookback_days')
+	[[ -z "$BOOTSTRAP_DAYS" || "$BOOTSTRAP_DAYS" == "null" ]] && BOOTSTRAP_DAYS=14
+	WATERMARK=$(python3 -c "
+import datetime
+delta = datetime.timedelta(days=${BOOTSTRAP_DAYS})
+now = datetime.datetime.now(datetime.timezone.utc)
+print((now - delta).strftime('%Y-%m-%dT%H:%M:%SZ'))
+" 2>/dev/null) || WATERMARK=""
+fi
+
+# ----------------------------------------------------------------------------
+# Emit scan.started and load candidate window.
+# ----------------------------------------------------------------------------
+
+SCAN_START_TS_S=$(date +%s)
+ARTIFACTS=$(librarian_archivist_load_since "$PROJECT_KEY" "$WATERMARK")
+ARTIFACT_COUNT=$(printf '%s' "$ARTIFACTS" | jq 'length' 2>/dev/null) || ARTIFACT_COUNT=0
+
+librarian_emit "librarian.scan.started" "$SESSION_ID" "$(jq -cn \
+	--arg trigger "session_end" \
+	--arg last_scan_at "$WATERMARK" \
+	--argjson artifact_count_in_window "$ARTIFACT_COUNT" \
+	'{ trigger: $trigger, last_scan_at: (if $last_scan_at == "" then null else $last_scan_at end),
+	   artifact_count_in_window: $artifact_count_in_window } | with_entries(select(.value != null))')"
+
+# Bail with scan.complete{outcome: ok, candidates: 0} when archivist has
+# nothing new for us. We still advance the watermark so subsequent scans
+# don't re-walk the same window.
+if [[ "$ARTIFACT_COUNT" == "0" ]]; then
+	librarian_storage_write_last_scan "$PROJECT_KEY" || true
+	DURATION_MS=$(( ($(date +%s) - SCAN_START_TS_S) * 1000 ))
+	librarian_emit "librarian.scan.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "empty" \
+		--argjson duration_ms "$DURATION_MS" \
+		--argjson candidates_proposed 0 \
+		--argjson candidates_dropped 0 \
+		--argjson artifact_count_in_window 0 \
+		'{ outcome: $outcome, duration_ms: $duration_ms,
+		   candidates_proposed: $candidates_proposed,
+		   candidates_dropped: $candidates_dropped,
+		   artifact_count_in_window: $artifact_count_in_window }')"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Durability filter — cheap, deterministic, no network.
+# ----------------------------------------------------------------------------
+
+MARKERS_JSON=$(librarian_config_get '.librarian.durability_filter.marker_phrases | tojson')
+[[ -z "$MARKERS_JSON" || "$MARKERS_JSON" == "null" ]] && MARKERS_JSON='[]'
+MIN_DETAIL=$(librarian_config_get '.librarian.scan.min_detail_chars')
+[[ -z "$MIN_DETAIL" || "$MIN_DETAIL" == "null" ]] && MIN_DETAIL=40
+
+FILTERED=$(librarian_durability_filter "$ARTIFACTS" "$MARKERS_JSON" "$MIN_DETAIL")
+KEPT=$(printf '%s' "$FILTERED" | jq '.kept')
+DROPPED=$(printf '%s' "$FILTERED" | jq '.dropped')
+
+# Emit one librarian.candidate.dropped event per artifact we filtered out
+# pre-classifier. Caps at a sane number per scan so the event log stays
+# scannable even if archivist piled up months of artifacts.
+MAX_DROPPED_EVENTS=20
+DROPPED_TOTAL=$(printf '%s' "$DROPPED" | jq 'length' 2>/dev/null) || DROPPED_TOTAL=0
+DROPPED_EMIT_COUNT=$(( DROPPED_TOTAL < MAX_DROPPED_EVENTS ? DROPPED_TOTAL : MAX_DROPPED_EVENTS ))
+for ((i = 0; i < DROPPED_EMIT_COUNT; i++)); do
+	DROP=$(printf '%s' "$DROPPED" | jq -c ".[$i]")
+	librarian_emit "librarian.candidate.dropped" "$SESSION_ID" "$(jq -cn \
+		--argjson drop "$DROP" \
+		'{ reason: $drop.reason, source_artifact_id: $drop.artifact_id }
+		 | with_entries(select(.value != null))')"
+done
+
+# ----------------------------------------------------------------------------
+# Classifier loop — one Haiku call per surviving candidate.
+# ----------------------------------------------------------------------------
+
+CLASSIFIER_MODEL=$(librarian_config_get '.librarian.classifier.model')
+CLASSIFIER_TEMP=$(librarian_config_get '.librarian.classifier.temperature')
+CLASSIFIER_MAX=$(librarian_config_get '.librarian.classifier.max_output_tokens')
+MIN_CONFIDENCE=$(librarian_config_get '.librarian.classifier.min_classifier_confidence')
+[[ -z "$MIN_CONFIDENCE" || "$MIN_CONFIDENCE" == "null" ]] && MIN_CONFIDENCE="0.6"
+TOMBSTONE_TTL=$(librarian_config_get '.librarian.tombstones.ttl_days')
+[[ -z "$TOMBSTONE_TTL" || "$TOMBSTONE_TTL" == "null" ]] && TOMBSTONE_TTL=180
+AUTO_PROMOTE_THRESHOLD=$(librarian_config_get '.librarian.auto_promote_threshold')
+[[ -z "$AUTO_PROMOTE_THRESHOLD" || "$AUTO_PROMOTE_THRESHOLD" == "null" ]] && AUTO_PROMOTE_THRESHOLD="0.85"
+
+KEPT_COUNT=$(printf '%s' "$KEPT" | jq 'length' 2>/dev/null) || KEPT_COUNT=0
+PROPOSED_COUNT=0
+POST_CLASSIFIER_DROPPED=0
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+for ((i = 0; i < KEPT_COUNT; i++)); do
+	ARTIFACT=$(printf '%s' "$KEPT" | jq -c ".[$i]")
+	[[ -z "$ARTIFACT" || "$ARTIFACT" == "null" ]] && continue
+
+	RESPONSE=$(librarian_classifier_call \
+		"$ARTIFACT" "$CLASSIFIER_MODEL" "$CLASSIFIER_TEMP" "$CLASSIFIER_MAX")
+
+	if [[ -z "$RESPONSE" ]]; then
+		POST_CLASSIFIER_DROPPED=$((POST_CLASSIFIER_DROPPED + 1))
+		librarian_emit "librarian.candidate.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "classified_null" \
+			--arg src "$(printf '%s' "$ARTIFACT" | jq -r '.id // ""')" \
+			'{ reason: $reason, source_artifact_id: (if $src == "" then null else $src end) }
+			 | with_entries(select(.value != null))')"
+		continue
+	fi
+
+	# Drop nulls and low-confidence classifications silently — by design,
+	# the proposal queue prefers misses over noise.
+	MEMORY_TYPE=$(printf '%s' "$RESPONSE" | jq -r '.type // ""')
+	CONFIDENCE=$(printf '%s' "$RESPONSE" | jq -r '.confidence // 0')
+	BODY=$(printf '%s' "$RESPONSE" | jq -r '.body // ""')
+	TITLE=$(printf '%s' "$RESPONSE" | jq -r '.title // ""')
+
+	BELOW_MIN=$(awk -v a="$CONFIDENCE" -v b="$MIN_CONFIDENCE" 'BEGIN { print (a < b) ? 1 : 0 }')
+
+	if [[ -z "$MEMORY_TYPE" || "$MEMORY_TYPE" == "null" ]]; then
+		POST_CLASSIFIER_DROPPED=$((POST_CLASSIFIER_DROPPED + 1))
+		librarian_emit "librarian.candidate.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "classified_null" \
+			--arg src "$(printf '%s' "$ARTIFACT" | jq -r '.id // ""')" \
+			'{ reason: $reason, source_artifact_id: (if $src == "" then null else $src end) }
+			 | with_entries(select(.value != null))')"
+		continue
+	fi
+
+	if [[ "$BELOW_MIN" == "1" ]]; then
+		POST_CLASSIFIER_DROPPED=$((POST_CLASSIFIER_DROPPED + 1))
+		librarian_emit "librarian.candidate.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "low_confidence" \
+			--arg src "$(printf '%s' "$ARTIFACT" | jq -r '.id // ""')" \
+			'{ reason: $reason, source_artifact_id: (if $src == "" then null else $src end) }
+			 | with_entries(select(.value != null))')"
+		continue
+	fi
+
+	# Skip if a tombstone exists for this exact body — the user already
+	# rejected this content, don't re-surface it.
+	BODY_HASH=$(librarian_body_hash "$BODY")
+	if [[ -n "$BODY_HASH" ]] && librarian_storage_has_tombstone \
+			"$PROJECT_KEY" "$BODY_HASH" "$TOMBSTONE_TTL"; then
+		POST_CLASSIFIER_DROPPED=$((POST_CLASSIFIER_DROPPED + 1))
+		librarian_emit "librarian.candidate.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "duplicate" \
+			--arg src "$(printf '%s' "$ARTIFACT" | jq -r '.id // ""')" \
+			'{ reason: $reason, source_artifact_id: (if $src == "" then null else $src end) }
+			 | with_entries(select(.value != null))')"
+		continue
+	fi
+
+	# Build and persist the proposal. Conflict detection against the user's
+	# memory store is deferred to a follow-up commit; everything ships as
+	# conflict_state: "none" for now.
+	PROPOSAL_ID=$(librarian_ulid)
+	FILENAME=$(librarian_classifier_filename "$MEMORY_TYPE" "$TITLE")
+	ARTIFACT_ID=$(printf '%s' "$ARTIFACT" | jq -r '.id // ""')
+	ARTIFACT_SESSION=$(printf '%s' "$ARTIFACT" | jq -r '.session_id // ""')
+
+	PROPOSAL_JSON=$(jq -n \
+		--arg id "$PROPOSAL_ID" \
+		--arg created_at "$NOW_TS" \
+		--arg memory_type "$MEMORY_TYPE" \
+		--arg filename "$FILENAME" \
+		--arg title "$TITLE" \
+		--arg body "$BODY" \
+		--argjson classifier_confidence "$CONFIDENCE" \
+		--arg conflict_state "none" \
+		--arg artifact_id "$ARTIFACT_ID" \
+		--arg artifact_session "$ARTIFACT_SESSION" \
+		'{
+			id: $id,
+			created_at: $created_at,
+			source_artifact_ids: (if $artifact_id == "" then [] else [$artifact_id] end),
+			source_session_ids: (if $artifact_session == "" then [] else [$artifact_session] end),
+			proposed: {
+				type: $memory_type,
+				filename: $filename,
+				title: $title,
+				body: $body,
+				classifier_confidence: $classifier_confidence
+			},
+			conflict_state: $conflict_state,
+			conflict_with: [],
+			status: "pending"
+		}')
+
+	librarian_storage_write_proposal "$PROJECT_KEY" "$PROPOSAL_ID" "$PROPOSAL_JSON" >/dev/null \
+		|| continue
+
+	PROPOSED_COUNT=$((PROPOSED_COUNT + 1))
+
+	librarian_emit "librarian.candidate.proposed" "$SESSION_ID" "$(jq -cn \
+		--arg proposal_id "$PROPOSAL_ID" \
+		--arg memory_type "$MEMORY_TYPE" \
+		--argjson classifier_confidence "$CONFIDENCE" \
+		--arg conflict_state "none" \
+		--arg src "$ARTIFACT_ID" \
+		'{
+			proposal_id: $proposal_id,
+			memory_type: $memory_type,
+			classifier_confidence: $classifier_confidence,
+			conflict_state: $conflict_state,
+			source_artifact_ids: (if $src == "" then [] else [$src] end)
+		}')"
+done
+
+# ----------------------------------------------------------------------------
+# Watermark advance + scan.complete.
+# ----------------------------------------------------------------------------
+
+librarian_storage_write_last_scan "$PROJECT_KEY" || true
+
+TOTAL_DROPPED=$((DROPPED_TOTAL + POST_CLASSIFIER_DROPPED))
+OUTCOME="ok"
+[[ "$PROPOSED_COUNT" == "0" ]] && OUTCOME="empty"
+DURATION_MS=$(( ($(date +%s) - SCAN_START_TS_S) * 1000 ))
+
+librarian_emit "librarian.scan.complete" "$SESSION_ID" "$(jq -cn \
+	--arg outcome "$OUTCOME" \
+	--argjson candidates_proposed "$PROPOSED_COUNT" \
+	--argjson candidates_dropped "$TOTAL_DROPPED" \
+	--argjson duration_ms "$DURATION_MS" \
+	--argjson artifact_count_in_window "$ARTIFACT_COUNT" \
+	'{
+		outcome: $outcome,
+		candidates_proposed: $candidates_proposed,
+		candidates_dropped: $candidates_dropped,
+		duration_ms: $duration_ms,
+		artifact_count_in_window: $artifact_count_in_window
+	}')"
+
+# Suppress AUTO_PROMOTE_THRESHOLD shellcheck warning — read for future use
+# (auto-promote path lands in the next commit).
+: "${AUTO_PROMOTE_THRESHOLD}"
+
+exit 0

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Librarian SessionStart surfacer.
+#
+# Counts pending proposals in the project's queue and injects a one-line
+# `additionalContext` pointer if any exist. The full proposal bodies live
+# in ~/.onlooker/librarian/<project-key>/proposals/ and are reviewed via
+# the /librarian review skill rather than inlined here — SessionStart
+# context is precious, and a queue of 20 distilled-but-unreviewed memories
+# isn't where it should go.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits valid hookSpecificOutput JSON, even when nothing to say.
+#   - No-ops when librarian.enabled is not true.
+#   - No-ops when there is no project key (no git context).
+
+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"
+fi
+
+# shellcheck source=../lib/librarian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-config.sh"
+# shellcheck source=../lib/librarian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+# shellcheck source=../lib/librarian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-storage.sh"
+
+# Emit hookSpecificOutput with the given additionalContext string. An
+# empty string is fine — the harness sees "nothing to say".
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '
+		{
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: $ctx
+			}
+		}
+	'
+}
+
+INPUT=$(cat 2>/dev/null || true)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+
+REPO_ROOT=$(librarian_project_repo_root "$CWD")
+librarian_config_load "$REPO_ROOT"
+
+if ! librarian_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+PROJECT_KEY=$(librarian_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+SKIP_WHEN_ZERO=$(librarian_config_get '.librarian.surfacer.skip_inject_when_zero')
+[[ -z "$SKIP_WHEN_ZERO" || "$SKIP_WHEN_ZERO" == "null" ]] && SKIP_WHEN_ZERO="true"
+
+MAX_PENDING=$(librarian_config_get '.librarian.surfacer.max_pending_for_inject')
+[[ -z "$MAX_PENDING" || "$MAX_PENDING" == "null" ]] && MAX_PENDING=20
+
+PENDING=$(librarian_storage_count_pending "$PROJECT_KEY")
+[[ -z "$PENDING" || "$PENDING" == "null" ]] && PENDING=0
+
+if [[ "$PENDING" -eq 0 && "$SKIP_WHEN_ZERO" == "true" ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Cap the surfaced number so a runaway queue doesn't make the pointer
+# itself look alarming. Users still see the truthful count in
+# /librarian review.
+if [[ "$PENDING" -gt "$MAX_PENDING" ]]; then
+	DISPLAY_COUNT="${MAX_PENDING}+"
+else
+	DISPLAY_COUNT="$PENDING"
+fi
+
+NOUN="proposals"
+[[ "$PENDING" -eq 1 ]] && NOUN="proposal"
+
+CONTEXT=$(printf 'Librarian has %s pending memory promotion %s. Review with `/librarian review`.' \
+	"$DISPLAY_COUNT" "$NOUN")
+
+_emit "$CONTEXT"
+exit 0

package/plugins/librarian/scripts/lib/librarian-archivist-reader.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Reads archivist artifacts for the librarian scan pipeline.
+#
+# Archivist stores per-session artifacts under:
+#   $ONLOOKER_DIR/archivist/<project-key>/{decisions,dead_ends,open_questions}/<ulid>.json
+#
+# Each artifact has the shape (see archivist's storage.sh):
+#   { id, kind, project_key, source, created_at, updated_at, summary,
+#     detail, files, session_id, trigger }
+#
+# Librarian reads the same project-key directory and filters by created_at,
+# returning candidates newer than the watermark.
+
+# Resolve the archivist project dir for a given project key.
+# Returns empty if archivist artifacts are not present.
+librarian_archivist_project_dir() {
+	local project_key="$1"
+	[[ -z "$project_key" ]] && return 0
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	local dir="${base}/archivist/${project_key}"
+	[[ -d "$dir" ]] || return 0
+	printf '%s' "$dir"
+}
+
+# Load archivist artifacts created since the given watermark.
+#
+# Usage: librarian_archivist_load_since <project_key> <watermark_iso>
+#
+# Watermark format: ISO-8601 (e.g., "2026-06-01T12:34:56Z"). When the
+# watermark is empty, all artifacts are returned (used on first scan).
+#
+# Output: JSON array, one element per artifact, in chronological order.
+librarian_archivist_load_since() {
+	local project_key="$1"
+	local watermark="${2:-}"
+
+	local project_dir
+	project_dir=$(librarian_archivist_project_dir "$project_key")
+	[[ -z "$project_dir" ]] && { echo '[]'; return 0; }
+
+	local kind file all='[]'
+	for kind in decisions dead_ends open_questions; do
+		[[ -d "${project_dir}/${kind}" ]] || continue
+		for file in "${project_dir}/${kind}"/*.json; do
+			[[ -f "$file" ]] || continue
+			local item created_at
+			item=$(jq '.' "$file" 2>/dev/null) || continue
+			[[ -z "$item" || "$item" == "null" ]] && continue
+
+			# Filter by watermark when provided.
+			if [[ -n "$watermark" ]]; then
+				created_at=$(printf '%s' "$item" | jq -r '.created_at // .updated_at // ""' 2>/dev/null)
+				[[ -z "$created_at" ]] && continue
+				# Lexicographic compare works for ISO-8601 UTC strings.
+				if [[ "$created_at" < "$watermark" || "$created_at" == "$watermark" ]]; then
+					continue
+				fi
+			fi
+
+			all=$(printf '%s' "$all" | jq --argjson item "$item" '. + [$item]')
+		done
+	done
+
+	# Sort chronologically; downstream classifier groups by session_id and
+	# benefits from stable order.
+	printf '%s' "$all" | jq 'sort_by(.created_at // .updated_at // "")'
+}

package/plugins/librarian/scripts/lib/librarian-classifier.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Type classifier for librarian candidates.
+#
+# Calls `claude -p` with a structured prompt that maps a single archivist
+# artifact to one of the four memory types (user, feedback, project,
+# reference) or null when the artifact is interesting but session-only.
+#
+# Returns the model's JSON response on stdout, or empty string on any
+# error (timeout, missing CLI, invalid JSON, low confidence). Callers
+# treat empty as "drop this candidate".
+#
+# Config inputs (read via librarian_config_get from the caller):
+#   librarian.classifier.model              Anthropic model id
+#   librarian.classifier.temperature        Sampling temperature
+#   librarian.classifier.max_output_tokens  Output cap
+#   librarian.classifier.min_classifier_confidence  Drop below this
+
+# Hard wall-clock ceiling for a single classifier call. We never want a
+# hung LLM to delay SessionEnd more than this.
+_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS=20
+
+# Build the classifier prompt for a single artifact.
+# Usage: librarian_classifier_build_prompt <artifact_json>
+librarian_classifier_build_prompt() {
+	local artifact="$1"
+	local kind summary detail files_list session_id created_at
+
+	kind=$(printf '%s' "$artifact" | jq -r '.kind // ""')
+	summary=$(printf '%s' "$artifact" | jq -r '.summary // ""')
+	detail=$(printf '%s' "$artifact" | jq -r '.detail // ""')
+	files_list=$(printf '%s' "$artifact" | jq -r '(.files // []) | join(", ")')
+	session_id=$(printf '%s' "$artifact" | jq -r '.session_id // ""')
+	created_at=$(printf '%s' "$artifact" | jq -r '.created_at // ""')
+
+	cat <<EOF
+You are classifying a session artifact for promotion into a long-term memory store.
+
+The store has four types:
+- user: durable facts about the user's role, expertise, or working style
+- feedback: corrections or validated preferences ("don't do X", "yes, keep doing Y")
+- project: ongoing work facts, decisions, constraints not derivable from the code
+- reference: pointers to external systems (issue trackers, dashboards, channels)
+
+RULES:
+- Output ONLY a single JSON object on one line, no markdown fences, no prose.
+- Schema: { "type": "<user|feedback|project|reference|null>",
+            "title": "<<=60 chars>",
+            "body": "<the memory content; structure per type>",
+            "confidence": <float 0-1> }
+- Use "type": null when the artifact is interesting but session-only (a
+  specific bug fix, a one-off question that got answered, an exploration
+  that didn't change anything).
+- For feedback and project types, include **Why:** and **How to apply:**
+  lines inside the body.
+
+<artifact>
+kind: ${kind}
+summary: ${summary}
+detail: ${detail}
+files: ${files_list}
+session_id: ${session_id}
+created_at: ${created_at}
+</artifact>
+EOF
+}
+
+# Call the classifier for one artifact. Prints the model's JSON output or
+# empty string on error.
+#
+# Usage: librarian_classifier_call <artifact_json> <model> <temperature>
+#                                  <max_output_tokens>
+librarian_classifier_call() {
+	local artifact="$1"
+	local model="${2:-}"
+	local temperature="${3:-0.2}"
+	local max_tokens="${4:-256}"
+
+	command -v claude >/dev/null 2>&1 || return 0
+	[[ -z "$artifact" ]] && return 0
+
+	local prompt_file
+	prompt_file=$(mktemp -t librarian-classify.XXXXXX 2>/dev/null) \
+		|| prompt_file="/tmp/librarian-classify.$$"
+	# shellcheck disable=SC2064
+	trap "rm -f '$prompt_file'" EXIT
+
+	librarian_classifier_build_prompt "$artifact" > "$prompt_file" || return 0
+
+	local args=(-p --max-turns 1)
+	[[ -n "$model" ]] && args+=(--model "$model")
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	rm -f "$prompt_file"
+	trap - EXIT
+
+	[[ -z "$response" ]] && return 0
+
+	# Strip accidental markdown fences before parsing.
+	local clean
+	clean=$(printf '%s' "$response" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+
+	# Validate the response shape before passing it back.
+	if ! printf '%s' "$clean" | jq -e '
+		(.type == null or (.type | IN("user", "feedback", "project", "reference")))
+		and (.title | type) == "string"
+		and (.body | type) == "string"
+		and (.confidence | type) == "number"
+	' >/dev/null 2>&1; then
+		return 0
+	fi
+
+	printf '%s' "$clean"
+}
+
+# Synthesize a deterministic filename from a classifier result.
+# Used when writing accepted promotions into the typed memory store.
+# Format: <type>_<slugified-title>.md
+#
+# Usage: librarian_classifier_filename <type> <title>
+librarian_classifier_filename() {
+	local type="$1"
+	local title="$2"
+	local slug
+	slug=$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' \
+		| sed -E 's/[^a-z0-9]+/_/g; s/^_+|_+$//g' \
+		| cut -c1-60)
+	[[ -z "$slug" ]] && slug="memory"
+	printf '%s_%s.md' "$type" "$slug"
+}