@toolu/opencode 6.8.0

package/plugins/toolu/hooks/lib/push-waiver.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Push-review waivers — "yes, push anyway", remembered for exactly that diff.
+#
+# A PreToolUse hook never learns how the user answered its `ask`. PostToolUse
+# does, implicitly: it runs only when the tool actually ran. So the two halves
+# talk through a file.
+#
+#   1. push-review.sh asks, and records a PENDING waiver naming the diff SHA
+#      it asked about.
+#   2. post-tools/modules/push-waiver.sh sees the push happened, and promotes
+#      the pending marker to a real waiver — but only when the push SUCCEEDED
+#      and the SHA still matches.
+#   3. push-review.sh finds the waiver on the next push of that same diff and
+#      stays quiet. A new commit changes the SHA, so the waiver stops applying
+#      and the gate asks again.
+#
+# A refused ask simply leaves the pending marker behind; nothing promotes it,
+# and the state sweeper reclaims it. Both writes are atomic (tmp + mv) so a
+# half-written waiver can never read as a valid one.
+#
+# Public API:
+#   push_waiver_dir ROOT
+#   push_waiver_path ROOT SLUG
+#   push_waiver_pending_path ROOT SLUG
+#   push_waiver_matches ROOT SLUG SHA
+#   push_waiver_pend ROOT SLUG SHA BASE REASON_CODE
+#   push_waiver_promote ROOT SLUG SHA
+
+_TOOLU_PUSH_WAIVER_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=host.sh
+. "$_TOOLU_PUSH_WAIVER_LIB_DIR/host.sh"
+
+PUSH_WAIVER_VERSION=1
+
+# push_waiver_dir ROOT -> the push-review state directory for ROOT.
+# $STATE_DIR overrides, matching push-review.sh and the toolu-review state
+# writer, so tests and worktree flows point all three at the same place.
+push_waiver_dir() {
+  local root="${1:-}"
+  printf '%s' "${STATE_DIR:-$(toolu_project_state_dir push-review "$root")}"
+}
+
+push_waiver_path() {
+  printf '%s/%s.waiver.json' "$(push_waiver_dir "$1")" "$2"
+}
+
+push_waiver_pending_path() {
+  printf '%s/%s.pending-waiver.json' "$(push_waiver_dir "$1")" "$2"
+}
+
+# _push_waiver_write FILE JSON -> atomic write, 0 on success.
+# A failed mktemp or write leaves no file at all rather than a partial one;
+# the caller decides whether that is fatal (it never is — a missing waiver
+# just means the gate asks again).
+_push_waiver_write() {
+  local file="$1" json="$2" tmp
+  mkdir -p "$(dirname "$file")" 2>/dev/null || return 1
+  tmp=$(mktemp "${file}.XXXXXX" 2>/dev/null) || return 1
+  if printf '%s\n' "$json" > "$tmp" 2>/dev/null; then
+    mv -f "$tmp" "$file" 2>/dev/null && return 0
+  fi
+  rm -f "$tmp" 2>/dev/null
+  return 1
+}
+
+# _push_waiver_sha FILE -> print the diff_sha of a v1 waiver-shaped FILE.
+# Prints nothing (and returns 1) for a missing file, unreadable JSON, or a
+# version this code does not understand — all of which must read as "no
+# waiver", never as a match.
+_push_waiver_sha() {
+  local file="$1" version sha
+  [ -f "$file" ] || return 1
+  version=$(jq -r '.version // ""' "$file" 2>/dev/null) || return 1
+  [ "$version" = "$PUSH_WAIVER_VERSION" ] || return 1
+  sha=$(jq -r '.diff_sha // ""' "$file" 2>/dev/null) || return 1
+  [ -n "$sha" ] || return 1
+  printf '%s' "$sha"
+}
+
+# push_waiver_matches ROOT SLUG SHA -> 0 iff a waiver covers exactly SHA.
+push_waiver_matches() {
+  local root="$1" slug="$2" sha="$3" recorded
+  [ -n "$sha" ] || return 1
+  recorded=$(_push_waiver_sha "$(push_waiver_path "$root" "$slug")") || return 1
+  [ "$recorded" = "$sha" ]
+}
+
+# push_waiver_pend ROOT SLUG SHA BASE REASON_CODE
+# Record that the user was asked about SHA. Overwrites any earlier pending
+# marker: only the most recent question is answerable.
+push_waiver_pend() {
+  local root="$1" slug="$2" sha="$3" base="$4" code="$5" json now
+  [ -n "$sha" ] || return 1
+  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  json=$(jq -cn --argjson version "$PUSH_WAIVER_VERSION" --arg branch "$slug" \
+    --arg sha "$sha" --arg base "$base" --arg code "$code" --arg now "$now" \
+    '{version: $version, branch: $branch, diff_sha: $sha, base_branch: $base,
+      reason_code: $code, asked_at: $now}') || return 1
+  _push_waiver_write "$(push_waiver_pending_path "$root" "$slug")" "$json"
+}
+
+# push_waiver_promote ROOT SLUG SHA -> 0 iff a waiver was written.
+# The SHA guard is the whole point: a pending marker from an older diff must
+# not be cashed in by a push of different code.
+push_waiver_promote() {
+  local root="$1" slug="$2" sha="$3" pending pending_sha json now
+  [ -n "$sha" ] || return 1
+  pending=$(push_waiver_pending_path "$root" "$slug")
+  pending_sha=$(_push_waiver_sha "$pending") || return 1
+  [ "$pending_sha" = "$sha" ] || return 1
+  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  json=$(jq -c --arg now "$now" 'del(.asked_at) + {waived_at: $now}' "$pending" 2>/dev/null) || return 1
+  _push_waiver_write "$(push_waiver_path "$root" "$slug")" "$json" || return 1
+  rm -f "$pending" 2>/dev/null
+  return 0
+}

package/plugins/toolu/hooks/lib/quality-config.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Quality-threshold resolver for the rust-quality / ts-quality hooks.
+#
+# Limits are NOT hardcoded in the quality modules. Each threshold resolves with
+# this precedence (first hit wins, always a positive integer):
+#   1. Project / user override — `lang.<lang>.<key>` in the merged toolu
+#      config (.claude/toolu.config.json), via lib/config.sh.
+#   2. Native tool config (TS + maxFileLines only) — the `max-lines` rule from
+#      .eslintrc.json / .oxlintrc.json. Flat eslint config (eslint.config.{js,mjs,ts})
+#      is JS and NOT parseable here — skipped gracefully.
+#   3. Built-in default (DEFAULT_* below).
+#
+# Every reader is guarded (jq present, file present) and 2>/dev/null — any
+# failure falls through to the next layer. Never errors, never blocks a tool.
+#
+# Source via:  . "$TOOLU_LIB_DIR/quality-config.sh"
+# (pulls in config.sh + detect.sh from the same dir).
+
+_QC_LIB_DIR="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}"
+# shellcheck source=./config.sh
+[ -f "$_QC_LIB_DIR/config.sh" ] && . "$_QC_LIB_DIR/config.sh"
+# shellcheck source=./detect.sh
+[ -f "$_QC_LIB_DIR/detect.sh" ] && . "$_QC_LIB_DIR/detect.sh"
+
+# Built-in defaults — single source of truth, overridable from the environment
+# (tests set these to assert fall-through without touching call sites).
+: "${DEFAULT_TS_MAX_FILE_LINES:=300}"
+: "${DEFAULT_TS_MAX_FN_LINES:=60}"
+: "${DEFAULT_RUST_MAX_FILE_LINES:=500}"
+: "${DEFAULT_RUST_MAX_FN_LINES:=50}"
+: "${DEFAULT_RUST_MAX_IMPL_LINES:=200}"
+: "${DEFAULT_PYTHON_MAX_FILE_LINES:=400}"
+: "${DEFAULT_PYTHON_MAX_FN_LINES:=50}"
+
+# One jq filter that normalizes every eslint/oxlint `max-lines` encoding to a
+# positive integer (or empty): bare number, ["error", N], ["error", {"max": N}].
+# "off" / 0 / negatives / missing all yield empty -> the layer is skipped.
+_QC_ESLINT_MAXLINES_FILTER='
+  .rules?["max-lines"]?
+  | if type=="array" then (
+          if (.[0] == "off" or .[0] == 0) then empty   # rule disabled by severity
+          else ( .[1] | if type=="object" then .max else . end )
+          end )
+    elif (type=="number" or type=="string") then .
+    else empty end
+  | (if type=="string" then (tonumber? // empty) else . end)   # accept "120"
+  | if type=="number" and . > 0 then (.|floor|tostring) else empty end
+'
+
+# _qc_project_override LANG KEY  ->  echoes a positive int or "".
+# Reads the already-merged config cache (config.sh handles user+project merge,
+# malformed JSON, and missing jq).
+_qc_project_override() {
+  local lang="$1" key="$2"
+  command -v toolu_load_config >/dev/null 2>&1 || return 0
+  toolu_load_config
+  [ "${_TOOLU_HAS_JQ:-0}" = "1" ] || return 0
+  [ -n "${TOOLU_CFG_JSON:-}" ] || return 0
+  jq -r --arg l "$lang" --arg k "$key" '
+    ((.lang? // {})[$l]? // {})[$k]?
+    | (if type=="string" then (tonumber? // empty) else . end)   # accept "120"
+    | if type=="number" and . > 0 then (.|floor|tostring) else empty end
+  ' <<< "$TOOLU_CFG_JSON" 2>/dev/null
+}
+
+# quality_flag LANG KEY DEFAULT  ->  echoes "true" or "false".
+# Boolean reader for `.lang.<lang>.<key>` in the merged config, for keys that
+# ARE booleans (e.g. noMocks) — _qc_project_override above filters to positive
+# integers and can't carry a boolean, so this is a separate reader rather than
+# an extension of it. Only a literal JSON `true`/`false` is honored; anything
+# else (key absent, wrong type, malformed config, no jq) falls back to DEFAULT
+# unchanged. Never errors, never blocks a tool.
+quality_flag() {
+  local lang="$1" key="$2" def="$3"
+  command -v toolu_load_config >/dev/null 2>&1 || { printf '%s' "$def"; return 0; }
+  toolu_load_config
+  [ "${_TOOLU_HAS_JQ:-0}" = "1" ] || { printf '%s' "$def"; return 0; }
+  [ -n "${TOOLU_CFG_JSON:-}" ] || { printf '%s' "$def"; return 0; }
+  local val
+  val=$(jq -r --arg l "$lang" --arg k "$key" '
+    ((.lang? // {})[$l]? // {})[$k]?
+    | if type == "boolean" then tostring else empty end
+  ' <<< "$TOOLU_CFG_JSON" 2>/dev/null)
+  case "$val" in
+    true|false) printf '%s' "$val" ;;
+    *)          printf '%s' "$def" ;;
+  esac
+}
+
+# Memoize the git toplevel for this process. detect_project_root shells out to
+# `git rev-parse` every call; the root can't change mid-hook, so cache it once
+# (mirrors toolu_load_config's caching). A separate _CACHED flag is used so
+# an EMPTY result (non-git cwd) is still treated as cached — keying on
+# _QC_PROJECT_ROOT being non-empty would re-shell git on every call there. Tests
+# re-source this file (resetting both) between cases.
+_QC_PROJECT_ROOT=""
+_QC_PROJECT_ROOT_CACHED=0
+_qc_project_root() {
+  [ "$_QC_PROJECT_ROOT_CACHED" = "1" ] && { printf '%s' "$_QC_PROJECT_ROOT"; return 0; }
+  command -v detect_project_root >/dev/null 2>&1 || return 0
+  _QC_PROJECT_ROOT=$(detect_project_root)
+  _QC_PROJECT_ROOT_CACHED=1
+  printf '%s' "$_QC_PROJECT_ROOT"
+}
+
+# _qc_native_ts_max_lines  ->  echoes a positive int or "".
+# Reads the config of the linter detect_ts_linter reports as ACTIVE, so a repo
+# carrying BOTH .eslintrc.json and .oxlintrc.json (e.g. mid-migration) gets the
+# limit from the one it actually runs — not whichever file is listed first.
+# detect_ts_linter precedence is biome > oxc > eslint; biome's max-lines isn't
+# parsed here (no machine-readable rule), so it falls through to the default.
+# Limitation: only JSON config forms are parsed — `.eslintrc.yaml/.yml`, flat
+# `eslint.config.*`, and `package.json#eslintConfig` fall through to the default.
+# detect_ts_linter still reports "eslint" for those, so the over-limit advisory
+# stays honest ("limit didn't come from its config").
+# Limitation: only the top-level `.rules["max-lines"]` is read. A per-glob
+# `overrides[].rules["max-lines"]` is intentionally NOT traversed — picking a
+# value without matching the override's `files` glob to the edited file could
+# enforce a limit that doesn't apply and wrongly BLOCK an edit. We fall through
+# to the (stricter-or-equal) default instead; the over-limit advisory says so.
+_qc_native_ts_max_lines() {
+  command -v jq >/dev/null 2>&1 || return 0
+  local root linter f v
+  root=$(_qc_project_root)
+  [ -n "$root" ] || return 0
+  # Map the active linter to its machine-readable config file.
+  linter=""
+  command -v detect_ts_linter >/dev/null 2>&1 && linter=$(detect_ts_linter)
+  case "$linter" in
+    oxc)    f="$root/.oxlintrc.json" ;;
+    eslint) f="$root/.eslintrc.json" ;;
+    *)      return 0 ;;   # biome / none / unparseable form -> default
+  esac
+  [ -f "$f" ] || return 0
+  v=$(jq -r "$_QC_ESLINT_MAXLINES_FILTER" "$f" 2>/dev/null)
+  [ -n "$v" ] && printf '%s' "$v"
+}
+
+# quality_threshold LANG KEY DEFAULT  ->  always echoes a positive integer.
+quality_threshold() {
+  local lang="$1" key="$2" def="$3" v
+  v=$(_qc_project_override "$lang" "$key")
+  [ -n "$v" ] && { printf '%s' "$v"; return 0; }
+  if [ "$lang" = "ts" ] && [ "$key" = "maxFileLines" ]; then
+    v=$(_qc_native_ts_max_lines)
+    [ -n "$v" ] && { printf '%s' "$v"; return 0; }
+  fi
+  printf '%s' "$def"
+}
+
+# count_code_lines lives in detect.sh (sourced above) — both lang modules
+# hard-require detect.sh, so it needs no per-module fallback.
+
+# Echo where ts maxFileLines actually resolved from: override | native | default.
+# Lets the lang module word its advisory honestly — claiming "eslint enforces
+# this" only when the limit really came from a parsed eslint/oxlint config, not
+# when a linter is merely present with a config we can't read (e.g. .eslintrc.cjs).
+ts_max_file_lines_source() {
+  [ -n "$(_qc_project_override ts maxFileLines)" ] && { printf 'override'; return; }
+  [ -n "$(_qc_native_ts_max_lines)" ]             && { printf 'native';   return; }
+  printf 'default'
+}
+
+# Resolve the ts maxFileLines value AND its source in a single pass — prints
+# "<value> <source>". The lang module needs both, and resolving them via two
+# separate calls (ts_max_file_lines + ts_max_file_lines_source) repeats the
+# override/native lookups; this does each lookup once.
+ts_max_file_lines_resolved() {
+  local v
+  v=$(_qc_project_override ts maxFileLines)
+  [ -n "$v" ] && { printf '%s override' "$v"; return; }
+  v=$(_qc_native_ts_max_lines)
+  [ -n "$v" ] && { printf '%s native' "$v"; return; }
+  printf '%s default' "$DEFAULT_TS_MAX_FILE_LINES"
+}
+
+# Convenience wrappers the quality modules call.
+ts_max_file_lines()   { quality_threshold ts   maxFileLines "$DEFAULT_TS_MAX_FILE_LINES"; }
+ts_max_fn_lines()     { quality_threshold ts   maxFnLines   "$DEFAULT_TS_MAX_FN_LINES"; }
+rust_max_file_lines() { quality_threshold rust maxFileLines "$DEFAULT_RUST_MAX_FILE_LINES"; }
+rust_max_fn_lines()   { quality_threshold rust maxFnLines   "$DEFAULT_RUST_MAX_FN_LINES"; }
+rust_max_impl_lines() { quality_threshold rust maxImplLines "$DEFAULT_RUST_MAX_IMPL_LINES"; }
+python_max_file_lines() { quality_threshold python maxFileLines "$DEFAULT_PYTHON_MAX_FILE_LINES"; }
+python_max_fn_lines()   { quality_threshold python maxFnLines   "$DEFAULT_PYTHON_MAX_FN_LINES"; }

package/plugins/toolu/hooks/lib/registry.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Shared runtime registry for hook modules contributed by other plugins.
+# Modules placed under <root>/<event>.d/<plugin-spec>__<name>.sh are executed
+# by the core dispatcher after its built-in modules, gated on the owning plugin
+# being installed. The "__" separator is load-bearing: plugin specs may contain
+# "." (e.g. name@git.example.com) but must not contain "__". The registry holds
+# GENERATED state (synced each session by each plugin's register.sh); the
+# source of truth for a module is its own plugin.
+
+_TOOLU_REGISTRY_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=host.sh
+. "$_TOOLU_REGISTRY_LIB_DIR/host.sh"
+
+# toolu_registry_root -> prints the registry root dir (not created).
+toolu_registry_root() {
+  local agent_dir
+  agent_dir=$(toolu_config_root)
+  printf '%s/toolu' "$agent_dir"
+}
+
+# toolu_registry_event_dir EVENT -> prints "<root>/<event-slug>.d".
+# Known events map to the repo's existing naming; others are CamelCase->kebab.
+toolu_registry_event_dir() {
+  local event="$1" slug
+  case "$event" in
+    PreToolUse)  slug="pre-tools" ;;
+    PostToolUse) slug="post-tools" ;;
+    *)
+      # Best-effort kebab-casing: consecutive-uppercase runs are NOT split
+      # (e.g. "MCPNotification" -> "mcpnotification"). Fine for the current
+      # Claude Code event names; extend the case table for anything odd.
+      slug=$(printf '%s' "$event" \
+        | sed -E 's/([a-z0-9])([A-Z])/\1-\2/g' \
+        | tr '[:upper:]' '[:lower:]')
+      ;;
+  esac
+  printf '%s/%s.d' "$(toolu_registry_root)" "$slug"
+}
+
+# Remove generated registry modules whose owning plugin is definitively absent
+# from Codex's ready SessionStart snapshot. Missing/malformed/indeterminate
+# snapshots prune nothing. Symlinks and un-namespaced files are never removed.
+toolu_registry_prune_inactive() {
+  [ "$(toolu_host)" = codex ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+
+  local snapshot root event_dir module base spec
+  snapshot=$(toolu_codex_plugin_snapshot_path)
+  [ -f "$snapshot" ] || return 0
+  jq -e '.version == 1 and .status == "ready" and (.plugins | type == "array")' \
+    "$snapshot" >/dev/null 2>&1 || return 0
+
+  root=$(toolu_registry_root)
+  for event_dir in "$root/pre-tools.d" "$root/post-tools.d"; do
+    [ -d "$event_dir" ] || continue
+    for module in "$event_dir"/*.sh; do
+      [ -f "$module" ] || continue
+      [ -L "$module" ] && continue
+      [ "${module%/*}" = "$event_dir" ] || continue
+      base=$(basename "$module")
+      case "$base" in
+        ?*__*.sh) spec=${base%%__*} ;;
+        *) continue ;;
+      esac
+      [ -n "$spec" ] || continue
+      if ! jq -e --arg spec "$spec" 'any(.plugins[]; . == $spec)' "$snapshot" >/dev/null 2>&1; then
+        rm -f -- "$module"
+      fi
+    done
+  done
+  return 0
+}

package/plugins/toolu/hooks/lib/state-sweeper.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# Transient-state sweeper for <repo>/<host-dir>/tmp.
+#
+# toolu's gates key their state by branch, and nothing ever reclaimed it: a
+# push-review state for a branch merged three weeks ago, a plan ledger for a
+# branch that no longer exists, a quality-gate record naming files that were
+# deleted. The pile is harmless right up until it is confusing, and the fix
+# was `rm -rf .claude/tmp/*` by hand.
+#
+# This runs once at SessionStart and reclaims only what is provably spent:
+#
+#   push-review/, plan-ledger/, docs-sync/  per-branch state — dropped when the
+#     branch is gone, merged into base, or older than the TTL. The CURRENT
+#     branch is never touched, however old: it is the one you are working on.
+#   quality-gate-status.json  dropped when passing, or when failing about files
+#     that no longer exist. A failing record about live files SURVIVES — a
+#     violation is not fixed by forgetting it.
+#   telemetry/<slug>.jsonl  trimmed to the retention window, never deleted
+#     wholesale; the history is the point.
+#
+# Anything else under tmp/ — including the permissions sentinel — is not ours
+# and is left alone.
+#
+# Everything here is best-effort: a failure warns and returns 0, because a
+# session must start whether or not old scratch files could be cleaned.
+#
+# Public API:
+#   toolu_sweep_state ROOT
+
+_TOOLU_SWEEPER_LIB_DIR="$(cd "${BASH_SOURCE%/*}" && pwd)"
+# shellcheck source=config.sh
+. "$_TOOLU_SWEEPER_LIB_DIR/config.sh"
+# shellcheck source=detect.sh
+. "$_TOOLU_SWEEPER_LIB_DIR/detect.sh"
+
+TOOLU_SWEEP_DEFAULT_TTL_HOURS=24
+TOOLU_SWEEP_DEFAULT_RETENTION_DAYS=7
+TOOLU_SWEEP_BRANCH_DIRS="push-review plan-ledger docs-sync"
+
+_toolu_sweep_warn() {
+  printf 'toolu-sweep: %s\n' "$1" >&2
+}
+
+# _toolu_sweep_number PATH DEFAULT -> a positive integer from config, or DEFAULT.
+# A zero, a negative, or a non-number means "not configured" rather than an
+# error — the same lenient reading the quality thresholds use.
+_toolu_sweep_number() {
+  local path="$1" def="$2" val
+  toolu_load_config
+  if [ "$_TOOLU_HAS_JQ" != "1" ]; then
+    printf '%s' "$def"
+    return 0
+  fi
+  val=$(jq -r --arg p "$path" '
+    ($p | split(".")) as $ks
+    | (getpath($ks)) as $v
+    | if ($v | type) == "number" and $v > 0 then ($v | floor | tostring) else "" end
+  ' <<< "$TOOLU_CFG_JSON" 2>/dev/null)
+  [ -n "$val" ] && printf '%s' "$val" || printf '%s' "$def"
+}
+
+# _toolu_sweep_cutoff DAYS -> an ISO-8601 UTC timestamp DAYS ago.
+# GNU date first, BSD/macOS second; prints nothing if neither works, which
+# callers read as "cannot judge age, keep everything".
+_toolu_sweep_cutoff() {
+  local days="$1"
+  date -u -d "-${days} days" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || date -u -v-"${days}"d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || return 1
+}
+
+# _toolu_sweep_slug_of FILE -> the branch slug a state file belongs to.
+# Strips the compound suffixes first so feat_x.waiver.json and
+# feat_x.pending-waiver.json both resolve to feat_x.
+_toolu_sweep_slug_of() {
+  local base
+  base=$(basename "$1")
+  base="${base%.json}"
+  base="${base%.pending-waiver}"
+  base="${base%.waiver}"
+  printf '%s' "$base"
+}
+
+# _toolu_sweep_reclaimable SLUG LIVE MERGED FILE TTL -> 0 iff FILE can go.
+_toolu_sweep_reclaimable() {
+  local slug="$1" live="$2" merged="$3" file="$4" ttl_hours="$5"
+  case "$merged" in *" $slug "*) return 0 ;; esac
+  case "$live" in *" $slug "*) ;; *) return 0 ;; esac
+  # Branch still exists and is unmerged: age is the only remaining reason.
+  [ -n "$(find "$file" -maxdepth 0 -mmin "+$((ttl_hours * 60))" 2>/dev/null)" ]
+}
+
+# _toolu_sweep_branch_state ROOT STATE_ROOT TTL -> prune per-branch state dirs.
+_toolu_sweep_branch_state() {
+  local root="$1" state_root="$2" ttl_hours="$3"
+  local base_branch current_branch current_slug live=" " merged=" " name dir file slug
+
+  current_branch=$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  current_slug=$(branch_slug "$current_branch")
+  base_branch=$(detect_base_branch "$root")
+
+  while IFS= read -r name; do
+    [ -n "$name" ] && live="${live}$(branch_slug "$name") "
+  done < <(git -C "$root" branch --format='%(refname:short)' 2>/dev/null)
+
+  # `--merged` sees ancestry only, so a SQUASH-merged branch never appears here.
+  # Those are reclaimed by the TTL path instead — which is exactly why the TTL
+  # exists alongside this check rather than being redundant with it.
+  while IFS= read -r name; do
+    [ -n "$name" ] && merged="${merged}$(branch_slug "$name") "
+  done < <(git -C "$root" branch --merged "$base_branch" --format='%(refname:short)' 2>/dev/null)
+
+  for dir in $TOOLU_SWEEP_BRANCH_DIRS; do
+    [ -d "$state_root/$dir" ] || continue
+    for file in "$state_root/$dir"/*.json; do
+      [ -f "$file" ] || continue
+      slug=$(_toolu_sweep_slug_of "$file")
+      [ "$slug" = "$current_slug" ] && continue
+      if _toolu_sweep_reclaimable "$slug" "$live" "$merged" "$file" "$ttl_hours"; then
+        rm -f "$file" 2>/dev/null || _toolu_sweep_warn "could not remove $file"
+      fi
+    done
+  done
+}
+
+# _toolu_sweep_gate_file GATE_FILE -> drop a spent quality-gate record.
+_toolu_sweep_gate_file() {
+  local gate_file="$1" status live_violation entry
+  [ -f "$gate_file" ] || return 0
+  status=$(jq -r '.status // ""' "$gate_file" 2>/dev/null) || return 0
+  if [ "$status" = "passing" ]; then
+    rm -f "$gate_file" 2>/dev/null || _toolu_sweep_warn "could not remove $gate_file"
+    return 0
+  fi
+  [ "$status" = "failing" ] || return 0
+
+  # A failing record is only spent when every file it complains about is gone.
+  # Age alone must never clear it: that would silently reopen a real violation.
+  live_violation=0
+  while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    [ "$entry" = "__global__" ] && { live_violation=1; break; }
+    [ -e "$entry" ] && { live_violation=1; break; }
+  done < <(jq -r 'if (.entries? | type) == "object" then (.entries | keys[]) else (.file // "__global__") end' \
+             "$gate_file" 2>/dev/null)
+
+  [ "$live_violation" = "1" ] && return 0
+  rm -f "$gate_file" 2>/dev/null || _toolu_sweep_warn "could not remove $gate_file"
+}
+
+# _toolu_sweep_telemetry DIR DAYS -> trim each jsonl to the retention window.
+_toolu_sweep_telemetry() {
+  local dir="$1" days="$2" cutoff file tmp
+  [ -d "$dir" ] || return 0
+  cutoff=$(_toolu_sweep_cutoff "$days") || return 0
+  for file in "$dir"/*.jsonl; do
+    [ -f "$file" ] || continue
+    tmp=$(mktemp "${file}.XXXXXX" 2>/dev/null) || continue
+    # A file jq cannot parse is left exactly as it is: it may be another
+    # tool's, or a partially written line worth keeping for debugging.
+    if jq -c --arg cutoff "$cutoff" 'select((.t // "") >= $cutoff)' "$file" > "$tmp" 2>/dev/null; then
+      if [ -s "$tmp" ]; then
+        mv -f "$tmp" "$file" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+      else
+        rm -f "$tmp" "$file" 2>/dev/null
+      fi
+    else
+      rm -f "$tmp" 2>/dev/null
+    fi
+  done
+}
+
+# toolu_sweep_state ROOT -> reclaim spent transient state. Always returns 0.
+toolu_sweep_state() {
+  local root="${1:-}" state_root ttl_hours retention_days
+  [ -n "$root" ] || root=$(toolu_project_root)
+  [ -n "$root" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+
+  # Opt-out, and a hard requirement of git for the branch questions below.
+  toolu_enabled gates sweep || return 0
+  command -v git >/dev/null 2>&1 || return 0
+
+  state_root=$(toolu_project_state_root "$root")
+  [ -n "$state_root" ] && [ -d "$state_root" ] || return 0
+
+  ttl_hours=$(_toolu_sweep_number gates.stateTtlHours "$TOOLU_SWEEP_DEFAULT_TTL_HOURS")
+  retention_days=$(_toolu_sweep_number gates.telemetryRetentionDays "$TOOLU_SWEEP_DEFAULT_RETENTION_DAYS")
+
+  _toolu_sweep_branch_state "$root" "$state_root" "$ttl_hours"
+  _toolu_sweep_gate_file "$state_root/quality-gate-status.json"
+  _toolu_sweep_telemetry "$state_root/telemetry" "$retention_days"
+  return 0
+}

package/plugins/toolu/hooks/lib/telemetry.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Workflow telemetry append engine: the one write path every gate/lib event
+# funnels through, so telemetry.enabled / jq-absent / no-branch all degrade
+# the same way regardless of caller.
+#
+# Public API:
+#   telemetry_append REPO_ROOT EVENT [EXTRA_JSON_OBJECT]
+#     Appends one line `{"v":1,"t":<iso8601 UTC>,"branch":<branch>,
+#     "event":<name>, ...EXTRA_JSON_OBJECT}` to
+#     REPO_ROOT/<host-state>/tmp/telemetry/<branch_slug>.jsonl
+#     ($TELEMETRY_DIR overrides the directory). EXTRA_JSON_OBJECT defaults to
+#     "{}"; its keys are merged in but can never override v/t/branch/event.
+#     Always returns 0 — a telemetry bug must never fail the caller's real
+#     work — no-op (nothing written) when:
+#       - telemetry.enabled=false in the merged toolu config
+#       - jq is missing
+#       - HEAD is unborn/detached (mirrors push-review.sh's and docs-sync.sh's
+#         own detached-HEAD refusal: branch_slug would otherwise collapse
+#         every such caller onto the shared "_default" slug, mixing unrelated
+#         branches' events into one file)
+#     A malformed EXTRA_JSON_OBJECT, or an assembled line over 3900 bytes,
+#     is a soft failure: warns on stderr, appends nothing, still returns 0.
+#
+# CONCURRENCY: exactly one `printf '%s\n' >>` per call — a single O_APPEND
+# write. That is atomic only while the line stays under the platform's
+# atomic-pipe-write floor (historically 4 KB on POSIX), so the assembled
+# line's byte length is checked before every write: over 3900 bytes
+# (headroom under that floor) it is dropped rather than risking a
+# torn/interleaved write with a concurrent writer — callers must still keep
+# EXTRA_JSON_OBJECT small so their events aren't silently lost this way.
+#
+# Source via:  . "${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}/telemetry.sh"
+
+_TELEMETRY_LIB_DIR="${TOOLU_LIB_DIR:-${BASH_SOURCE%/*}}"
+# shellcheck source=./detect.sh
+[ -f "$_TELEMETRY_LIB_DIR/detect.sh" ] && . "$_TELEMETRY_LIB_DIR/detect.sh"
+# shellcheck source=./config.sh
+[ -f "$_TELEMETRY_LIB_DIR/config.sh" ] && . "$_TELEMETRY_LIB_DIR/config.sh"
+
+# telemetry_append REPO_ROOT EVENT [EXTRA_JSON_OBJECT]
+telemetry_append() {
+  local repo_root="$1" event="$2" extra="${3:-}"
+  [ -n "$extra" ] || extra='{}'
+  [ -n "$repo_root" ] && [ -n "$event" ] || return 0
+
+  command -v jq  >/dev/null 2>&1 || return 0
+  command -v git >/dev/null 2>&1 || return 0
+
+  # Default-on: absent/malformed config -> enabled; explicit false -> no-op.
+  if command -v toolu_enabled >/dev/null 2>&1; then
+    toolu_enabled telemetry enabled || return 0
+  fi
+
+  local branch
+  branch=$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  [[ -z "$branch" || "$branch" == "HEAD" ]] && return 0
+
+  # branch_slug comes from detect.sh, sourced softly above — an older/absent
+  # detect.sh must not turn into an unbound-function crash for every caller.
+  command -v branch_slug >/dev/null 2>&1 || return 0
+
+  local slug now line dir file line_bytes
+  slug=$(branch_slug "$branch")
+  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # $extra merged FIRST so the protocol fields (v/t/branch/event) always win
+  # on key collision — a caller-supplied "branch" or "event" in extra can
+  # never spoof the real ones. A malformed or non-object $extra makes this
+  # jq call fail; treat that as the one "malformed extra JSON" soft-failure.
+  if ! line=$(jq -cn --argjson extra "$extra" --arg t "$now" --arg branch "$branch" \
+        --arg event "$event" '$extra + {v: 1, t: $t, branch: $branch, event: $event}' \
+        2>/dev/null) || [ -z "$line" ]; then
+    printf 'telemetry: malformed extra JSON for event "%s"; skipping append\n' "$event" >&2
+    return 0
+  fi
+
+  # Keep the single O_APPEND write atomic (see CONCURRENCY above): a line
+  # over 3900 bytes risks crossing the platform's atomic-pipe-write floor, so
+  # drop it rather than risk tearing/interleaving with a concurrent writer.
+  line_bytes=$(printf '%s' "$line" | wc -c | tr -d ' ')
+  if [ "$line_bytes" -gt 3900 ]; then
+    printf 'telemetry: assembled line for event "%s" is %d bytes (>3900); skipping append\n' \
+      "$event" "$line_bytes" >&2
+    return 0
+  fi
+
+  dir="${TELEMETRY_DIR:-$(toolu_project_state_dir telemetry "$repo_root")}"
+  file="$dir/${slug}.jsonl"
+  mkdir -p "$dir" 2>/dev/null || return 0
+
+  printf '%s\n' "$line" >> "$file" 2>/dev/null
+
+  return 0
+}