@onlooker-community/ecosystem 0.28.1 → 0.29.0

package/test/bats/session-tracker.bats

@@ -73,3 +73,263 @@ setup() {
 @test "session_tracker_map_end_reason maps logout to user_exit" {
   [ "$(session_tracker_map_end_reason logout)" = "user_exit" ]
 }
+
+# Seed a tracker file's start_time_ms to a deterministic point in the past.
+# Usage: seed_start_ms_ago "$session_id" 5000
+seed_start_ms_ago() {
+  local session_id="$1"
+  local ago_ms="$2"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${session_id}"
+  turn_state_ensure_session "$session_id"
+  local past
+  past=$(( $(session_tracker_now_ms) - ago_ms ))
+  jq --argjson start_ms "$past" '.start_time_ms = $start_ms' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+}
+
+@test "session_tracker_now_ms returns 13-digit epoch milliseconds" {
+  local ms
+  ms=$(session_tracker_now_ms)
+  [[ "$ms" =~ ^[0-9]+$ ]]
+  [ "${#ms}" -eq 13 ]
+}
+
+@test "session_tracker_now_ms is monotonic-ish across two calls" {
+  local first second
+  first=$(session_tracker_now_ms)
+  second=$(session_tracker_now_ms)
+  [ "$second" -ge "$first" ]
+}
+
+@test "session_tracker_git_context returns nothing for empty cwd" {
+  run session_tracker_git_context ""
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "session_tracker_git_context returns two empty lines for non-git dir" {
+  local non_git="${BATS_TEST_TMPDIR}/not-a-repo"
+  mkdir -p "$non_git"
+  run session_tracker_git_context "$non_git"
+  [ "$status" -eq 0 ]
+  # Two empty fields: branch line + commit line, both empty.
+  [ -z "$output" ]
+  local branch commit
+  branch=$(session_tracker_git_context "$non_git" | sed -n '1p')
+  commit=$(session_tracker_git_context "$non_git" | sed -n '2p')
+  [ -z "$branch" ]
+  [ -z "$commit" ]
+}
+
+@test "session_tracker_git_context returns branch and short commit for a repo" {
+  local repo="${BATS_TEST_TMPDIR}/gitrepo"
+  mkdir -p "$repo"
+  git -C "$repo" init -q -b trunk
+  git -C "$repo" config user.email "test@example.com"
+  git -C "$repo" config user.name "Test"
+  touch "$repo/file.txt"
+  git -C "$repo" add file.txt
+  git -C "$repo" commit -q -m "initial"
+
+  local out branch commit
+  out=$(session_tracker_git_context "$repo")
+  branch=$(echo "$out" | sed -n '1p')
+  commit=$(echo "$out" | sed -n '2p')
+  [ "$branch" = "trunk" ]
+  [[ "$commit" =~ ^[0-9a-f]{7}$ ]]
+}
+
+@test "session_tracker_record_start writes start metadata to tracker" {
+  local sid="rec-start-001"
+  local input='{"cwd":"/p","source":"startup","model":"m","transcript_path":"/t","agent_type":"a"}'
+  session_tracker_record_start "$sid" "$input"
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  [ -f "$tracker" ]
+  jq -e '.cwd == "/p"
+    and .start_source == "startup"
+    and .model == "m"
+    and .transcript_path == "/t"
+    and .agent_type == "a"
+    and (.start_time_ms | type) == "number"
+    and .start_time_ms > 0' "$tracker" >/dev/null
+}
+
+@test "session_tracker_record_start no-ops on empty input" {
+  local sid="rec-start-empty"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  rm -f "$tracker"
+  run session_tracker_record_start "$sid" ""
+  [ "$status" -eq 0 ]
+  [ ! -f "$tracker" ]
+}
+
+@test "session_tracker_record_start no-ops on null session_id" {
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/null"
+  rm -f "$tracker"
+  run session_tracker_record_start "null" '{"cwd":"/p"}'
+  [ "$status" -eq 0 ]
+  [ ! -f "$tracker" ]
+}
+
+@test "session_tracker_build_start_payload sets working_directory and git fields in repo" {
+  local repo="${BATS_TEST_TMPDIR}/payload-repo"
+  mkdir -p "$repo"
+  git -C "$repo" init -q -b main
+  git -C "$repo" config user.email "test@example.com"
+  git -C "$repo" config user.name "Test"
+  touch "$repo/f"
+  git -C "$repo" add f
+  git -C "$repo" commit -q -m "init"
+
+  local payload
+  payload=$(session_tracker_build_start_payload "{\"cwd\":\"$repo\"}")
+  echo "$payload" | jq -e --arg wd "$repo" '.working_directory == $wd
+    and .git_branch == "main"
+    and (.git_commit | test("^[0-9a-f]{7}$"))' >/dev/null
+}
+
+@test "session_tracker_build_start_payload falls back to pwd and omits git fields outside repo" {
+  local non_git="${BATS_TEST_TMPDIR}/payload-nogit"
+  mkdir -p "$non_git"
+  local payload
+  payload=$(cd "$non_git" && session_tracker_build_start_payload '{}')
+  echo "$payload" | jq -e --arg wd "$non_git" '.working_directory == $wd
+    and (has("git_branch") | not)
+    and (has("git_commit") | not)' >/dev/null
+}
+
+@test "session_tracker_build_end_payload computes duration, turn_count, and end_reason" {
+  local sid="end-payload-001"
+  seed_start_ms_ago "$sid" 5000
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq '.turn_number = 2' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  local payload
+  payload=$(session_tracker_build_end_payload "$sid" '{"reason":"logout"}')
+  echo "$payload" | jq -e '.duration_ms >= 5000
+    and .turn_count == 2
+    and .end_reason == "user_exit"' >/dev/null
+}
+
+@test "session_tracker_build_end_payload defaults when no tracker exists" {
+  local sid="end-payload-missing"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  local payload
+  payload=$(session_tracker_build_end_payload "$sid" '{"reason":"logout"}')
+  echo "$payload" | jq -e '.duration_ms == 0 and .turn_count == 1' >/dev/null
+}
+
+@test "session_tracker_build_end_payload returns 1 for null session_id" {
+  run session_tracker_build_end_payload "null" '{"reason":"logout"}'
+  [ "$status" -eq 1 ]
+}
+
+@test "session_tracker_duration_ms returns elapsed ms for seeded start" {
+  local sid="dur-001"
+  seed_start_ms_ago "$sid" 3000
+  local dur
+  dur=$(session_tracker_duration_ms "$sid")
+  [[ "$dur" =~ ^[0-9]+$ ]]
+  [ "$dur" -ge 3000 ]
+}
+
+@test "session_tracker_duration_ms returns 0 for null session_id" {
+  [ "$(session_tracker_duration_ms null)" = "0" ]
+}
+
+@test "session_tracker_duration_ms returns 0 for missing tracker" {
+  local sid="dur-missing"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  [ "$(session_tracker_duration_ms "$sid")" = "0" ]
+}
+
+@test "session_tracker_duration_ms returns 0 for invalid start_time_ms" {
+  local sid="dur-invalid"
+  turn_state_ensure_session "$sid"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq '.start_time_ms = "not-a-number"' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+  [ "$(session_tracker_duration_ms "$sid")" = "0" ]
+}
+
+@test "session_tracker_update_duration persists session_duration_ms" {
+  local sid="upd-001"
+  seed_start_ms_ago "$sid" 2000
+  session_tracker_update_duration "$sid"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq -e '.session_duration_ms >= 2000' "$tracker" >/dev/null
+}
+
+@test "session_tracker_update_duration returns 0 for null session_id" {
+  run session_tracker_update_duration "null"
+  [ "$status" -eq 0 ]
+}
+
+@test "session_tracker_update_duration creates tracker with zero duration for new sid" {
+  local sid="upd-new"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  rm -f "$tracker"
+  session_tracker_update_duration "$sid"
+  [ -f "$tracker" ]
+  jq -e '.session_duration_ms == 0' "$tracker" >/dev/null
+}
+
+@test "session_tracker_build_duration_context renders turn and humanized elapsed" {
+  local sid="ctx-001"
+  seed_start_ms_ago "$sid" 154000
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq '.turn_number = 3' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  local out
+  out=$(session_tracker_build_duration_context "$sid")
+  [[ "$out" == *"turn 3"* ]]
+  [[ "$out" == *"2m 34s"* ]]
+}
+
+@test "session_tracker_build_duration_context defaults for missing tracker" {
+  local sid="ctx-missing"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  local out
+  out=$(session_tracker_build_duration_context "$sid")
+  [[ "$out" == *"turn 1"* ]]
+  [[ "$out" == *"0s"* ]]
+}
+
+@test "session_tracker_emit appends to both session history and events log" {
+  export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+  local sid="emit-001"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${sid}.jsonl"
+  rm -f "$history_file"
+  : >"$ONLOOKER_EVENTS_LOG"
+
+  run session_tracker_emit "$sid" "session.start" '{"working_directory":"/tmp"}'
+  [ "$status" -eq 0 ]
+
+  [ -f "$history_file" ]
+  jq -e '.event_type == "session.start" and .session_id == "emit-001"' "$history_file" >/dev/null
+  grep -q '"event_type":"session.start"' "$ONLOOKER_EVENTS_LOG" \
+    || jq -e 'select(.event_type == "session.start" and .session_id == "emit-001")' "$ONLOOKER_EVENTS_LOG" >/dev/null
+}
+
+@test "session_tracker_emit no-ops on empty session_id" {
+  export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+  : >"$ONLOOKER_EVENTS_LOG"
+  run session_tracker_emit "" "session.start" '{"working_directory":"/tmp"}'
+  [ "$status" -eq 0 ]
+  [ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "session_tracker_emit no-ops on empty event_type" {
+  export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+  local sid="emit-noevent"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${sid}.jsonl"
+  rm -f "$history_file"
+  : >"$ONLOOKER_EVENTS_LOG"
+  run session_tracker_emit "$sid" "" '{"working_directory":"/tmp"}'
+  [ "$status" -eq 0 ]
+  [ ! -f "$history_file" ]
+  [ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}

package/test/bats/skill-usage-tracker.bats

@@ -74,3 +74,66 @@ setup() {
   tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -e '.event_type == "skill.invoked"' >/dev/null
   tail -n 1 "$ONLOOKER_EVENTS_LOG" | onlooker_validate_event
 }
+
+@test "skill_usage_append writes a built skill.invoked record to the session history file" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/user-prompt-expansion-skill.json"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/skill-session-001.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  local record
+  record=$(skill_usage_build_record "$(cat "$fixture")")
+
+  run skill_usage_append "skill-session-001" "$record"
+  [ "$status" -eq 0 ]
+
+  [ -f "$history_file" ]
+  tail -n 1 "$history_file" | jq -e \
+    '.event_type == "skill.invoked"
+     and .payload.skill_name == "code-review"
+     and .payload.invocation_source == "slash_command"
+     and .session_id == "skill-session-001"' \
+    >/dev/null
+  tail -n 1 "$history_file" | onlooker_validate_event
+}
+
+@test "skill_usage_append routes the record to the per-session file named after the session id" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/pre-tool-use-skill.json"
+  local session_id="skill-session-custom"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${session_id}.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  # Build a canonical record, then retarget its session_id; skill_usage_append
+  # must file it under the session_id argument, not the embedded one.
+  local record
+  record=$(skill_usage_build_record "$(cat "$fixture")" \
+    | jq -c --arg sid "$session_id" '.session_id = $sid')
+
+  run skill_usage_append "$session_id" "$record"
+  [ "$status" -eq 0 ]
+
+  [ -f "$history_file" ]
+  [ "$(wc -l <"$history_file")" -eq 1 ]
+  tail -n 1 "$history_file" | jq -e \
+    '.session_id == "skill-session-custom"
+     and .payload.skill_name == "code-review"
+     and .payload.invocation_source == "tool"' \
+    >/dev/null
+  tail -n 1 "$history_file" | onlooker_validate_event
+}
+
+@test "skill_usage_append is a no-op when the session id is empty" {
+  local fixture="${REPO_ROOT}/test/fixtures/hook-inputs/pre-tool-use-skill.json"
+  local record
+  record=$(skill_usage_build_record "$(cat "$fixture")")
+
+  # Snapshot the history dir, then assert the empty-session call adds nothing.
+  local before
+  before=$(find "$ONLOOKER_SESSION_HISTORY_DIR" -type f | sort)
+
+  run skill_usage_append "" "$record"
+  [ "$status" -eq 0 ]
+
+  local after
+  after=$(find "$ONLOOKER_SESSION_HISTORY_DIR" -type f | sort)
+  [ "$before" = "$after" ]
+}

package/test/bats/task-tracker.bats

@@ -97,3 +97,105 @@ setup() {
   tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -e '.event_type == "task.start"' >/dev/null
   tail -n 1 "$ONLOOKER_EVENTS_LOG" | onlooker_validate_event
 }
+
+@test "task_tracker_record_created writes start_time_ms as a number" {
+  local sid="rec-session-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+
+  run task_tracker_record_created "$sid" "task-rec-001"
+  [ "$status" -eq 0 ]
+  [ -f "$tracker" ]
+  jq -e '.tasks["task-rec-001"].start_time_ms | type == "number"' "$tracker" >/dev/null
+}
+
+@test "task_tracker_record_created no-ops on empty session_id" {
+  run task_tracker_record_created "" "task-rec-002"
+  [ "$status" -eq 0 ]
+  # load_validate_path always creates the trackers dir; assert no tracker file landed.
+  [ -z "$(find "${ONLOOKER_SESSION_TRACKERS_DIR}" -type f 2>/dev/null)" ]
+}
+
+@test "task_tracker_record_created no-ops on null session_id" {
+  run task_tracker_record_created "null" "task-rec-003"
+  [ "$status" -eq 0 ]
+  [ ! -f "${ONLOOKER_SESSION_TRACKERS_DIR}/null" ]
+}
+
+@test "task_tracker_record_created no-ops on empty task_id" {
+  local sid="rec-session-empty-task"
+  run task_tracker_record_created "$sid" ""
+  [ "$status" -eq 0 ]
+  [ ! -f "${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}" ]
+}
+
+@test "task_tracker_duration_ms returns elapsed ms for a seeded task" {
+  local sid="dur-session-001"
+  turn_state_ensure_session "$sid"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+
+  local past
+  past=$(( $(session_tracker_now_ms) - 2000 ))
+  jq --argjson ms "$past" '.tasks["task-dur-001"] = {start_time_ms: $ms}' \
+    "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  local elapsed
+  elapsed=$(task_tracker_duration_ms "$sid" "task-dur-001")
+  [ -n "$elapsed" ]
+  echo "$elapsed" | grep -Eq '^[0-9]+$'
+  [ "$elapsed" -ge 1900 ]
+}
+
+@test "task_tracker_duration_ms is empty for an unknown task_id" {
+  local sid="dur-session-unknown"
+  turn_state_ensure_session "$sid"
+
+  local out
+  run task_tracker_duration_ms "$sid" "task-does-not-exist"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "task_tracker_clear removes the task timing entry" {
+  local sid="clear-session-001"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+
+  task_tracker_record_created "$sid" "task-clear-001"
+  jq -e '.tasks["task-clear-001"]' "$tracker" >/dev/null
+
+  run task_tracker_clear "$sid" "task-clear-001"
+  [ "$status" -eq 0 ]
+
+  run jq -e '.tasks["task-clear-001"]' "$tracker"
+  [ "$status" -ne 0 ]
+}
+
+@test "task_tracker_clear no-ops when tracker file is missing" {
+  local sid="clear-session-missing"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  rm -f "$tracker"
+
+  run task_tracker_clear "$sid" "task-nope"
+  [ "$status" -eq 0 ]
+  [ ! -f "$tracker" ]
+}
+
+@test "task_tracker_append delegates to tool_history_append" {
+  local sid="append-session-001"
+  local history_file="${ONLOOKER_SESSION_HISTORY_DIR}/${sid}.jsonl"
+  rm -f "$history_file" "${history_file}.lock"
+
+  local event
+  event=$(jq -c -n --arg sid "$sid" \
+    '{schema_version: "1.0",
+      plugin: "ecosystem",
+      session_id: $sid,
+      event_type: "task.start",
+      payload: {task_summary: "append test"}}')
+
+  run task_tracker_append "$sid" "$event"
+  [ "$status" -eq 0 ]
+  [ -f "$history_file" ]
+  tail -n 1 "$history_file" | jq -e '.event_type == "task.start"' >/dev/null
+  tail -n 1 "$history_file" | jq -e '.session_id == "append-session-001"' >/dev/null
+}

package/test/bats/turn-tracker.bats

@@ -0,0 +1,180 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  load_validate_path
+  export CLAUDE_PLUGIN_ROOT="${REPO_ROOT}"
+  # shellcheck source=../../scripts/lib/onlooker-schema.sh
+  source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+  # shellcheck source=../../scripts/lib/tool-history.sh
+  source "${REPO_ROOT}/scripts/lib/tool-history.sh"
+  # shellcheck source=../../scripts/lib/session-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/session-tracker.sh"
+  # shellcheck source=../../scripts/lib/turn-tracker.sh
+  source "${REPO_ROOT}/scripts/lib/turn-tracker.sh"
+}
+
+# ── turn_tracker_summarize_prompt ──────────────────────────────────────────
+
+@test "turn_tracker_summarize_prompt collapses newlines and runs of spaces" {
+  local out
+  out=$(turn_tracker_summarize_prompt $'hello\n\nworld   foo')
+  [ "$out" = "hello world foo" ]
+}
+
+@test "turn_tracker_summarize_prompt trims leading and trailing spaces" {
+  local out
+  out=$(turn_tracker_summarize_prompt "  padded text  ")
+  [ "$out" = "padded text" ]
+}
+
+@test "turn_tracker_summarize_prompt leaves a short prompt unchanged" {
+  local out
+  out=$(turn_tracker_summarize_prompt "fix the bug")
+  [ "$out" = "fix the bug" ]
+}
+
+@test "turn_tracker_summarize_prompt does not truncate input of exactly 200 chars" {
+  local exact
+  exact=$(printf 'b%.0s' {1..200})
+  local out
+  out=$(turn_tracker_summarize_prompt "$exact")
+  [ "${#out}" -eq 200 ]
+  [[ "$out" != *…* ]]
+}
+
+@test "turn_tracker_summarize_prompt truncates to 200 chars plus an ellipsis when over 200" {
+  local long
+  long=$(printf 'a%.0s' {1..300})
+  local out
+  out=$(turn_tracker_summarize_prompt "$long")
+  # 200 retained characters + the single-character ellipsis = length 201.
+  [ "${#out}" -eq 201 ]
+  [[ "$out" == *… ]]
+  [ "${out%…}" = "$(printf 'a%.0s' {1..200})" ]
+}
+
+@test "turn_tracker_summarize_prompt returns empty and succeeds on empty input" {
+  run turn_tracker_summarize_prompt ""
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── turn_tracker_on_user_prompt ────────────────────────────────────────────
+
+@test "turn_tracker_on_user_prompt keeps turn 1 and marks prompts seen on first prompt" {
+  local sid="turn-first-001"
+  turn_tracker_on_user_prompt "$sid"
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  [ -f "$tracker" ]
+  jq -e '.turn_number == 1
+    and .user_prompts_seen == true
+    and .turn_tool_seq == 0' "$tracker" >/dev/null
+}
+
+@test "turn_tracker_on_user_prompt advances the turn on the second prompt" {
+  local sid="turn-second-001"
+  turn_tracker_on_user_prompt "$sid"
+  turn_tracker_on_user_prompt "$sid"
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq -e '.turn_number == 2
+    and .user_prompts_seen == true
+    and .turn_tool_seq == 0' "$tracker" >/dev/null
+}
+
+@test "turn_tracker_on_user_prompt increments once per subsequent prompt" {
+  local sid="turn-many-001"
+  turn_tracker_on_user_prompt "$sid"  # turn 1, marks seen
+  turn_tracker_on_user_prompt "$sid"  # turn 2
+  turn_tracker_on_user_prompt "$sid"  # turn 3
+  turn_tracker_on_user_prompt "$sid"  # turn 4
+
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq -e '.turn_number == 4' "$tracker" >/dev/null
+}
+
+@test "turn_tracker_on_user_prompt no-ops on empty session_id" {
+  run turn_tracker_on_user_prompt ""
+  [ "$status" -eq 0 ]
+  # No tracker file should have been created for an empty id.
+  [ ! -f "${ONLOOKER_SESSION_TRACKERS_DIR}/" ]
+  [ -z "$(ls -A "${ONLOOKER_SESSION_TRACKERS_DIR}")" ]
+}
+
+@test "turn_tracker_on_user_prompt no-ops on null session_id" {
+  run turn_tracker_on_user_prompt "null"
+  [ "$status" -eq 0 ]
+  [ ! -f "${ONLOOKER_SESSION_TRACKERS_DIR}/null" ]
+}
+
+# ── turn_tracker_build_prompt_payload ──────────────────────────────────────
+
+@test "turn_tracker_build_prompt_payload reads turn_number from the tracker and includes input_summary" {
+  local sid="payload-001"
+  turn_state_ensure_session "$sid"
+  local tracker="${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+  jq '.turn_number = 5' "$tracker" >"${tracker}.tmp"
+  mv "${tracker}.tmp" "$tracker"
+
+  local payload
+  payload=$(turn_tracker_build_prompt_payload "$sid" $'review   the\n\ndiff')
+  echo "$payload" | jq -e '.turn_number == 5
+    and .input_summary == "review the diff"' >/dev/null
+}
+
+@test "turn_tracker_build_prompt_payload defaults turn_number to 1 when tracker is missing" {
+  local sid="payload-missing"
+  rm -f "${ONLOOKER_SESSION_TRACKERS_DIR}/${sid}"
+
+  local payload
+  payload=$(turn_tracker_build_prompt_payload "$sid" "hello")
+  echo "$payload" | jq -e '.turn_number == 1 and .input_summary == "hello"' >/dev/null
+}
+
+@test "turn_tracker_build_prompt_payload omits input_summary for an empty prompt" {
+  local sid="payload-empty"
+  turn_state_ensure_session "$sid"
+
+  local payload
+  payload=$(turn_tracker_build_prompt_payload "$sid" "")
+  echo "$payload" | jq -e '.turn_number == 1 and (has("input_summary") | not)' >/dev/null
+}
+
+@test "turn_tracker_build_prompt_payload truncates a long prompt in input_summary" {
+  local sid="payload-long"
+  turn_state_ensure_session "$sid"
+  local long
+  long=$(printf 'x%.0s' {1..300})
+
+  local payload summary
+  payload=$(turn_tracker_build_prompt_payload "$sid" "$long")
+  summary=$(echo "$payload" | jq -r '.input_summary')
+  [ "${#summary}" -eq 201 ]
+  [[ "$summary" == *… ]]
+}
+
+@test "turn_tracker_build_prompt_payload returns 1 for null session_id" {
+  run turn_tracker_build_prompt_payload "null" "hi"
+  [ "$status" -eq 1 ]
+}
+
+@test "turn_tracker_build_prompt_payload returns 1 for empty session_id" {
+  run turn_tracker_build_prompt_payload "" "hi"
+  [ "$status" -eq 1 ]
+}
+
+# ── integration: orchestrator + payload reflect the same turn ──────────────
+
+@test "turn_tracker payload reflects turn advanced by turn_tracker_on_user_prompt" {
+  local sid="turn-integration-001"
+  # Two prompts -> turn 2; payload built afterward should report turn 2.
+  turn_tracker_on_user_prompt "$sid"
+  turn_tracker_on_user_prompt "$sid"
+
+  local payload
+  payload=$(turn_tracker_build_prompt_payload "$sid" "second prompt")
+  echo "$payload" | jq -e '.turn_number == 2 and .input_summary == "second prompt"' >/dev/null
+}