@onlooker-community/ecosystem 0.20.0 → 0.22.0

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

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# Storage layout helpers for Curator.
+#
+# Layout (under $ONLOOKER_DIR/curator/<project-key>/):
+#   manifest.json              project metadata (remote_url, repo_root, last_seen_at)
+#   last_cheap_scan.json       watermark: when cheap-tier last ran
+#   last_llm_sweep.json        watermark: when LLM sweep last ran
+#   findings/<ulid>.json       one finding per file (open, acknowledged, or resolved)
+
+# ============================================================================
+# Path helpers
+# ============================================================================
+
+curator_storage_root() {
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	printf '%s/curator' "$base"
+}
+
+curator_project_dir() {
+	local key="$1"
+	printf '%s/%s' "$(curator_storage_root)" "$key"
+}
+
+curator_findings_dir() {
+	local key="$1"
+	printf '%s/findings' "$(curator_project_dir "$key")"
+}
+
+curator_storage_init() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	local project_dir
+	project_dir=$(curator_project_dir "$key")
+	mkdir -p "$project_dir/findings" 2>/dev/null
+}
+
+curator_storage_write_manifest() {
+	local key="$1"
+	local remote_url="$2"
+	local repo_root="$3"
+	[[ -z "$key" ]] && return 1
+
+	curator_storage_init "$key" || return 1
+	local manifest_path now
+	manifest_path="$(curator_project_dir "$key")/manifest.json"
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	jq -n \
+		--arg key "$key" \
+		--arg remote "$remote_url" \
+		--arg root "$repo_root" \
+		--arg now "$now" \
+		'{
+			project_key: $key,
+			remote_url: (if $remote == "" then null else $remote end),
+			repo_root: (if $root == "" then null else $root end),
+			last_seen_at: $now
+		}' > "$manifest_path" 2>/dev/null
+}
+
+# ============================================================================
+# Watermarks
+# ============================================================================
+
+curator_last_cheap_scan_path() {
+	printf '%s/last_cheap_scan.json' "$(curator_project_dir "$1")"
+}
+
+curator_last_llm_sweep_path() {
+	printf '%s/last_llm_sweep.json' "$(curator_project_dir "$1")"
+}
+
+curator_storage_read_watermark() {
+	local path="$1"
+	[[ -f "$path" ]] || return 0
+	jq -r '.scanned_at // empty' "$path" 2>/dev/null
+}
+
+curator_storage_write_watermark() {
+	local path="$1"
+	[[ -z "$path" ]] && return 1
+	mkdir -p "$(dirname "$path")" 2>/dev/null
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	jq -n --arg t "$now" '{ scanned_at: $t }' > "$path" 2>/dev/null
+}
+
+# ============================================================================
+# Findings
+# ============================================================================
+
+# Write a finding to disk, keyed by ULID. Dedup is by deduped_hash so a
+# repeat scan that surfaces the same fact does not write a new finding.
+#
+# Usage: curator_storage_write_finding <key> <ulid> <json>
+curator_storage_write_finding() {
+	local key="$1"
+	local id="$2"
+	local json="$3"
+	[[ -z "$key" || -z "$id" || -z "$json" ]] && return 1
+
+	curator_storage_init "$key" || return 1
+	local path
+	path="$(curator_findings_dir "$key")/${id}.json"
+	printf '%s\n' "$json" > "$path" 2>/dev/null && printf '%s' "$path"
+}
+
+# Load all findings for a project key as a JSON array.
+curator_storage_load_findings() {
+	local key="$1"
+	[[ -z "$key" ]] && { echo '[]'; return 0; }
+	local dir
+	dir=$(curator_findings_dir "$key")
+	[[ -d "$dir" ]] || { echo '[]'; return 0; }
+
+	local file all='[]'
+	for file in "$dir"/*.json; do
+		[[ -f "$file" ]] || continue
+		local item
+		item=$(jq '.' "$file" 2>/dev/null) || continue
+		all=$(printf '%s' "$all" | jq --argjson item "$item" '. + [$item]')
+	done
+	printf '%s' "$all"
+}
+
+# Return 0 if a finding with the given dedup hash already exists (open).
+curator_storage_has_finding_with_hash() {
+	local key="$1"
+	local hash="$2"
+	[[ -z "$key" || -z "$hash" ]] && return 1
+	local existing
+	existing=$(curator_storage_load_findings "$key")
+	printf '%s' "$existing" | jq -e --arg h "$hash" '
+		any(.[]; (.deduped_hash // "") == $h and (.status // "open") == "open")
+	' >/dev/null 2>&1
+}
+
+curator_storage_count_open() {
+	local key="$1"
+	local all
+	all=$(curator_storage_load_findings "$key")
+	printf '%s' "$all" | jq '[.[] | select((.status // "open") == "open")] | length' 2>/dev/null
+}
+
+# Open-finding counts grouped by kind. Used by the surfacer to render a
+# pointer like "2 path-broken, 1 date-decayed".
+#
+# jq's group_by groups CONSECUTIVE matches, so the array must be sorted
+# by .kind first or the same kind can produce multiple groups (and the
+# downstream summary double-counts).
+curator_storage_open_counts_by_kind() {
+	local key="$1"
+	local all
+	all=$(curator_storage_load_findings "$key")
+	printf '%s' "$all" | jq -c '
+		[.[] | select((.status // "open") == "open")]
+		| sort_by(.kind)
+		| group_by(.kind)
+		| map({ kind: .[0].kind, count: length })
+		| sort_by(-.count)
+	'
+}
+
+# Hash a finding's identity-relevant fields. Two findings with the same
+# kind + memory_file + matched_phrase (where applicable) share a hash.
+# Plain shasum input — no expensive normalization needed.
+curator_finding_hash() {
+	local raw="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$raw" | shasum -a 256 2>/dev/null | cut -c1-16
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$raw" | sha256sum 2>/dev/null | cut -c1-16
+	else
+		return 1
+	fi
+}

package/plugins/curator/scripts/lib/curator-ulid.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Curator finding IDs.
+#
+# Spec: https://github.com/ulid/spec — 48-bit timestamp + 80-bit randomness,
+# lexicographically sortable, Crockford Base32. Monotonicity within a single
+# millisecond is not required; findings are written infrequently.
+
+_CURATOR_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_curator_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_CURATOR_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+curator_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hi rand_lo
+	rand_hi=$((RANDOM * 32768 + RANDOM))
+	rand_lo=$((RANDOM * 32768 + RANDOM))
+	rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+
+	local ts_part hi_part lo_part
+	ts_part=$(_curator_ulid_encode "$now_ms" 10)
+	hi_part=$(_curator_ulid_encode "$rand_hi" 8)
+	lo_part=$(_curator_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

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

@@ -0,0 +1,14 @@
+{
+  "name": "historian",
+  "version": "0.1.0",
+  "description": "Episodic memory layer. At SessionEnd, chunks and sanitizes the session transcript and stores the chunks locally under ~/.onlooker/historian/<project-key>/sessions/. Future-tense retrieval (vector embeddings + UserPromptSubmit similarity surfacer) lands in a follow-up; this PR ships the indexing pipeline only. 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/historian/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/historian-v0.0.1...historian-v0.1.0) (2026-06-04)
+
+
+### Features
+
+* **historian:** introduce SessionEnd indexing :spiral_notepad: ([#59](https://github.com/onlooker-community/ecosystem/issues/59)) ([dd6c7f6](https://github.com/onlooker-community/ecosystem/commit/dd6c7f6ea872437cab6b16de50838dfc72750c7b))
+
+## Changelog

package/plugins/historian/README.md

@@ -0,0 +1,70 @@
+# Historian
+
+Episodic memory layer for past Claude Code sessions.
+
+At every `SessionEnd`, Historian reads the session transcript, splits it into overlapping chunks at turn boundaries, redacts secret-shaped substrings, and persists the chunks under `~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl`. Future sessions can retrieve relevant past chunks when the user starts a similar problem.
+
+Historian is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present. It is parallel to [`librarian`](../librarian) (which consolidates session decisions into the typed memory store) — both turn session-scoped material into something queryable across sessions, but at different levels of distillation. Librarian distills; historian preserves verbatim.
+
+See [`docs/design.md`](docs/design.md) and [ADR-001](docs/adr/001-local-embeddings-only.md) for the full design, including the local-embeddings-by-default decision.
+
+## How it works
+
+| Hook | What Historian does |
+|------|---------------------|
+| `SessionEnd` | Reads the transcript at `transcript_path`, drops tool calls and tool results (keeps user + assistant messages), chunks at turn boundaries inside the configured character target with overlap, runs the sanitizer (secret redaction + `[historian:skip]` markers + path-deny list), and appends one JSONL line per chunk to the session's file. Emits `historian.indexing.*` and `historian.chunk.*` events along the way. |
+| `UserPromptSubmit` | No-op in this PR — the rate gate, query embedder, ANN lookup, and surfacer are deferred to a follow-up that ships the retrieval pipeline alongside the first embedder backend. |
+
+## Activation
+
+Historian is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "historian": {
+    "enabled": true
+  }
+}
+```
+
+See [`config.json`](config.json) for the full set of tunable defaults.
+
+## Storage layout
+
+```text
+~/.onlooker/historian/<project-key>/
+├── manifest.json                          # project metadata
+└── sessions/<session-id>.jsonl            # one chunk per line, append-only
+```
+
+Each chunk line:
+
+```json
+{
+  "chunk_id": "01J...",
+  "session_id": "...",
+  "chunk_index": 0,
+  "start_turn_index": 0,
+  "end_turn_index": 3,
+  "body_redacted": "...",
+  "body_chars": 2103,
+  "created_at": "2026-06-04T...",
+  "source": "local",
+  "redaction_count": 0
+}
+```
+
+## Status
+
+This plugin ships **scaffolding + the SessionEnd indexing pipeline (transcript reader → chunker → sanitizer → JSONL store)**. Deferred to follow-up landings:
+
+- **Retrieval and surfacer** — `UserPromptSubmit` rate gate, query embedding, ANN lookup, and `additionalContext` injection of the top match.
+- **Embedder backends** — ollama (`nomic-embed-text`), fastembed sidecar, and remote (opt-in via the two-key egress affirmation from [ADR-001](docs/adr/001-local-embeddings-only.md)). Chunks are indexed without vectors today; the JSONL records make adding embeddings a future column-add, not a re-index.
+- **Prune (retention sweep) and purge (manual)** skills.
+- **`/historian recall`, `/historian setup`, `/historian stats`, `/historian purge`** slash commands.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for `~/.onlooker/` substrate).
+- `jq` for JSON manipulation.
+- `python3` for chunking and sanitization (no extra packages — stdlib only).

package/plugins/historian/config.json

@@ -0,0 +1,30 @@
+{
+  "plugin_name": "historian",
+  "storage_path": "~/.onlooker",
+  "historian": {
+    "enabled": false,
+    "indexing": {
+      "trigger": "SessionEnd",
+      "min_transcript_chars_to_index": 1200,
+      "chunk_target_chars": 2400,
+      "chunk_overlap_chars": 400,
+      "retention_days": 365
+    },
+    "sanitization": {
+      "redact_secret_patterns": true,
+      "drop_skip_marker": true,
+      "never_index_paths": []
+    },
+    "session_archive": {
+      "enabled": false,
+      "_note": "When true, the full transcript at SessionEnd is copied alongside the chunks so retrieval can link to the source. When false, only chunk bodies are retained."
+    },
+    "embedder": {
+      "backend": "none",
+      "_note": "Embedder backends (ollama, fastembed, remote) are deferred to a follow-up. The current 'none' value indexes chunks without vectors; retrieval is also deferred."
+    },
+    "retrieval": {
+      "_note": "UserPromptSubmit retrieval and surfacer are deferred to a follow-up commit; the hook currently no-ops."
+    }
+  }
+}

package/plugins/historian/hooks/hooks.json

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

package/plugins/historian/scripts/hooks/historian-prompt-submit.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Historian UserPromptSubmit hook — STUB.
+#
+# The full retrieval pipeline (rate gate → query embedder → ANN lookup →
+# additionalContext surfacer) is deferred to a follow-up landing that ships
+# the first embedder backend. Today the hook is intentionally a no-op so
+# the plugin can be installed and indexing can run without retrieval.
+#
+# Hook contract:
+#   - Always exits 0.
+#   - Never produces additionalContext while the retrieval pipeline is
+#     unimplemented.
+
+set -uo pipefail
+exit 0

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# Historian SessionEnd indexing pipeline.
+#
+# Reads the session transcript, drops tool calls / tool results, chunks
+# the remaining user + assistant turns at turn boundaries, redacts
+# secret-shaped substrings, and appends one JSONL line per surviving
+# chunk to ~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session shutdown.
+#   - No-ops when historian.enabled is not true.
+#   - No-ops when there is no project key, no transcript path, or the
+#     transcript is shorter than min_transcript_chars_to_index.
+#   - Indexing failures are fail-soft: an emitted historian.indexing.complete
+#     with outcome "skipped" + a skip_reason is the worst case.
+
+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/historian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-config.sh"
+# shellcheck source=../lib/historian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-project-key.sh"
+# shellcheck source=../lib/historian-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-ulid.sh"
+# shellcheck source=../lib/historian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-storage.sh"
+# shellcheck source=../lib/historian-emit.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-emit.sh"
+# shellcheck source=../lib/historian-transcript.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-transcript.sh"
+# shellcheck source=../lib/historian-chunker.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-chunker.sh"
+# shellcheck source=../lib/historian-sanitizer.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-sanitizer.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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+REPO_ROOT=$(historian_project_repo_root "$CWD")
+historian_config_load "$REPO_ROOT"
+historian_config_enabled || exit 0
+
+PROJECT_KEY=$(historian_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+historian_storage_init "$PROJECT_KEY" || exit 0
+REMOTE_URL=$(historian_project_remote_url "$CWD")
+historian_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+# ----------------------------------------------------------------------------
+# Transcript-availability check first — emit no started/complete for the
+# transcript_unavailable path, just a complete-with-skip so the timeline
+# reads cleanly. Once we have a real char count, emit started with that
+# count (the schema requires transcript_chars on started, so emitting
+# zero before the read produced misleading telemetry).
+# ----------------------------------------------------------------------------
+
+SCAN_START_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| SCAN_START_MS=$(($(date +%s) * 1000))
+
+_emit_skip() {
+	local reason="$1"
+	local now_ms duration_ms
+	now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+		|| now_ms=$(($(date +%s) * 1000))
+	duration_ms=$((now_ms - SCAN_START_MS))
+	historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "skipped" \
+		--arg skip_reason "$reason" \
+		--argjson duration_ms "$duration_ms" \
+		'{ outcome: $outcome, skip_reason: $skip_reason, duration_ms: $duration_ms }')"
+}
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_emit_skip "transcript_unavailable"
+	exit 0
+fi
+
+MIN_CHARS=$(historian_config_get '.historian.indexing.min_transcript_chars_to_index')
+[[ -z "$MIN_CHARS" || "$MIN_CHARS" == "null" ]] && MIN_CHARS=1200
+
+TURNS=$(historian_transcript_load "$TRANSCRIPT_PATH")
+TRANSCRIPT_CHARS=$(historian_transcript_char_count "$TURNS")
+[[ -z "$TRANSCRIPT_CHARS" || "$TRANSCRIPT_CHARS" == "null" ]] && TRANSCRIPT_CHARS=0
+
+historian_emit "historian.indexing.started" "$SESSION_ID" "$(jq -cn \
+	--arg session_id "$SESSION_ID" \
+	--argjson transcript_chars "$TRANSCRIPT_CHARS" \
+	'{ session_id: $session_id, transcript_chars: $transcript_chars }')"
+
+if (( TRANSCRIPT_CHARS < MIN_CHARS )); then
+	_emit_skip "too_short"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Chunker → sanitizer → JSONL store.
+# ----------------------------------------------------------------------------
+
+TARGET_CHARS=$(historian_config_get '.historian.indexing.chunk_target_chars')
+[[ -z "$TARGET_CHARS" || "$TARGET_CHARS" == "null" ]] && TARGET_CHARS=2400
+OVERLAP_CHARS=$(historian_config_get '.historian.indexing.chunk_overlap_chars')
+[[ -z "$OVERLAP_CHARS" || "$OVERLAP_CHARS" == "null" ]] && OVERLAP_CHARS=400
+
+CHUNKS=$(historian_chunker_split "$TURNS" "$TARGET_CHARS" "$OVERLAP_CHARS")
+NEVER_INDEX_PATHS=$(historian_config_get '.historian.sanitization.never_index_paths | tojson')
+[[ -z "$NEVER_INDEX_PATHS" || "$NEVER_INDEX_PATHS" == "null" ]] && NEVER_INDEX_PATHS='[]'
+
+# Honor the two on/off knobs from the config block.
+REDACT_SECRETS=$(historian_config_get '.historian.sanitization.redact_secret_patterns')
+[[ -z "$REDACT_SECRETS" || "$REDACT_SECRETS" == "null" ]] && REDACT_SECRETS="true"
+DROP_SKIP=$(historian_config_get '.historian.sanitization.drop_skip_marker')
+[[ -z "$DROP_SKIP" || "$DROP_SKIP" == "null" ]] && DROP_SKIP="true"
+
+SANITIZED=$(historian_sanitizer_run "$CHUNKS" "$NEVER_INDEX_PATHS" "$REDACT_SECRETS" "$DROP_SKIP")
+KEPT=$(printf '%s' "$SANITIZED" | jq '.kept')
+DROPPED=$(printf '%s' "$SANITIZED" | jq '.dropped')
+
+# Re-indexing replaces the existing session file rather than appending,
+# so SessionEnd is safely idempotent if re-fired against the same id.
+historian_storage_reset_session "$PROJECT_KEY" "$SESSION_ID"
+
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+CHUNKS_INDEXED=0
+KEPT_COUNT=$(printf '%s' "$KEPT" | jq 'length' 2>/dev/null) || KEPT_COUNT=0
+
+for ((i = 0; i < KEPT_COUNT; i++)); do
+	CHUNK=$(printf '%s' "$KEPT" | jq -c ".[$i]")
+	[[ -z "$CHUNK" || "$CHUNK" == "null" ]] && continue
+
+	CHUNK_ID=$(historian_ulid)
+	REDACTION_COUNT=$(printf '%s' "$CHUNK" | jq -r '.redaction_count // 0')
+
+	RECORD=$(jq -cn \
+		--arg chunk_id "$CHUNK_ID" \
+		--arg session_id "$SESSION_ID" \
+		--argjson chunk_input "$CHUNK" \
+		--arg created_at "$NOW_TS" \
+		--arg source "local" \
+		'$chunk_input + {
+			chunk_id: $chunk_id,
+			session_id: $session_id,
+			created_at: $created_at,
+			source: $source
+		}')
+
+	if historian_storage_append_chunk "$PROJECT_KEY" "$SESSION_ID" "$RECORD"; then
+		CHUNKS_INDEXED=$((CHUNKS_INDEXED + 1))
+		if (( REDACTION_COUNT > 0 )); then
+			historian_emit "historian.chunk.sanitized" "$SESSION_ID" "$(jq -cn \
+				--arg chunk_id "$CHUNK_ID" \
+				--argjson redaction_count "$REDACTION_COUNT" \
+				'{ chunk_id: $chunk_id, redaction_count: $redaction_count }')"
+		fi
+	fi
+done
+
+# Emit one chunk.dropped event per skip reason summary (caps at the
+# number of unique reasons; per-chunk emission would spam the log).
+DROPPED_COUNT=$(printf '%s' "$DROPPED" | jq 'length' 2>/dev/null) || DROPPED_COUNT=0
+if (( DROPPED_COUNT > 0 )); then
+	for reason in $(printf '%s' "$DROPPED" | jq -r '.[].reason' | sort -u); do
+		historian_emit "historian.chunk.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "$reason" \
+			'{ reason: $reason }')"
+	done
+fi
+
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| NOW_MS=$(($(date +%s) * 1000))
+DURATION_MS=$((NOW_MS - SCAN_START_MS))
+
+historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+	--arg outcome "ok" \
+	--argjson chunks_indexed "$CHUNKS_INDEXED" \
+	--argjson chunks_dropped "$DROPPED_COUNT" \
+	--argjson duration_ms "$DURATION_MS" \
+	'{
+		outcome: $outcome,
+		chunks_indexed: $chunks_indexed,
+		chunks_dropped: $chunks_dropped,
+		duration_ms: $duration_ms
+	}')"
+
+exit 0