@onlooker-community/ecosystem 0.27.0 → 0.28.1

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

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Build and append lineage change records.
+#
+# Storage: $ONLOOKER_DIR/lineage/<project-key>/changes.jsonl — append-only, one
+# change per line. 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 bus event (lineage.change.recorded) carries metadata + content_sha256
+# only; the added content lives here in the per-project ledger, where the
+# /lineage query content-anchors a line back to the change that introduced it.
+#
+# Requires lineage-redact.sh and portable-lock.sh sourced beforehand.
+
+lineage_record_dir() {
+	local key="${1:-unknown}"
+	local safe
+	safe=$(printf '%s' "$key" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/lineage/%s' "${ONLOOKER_DIR:-${HOME}/.onlooker}" "$safe"
+}
+
+lineage_record_path() { printf '%s/changes.jsonl' "$(lineage_record_dir "$1")"; }
+
+lineage_now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf ''; }
+lineage_now_epoch() { date +%s 2>/dev/null || printf '0'; }
+
+lineage_sha256() {
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$1" | shasum -a 256 2>/dev/null | cut -d' ' -f1
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$1" | sha256sum 2>/dev/null | cut -d' ' -f1
+	else
+		printf ''
+	fi
+}
+
+# Line count of a text blob (0 for empty). `grep -c ''` counts every line,
+# including a final line with no trailing newline.
+_lineage_count_lines() {
+	[[ -z "$1" ]] && { printf '0'; return 0; }
+	printf '%s' "$1" | grep -c '' 2>/dev/null || printf '0'
+}
+
+# Tool → operation enum (create|overwrite|edit|multi_edit). Write is recorded as
+# a coarse "create"; the create/overwrite distinction is not reliably knowable
+# at PostToolUse and does not affect the provenance answer.
+_lineage_operation() {
+	case "$1" in
+		Edit) printf 'edit' ;;
+		MultiEdit) printf 'multi_edit' ;;
+		Write) printf 'create' ;;
+		*) printf 'edit' ;;
+	esac
+}
+
+# Added / removed content extracted from the tool_input JSON, per tool.
+_lineage_added() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.new_string // ""' 2>/dev/null ;;
+		Write) printf '%s' "$ti" | jq -r '.content // ""' 2>/dev/null ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.new_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+_lineage_removed() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.old_string // ""' 2>/dev/null ;;
+		Write) printf '' ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.old_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+# Build a change record JSON (pure — no I/O). Echoes the record.
+# Usage: lineage_build_record <change_id> <ts> <ts_epoch> <session_id> <turn>
+#          <tool> <file_path> <tool_input_json> <max_chars> <do_redact> <transcript_path>
+lineage_build_record() {
+	local change_id="$1" ts="$2" ts_epoch="$3" session_id="$4" turn="$5"
+	local tool="$6" file_path="$7" ti="$8" max_chars="$9" do_redact="${10}" transcript_path="${11}"
+
+	local added removed added_red lines_added lines_removed bytes digest op edit_count
+	added=$(_lineage_added "$tool" "$ti")
+	removed=$(_lineage_removed "$tool" "$ti")
+	lines_added=$(_lineage_count_lines "$added")
+	lines_removed=$(_lineage_count_lines "$removed")
+	bytes=$(printf '%s' "$added" | wc -c | tr -d ' ')
+	digest=$(lineage_sha256 "$added")
+	op=$(_lineage_operation "$tool")
+	edit_count=$(printf '%s' "$ti" | jq -r 'if .edits then (.edits | length) else 1 end' 2>/dev/null) || edit_count=1
+	added_red=$(printf '%s' "$added" | lineage_redact "$max_chars" "$do_redact")
+
+	jq -n \
+		--arg cid "$change_id" --arg ts "$ts" --argjson te "${ts_epoch:-0}" \
+		--arg sid "$session_id" --arg tool "$tool" --arg op "$op" \
+		--arg fp "$file_path" --arg snip "$added_red" --arg tp "$transcript_path" \
+		--argjson la "${lines_added:-0}" --argjson lr "${lines_removed:-0}" \
+		--argjson by "${bytes:-0}" --arg digest "$digest" \
+		--argjson ec "${edit_count:-1}" --arg turn "$turn" \
+		'{
+			change_id: $cid, ts: $ts, ts_epoch: $te,
+			session_id: $sid, tool: $tool, operation: $op, file_path: $fp,
+			lines_added: $la, lines_removed: $lr, bytes: $by,
+			edit_count: $ec, content_sha256: $digest,
+			added_snippets: [$snip], transcript_path: $tp
+		}
+		+ (if $turn != "" then {turn: ($turn | tonumber)} else {} end)' 2>/dev/null
+}
+
+# Append a record to the project ledger under its write lock.
+# Usage: lineage_append <project_key> <record_json>
+lineage_append() {
+	local key="$1" record="$2"
+	[[ -z "$key" || -z "$record" ]] && return 1
+
+	local dir path lock rec_compact
+	dir=$(lineage_record_dir "$key")
+	path="${dir}/changes.jsonl"
+	lock="${path}.lock"
+	mkdir -p "$dir" 2>/dev/null || return 1
+
+	rec_compact=$(printf '%s' "$record" | jq -c . 2>/dev/null) || return 1
+
+	if lock_acquire "$lock" 5; then
+		printf '%s\n' "$rec_compact" >> "$path" 2>/dev/null
+		local ok=$?
+		lock_release "$lock"
+		return "$ok"
+	fi
+	return 1
+}

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Secret redaction + size capping for lineage change snippets.
+#
+# Mirrors the conservative secret patterns in historian-sanitizer.sh (false
+# positives acceptable; false negatives are the failure mode that matters).
+# The heavy lifting runs in an inline python3 block — the same pattern
+# historian uses — because portable case-insensitive regex across BSD/GNU sed
+# is not worth the fragility on a path that handles user code.
+
+# Redact secret-shaped substrings from stdin, then cap to <max_chars>.
+# Usage: printf '%s' "$content" | lineage_redact <max_chars> <redact:true|false>
+lineage_redact() {
+	local max_chars="${1:-4000}"
+	local do_redact="${2:-true}"
+	# Pass the program via -c (not a heredoc on stdin): -c keeps stdin free for
+	# the piped content, so sys.stdin.read() actually receives it.
+	local _prog
+	_prog=$(cat <<'PY'
+import re
+import sys
+
+max_chars = int(sys.argv[1] or "4000")
+do_redact = sys.argv[2] != "false"
+text = sys.stdin.read()
+
+if do_redact:
+    patterns = [
+        re.compile(r"\bAKIA[0-9A-Z]{16}\b"),            # AWS access key id
+        re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),  # GitHub tokens
+        re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}\b"),   # Anthropic API keys
+        re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),         # OpenAI-style keys
+        re.compile(r"(?i:Bearer)\s+[A-Za-z0-9._\-+/=]{20,}"),  # bearer tokens
+    ]
+    for pat in patterns:
+        text = pat.sub("[REDACTED:secret]", text)
+    # KEY=value or "key": "value" where the key name implies a secret;
+    # preserve the key, redact the value.
+    kv = re.compile(
+        r'([A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD)[A-Za-z0-9_]*"?\s*[:=]\s*"?)\S+',
+        re.IGNORECASE,
+    )
+    text = kv.sub(lambda m: m.group(1) + "[REDACTED:secret]", text)
+
+if len(text) > max_chars:
+    text = text[:max_chars] + "… [truncated %d chars]" % (len(text) - max_chars)
+
+sys.stdout.write(text)
+PY
+)
+	python3 -c "$_prog" "$max_chars" "$do_redact"
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for lineage record ids.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+#
+# Copied from plugins/tribunal/scripts/lib/tribunal-ulid.sh and renamed; the
+# ecosystem ships one *_ulid helper per plugin rather than a shared one.
+
+_LINEAGE_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_lineage_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_LINEAGE_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+lineage_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_lineage_ulid_encode "$now_ms" 10)
+	hi_part=$(_lineage_ulid_encode "$rand_hi" 8)
+	lo_part=$(_lineage_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/lineage/scripts/lib/portable-lock.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# portable-lock.sh — vendored copy of the ecosystem substrate's portable lock.
+#
+# Vendored into the lineage plugin so the per-project ledger's atomic upserts
+# keep working when lineage is installed standalone from the marketplace: the
+# cache layout (~/.claude/plugins/cache/<owner>/lineage/<version>/) does not
+# include the ecosystem repo's top-level scripts/lib/. Without a local copy,
+# lock_acquire would be undefined and concurrent PostToolUse appends (e.g.
+# from parallel subagents) could clobber the change ledger. This mirrors the
+# per-plugin vendoring of lineage-ulid.sh and friends.
+# Keep in sync with scripts/lib/portable-lock.sh at the repo root.
+#
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see concurrent writes to $ONLOOKER_DIR silently clobber each other.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}