@onlooker-community/ecosystem 0.28.1 → 0.29.0

package/plugins/inspector/scripts/lib/inspector-run.sh

@@ -0,0 +1,305 @@
+#!/usr/bin/env bash
+# inspector-run.sh — execute the configured checks for a single touched file.
+#
+# Reads:   $INSPECTOR_FILE, $INSPECTOR_FILE_RELATIVE, $INSPECTOR_REPO_ROOT,
+#          $INSPECTOR_PROJECT_KEY, $INSPECTOR_TOOL_NAME
+# Emits:   inspector.check.passed / .failed / .skipped (per check), then
+#          inspector.run.completed (once).
+# Writes:  a compact per-file summary to stdout, intended to be shown to the
+#          agent as PostToolUse additional context.
+
+set -uo pipefail
+
+_inspector_now_ms() {
+	if date +%s%3N &>/dev/null && [[ "$(date +%s%3N)" =~ ^[0-9]{13}$ ]]; then
+		date +%s%3N
+	else
+		python3 -c 'import time; print(int(time.time() * 1000))'
+	fi
+}
+
+# Substitute ${file}, ${file_relative}, ${repo_root} in each argv element.
+_inspector_expand_argv() {
+	local raw_argv_json="$1"
+	jq -c \
+		--arg file "$INSPECTOR_FILE" \
+		--arg rel "$INSPECTOR_FILE_RELATIVE" \
+		--arg root "$INSPECTOR_REPO_ROOT" \
+		'map(
+			gsub("\\$\\{file\\}"; $file)
+			| gsub("\\$\\{file_relative\\}"; $rel)
+			| gsub("\\$\\{repo_root\\}"; $root)
+		)' <<<"$raw_argv_json"
+}
+
+# Run a single check. Stdout: the captured combined output, truncated to
+# output_excerpt_max_bytes. Exit code: the underlying command's exit, or 124 on
+# timeout, or 127 when the command is not on PATH.
+_inspector_invoke_check() {
+	local expanded_json="$1"
+	local timeout_s="$2"
+	local max_bytes="$3"
+
+	# Build argv array from JSON for safe execution.
+	# bash 3.2 (macOS default) has no `mapfile`; collect with a while-read loop.
+	local expanded_argv=()
+	local _line
+	while IFS= read -r _line; do
+		expanded_argv+=("$_line")
+	done < <(jq -r '.[]' <<<"$expanded_json")
+	local cmd="${expanded_argv[0]:-}"
+	if [[ -z "$cmd" ]]; then
+		printf 'inspector: empty argv\n'
+		return 127
+	fi
+	if ! command -v "$cmd" >/dev/null 2>&1; then
+		return 127
+	fi
+
+	local output_file rc=0
+	output_file=$(mktemp -t inspector-out.XXXXXX 2>/dev/null) \
+		|| output_file="/tmp/inspector-out.$$"
+
+	if command -v timeout >/dev/null 2>&1; then
+		timeout "${timeout_s}s" "${expanded_argv[@]}" >"$output_file" 2>&1
+		rc=$?
+	else
+		"${expanded_argv[@]}" >"$output_file" 2>&1
+		rc=$?
+	fi
+
+	# Truncate output for the event payload and the agent-facing line.
+	local bytes=0
+	bytes=$(wc -c <"$output_file" 2>/dev/null || printf '0')
+	if (( bytes > max_bytes )); then
+		head -c "$max_bytes" "$output_file"
+		printf '\n…[truncated]\n'
+	else
+		cat "$output_file"
+	fi
+	rm -f "$output_file"
+	return "$rc"
+}
+
+# Count issues from output — best-effort. One non-empty, non-whitespace line per
+# issue, ignoring trivial header/footer markers. Returns the literal string
+# "null" when the output is empty or only whitespace.
+_inspector_count_issues() {
+	local text="$1"
+	[[ -z "$text" ]] && { printf 'null'; return; }
+	local count
+	count=$(printf '%s' "$text" | grep -cE '^[^[:space:]]' || true)
+	if [[ -z "$count" || "$count" == "0" ]]; then
+		printf 'null'
+	else
+		printf '%s' "$count"
+	fi
+}
+
+# Public entrypoint. Iterates the configured checks for the file's extension.
+inspector_run() {
+	local checks_json="${1:-[]}"
+	local timeout_per_check
+	timeout_per_check=$(inspector_config_timeout_per_check)
+	local total_timeout
+	total_timeout=$(inspector_config_total_timeout)
+	local max_bytes
+	max_bytes=$(inspector_config_output_excerpt_max_bytes)
+	local show_clean=0
+	inspector_config_show_clean_runs && show_clean=1
+
+	local check_count
+	check_count=$(jq 'length' <<<"$checks_json")
+
+	local run_start
+	run_start=$(_inspector_now_ms)
+	local passed=0 failed=0 skipped=0 ran=0
+
+	# Buffer agent-facing output so we only print the file header when at least
+	# one issue (or, when show_clean is set, one check) is worth reporting.
+	local agent_lines=()
+	local issues_seen=0
+
+	local i
+	for (( i = 0; i < check_count; i++ )); do
+		# Budget check before each run.
+		local now_ms
+		now_ms=$(_inspector_now_ms)
+		if (( (now_ms - run_start) >= (total_timeout * 1000) )); then
+			local rem
+			rem=$(jq -c --argjson i "$i" '.[$i:]' <<<"$checks_json")
+			local rem_count
+			rem_count=$(jq 'length' <<<"$rem")
+			local j
+			for (( j = 0; j < rem_count; j++ )); do
+				local r_name r_kind
+				r_name=$(jq -r --argjson j "$j" '.[$j].name // "check"' <<<"$rem")
+				r_kind=$(jq -r --argjson j "$j" '.[$j].kind // "lint"' <<<"$rem")
+				_inspector_emit_skipped "$r_name" "$r_kind" "total_budget_exhausted"
+				(( skipped++ ))
+			done
+			break
+		fi
+
+		local check_name check_kind argv_raw
+		check_name=$(jq -r --argjson i "$i" '.[$i].name' <<<"$checks_json")
+		check_kind=$(jq -r --argjson i "$i" '.[$i].kind' <<<"$checks_json")
+		argv_raw=$(jq -c --argjson i "$i" '.[$i].argv' <<<"$checks_json")
+		local argv_expanded
+		argv_expanded=$(_inspector_expand_argv "$argv_raw")
+
+		local check_start
+		check_start=$(_inspector_now_ms)
+		local output rc=0
+		output=$(_inspector_invoke_check "$argv_expanded" "$timeout_per_check" "$max_bytes")
+		rc=$?
+		local check_end
+		check_end=$(_inspector_now_ms)
+		local dur=$(( check_end - check_start ))
+
+		if (( rc == 127 )); then
+			# Tool not on PATH.
+			_inspector_emit_skipped "$check_name" "$check_kind" "tool_missing"
+			(( skipped++ ))
+			continue
+		fi
+
+		if (( rc == 124 )); then
+			# Timed out — emit skipped + a single agent-facing line.
+			_inspector_emit_skipped "$check_name" "$check_kind" "timeout"
+			agent_lines+=("  · $check_name timed out after ${timeout_per_check}s")
+			(( skipped++ ))
+			(( issues_seen++ ))
+			continue
+		fi
+
+		(( ran++ ))
+		if (( rc == 0 )); then
+			(( passed++ ))
+			_inspector_emit_passed "$check_name" "$check_kind" "$argv_expanded" "$dur"
+			if (( show_clean )); then
+				agent_lines+=("  ✓ $check_name (${dur}ms)")
+			fi
+		else
+			(( failed++ ))
+			local issue_count
+			issue_count=$(_inspector_count_issues "$output")
+			_inspector_emit_failed "$check_name" "$check_kind" "$argv_expanded" "$dur" "$rc" "$issue_count" "$output"
+			local issues_label="${issue_count}"
+			if [[ "$issues_label" == "null" ]]; then
+				issues_label="issues"
+			else
+				issues_label="${issues_label} issue(s)"
+			fi
+			agent_lines+=("  ✗ $check_name (${issues_label}, exit ${rc})")
+			# Append up to 6 issue lines for at-a-glance context.
+			local snippet
+			snippet=$(printf '%s\n' "$output" | grep -E '^[^[:space:]]' | head -n 6 || true)
+			while IFS= read -r line; do
+				[[ -z "$line" ]] && continue
+				agent_lines+=("      $line")
+			done <<<"$snippet"
+			(( issues_seen++ ))
+		fi
+	done
+
+	local run_end
+	run_end=$(_inspector_now_ms)
+	local run_dur=$(( run_end - run_start ))
+
+	_inspector_emit_run_completed "$ran" "$passed" "$failed" "$skipped" "$run_dur"
+
+	if (( issues_seen > 0 )) || (( show_clean && (passed + failed) > 0 )); then
+		printf 'inspector: %s\n' "$INSPECTOR_FILE_RELATIVE"
+		printf '%s\n' "${agent_lines[@]}"
+	fi
+}
+
+_inspector_emit_passed() {
+	local name="$1" kind="$2" argv_json="$3" dur="$4"
+	local payload
+	payload=$(jq -n \
+		--arg file "$INSPECTOR_FILE" \
+		--arg rel "$INSPECTOR_FILE_RELATIVE" \
+		--arg tool "$INSPECTOR_TOOL_NAME" \
+		--arg name "$name" \
+		--arg kind "$kind" \
+		--arg pk "$INSPECTOR_PROJECT_KEY" \
+		--argjson argv "$argv_json" \
+		--argjson dur "$dur" \
+		'{file_path:$file,file_path_relative:$rel,tool_name:$tool,check_name:$name,check_kind:$kind,argv:$argv,duration_ms:$dur,project_key:$pk}')
+	inspector_emit_event "inspector.check.passed" "$payload" || true
+}
+
+_inspector_emit_failed() {
+	local name="$1" kind="$2" argv_json="$3" dur="$4" rc="$5" issues="$6" output="$7"
+	local issues_arg
+	if [[ "$issues" == "null" ]]; then
+		issues_arg="null"
+	else
+		issues_arg="$issues"
+	fi
+	local truncated="false"
+	[[ "$output" == *"…[truncated]"* ]] && truncated="true"
+	local payload
+	payload=$(jq -n \
+		--arg file "$INSPECTOR_FILE" \
+		--arg rel "$INSPECTOR_FILE_RELATIVE" \
+		--arg tool "$INSPECTOR_TOOL_NAME" \
+		--arg name "$name" \
+		--arg kind "$kind" \
+		--arg pk "$INSPECTOR_PROJECT_KEY" \
+		--arg output "$output" \
+		--argjson argv "$argv_json" \
+		--argjson dur "$dur" \
+		--argjson rc "$rc" \
+		--argjson issues "$issues_arg" \
+		--argjson truncated "$truncated" \
+		'{file_path:$file,file_path_relative:$rel,tool_name:$tool,check_name:$name,check_kind:$kind,argv:$argv,duration_ms:$dur,exit_code:$rc,issue_count:$issues,output_excerpt:$output,output_truncated:$truncated,project_key:$pk}')
+	inspector_emit_event "inspector.check.failed" "$payload" || true
+}
+
+_inspector_emit_skipped() {
+	local name="$1" kind="$2" reason="$3"
+	local payload
+	payload=$(jq -n \
+		--arg file "$INSPECTOR_FILE" \
+		--arg rel "$INSPECTOR_FILE_RELATIVE" \
+		--arg tool "$INSPECTOR_TOOL_NAME" \
+		--arg name "$name" \
+		--arg kind "$kind" \
+		--arg reason "$reason" \
+		--arg pk "$INSPECTOR_PROJECT_KEY" \
+		'{file_path:$file,file_path_relative:$rel,tool_name:$tool,check_name:$name,check_kind:$kind,reason:$reason,project_key:$pk}')
+	inspector_emit_event "inspector.check.skipped" "$payload" || true
+}
+
+inspector_emit_whole_file_skipped() {
+	local reason="$1"
+	local payload
+	payload=$(jq -n \
+		--arg file "${INSPECTOR_FILE:-}" \
+		--arg rel "${INSPECTOR_FILE_RELATIVE:-}" \
+		--arg tool "${INSPECTOR_TOOL_NAME:-}" \
+		--arg reason "$reason" \
+		--arg pk "${INSPECTOR_PROJECT_KEY:-}" \
+		'{file_path:$file,file_path_relative:$rel,tool_name:$tool,reason:$reason,project_key:$pk}')
+	inspector_emit_event "inspector.check.skipped" "$payload" || true
+}
+
+_inspector_emit_run_completed() {
+	local ran="$1" passed="$2" failed="$3" skipped="$4" dur="$5"
+	local payload
+	payload=$(jq -n \
+		--arg file "$INSPECTOR_FILE" \
+		--arg rel "$INSPECTOR_FILE_RELATIVE" \
+		--arg tool "$INSPECTOR_TOOL_NAME" \
+		--arg pk "$INSPECTOR_PROJECT_KEY" \
+		--argjson ran "$ran" \
+		--argjson passed "$passed" \
+		--argjson failed "$failed" \
+		--argjson skipped "$skipped" \
+		--argjson dur "$dur" \
+		'{file_path:$file,file_path_relative:$rel,tool_name:$tool,checks_run:$ran,checks_passed:$passed,checks_failed:$failed,checks_skipped:$skipped,duration_ms:$dur,project_key:$pk}')
+	inspector_emit_event "inspector.run.completed" "$payload" || true
+}

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# inspector-ulid.sh — ULID generation for Inspector.
+#
+# 10-char Crockford Base32 timestamp + 16-char random component = 26 chars.
+#
+# Usage:
+#   id=$(inspector_ulid)
+
+_INSPECTOR_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_inspector_ulid_encode() {
+	local n="${1:-0}"
+	local len="${2:-10}"
+	local result=""
+	local i
+	for (( i = 0; i < len; i++ )); do
+		result="${_INSPECTOR_ULID_ALPHABET:$(( n & 31 )):1}${result}"
+		n=$(( n >> 5 ))
+	done
+	printf '%s' "$result"
+}
+
+inspector_ulid() {
+	local ts_ms
+	if date +%s%3N &>/dev/null && [[ "$(date +%s%3N)" =~ ^[0-9]{13}$ ]]; then
+		ts_ms=$(date +%s%3N)
+	else
+		ts_ms=$(python3 -c 'import time; print(int(time.time() * 1000))')
+	fi
+
+	local ts_encoded
+	ts_encoded=$(_inspector_ulid_encode "$ts_ms" 10)
+
+	local rand_hex
+	rand_hex=$(openssl rand -hex 10 2>/dev/null) \
+		|| rand_hex=$(printf '%020x' $(( (RANDOM * RANDOM & 0xFFFFF) * 0x100000 + (RANDOM * RANDOM & 0xFFFFF) )))
+
+	local rand_hi rand_lo
+	rand_hi=$(( 16#${rand_hex:0:10} ))
+	rand_lo=$(( 16#${rand_hex:10:10} ))
+	local rand_encoded
+	rand_encoded="$(_inspector_ulid_encode "$rand_hi" 8)$(_inspector_ulid_encode "$rand_lo" 8)"
+
+	printf '%s%s' "$ts_encoded" "$rand_encoded"
+}

package/test/bats/archivist-project-key.bats

@@ -73,3 +73,82 @@ setup() {
   [ -n "$kb" ]
   [ "$ka" != "$kb" ]
 }
+
+@test "archivist_project_remote_url prints origin url when set" {
+  local d="${BATS_TEST_TMPDIR}/remote-set"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" remote add origin https://example.com/x.git
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ "$output" = "https://example.com/x.git" ]
+}
+
+@test "archivist_project_remote_url returns empty when repo has no remote" {
+  local d="${BATS_TEST_TMPDIR}/remote-none"
+  mkdir -p "$d"
+  git -C "$d" init -q
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_remote_url returns empty for a non-git directory" {
+  local d="${BATS_TEST_TMPDIR}/remote-non-git"
+  mkdir -p "$d"
+
+  run archivist_project_remote_url "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_remote_url returns empty for a nonexistent path" {
+  run archivist_project_remote_url "${BATS_TEST_TMPDIR}/does-not-exist"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_repo_root prints the repo toplevel realpath" {
+  local d="${BATS_TEST_TMPDIR}/root-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+
+  # Physical path: matches the function's pwd -P resolution on platforms
+  # (e.g. macOS) where the temp dir is reached through a symlink.
+  local expected
+  expected="$(cd "$d" && pwd -P)"
+
+  run archivist_project_repo_root "$d"
+  [ "$status" -eq 0 ]
+  [ "$output" = "$expected" ]
+}
+
+@test "archivist_project_repo_root resolves toplevel from a subdirectory" {
+  local d="${BATS_TEST_TMPDIR}/root-repo-sub"
+  mkdir -p "$d/nested/deep"
+  git -C "$d" init -q
+
+  local expected
+  expected="$(cd "$d" && pwd -P)"
+
+  run archivist_project_repo_root "$d/nested/deep"
+  [ "$status" -eq 0 ]
+  [ "$output" = "$expected" ]
+}
+
+@test "archivist_project_repo_root returns empty for a non-git directory" {
+  local d="${BATS_TEST_TMPDIR}/root-non-git"
+  mkdir -p "$d"
+
+  run archivist_project_repo_root "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "archivist_project_repo_root returns empty for a nonexistent path" {
+  run archivist_project_repo_root "${BATS_TEST_TMPDIR}/root-missing"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}

package/test/bats/archivist-storage.bats

@@ -117,3 +117,82 @@ setup() {
   first_id=$(printf '%s' "$ranked" | jq -r '.[0].id')
   [ "$first_id" = "$newer_id" ]
 }
+
+@test "storage_root prints the archivist dir under ONLOOKER_DIR" {
+  run archivist_storage_root
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist" ]
+}
+
+@test "project_dir prints root joined with the key" {
+  local key="abc123def456"
+  run archivist_project_dir "$key"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}" ]
+}
+
+@test "kind_dir prints the per-kind subdir under the project dir" {
+  local key="abc123def456"
+  run archivist_kind_dir "$key" "decisions"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}/decisions" ]
+}
+
+@test "kind_dir honors an arbitrary kind name" {
+  local key="abc123def456"
+  run archivist_kind_dir "$key" "dead_ends"
+  [ "$status" -eq 0 ]
+  [ "$output" = "${ONLOOKER_DIR}/archivist/${key}/dead_ends" ]
+}
+
+@test "write_manifest creates manifest.json under the project dir" {
+  local key="abc123def456"
+  run archivist_storage_write_manifest "$key" "git@github.com:org/repo.git" "$REPO"
+  [ "$status" -eq 0 ]
+  [ -f "${ONLOOKER_DIR}/archivist/${key}/manifest.json" ]
+}
+
+@test "write_manifest records the project_key, remote_url, and repo_root" {
+  local key="abc123def456"
+  local remote="git@github.com:org/repo.git"
+  archivist_storage_write_manifest "$key" "$remote" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.project_key' "$manifest")" = "$key" ]
+  [ "$(jq -r '.remote_url' "$manifest")" = "$remote" ]
+  [ "$(jq -r '.repo_root' "$manifest")" = "$REPO" ]
+  [ "$(jq -r '.source' "$manifest")" = "local" ]
+}
+
+@test "write_manifest stamps an ISO-8601 last_compact_at timestamp" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "remote" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  local ts
+  ts=$(jq -r '.last_compact_at' "$manifest")
+  [[ "$ts" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]]
+}
+
+@test "write_manifest stores null for an empty remote_url" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "" "$REPO"
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.remote_url' "$manifest")" = "null" ]
+  [ "$(jq '.remote_url == null' "$manifest")" = "true" ]
+}
+
+@test "write_manifest stores null for an empty repo_root" {
+  local key="abc123def456"
+  archivist_storage_write_manifest "$key" "remote" ""
+  local manifest="${ONLOOKER_DIR}/archivist/${key}/manifest.json"
+
+  [ "$(jq -r '.repo_root' "$manifest")" = "null" ]
+  [ "$(jq '.repo_root == null' "$manifest")" = "true" ]
+}
+
+@test "write_manifest rejects an empty key" {
+  run archivist_storage_write_manifest "" "remote" "$REPO"
+  [ "$status" -ne 0 ]
+}

package/test/bats/compact-tracker.bats

@@ -71,3 +71,128 @@ setup() {
 @test "compact_tracker_estimate_tokens estimates from string length" {
   [ "$(compact_tracker_estimate_tokens "abcdefghij" false)" -eq 2 ]
 }
+
+@test "compact_tracker_state_file prints path under compact trackers dir" {
+  local session_id="unit-state-file"
+  local result
+  result=$(compact_tracker_state_file "$session_id")
+  [ "$result" = "${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}" ]
+}
+
+@test "compact_tracker_record_pre creates state file with pending and compact_count 1" {
+  local session_id="unit-record-pre-1"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+
+  [ -f "$state_file" ]
+  jq -e '.pending == true
+    and .trigger == "manual"
+    and .compact_count == 1
+    and (.started_ms | type) == "number"' \
+    "$state_file" >/dev/null
+}
+
+@test "compact_tracker_record_pre increments compact_count on second call" {
+  local session_id="unit-record-pre-2"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+  jq -e '.compact_count == 1' "$state_file" >/dev/null
+
+  compact_tracker_record_pre "$session_id" '{"trigger":"manual","transcript_path":""}'
+  jq -e '.compact_count == 2' "$state_file" >/dev/null
+}
+
+@test "compact_tracker_record_pre preserves custom_instructions when present" {
+  local session_id="unit-record-pre-3"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file"
+
+  compact_tracker_record_pre "$session_id" \
+    '{"trigger":"manual","transcript_path":"","custom_instructions":"keep the API design notes"}'
+
+  jq -e '.custom_instructions == "keep the API design notes"' "$state_file" >/dev/null
+}
+
+@test "compact_tracker_append_summary appends a JSONL record" {
+  local session_id="unit-append-1"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  compact_tracker_append_summary "$session_id" \
+    '{"trigger":"manual","compact_summary":"first summary"}'
+
+  [ -f "$summary_file" ]
+  # Records are written as a JSON stream; count objects rather than physical lines.
+  [ "$(jq -s 'length' "$summary_file")" -eq 1 ]
+  jq -se '.[0].compact_summary == "first summary" and .[0].trigger == "manual"' "$summary_file" >/dev/null
+}
+
+@test "compact_tracker_append_summary appends a second line on second call" {
+  local session_id="unit-append-2"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  compact_tracker_append_summary "$session_id" '{"trigger":"manual","compact_summary":"one"}'
+  compact_tracker_append_summary "$session_id" '{"trigger":"auto","compact_summary":"two"}'
+
+  [ "$(jq -s 'length' "$summary_file")" -eq 2 ]
+  [ "$(jq -s -r '.[0].compact_summary' "$summary_file")" = "one" ]
+  [ "$(jq -s -r '.[1].trigger' "$summary_file")" = "auto" ]
+}
+
+@test "compact_tracker_append_summary is a no-op when compact_summary is empty" {
+  local session_id="unit-append-3"
+  local summary_file="${ONLOOKER_SESSION_SUMMARIES_DIR}/${session_id}.jsonl"
+  rm -f "$summary_file"
+
+  run compact_tracker_append_summary "$session_id" '{"trigger":"manual","compact_summary":""}'
+  [ "$status" -eq 0 ]
+  [ ! -f "$summary_file" ]
+}
+
+@test "compact_tracker_build_compact_payload uses tokens_before from state file" {
+  local session_id="unit-build-payload"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  printf '%s\n' '{"tokens_before":1000}' >"$state_file"
+
+  local payload
+  payload=$(compact_tracker_build_compact_payload "$session_id" \
+    '{"compact_summary":"a short compacted summary of the prior context"}')
+
+  echo "$payload" | jq -e '.tokens_before == 1000
+    and (.tokens_after | type) == "number"
+    and (.compression_ratio | type) == "number"' >/dev/null
+}
+
+@test "compact_tracker_record_post finalizes state and resets turn_tool_seq" {
+  local session_id="unit-record-post-1"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+
+  printf '%s\n' '{"pending":true,"started_ms":1700000000000,"compact_count":1}' >"$state_file"
+  printf '%s\n' '{"turn_number":3,"turn_tool_seq":5}' >"$tracker_file"
+
+  compact_tracker_record_post "$session_id" '{"trigger":"manual","compact_summary":"done"}'
+
+  jq -e '.pending == false and (.completed_ms | type) == "number"' "$state_file" >/dev/null
+  jq -e '.turn_tool_seq == 0 and .turn_number == 3' "$tracker_file" >/dev/null
+}
+
+@test "compact_tracker_record_post falls back to create state when none exists" {
+  local session_id="unit-record-post-2"
+  local state_file="${ONLOOKER_COMPACT_TRACKERS_DIR}/${session_id}"
+  local tracker_file="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  rm -f "$state_file" "$tracker_file"
+
+  compact_tracker_record_post "$session_id" '{"trigger":"auto","compact_summary":"recovered"}'
+
+  [ -f "$state_file" ]
+  jq -e '.pending == false
+    and (.completed_ms | type) == "number"
+    and .compact_count == 1' \
+    "$state_file" >/dev/null
+}