@onlooker-community/ecosystem 0.28.1 → 0.29.1

package/test/bats/onlooker-schema.bats

@@ -0,0 +1,111 @@
+#!/usr/bin/env bats
+
+# Exercises scripts/lib/onlooker-schema.sh — the bash wrappers around the
+# canonical event emitter (scripts/lib/onlooker-event.mjs). Events are
+# validated against the real installed @onlooker-community/schema.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	load_validate_path
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export ONLOOKER_PLUGIN_NAME="onlooker"
+	# shellcheck disable=SC1091
+	source "${REPO_ROOT}/scripts/lib/onlooker-schema.sh"
+}
+
+_fixture() {
+	cat "${REPO_ROOT}/test/fixtures/hook-inputs/${1}"
+}
+
+# --- onlooker_append_event -------------------------------------------------
+
+@test "onlooker_append_event appends a parseable line carrying the event_type" {
+	local line
+	line='{"event_type":"tool.file.read","payload":{"path":"/x"}}'
+	run onlooker_append_event "$line"
+	[ "$status" -eq 0 ]
+
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	# Round-trips through jq (valid JSON) and preserves the event_type.
+	[ "$(printf '%s' "$last" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_append_event with empty input is a no-op returning 0" {
+	run onlooker_append_event ""
+	[ "$status" -eq 0 ]
+	# No log line written.
+	[ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "onlooker_append_event creates parent dirs when missing" {
+	# Point the log at a path whose parent does not yet exist.
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/nested/deeper/onlooker-events.jsonl"
+	[ ! -d "$(dirname "$ONLOOKER_EVENTS_LOG")" ]
+
+	run onlooker_append_event '{"event_type":"tool.file.read"}'
+	[ "$status" -eq 0 ]
+	[ -d "$(dirname "$ONLOOKER_EVENTS_LOG")" ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_append_event appends rather than truncating" {
+	onlooker_append_event '{"event_type":"tool.file.read"}'
+	onlooker_append_event '{"event_type":"tool.shell.exec"}'
+	[ "$(wc -l <"$ONLOOKER_EVENTS_LOG" | tr -d ' ')" -eq 2 ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.shell.exec" ]
+}
+
+# --- onlooker_event_from_hook ----------------------------------------------
+
+@test "onlooker_event_from_hook maps a mappable fixture to tool.file.read" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture post-tool-use-read.json)")
+	[ -n "$event" ]
+	[ "$(printf '%s' "$event" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_event_from_hook output validates against the schema" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture post-tool-use-read.json)")
+	[ -n "$event" ]
+	printf '%s' "$event" | node "$_ONLOOKER_EVENT_JS" validate
+}
+
+@test "onlooker_event_from_hook prints empty for an unmappable fixture" {
+	local event
+	event=$(onlooker_event_from_hook "$(_fixture session-start-startup.json)")
+	[ -z "$event" ]
+}
+
+@test "onlooker_event_from_hook with empty input returns 0 and prints nothing" {
+	run onlooker_event_from_hook ""
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+# --- onlooker_emit_from_hook -----------------------------------------------
+
+@test "onlooker_emit_from_hook writes exactly one tool.file.read line" {
+	run onlooker_emit_from_hook "$(_fixture post-tool-use-read.json)"
+	[ "$status" -eq 0 ]
+
+	[ "$(wc -l <"$ONLOOKER_EVENTS_LOG" | tr -d ' ')" -eq 1 ]
+	[ "$(tail -n 1 "$ONLOOKER_EVENTS_LOG" | jq -r '.event_type')" = "tool.file.read" ]
+}
+
+@test "onlooker_emit_from_hook leaves the log empty for an unmappable fixture" {
+	run onlooker_emit_from_hook "$(_fixture session-start-startup.json)"
+	[ "$status" -eq 0 ]
+	[ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "onlooker_emit_from_hook records blocked=true for a failed Bash tool" {
+	run onlooker_emit_from_hook "$(_fixture post-tool-use-failure-bash.json)"
+	[ "$status" -eq 0 ]
+
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ "$(printf '%s' "$last" | jq -r '.event_type')" = "tool.shell.exec" ]
+	[ "$(printf '%s' "$last" | jq -r '.payload.blocked')" = "true" ]
+}

package/test/bats/prompt-rules.bats

@@ -267,3 +267,101 @@ write_project_rules() {
   echo "$out" | grep -A2 "id: r1" | grep -q "fired: yes"
   echo "$out" | grep -A2 "id: r2" | grep -q "fired: no"
 }
+
+@test "project_path: appends .claude/prompt-rules.json to the given cwd" {
+  local path
+  path=$(prompt_rules_project_path "/some/where")
+  [ "$path" = "/some/where/.claude/prompt-rules.json" ]
+}
+
+@test "project_path: defaults to \$PWD when no cwd is given" {
+  local path expected
+  path=$(prompt_rules_project_path)
+  expected="$PWD/.claude/prompt-rules.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "fired_path: builds path under the sessions dir from the session id" {
+  local path expected
+  path=$(prompt_rules_fired_path "sess-XYZ")
+  expected="$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/sess-XYZ.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "fired_path: defaults session id to 'unknown' when none is given" {
+  local path expected
+  path=$(prompt_rules_fired_path)
+  expected="$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/unknown.json"
+  [ "$path" = "$expected" ]
+}
+
+@test "emit: appends a JSON event line with type, session, payload, and plugin" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-emit" "prompt_rule.matched" '{"rule_id":"rule-1"}'
+  [ "$status" -eq 0 ]
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.event_type')" = "prompt_rule.matched" ]
+  [ "$(echo "$line" | jq -r '.session_id')" = "sess-emit" ]
+  [ "$(echo "$line" | jq -r '.payload.rule_id')" = "rule-1" ]
+  # No ONLOOKER_PLUGIN_NAME exported in this test → defaults to "onlooker".
+  [ "$(echo "$line" | jq -r '.plugin')" = "onlooker" ]
+}
+
+@test "emit: honors ONLOOKER_PLUGIN_NAME for the plugin field" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  ONLOOKER_PLUGIN_NAME="prompt-rules" prompt_rules_emit "sess-plugin" "prompt_rule.applied" '{"rule_id":"r9"}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.plugin')" = "prompt-rules" ]
+}
+
+@test "emit: defaults payload to an empty object when none is given" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-nopayload" "prompt_rule.matched"
+  [ "$status" -eq 0 ]
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -c '.payload')" = "{}" ]
+}
+
+@test "emit: defaults session id to 'unknown' when none is given" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  prompt_rules_emit "" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.session_id')" = "unknown" ]
+}
+
+@test "emit: includes a numeric turn field when ONLOOKER_TURN_NUMBER is exported" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  ONLOOKER_TURN_NUMBER=7 prompt_rules_emit "sess-turn" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -r '.turn')" = "7" ]
+  [ "$(echo "$line" | jq -r '.turn | type')" = "number" ]
+}
+
+@test "emit: omits the turn field when ONLOOKER_TURN_NUMBER is unset" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  # Guard against any ambient value leaking in from the environment.
+  unset ONLOOKER_TURN_NUMBER
+  prompt_rules_emit "sess-noturn" "prompt_rule.matched" '{}'
+
+  local line
+  line=$(tail -1 "$ONLOOKER_EVENTS_LOG")
+  [ "$(echo "$line" | jq -e 'has("turn")')" = "false" ] || \
+    [ "$(echo "$line" | jq 'has("turn")')" = "false" ]
+}
+
+@test "emit: returns 1 and writes nothing when event_type is empty" {
+  : >"$ONLOOKER_EVENTS_LOG"
+  run prompt_rules_emit "sess-empty" ""
+  [ "$status" -eq 1 ]
+  [ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}

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
+}