@onlooker-community/ecosystem 0.26.1 → 0.28.0

package/plugins/lineage/README.md

@@ -0,0 +1,133 @@
+# Lineage
+
+Per-change provenance for the Onlooker ecosystem — "why does this line exist?"
+
+Git records *what* changed and scribe records a session's *intent*, but nothing
+connects a **specific piece of code** to the prompt, agent, and session that
+produced it. Lineage records provenance for every `Edit`/`Write`/`MultiEdit` at
+`PostToolUse`, then answers `/lineage <file>:<line>` by joining its change records
+to the transcripts [historian](../historian) preserves.
+
+Lineage is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker
+observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | Matcher | What Lineage does |
+|------|---------|-------------------|
+| `PostToolUse` | `Edit`, `Write`, `MultiEdit` | Derives the project key from `cwd`, reads the current turn from the session tracker, extracts the change's added content, redacts secrets + caps size, and appends one record to the per-project change ledger. Emits a lean `lineage.change.recorded` (metadata + digest, never the content). Skips disabled sessions, ignored paths, and files outside the repo. |
+
+The `/lineage` skill is the query side: it reads the ledger and resolves each
+change's originating prompt at query time. It makes no LLM call.
+
+### Content-anchored provenance
+
+Lineage records the **added content** of each change (redacted, capped at
+`max_snippet_chars`). To answer "why does line N exist?", it reads the current
+line's text and finds the most recent change whose added content contains it.
+This is honest about what it is: *what change introduced this content, and why* —
+not a git-blame-exact line mapping. If later edits move or rewrite the line, the
+match is the most recent change that introduced the matching text.
+
+### The historian join
+
+Lineage records only `session_id` + `turn` (+ a `transcript_path` pointer) on the
+hot path — never the prompt. The prompt is resolved lazily at query time:
+
+1. **historian** — read the session's durable chunks at
+   `~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl` and take the
+   chunk whose turn range contains the change's turn (tolerant: nearest preceding,
+   else the last chunk). This is the preferred source because historian persists
+   transcripts long after the live `transcript_path` is gone.
+2. **transcript** — fall back to the live `transcript_path` (the turn-th user
+   message).
+3. **none** — neither available; report the change without a prompt.
+
+The content match — not the turn — is the precise provenance key; the prompt is
+best-effort context, since historian's turn indices need not line up exactly with
+the substrate's turn counter.
+
+## Activation
+
+Lineage is **off by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "lineage": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`. While disabled, the hook skips silently
+and no ledger is written.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "lineage": {
+    "enabled": false,
+    "max_snippet_chars": 4000,
+    "redact_secrets": true,
+    "ignore_globs": ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/*.lock"],
+    "prompt_source": "historian_then_transcript"
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for recording, querying, or event emission to run. |
+| `max_snippet_chars` | `4000` | Cap on the added-content snippet stored per change. |
+| `redact_secrets` | `true` | Scrub secret-shaped substrings (AWS/GitHub/Anthropic/OpenAI keys, bearer tokens, KEY=value secrets) before storing a snippet. |
+| `ignore_globs` | `[".git", "node_modules", "dist", "*.lock"]` | Paths matching these are not recorded. Supports `**/<dir>/**` (path segment) and `**/*.<ext>` (suffix) shapes. |
+| `prompt_source` | `"historian_then_transcript"` | Prompt-resolution strategy: `historian_then_transcript`, `historian_only`, or `transcript_only`. |
+
+Config resolves in three layers, latest wins: plugin `config.json` →
+`~/.claude/settings.json` → `<repo>/.claude/settings.json`.
+
+## The `/lineage` query
+
+| Invocation | Answers |
+|------------|---------|
+| `/lineage <file>` | Full change history for the file, newest first, each with its resolved prompt context. |
+| `/lineage <file>:<line>` or `/lineage <file> --line N` | Which change introduced the content currently on line N — with the prompt/agent/session behind it. |
+| `/lineage <file> --grep <text>` | Which change introduced content matching `<text>`. |
+| `/lineage --status` | Ledger stats for the project (changes recorded, files touched). |
+
+## Storage layout
+
+```text
+~/.onlooker/lineage/<project-key>/
+├── changes.jsonl        # append-only, one change record per line
+└── changes.jsonl.lock   # write lock
+```
+
+Each record: `{ change_id, ts, ts_epoch, session_id, turn?, tool, operation,
+file_path, lines_added, lines_removed, bytes, edit_count, content_sha256,
+added_snippets[], transcript_path }`. The added content lives only in this ledger;
+the bus event carries metadata and the `content_sha256` digest, never the content.
+
+Lineage honors `$ONLOOKER_DIR`; it never hardcodes `~/.onlooker`, so the test
+suite's isolated temp home is respected.
+
+## Events emitted
+
+Lineage emits the canonical `lineage.*` surface from
+[`@onlooker-community/schema`](https://github.com/onlooker-community/schema) v2.8.0+.
+
+| Event | When |
+|-------|------|
+| `lineage.change.recorded` | At `PostToolUse`, after a change is appended to the ledger. Carries `project_key`, `session_id`, `file_path`, `tool`, `operation`, `change_id`, and metadata (`lines_added`/`lines_removed`/`bytes`/`edit_count`/`content_sha256`); no content. |
+| `lineage.query.answered` | When `/lineage` answers. Carries `project_key`, `file_path`, `matches`, and (for line queries) `line` and `resolved_via`. |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- The [`historian`](../historian) plugin enabled, for the most reliable prompt resolution. Without it, lineage falls back to the live transcript, then to "prompt unavailable."
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `python3` for secret redaction (the same dependency historian uses for sanitizing).

package/plugins/lineage/config.json

@@ -0,0 +1,11 @@
+{
+  "plugin_name": "lineage",
+  "storage_path": "~/.onlooker",
+  "lineage": {
+    "enabled": false,
+    "max_snippet_chars": 4000,
+    "redact_secrets": true,
+    "ignore_globs": ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/*.lock"],
+    "prompt_source": "historian_then_transcript"
+  }
+}

package/plugins/lineage/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Lineage PostToolUse hook (Edit / Write / MultiEdit).
+#
+# Records per-change provenance into the per-project change ledger and emits a
+# lean lineage.change.recorded event. Kept cheap: metadata + a redacted,
+# size-capped snippet of the added content + a digest — no transcript parsing
+# (the prompt is resolved lazily at /lineage query time).
+#
+# Hook contract: always exits 0; never blocks the tool. Skips silently when
+# disabled, when the path is ignored, or when the file is outside the repo.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+# shellcheck source=../lib/lineage-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-config.sh"
+# shellcheck source=../lib/lineage-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-events.sh"
+# shellcheck source=../lib/lineage-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-project-key.sh"
+# shellcheck source=../lib/lineage-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-ulid.sh"
+# shellcheck source=../lib/lineage-redact.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-redact.sh"
+# shellcheck source=../lib/lineage-record.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-record.sh"
+
+INPUT=$(cat)
+_done() { exit 0; }
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL=""
+TOOL_INPUT=$(printf '%s' "$INPUT" | jq -c '.tool_input // {}' 2>/dev/null) || TOOL_INPUT="{}"
+TOOL_USE_ID=$(printf '%s' "$INPUT" | jq -r '.tool_use_id // ""' 2>/dev/null) || TOOL_USE_ID=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+
+case "$TOOL" in
+	Edit | Write | MultiEdit) ;;
+	*) _done ;;
+esac
+
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+REPO_ROOT=$(lineage_project_repo_root "$CWD")
+lineage_config_load "$REPO_ROOT"
+lineage_config_enabled || _done
+
+PROJECT_KEY=$(lineage_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done
+
+FILE_PATH=""
+case "$TOOL" in
+	MultiEdit)
+		# MultiEdit applies to one file via a top-level file_path; some shapes
+		# nest file_path per edit, so fall back to the first edit's.
+		FILE_PATH=$(printf '%s' "$TOOL_INPUT" | jq -r '.file_path // .edits[0].file_path // ""' 2>/dev/null) || FILE_PATH=""
+		# If edits carry distinct per-file paths spanning more than one file,
+		# skip to avoid misattribution. (Future: split into one record per file.)
+		unique_count=$(printf '%s' "$TOOL_INPUT" | jq -r '[.edits[]?.file_path // empty] | unique | length' 2>/dev/null) || unique_count=0
+		[[ "${unique_count:-0}" -gt 1 ]] && _done
+		;;
+	*)
+		FILE_PATH=$(printf '%s' "$TOOL_INPUT" | jq -r '.file_path // .path // ""' 2>/dev/null) || FILE_PATH=""
+		;;
+esac
+[[ -z "$FILE_PATH" ]] && _done
+
+# Skip ignored paths. Supports the common glob shapes in config:
+#   **/<dir>/**  → path-segment match ;  **/*.<ext> → suffix match.
+_lineage_ignored() {
+	local path="$1" glob core
+	while IFS= read -r glob; do
+		[[ -z "$glob" ]] && continue
+		core="$glob"
+		core="${core#\*\*/}"
+		core="${core%/\*\*}"
+		case "$core" in
+			\*.*) [[ "$path" == *"${core#\*}" ]] && return 0 ;;
+			*) [[ "/$path/" == *"/$core/"* ]] && return 0 ;;
+		esac
+	done < <(lineage_config_ignore_globs)
+	return 1
+}
+_lineage_ignored "$FILE_PATH" && _done
+
+# Skip files outside the repo (best-effort). Resolve the file's directory to a
+# real path so the prefix test survives symlinked roots (e.g. macOS /var →
+# /private/var, where REPO_ROOT is already realpath-resolved).
+if [[ -n "$REPO_ROOT" && "$FILE_PATH" == /* ]]; then
+	_file_dir=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd -P) || _file_dir=""
+	if [[ -n "$_file_dir" && "$_file_dir" != "$REPO_ROOT" && "$_file_dir"/ != "$REPO_ROOT"/* ]]; then
+		_done
+	fi
+fi
+
+# Turn number (best-effort) from the substrate session tracker.
+TURN=""
+TRACKER="${ONLOOKER_DIR:-$HOME/.onlooker}/session-trackers/${SESSION_ID}"
+[[ -n "$SESSION_ID" && -f "$TRACKER" ]] && TURN=$(jq -r '.turn_number // empty' "$TRACKER" 2>/dev/null)
+
+MAX_CHARS=$(lineage_config_max_snippet_chars)
+DO_REDACT=true
+lineage_config_redact_enabled || DO_REDACT=false
+CHANGE_ID=$(lineage_ulid)
+TS=$(lineage_now_iso)
+TS_EPOCH=$(lineage_now_epoch)
+
+RECORD=$(lineage_build_record "$CHANGE_ID" "$TS" "$TS_EPOCH" "$SESSION_ID" "$TURN" \
+	"$TOOL" "$FILE_PATH" "$TOOL_INPUT" "$MAX_CHARS" "$DO_REDACT" "$TRANSCRIPT_PATH")
+[[ -z "$RECORD" ]] && _done
+
+if lineage_append "$PROJECT_KEY" "$RECORD"; then
+	# Lean bus event: metadata + digest only — never the added content.
+	EV=$(printf '%s' "$RECORD" | jq -c --arg pk "$PROJECT_KEY" --arg tuid "$TOOL_USE_ID" '
+		{
+			project_key: $pk, session_id: .session_id, file_path: .file_path,
+			tool: .tool, operation: .operation, change_id: .change_id,
+			lines_added: .lines_added, lines_removed: .lines_removed,
+			bytes: .bytes, edit_count: .edit_count, content_sha256: .content_sha256
+		}
+		+ (if .turn != null then {turn: .turn} else {} end)
+		+ (if $tuid != "" then {tool_use_id: $tuid} else {} end)
+	' 2>/dev/null)
+	[[ -n "$EV" ]] && lineage_emit_event "lineage.change.recorded" "$EV" "$SESSION_ID" || true
+fi
+
+_done

package/plugins/lineage/scripts/lib/lineage-config.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Config resolution for lineage.
+#
+# Reads three layers, latest wins:
+#   1. plugins/lineage/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   lineage_config_load <repo_root>     # populates _LINEAGE_CONFIG (JSON)
+#   lineage_config_get <jq-path>        # echoes string value (empty if unset)
+#   lineage_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   lineage_config_enabled              # 0 if lineage.enabled is true
+#   lineage_config_max_snippet_chars    # echoes the snippet cap (default 4000)
+#   lineage_config_redact_enabled       # 0 unless redact_secrets is false
+#   lineage_config_prompt_source        # echoes the prompt-source strategy
+#   lineage_config_ignore_globs         # echoes ignore globs, one per line
+
+_LINEAGE_CONFIG="{}"
+
+lineage_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ lineage: (.lineage // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_LINEAGE_CONFIG="$merged"
+}
+
+lineage_config_get() {
+	local path="$1"
+	printf '%s' "$_LINEAGE_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+lineage_config_get_json() {
+	local path="$1"
+	printf '%s' "$_LINEAGE_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+lineage_config_enabled() {
+	local v
+	v=$(lineage_config_get '.lineage.enabled')
+	[[ "$v" == "true" ]]
+}
+
+lineage_config_max_snippet_chars() {
+	local v
+	v=$(lineage_config_get '.lineage.max_snippet_chars')
+	printf '%s' "${v:-4000}"
+}
+
+lineage_config_redact_enabled() {
+	# Default on. jq's `//` treats a literal `false` as empty, so read the raw
+	# JSON value and only disable on an explicit false.
+	local v
+	v=$(lineage_config_get_json '.lineage.redact_secrets')
+	[[ "$v" != "false" ]]
+}
+
+lineage_config_prompt_source() {
+	local v
+	v=$(lineage_config_get '.lineage.prompt_source')
+	printf '%s' "${v:-historian_then_transcript}"
+}
+
+lineage_config_ignore_globs() {
+	printf '%s' "$_LINEAGE_CONFIG" | jq -r '.lineage.ignore_globs[]? // empty' 2>/dev/null
+}

package/plugins/lineage/scripts/lib/lineage-events.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Canonical lineage.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema (>= 2.8.0,
+# which registers the lineage.* event types) before being appended to
+# ~/.onlooker/logs/onlooker-events.jsonl.
+#
+# Usage:
+#   lineage_emit_event "lineage.change.recorded" '{"project_key":"...",...}' "$SESSION_ID"
+_LINEAGE_PLUGIN_NAME="lineage"
+
+_lineage_event_js_path() {
+	if [[ -n "${_ONLOOKER_EVENT_JS:-}" && -f "$_ONLOOKER_EVENT_JS" ]]; then
+		printf '%s' "$_ONLOOKER_EVENT_JS"
+		return 0
+	fi
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local candidates=(
+		"${plugin_root}/scripts/lib/onlooker-event.mjs"
+		"${plugin_root}/../../scripts/lib/onlooker-event.mjs"
+	)
+	local c
+	for c in "${candidates[@]}"; do
+		[[ -f "$c" ]] && { printf '%s' "$c"; return 0; }
+	done
+	return 1
+}
+
+_lineage_session_id() {
+	if [[ -n "${_HOOK_SESSION_ID:-}" ]]; then
+		printf '%s' "$_HOOK_SESSION_ID"
+		return 0
+	fi
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+	printf 'unknown'
+}
+
+# Emit a single lineage.* event. Returns 0 on success, non-zero on failure.
+# Usage: lineage_emit_event <event_type> <payload_json> [session_id]
+lineage_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+	local session_id="${3:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+	[[ -z "$session_id" ]] && session_id=$(_lineage_session_id)
+
+	local event_js
+	event_js=$(_lineage_event_js_path) || return 1
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_LINEAGE_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}' \
+		2>/dev/null) || return 1
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t lineage-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/lineage-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_LINEAGE_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'lineage_emit_event: schema validation failed for %s\n' "$event_type" >&2
+		[[ -s "$stderr_file" ]] && cat "$stderr_file" >&2
+		rm -f "$stderr_file"
+		return 1
+	}
+	rm -f "$stderr_file"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	mkdir -p "$(dirname "$log_path")" 2>/dev/null || return 1
+	printf '%s\n' "$event" >> "$log_path"
+}

package/plugins/lineage/scripts/lib/lineage-project-key.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Project key derivation for lineage.
+#
+# Mirrors the archivist/tribunal project-key scheme so the plugins partition
+# storage identically. A project key is a stable 12-char hex identifier that
+# survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works.
+
+_lineage_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
+}
+
+lineage_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+lineage_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	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
+		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"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty string.
+lineage_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(lineage_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_lineage_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(lineage_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_lineage_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}

package/plugins/lineage/scripts/lib/lineage-query.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Query side of lineage: read the change ledger and resolve prompts.
+#
+# The /lineage skill is a thin wrapper over these functions; the logic lives
+# here so it is unit-testable in bats without driving the skill runtime.
+#
+# Requires lineage-record.sh (for lineage_record_path) and lineage-redact.sh
+# (for capping/scrubbing resolved prompts) sourced beforehand.
+
+# All change records for a file, newest first (one compact JSON per line).
+# Usage: lineage_changes_for_file <project_key> <file_path>
+lineage_changes_for_file() {
+	local key="$1" file="$2"
+	local path
+	path=$(lineage_record_path "$key")
+	[[ -f "$path" ]] || return 0
+	jq -s -c --arg f "$file" \
+		'[ .[] | select(.file_path == $f) ] | reverse | .[]' \
+		"$path" 2>/dev/null
+}
+
+# The newest change whose added content contains <line_text> (substring),
+# i.e. the change that introduced that content. Echoes one record or nothing.
+# Usage: lineage_match_line <project_key> <file_path> <line_text>
+lineage_match_line() {
+	local key="$1" file="$2" needle="$3"
+	local path
+	path=$(lineage_record_path "$key")
+	[[ -f "$path" ]] || return 0
+	# An empty/whitespace needle has no meaningful introducing change.
+	[[ -z "${needle//[[:space:]]/}" ]] && return 0
+	jq -s -c --arg f "$file" --arg t "$needle" '
+		[ .[] | select(.file_path == $f) ] | reverse
+		| map(select(any(.added_snippets[]?; type == "string" and contains($t))))
+		| (.[0] // empty)
+	' "$path" 2>/dev/null
+}
+
+# Resolve the originating prompt for a change. Tries historian's durable
+# per-session chunks first (tolerant turn-range match), then the live
+# transcript, then gives up. Echoes {prompt, resolved_via} as JSON.
+# Usage: lineage_resolve_prompt <project_key> <session_id> <turn> <transcript_path> [prompt_source]
+lineage_resolve_prompt() {
+	local key="$1" sid="$2" turn="$3" transcript_path="$4" source="${5:-historian_then_transcript}"
+	local prompt="" via="none"
+	local onlooker="${ONLOOKER_DIR:-$HOME/.onlooker}"
+
+	# 1) historian: chunk whose [start_turn_index,end_turn_index] contains the
+	#    turn, else nearest preceding, else the last chunk. body_redacted is the
+	#    conversation context historian preserved for that span.
+	if [[ "$source" != "transcript_only" && -n "$key" && -n "$sid" ]]; then
+		local safe_sid hist_file
+		safe_sid=$(printf '%s' "$sid" | tr -cd '[:alnum:]._-')
+		[[ -z "$safe_sid" ]] && safe_sid="unknown"
+		hist_file="${onlooker}/historian/${key}/sessions/${safe_sid}.jsonl"
+		if [[ -f "$hist_file" ]]; then
+			prompt=$(jq -rs --argjson t "${turn:-0}" '
+				( [ .[] | select((.start_turn_index // 0) <= $t and (.end_turn_index // 0) >= $t) ] | .[0] )
+				// ( [ .[] | select((.end_turn_index // 0) <= $t) ] | sort_by(.end_turn_index) | last )
+				// (.[-1] // empty)
+				| (.body_redacted // "")
+			' "$hist_file" 2>/dev/null) || prompt=""
+			[[ -n "$prompt" ]] && via="historian"
+		fi
+	fi
+
+	# 2) transcript fallback: the turn-th user message (1-based), else the last.
+	#    Tolerant of both transcript shapes (.role/.content and .type/.message.content).
+	if [[ -z "$prompt" && "$source" != "historian_only" && -n "$transcript_path" && -f "$transcript_path" ]]; then
+		prompt=$(jq -rs --argjson t "${turn:-0}" '
+			[ .[]
+			  | select((.role // .type) == "user")
+			  | ((.content // .message.content) as $c
+			     | if ($c | type) == "array"
+			       then [ $c[]? | select(.type == "text") | .text ] | join("\n")
+			       else ($c // "") end)
+			] as $u
+			| ($u[($t - 1)] // ($u[-1] // ""))
+		' "$transcript_path" 2>/dev/null) || prompt=""
+		[[ -n "$prompt" ]] && via="transcript"
+	fi
+
+	# Cap + scrub for display (historian bodies are already redacted; this also
+	# scrubs the transcript path and keeps the excerpt short).
+	prompt=$(printf '%s' "$prompt" | lineage_redact 1000 true)
+
+	jq -nc --arg p "$prompt" --arg v "$via" '{prompt: $p, resolved_via: $v}'
+}