@soleur/opencode 0.0.0-stage → 1.0.0

package/hooks/devin-session-start.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# DEVIN_DIR is in the gate deliberately: it is the measured cloud-only marker
+# (cloud-probe.md), so if a repo-level SessionStart registration ever fires on a
+# cloud VM this hook must still write — the `hook_source=repo` sentinel is what
+# makes the classifier's non-plugin-source arm discriminate.
+[[ -n "${DEVIN:-}" || -n "${DEVIN_HOME:-}" || -n "${DEVIN_PROJECT_DIR:-}" || -n "${DEVIN_PLUGIN_ROOT:-}" || -n "${DEVIN_DIR:-}" ]] || exit 0
+SOLEUR_PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# --- Local-session sentinel (Soleur Cloud Mode, FR1) ---
+# Content-bearing proof-of-local for scripts/cloud-detect.sh: SessionStart is the
+# one plugin hook event documented absent in Devin Cloud, so a plugin-sourced
+# sentinel on this host is what distinguishes a local Devin session. The write is
+# UNCONDITIONAL under the Devin-env guard above — no plugins/soleur dir check:
+# user repos consuming via requiredPlugins don't vendor the plugin dir, and a
+# scope guard there would invert detection into permanent false-cloud.
+#
+# hook_source records which registration fired, because a repo-level SessionStart
+# firing on a cloud VM writes a matching-host sentinel that must NOT classify
+# local. Resolution order:
+#   1. SOLEUR_HOOK_SOURCE env override (a registration may inject it explicitly)
+#   2. CLAUDE_PLUGIN_ROOT set and resolving to this script's plugin root → plugin
+#   3. otherwise → repo (the fail-safe direction for detection)
+#
+# The sentinel write runs BEFORE the jq emit: a jq-less minimal host must not
+# lose proof-of-local because the context emit died first (the write block is
+# already `|| true`-isolated; a jq failure below still exits non-zero but the
+# sentinel survives).
+#
+# Canonical copy of test-helpers.sh's assert_fixture_dir — P1a requires every
+# tracked copy be byte-equal, and the P1b scanner recognises ONLY this name.
+assert_fixture_dir() {
+  case "${1-}" in
+    "") printf 'FATAL: fixture dir is EMPTY; git -C "" would operate on %s\n' "$PWD" >&2; exit 2 ;;
+    */../*|*/..) printf 'FATAL: fixture dir %s contains ..; refusing\n' "$1" >&2; exit 2 ;;
+    /proc/*|/sys/*|/dev/*) printf 'FATAL: fixture dir %s is a synthetic-fs path; refusing\n' "$1" >&2; exit 2 ;;
+    /|//|/.) printf 'FATAL: fixture dir resolves to the filesystem root; refusing\n' >&2; exit 2 ;;
+    /*) : ;;
+    *)  printf 'FATAL: fixture dir %s is RELATIVE; refusing\n' "$1" >&2; exit 2 ;;
+  esac
+}
+{
+  # An inherited GIT_DIR would aim rev-parse at a foreign repo and print the
+  # cwd-derived toplevel (e.g. `/` — which passes the absolute check below and
+  # would mint `/.devin` on a uid-0 host). Same scrub list as the bare-root arms.
+  unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
+    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_NAMESPACE
+  _sentinel_root="$(git rev-parse --show-toplevel 2>/dev/null)" && \
+  # Guard: a non-empty ABSOLUTE path is required before any write — a relative or
+  # pathological toplevel (or a scrubbed-env empty) degrades to context-only;
+  # a bare-root session emits context only (#10392 audit).
+  [[ -n "$_sentinel_root" && "$_sentinel_root" == /* ]] && \
+  _sentinel_source="${SOLEUR_HOOK_SOURCE:-}" && \
+  if [[ -z "$_sentinel_source" ]]; then
+    _sentinel_source="repo"
+    if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]] && \
+       [[ "$(cd "${CLAUDE_PLUGIN_ROOT}" 2>/dev/null && pwd)" == "$SOLEUR_PLUGIN_ROOT" ]]; then
+      _sentinel_source="plugin"
+    fi
+  fi && \
+  mkdir -p "$_sentinel_root/.devin" && \
+  _sentinel="$_sentinel_root/.devin/soleur-local-session" && \
+  # Single live registration (plugin hooks.json `""` — source matchers are
+  # dead under Devin, measured envelope-capture §3). The repo-source arm still
+  # matters: if a repo-level SessionStart registration ever fires on a cloud
+  # VM, its `repo` write must not mask an existing plugin-sourced sentinel on
+  # this host — that sentinel is proof-of-local, and masking it reads as
+  # permanent false-cloud.
+  if [[ "$_sentinel_source" == "repo" && -f "$_sentinel" ]] && \
+     grep -q '"hook_source"[[:space:]]*:[[:space:]]*"plugin"' "$_sentinel" 2>/dev/null; then
+    :
+  else
+    # ts is forensic-only (written for debugging; the classifier does not
+    # enforce freshness — a stale same-host sentinel is a documented limit).
+    # SOLEUR_HOOK_SOURCE is self-reported under the trusted-agent threat model —
+    # an env-forged `plugin` on a cloud VM still fails closed at the
+    # classifier's conflicting-evidence arm (DEVIN_DIR is set there).
+    assert_fixture_dir "$_sentinel" && \
+    printf '{"host":"%s","ts":"%s","hook_source":"%s"}\n' \
+      "$(hostname)" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$_sentinel_source" \
+      > "$_sentinel.tmp" && \
+    mv "$_sentinel.tmp" "$_sentinel"
+  fi
+} || true
+
+jq -n --arg root "$SOLEUR_PLUGIN_ROOT" \
+  --rawfile instructions "$SOLEUR_PLUGIN_ROOT/devin/INSTRUCTIONS.md" \
+  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext:
+    ("Soleur plugin root: " + $root + "\n" + $instructions)}}'

package/hooks/ext-filter-detect.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# ext-filter-detect.sh — SessionStart (matcher: startup|resume|clear|compact) external
+# output-filter detector (#10230). Emits ONE JSON object on stdout — detected tools
+# become newline-joined marker lines inside it (single-document stdout; sibling hooks
+# all emit exactly one object):
+#   {"systemMessage": "SOLEUR_EXT_FILTER tool=<t> version=<v> posture=<p>
+#     via=on-path|settings-hook|proxy-env measured_at=<date|-> [path=<settings>] ref=soleur.ai/known-external-tools"}
+# and `SOLEUR_EXT_FILTER tool=none` when nothing is detected — so "hook dead" is
+# distinguishable from "no filter" (the same liveness argument compaction-state.sh
+# makes for SOLEUR_COMPACTION_SKIPPED). systemMessage costs zero model tokens; this is
+# an operator-facing line, never additionalContext.
+#
+# Marker semantics (the marker is a per-session public claim — key=value only, never
+# editorial prose; severity lives in docs/pages/known-external-tools.md):
+#   posture=unmeasured             the divergence harness has NOT run against this tool
+#                                  — explicitly not an assurance
+#   posture=literal-clean          gate literals survived the divergence corpus (rtk, only
+#                                  after the Phase-3 measurement lands — see POSTURE_RTK below)
+#   posture=measured-incompatible  gate-literal divergence measured (headroom; only when the
+#                                  detected version is <= the evaluated version and identity
+#                                  is corroborated — never on a bare basename PATH hit, which
+#                                  could be an unrelated `headroom`)
+#   tool=proxy posture=unknown     ANTHROPIC_BASE_URL points at a non-default endpoint; a
+#                                  generic proxy (LiteLLM/Helicone/corporate) must NEVER be
+#                                  emitted under a vendor name
+#   version=unknown                version probe failed -> posture floors at unmeasured
+#
+# Skips silently (exit 0, no output) when CLAUDE_PLUGIN_ROOT is unset, on the non-Claude
+# harness markers version-banner.sh uses (CODEX_THREAD_ID, PLUGIN_ROOT), and when
+# SOLEUR_DISABLE_EXT_FILTER_DETECT=1. The marker is Claude-Code-only by design — a Devin
+# or other-harness session has no marker and that does NOT mean "no filter" (the doc's
+# three-rung diagnostic has a manual path for those).
+#
+# Fails open: every path exits 0 and any error prints nothing. Plugin hooks are GLOBAL
+# (they fire in every project), so a hook that errors or hangs would hit every session;
+# the stdin read and every version probe are bounded.
+
+[[ "${SOLEUR_DISABLE_EXT_FILTER_DETECT-}" == "1" ]] && exit 0
+set -uo pipefail
+case "$-" in
+  *x*) printf '[FATAL] refusing to run under xtrace: this script emits marker text and -x would echo it (see #7797)\n' >&2; exit 78 ;;
+esac
+trap 'exit 0' EXIT
+
+# --- posture constants (the Phase-3 conjunctive evidence gate flips POSTURE_RTK in the
+# same commit that lands ext-filter-divergence-report.md; a failed or un-run gate keeps
+# `unmeasured` — the marker never asserts an unmeasured claim) ---------------------------
+POSTURE_RTK="unmeasured"            # -> "literal-clean" only after ext-filter-divergence.sh proves zero gate-literal divergence on an rtk-present host
+POSTURE_HEADROOM="measured-incompatible"
+HEADROOM_EVAL_VERSION="0.37.0"      # the measured ceiling: claims apply at or below this version
+HEADROOM_MEASURED_AT="2026-09-07"   # archived eval date (specs/archive/…headroom-token-compression-eval)
+RTK_MEASURED_AT="-"                 # the Phase-3 report's date once measured
+
+trace() { [[ "${SOLEUR_HOOK_TRACE-}" == "1" ]] && printf 'ext-filter-detect: %s\n' "$*" >&2; return 0; }
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/ }"
+  s="${s//$'\r'/ }"
+  s="${s//$'\t'/ }"
+  printf '%s' "$s"
+}
+
+MARKERS=()
+emit() { # <marker fields...> -> append a marker line; flushed as ONE systemMessage object
+  # (every sibling SessionStart hook emits a single JSON document; N top-level objects
+  # risks first-object-only parsing dropping co-detection markers, or a plain-text
+  # fallback landing them in model context — one object, newline-joined markers)
+  MARKERS+=("SOLEUR_EXT_FILTER $*")
+}
+
+flush_markers() {
+  ((${#MARKERS[@]})) || return 0
+  local joined
+  joined="$(printf '%s\n' "${MARKERS[@]}")"
+  printf '{"systemMessage": "%s"}\n' "$(json_escape "$joined")"
+}
+
+# version_probe <tool> -> last field of `<tool> --version`'s first line, "unknown" on any failure.
+version_probe() {
+  local out
+  out="$(timeout 2 "$1" --version 2>/dev/null | head -1 | awk '{print $NF}')"
+  if [[ "$out" =~ ^v?[0-9]+\.[0-9]+ ]]; then printf '%s' "${out#v}"; else printf 'unknown'; fi
+}
+
+# ver_le a b -> 0 iff version a <= version b (dotted numerics). Pure bash — `sort -V`
+# is GNU-only and its absence silently withholds a measured-incompatible warning.
+ver_le() {
+  [[ "$1" =~ ^[0-9]+\.[0-9]+ ]] || return 1
+  local a1 a2 a3 b1 b2 b3
+  IFS=. read -r a1 a2 a3 <<<"$1"; IFS=. read -r b1 b2 b3 <<<"$2"
+  a3="${a3%%[^0-9]*}"; b3="${b3%%[^0-9]*}"
+  (( 10#${a1:-0} != 10#${b1:-0} )) && { (( 10#${a1:-0} < 10#${b1:-0} )); return; }
+  (( 10#${a2:-0} != 10#${b2:-0} )) && { (( 10#${a2:-0} < 10#${b2:-0} )); return; }
+  (( 10#${a3:-0} <= 10#${b3:-0} ))
+}
+
+# settings_hit <tool> -> prints the tilde-collapsed settings file that wires <tool> into
+# Claude hooks (a "command" entry naming it — a bare mention is not wiring), or nothing.
+# HOME- and cwd-level files; cwd arrives via CWD_CLAUDE dynamic scope.
+settings_hit() {
+  local tool="$1" f
+  for f in ${HOME:+"$HOME/.claude/settings.json" "$HOME/.claude/settings.local.json"} \
+           ${CWD_CLAUDE:+"$CWD_CLAUDE/settings.json" "$CWD_CLAUDE/settings.local.json"}; do
+    [[ -r "$f" ]] || continue
+    if grep -l '"hooks"' "$f" >/dev/null 2>&1 && grep -lE '"command"[^,}]*'"$tool" "$f" >/dev/null 2>&1; then
+      case "$f" in "${HOME:-}"/*) printf '~%s' "${f#"$HOME"}" ;; *) printf '%s' "${f// /%20}" ;; esac
+      return 0
+    fi
+  done
+  return 1
+}
+
+CWD_CLAUDE=""
+main() {
+  # --self-test bypasses the env gates: it exists for operator/agent discoverability
+  # ("run the hook, see the marker"), which is exactly when CLAUDE_PLUGIN_ROOT is absent.
+  local selftest=0
+  if [[ "${1:-}" == "--self-test" ]]; then selftest=1; shift; fi
+  (( selftest )) || [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]] || return 0
+  (( selftest )) || { [[ -n "${CODEX_THREAD_ID:-}" || -n "${PLUGIN_ROOT:-}" ]] && return 0; }
+
+  # Bounded stdin read for the envelope's cwd (a hook that hangs at SessionStart is worse
+  # than a crashed one — compaction-state.sh:123-129). Absent or malformed: no cwd arm.
+  local envelope=""
+  envelope="$(timeout 5 cat 2>/dev/null || true)"
+  local cwd
+  cwd="$(printf '%s' "$envelope" | grep -o '"cwd"[^,}]*' | head -1 | cut -d'"' -f4)"
+  [[ -n "$cwd" && -d "$cwd/.claude" ]] && CWD_CLAUDE="$cwd/.claude"
+  trace "cwd=$cwd CWD_CLAUDE=$CWD_CLAUDE"
+
+  local found=0 tool ver via posture m_at s_hit
+
+  # --- proxy arm: a non-default ANTHROPIC_BASE_URL emits the NEUTRAL marker, never a
+  # named vendor claim — a LiteLLM/Helicone/corporate proxy is the user's own infra.
+  case "${ANTHROPIC_BASE_URL:-}" in
+    ""|https://api.anthropic.com|https://api.anthropic.com/) : ;;
+    *) emit "tool=proxy posture=unknown via=proxy-env measured_at=- ref=soleur.ai/known-external-tools"; found=1 ;;
+  esac
+
+  for tool in rtk headroom; do
+    via=""; s_hit=""
+    command -v "$tool" >/dev/null 2>&1 && via="on-path"
+    s_hit="$(settings_hit "$tool")" && via="${via:+$via,}settings-hook"
+    [[ -n "$via" ]] || continue
+    found=1
+    ver="$(version_probe "$tool")"
+    case "$tool" in
+      rtk)
+        # a named posture requires corroboration AND a resolved version; a bare PATH
+        # basename hit is unmeasured by construction.
+        if [[ "$via" == *settings-hook* && "$ver" != unknown ]]; then posture="$POSTURE_RTK"; else posture="unmeasured"; fi
+        m_at="$RTK_MEASURED_AT" ;;
+      headroom)
+        if [[ "$via" == *settings-hook* && "$ver" != unknown ]] && ver_le "$ver" "$HEADROOM_EVAL_VERSION"; then
+          posture="$POSTURE_HEADROOM"; m_at="$HEADROOM_MEASURED_AT"
+        else
+          posture="unmeasured"; m_at="-"
+        fi ;;
+    esac
+    emit "tool=$tool version=$ver posture=$posture via=$via measured_at=$m_at${s_hit:+ path=${s_hit// /%20}} ref=soleur.ai/known-external-tools"
+  done
+
+  (( found )) || emit "tool=none ref=soleur.ai/known-external-tools"
+  flush_markers
+  return 0
+}
+
+main "$@"

package/hooks/hooks.json

@@ -0,0 +1,133 @@
+{
+  "description": "Soleur plugin hooks",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Bash|exec)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/browser-snapshot-credential-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "^(Bash|Monitor|Write|Edit|MultiEdit|NotebookEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/operator-stage-approval.sh",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/destructive-command-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/codex-session-start.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/devin-session-start.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/bare-root-cwd-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/welcome-hook.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/version-banner.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-state.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/ext-filter-detect.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/unkept-promise-hook.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-state.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/lib/hook-tool-kind.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Canonical Devin→Claude tool-kind map (issue #8205) — PLUGIN COPY.
+#
+# Plugin hooks run in projects that may not carry this repo's
+# .claude/hooks/lib/, so the map is duplicated here. Pinned against the
+# canonical map by .claude/hooks/hook-tool-kind.test.sh — update both or
+# neither. multi_edit/notebook_edit/apply_patch are probed-absent from Devin's
+# vocabulary (envelope-capture §7) — speculative passthroughs; re-probe before
+# relying on them.
+
+hook_tool_kind() {
+  case "${1-}" in
+    exec)              printf '%s\n' "Bash" ;;
+    write)             printf '%s\n' "Write" ;;
+    edit)              printf '%s\n' "Edit" ;;
+    multi_edit)        printf '%s\n' "MultiEdit" ;;
+    notebook_edit)     printf '%s\n' "NotebookEdit" ;;
+    apply_patch)       printf '%s\n' "Write" ;;
+    ask_user_question) printf '%s\n' "AskUserQuestion" ;;
+    run_subagent)      printf '%s\n' "Agent" ;;
+    skill)             printf '%s\n' "Skill" ;;
+    *)                 printf '%s\n' "${1-}" ;;
+  esac
+}

package/hooks/lib/log-rotation.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# log-rotation.sh — sourced helper for .claude/.*.jsonl rotation.
+#
+# Single source of truth for rotating telemetry sinks under .claude/. Called
+# at write time from each emitter (incidents.sh::emit_incident,
+# skill-invocation-logger.sh, agent-token-tee.sh) so growth is bounded on
+# every operator's machine — not only when the weekly aggregator runs.
+#
+# Source from a hook via:
+#   source "$(dirname "${BASH_SOURCE[0]}")/lib/log-rotation.sh"
+#
+# Strategy: copy-then-truncate-in-place (NOT atomic-rename). Mirrors the
+# pattern at scripts/rule-metrics-aggregate.sh:291-295. The rationale is
+# concurrency-correctness: writers identify the file by PATH and use `>>$file`
+# (open for append). flock advisories are inode-bound. A `mv $active →
+# $archive.tmp; : > $active` inside the flock would let a writer that opens
+# `>>$file` between the mv and its own flock acquire end up locking a DIFFERENT
+# inode (the freshly-created post-truncate file) than the rotator's open fd.
+# Two writers, two inodes, two flocks — torn writes return.
+#
+# Copy-then-truncate keeps the same inode throughout; readers/writers always
+# converge on the same inode and the lock semantics hold.
+#
+# Public API:
+#   rotate_if_needed <jsonl-path> [size-bytes] [age-days]
+#
+# The caller MUST pass a canonicalized absolute path (cd -P / pwd -P resolved)
+# so flock targets the same inode as concurrent writers on the same logical
+# file. All three production callers (incidents.sh, skill-invocation-logger.sh,
+# agent-token-tee.sh) canonicalize their repo-root via `cd -P + pwd -P` —
+# follow that pattern in any new caller. `stat` and the cat redirect both use
+# `-L`/path-following semantics so a symlinked sink rotates on the target's
+# size/mtime rather than the link's metadata.
+#
+# Defaults:
+#   size-bytes = $LOG_ROTATION_SIZE_BYTES (or 5 MB)
+#   age-days   = $LOG_ROTATION_AGE_DAYS   (or 30)
+#   timeout    = $LOG_ROTATION_FLOCK_TIMEOUT_S (or 5)
+#
+# Kill-switch: LOG_ROTATION_DISABLE=1 short-circuits before any work.
+# Test override: LOG_ROTATION_UNIQ_SUFFIX overrides the collision suffix.
+#
+# Exit codes:
+#   0 — no-op (below threshold, missing file, kill-switch, lock-acquire
+#       timeout) OR a successful rotation. Existing fire-and-forget callers
+#       using `|| true` swallow this either way.
+#   1 — archive-write failure (disk-full, permission-denied). The active file
+#       is preserved intact (truncate gated on cat success), the partial
+#       archive is removed, and ONE stderr warning is emitted per process
+#       (rate-limited via /tmp/log-rotation-warned-$$ — mirrors the pattern
+#       at incidents.sh:130-138).
+#
+# Sentinel-aware callers (issue #3509) branch on the non-zero return to emit
+# a `rotation_fail` drop sentinel before falling through to the data write:
+#   if ! rotate_if_needed "$file"; then
+#     _emit_drop_sentinel "$file" "$HOOK_EVENT_LITERAL" rotation_fail
+#   fi
+
+# Source session-state.sh (idempotent guard inside it). Used for
+# headless_or_stderr — routes warns to a log file under `claude --bg` and to
+# stderr foreground. Fallback to plain stderr echo when missing (legacy
+# worktrees).
+# shellcheck source=../../../plugins/soleur/scripts/lib/session-state.sh
+source "$(dirname "${BASH_SOURCE[0]}")/../../../plugins/soleur/scripts/lib/session-state.sh" 2>/dev/null || true
+if ! declare -f headless_or_stderr >/dev/null; then
+  headless_or_stderr() { echo "[$1] $2" >&2; }
+fi
+
+LOG_ROTATION_SIZE_BYTES_DEFAULT=$((5 * 1024 * 1024))   # 5 MB
+LOG_ROTATION_AGE_DAYS_DEFAULT=30
+LOG_ROTATION_FLOCK_TIMEOUT_S_DEFAULT=5
+
+rotate_if_needed() {
+  [[ "${LOG_ROTATION_DISABLE:-}" == "1" ]] && return 0
+
+  local active="${1:-}"
+  [[ -z "$active" ]] && return 0
+  [[ -f "$active" ]] || return 0
+  [[ -s "$active" ]] || return 0   # empty — no rotation regardless of mtime
+
+  local size_threshold="${2:-${LOG_ROTATION_SIZE_BYTES:-$LOG_ROTATION_SIZE_BYTES_DEFAULT}}"
+  local age_threshold_days="${3:-${LOG_ROTATION_AGE_DAYS:-$LOG_ROTATION_AGE_DAYS_DEFAULT}}"
+  local timeout_s="${LOG_ROTATION_FLOCK_TIMEOUT_S:-$LOG_ROTATION_FLOCK_TIMEOUT_S_DEFAULT}"
+
+  # Pre-check (cheap, no lock): >99% of calls exit here.
+  # `stat -L` dereferences symlinks so a relocated sink (operator-symlinked to
+  # tmpfs / larger volume) rotates on the target's size/mtime, not the link's.
+  local size mtime now age_seconds age_threshold_seconds
+  read -r size mtime < <(stat -L -c "%s %Y" "$active" 2>/dev/null) || return 0
+  now=$(date -u +%s 2>/dev/null) || return 0
+  age_seconds=$(( now - mtime ))
+  age_threshold_seconds=$(( age_threshold_days * 86400 ))
+  if (( size <= size_threshold )) && (( age_seconds <= age_threshold_seconds )); then
+    return 0
+  fi
+
+  # Compute archive path BEFORE entering flock subshell. Subshell variable
+  # reassignments do not propagate back (precedent at
+  # rule-metrics-aggregate.sh:288 — same hazard). An already-rotated `.gz`
+  # or a lingering uncompressed file from a mid-run crash both count as
+  # "already exists"; we append a uniquify suffix rather than clobbering.
+  local dir base ts archive suffix
+  dir=$(dirname "$active")
+  base=$(basename "$active" .jsonl)
+  ts=$(date -u +%Y-%m 2>/dev/null) || return 0
+  archive="$dir/${base}-${ts}.jsonl"
+  if [[ -f "${archive}.gz" || -f "$archive" ]]; then
+    suffix="${LOG_ROTATION_UNIQ_SUFFIX:-$(date -u +%H%M%S%N)}"
+    archive="$dir/${base}-${ts}-${suffix}.jsonl"
+  fi
+
+  # Acquire flock + re-check + copy-then-truncate. flock fd 9 against $active
+  # — same inode the writers use for their own flock. -w timeout matches the
+  # agent-token-tee.sh / aggregator precedent. On timeout: skip this round;
+  # the next call will rotate. We use exit-code 10 as a 1-bit signal channel
+  # ("rotated successfully") since subshell variable reassignments cannot
+  # propagate to the outer scope.
+  # The subshell exits 0 (no-op) or 10 (rotated). The non-zero exit-10 is a
+  # signal channel — caller-side `set -e` would otherwise treat it as an
+  # error, so we capture via `|| rotated=$?` (conditional context — set -e
+  # does not trigger on the LHS).
+  local rotated=0
+  # SC2094 disable: the flock-against-self pattern (`9>>"$active"`) opens fd 9
+  # against the file the body reads via `cat "$active"`. This is intentional —
+  # flock advisories are inode-bound, so the writer's flock and the rotator's
+  # flock must target the same inode for them to interlock. Same pattern as
+  # scripts/rule-metrics-aggregate.sh:291-295.
+  # shellcheck disable=SC2094
+  (
+    if ! flock -w "$timeout_s" -x 9; then
+      exit 0
+    fi
+    # Re-check inside lock (TOCTOU defense — a peer writer may have rotated
+    # between our pre-check and our acquire). `stat -L` parity with the
+    # outer pre-check.
+    local s2 m2 now2 age2
+    read -r s2 m2 < <(stat -L -c "%s %Y" "$active" 2>/dev/null) || exit 0
+    now2=$(date -u +%s 2>/dev/null) || exit 0
+    age2=$(( now2 - m2 ))
+    if (( s2 <= size_threshold )) && (( age2 <= age_threshold_seconds )); then
+      exit 0
+    fi
+    # Copy first, truncate only on success. Preserves data on disk-full / OOM:
+    # if cat fails, $active stays intact and the next call retries. We exit 11
+    # to signal "rotation attempted but archive write failed" so the outer
+    # scope can emit a one-shot warn AND clean up any partial archive bytes.
+    if cat "$active" >> "$archive" 2>/dev/null; then
+      : > "$active"
+      exit 10
+    fi
+    exit 11
+  ) 9>>"$active" 2>/dev/null || rotated=$?
+
+  case "$rotated" in
+    10)
+      # gzip outside the lock — concurrent writers don't wait on compression.
+      # Failure leaves the .jsonl archive intact, readable by aggregators.
+      gzip -f "$archive" 2>/dev/null || true
+      ;;
+    11)
+      # Archive write failed mid-copy. Clean up the partial archive so the
+      # next attempt starts clean (otherwise the collision-suffix branch fires
+      # and orphans the partial forever). Then warn ONCE per process via the
+      # marker pattern at incidents.sh:130-138, and signal the failure to
+      # sentinel-aware callers via a non-zero return (issue #3509).
+      rm -f "$archive" 2>/dev/null || true
+      local _log_rotation_warned_marker="/tmp/log-rotation-warned-$$"
+      if [[ ! -f "$_log_rotation_warned_marker" ]]; then
+        SOLEUR_HOOK_NAME="log-rotation" headless_or_stderr warn "failed to archive $active (disk full? permissions?)"
+        : > "$_log_rotation_warned_marker" 2>/dev/null || true
+      fi
+      return 1
+      ;;
+  esac
+  return 0
+}