session-orchestrator 5.11.0 → 5.13.0

package/mods/so-hud/hooks/heredoc-scan.ts

@@ -0,0 +1,394 @@
+// ---- Heredoc bodies the shell expands (#1696) ---------------------------------
+//
+// One pass over a command text with an explicit state machine (quotes, `$'…'`, `${…}`, `$(…)`, backticks,
+// arithmetic, comments) and a queue of the heredoc operators read on the current line. At a newline that the
+// shell reads as a command terminator, the queued bodies follow in order; each body line is read once, so the
+// whole scan is linear in the text. The scanner judges nothing itself: `secretIn` names the secret a body line
+// expands, `prints` says whether the stage a heredoc feeds reaches the transcript — both supplied by rules.ts.
+
+/** A stage of a pipeline as the scanner cut it: `[start, end)` in the text, -1 while open; `pipe`: the stage after `|`. */
+type Stage = { start: number; end: number; pipe: Stage | null; cuts: Array<[number, number]>; verdict: boolean | undefined }
+
+type Pending = { delimiter: string; quoted: boolean; tabs: boolean; stage: Stage; nested: boolean }
+
+/** What a stage feeds: its text without the heredoc operators, and the next stage (`null`: unreadable, `undefined`: none). */
+export type HeredocStage = { text: string | null; next: string | null | undefined; nested: boolean }
+
+export type HeredocFinding =
+  | { kind: 'body'; name: string; delimiter: string }
+  | { kind: 'fail-closed'; reason: 'unbalanced' | 'too-many' | 'no-delimiter' | 'unreadable' }
+
+// Frames of the state machine. `code` frames read commands and heredoc operators; the others only quoting.
+type Frame = 'root' | 'subst' | 'paren' | 'procsub' | 'tick' | 'dq' | 'brace' | 'dqbrace' | 'arith' | 'bracket'
+
+// Heredoc operators queued on one line before the bodies are read. Real commands use one or two; past the cap the
+// line is not read (the operator count was the lever of the reverted attempt's quadratic run) — fail-closed.
+// NAMED CEILING (BV-004): 16; revisit if a legitimate command needs more heredocs on one line.
+const MAX_PENDING = 16
+// The characters after which an unquoted `#` starts a comment (the start of a word).
+const WORD_BREAK = /[\s;&|()<>]/
+// Where an unquoted heredoc delimiter word ends. Not `\r`: the shell keeps it in the word, so `<<EOF` on a CRLF line
+// closes only at `EOF\r` — ending the word there too keeps the body from running past the shell's closing line.
+const WORD_END = /[ \t\n;&|<>()]/
+
+// Reserved words after which the next word is a command again (`if x; then case …`).
+const COMMAND_WORDS: ReadonlySet<string> = new Set(['then', 'do', 'else', 'elif', 'if', 'while', 'until', '!', 'time'])
+
+const CODE: ReadonlySet<Frame> = new Set(['root', 'subst', 'paren', 'procsub', 'tick'])
+// Frames whose output a command reads instead of the transcript seeing it directly: judged as printing (fail-closed).
+const CAPTURED: ReadonlySet<Frame> = new Set(['subst', 'procsub', 'tick'])
+
+/**
+ * Reads every heredoc in `text` and returns the first one whose body expands a secret while its stage prints
+ * (`prints`), or a fail-closed finding: an unbalanced quote or construct at the end of the text, more than
+ * {@link MAX_PENDING} operators on one line, or an operator without a delimiter word. A quoted delimiter
+ * (`<<'EOF'`, `<<"EOF"`, `<<\EOF`, any quote in the word) keeps its body literal and is never a finding. Whether a
+ * fail-closed finding matters (a secret named anywhere in the text) is the caller's call. Stops at the first finding.
+ */
+export function scanHeredocs(
+  text: string,
+  secretIn: (line: string) => string | undefined,
+  prints: (stage: HeredocStage) => boolean,
+): HeredocFinding | null {
+  const frames: Frame[] = ['root']
+  // One open stage per code frame, parallel to `frames` (null for quoting frames).
+  const stages: Array<Stage | null> = [newStage(0)]
+  let pending: Pending[] = []
+  // Per frame: `(`/`[` inside arithmetic, `{` inside a brace, open `case` words inside a code frame.
+  const depth: number[] = [0]
+  const n = text.length
+  // The `)` that ended the last case pattern: the word after it is a command (`a) case y in …`), unlike after `$(x)`.
+  let patternClose = -1
+
+  const top = (): Frame => frames[frames.length - 1] ?? 'root'
+  const push = (frame: Frame, at: number): void => {
+    frames.push(frame)
+    stages.push(CODE.has(frame) ? newStage(at) : null)
+    depth.push(0)
+  }
+  const pop = (at: number): void => {
+    const stage = stages[stages.length - 1]
+    if (stage !== null && stage !== undefined && stage.end === -1) stage.end = at
+    frames.pop()
+    stages.pop()
+    depth.pop()
+  }
+  // Ends the open stage of the current code frame at `at`; a pipe links it to the stage that starts at `from`.
+  const cut = (at: number, from: number, pipe: boolean): void => {
+    const stage = stages[stages.length - 1]
+    if (stage === null || stage === undefined) return
+    stage.end = at
+    const next = newStage(from)
+    if (pipe) stage.pipe = next
+    stages[stages.length - 1] = next
+  }
+  const nested = (): boolean => frames.some(frame => CAPTURED.has(frame))
+
+  for (let i = 0; i < n; i += 1) {
+    const ch = text[i] ?? ''
+    const next = text[i + 1] ?? ''
+    const frame = top()
+
+    if (frame === 'dq' || frame === 'dqbrace' || frame === 'brace') {
+      if (ch === '\\') i += 1
+      else if (frame === 'dq' && ch === '"') pop(i)
+      else if (frame !== 'dq' && ch === '}') pop(i)
+      // A raw `{` inside `${…}` (`"${x:-{}"`): the shells disagree on which `}` closes it — fail-closed (#1696 M2).
+      // A nested `${` opens its own frame through openDollar.
+      else if (frame !== 'dq' && ch === '{') return { kind: 'fail-closed', reason: 'unreadable' }
+      else if (frame !== 'dq' && ch === '"') push('dq', i)
+      else if (frame === 'brace' && ch === "'") {
+        const close = text.indexOf("'", i + 1)
+        if (close === -1) return { kind: 'fail-closed', reason: 'unbalanced' }
+        i = close
+      } else if (ch === '$' || ch === '`') i = openDollar(i, frame === 'brace' ? 'brace' : 'dqbrace')
+      continue
+    }
+    if (frame === 'arith' || frame === 'bracket') {
+      const [open, close] = frame === 'arith' ? ['(', ')'] : ['[', ']']
+      const d = depth[depth.length - 1] ?? 0
+      // A newline, or `$((`/`((` closed by `) )` instead of `))`, is a command in a subshell, not arithmetic: the
+      // shells run `$((cat <<EOF … ) )` (#1696 M1) — fail-closed rather than reading its heredoc as arithmetic.
+      if (ch === '\n') return { kind: 'fail-closed', reason: 'unreadable' }
+      if (ch === open) depth[depth.length - 1] = d + 1
+      else if (ch === close && d > 0) depth[depth.length - 1] = d - 1
+      else if (ch === close) {
+        if (frame === 'arith' && next !== ')') return { kind: 'fail-closed', reason: 'unreadable' }
+        if (frame === 'arith') i += 1
+        pop(i)
+      }
+      continue
+    }
+
+    // A code frame.
+    if (ch === '\\') {
+      i += 1
+      continue
+    }
+    if (ch === "'") {
+      const close = text.indexOf("'", i + 1)
+      if (close === -1) return { kind: 'fail-closed', reason: 'unbalanced' }
+      i = close
+      continue
+    }
+    if (ch === '"') {
+      push('dq', i)
+      continue
+    }
+    if (ch === '$' || ch === '`') {
+      if (ch === '`' && frame === 'tick') pop(i)
+      else i = openDollar(i, 'code')
+      continue
+    }
+    if (ch === '#' && (i === 0 || WORD_BREAK.test(text[i - 1] ?? ''))) {
+      const nl = text.indexOf('\n', i)
+      i = (nl === -1 ? n : nl) - 1
+      continue
+    }
+    if (ch === '<' && next === '<' && text[i + 2] === '<') {
+      i += 2
+      continue
+    }
+    if (ch === '<' && next === '<') {
+      const op = readOperator(i + 2)
+      if (op === null) return { kind: 'fail-closed', reason: 'no-delimiter' }
+      if (op === 'unbalanced') return { kind: 'fail-closed', reason: 'unbalanced' }
+      const stage = stages[stages.length - 1] ?? newStage(i)
+      stage.cuts.push([i, op.end])
+      pending.push({ delimiter: op.delimiter, quoted: op.quoted, tabs: op.tabs, stage, nested: nested() })
+      if (pending.length > MAX_PENDING) return { kind: 'fail-closed', reason: 'too-many' }
+      i = op.end - 1
+      continue
+    }
+    if ((ch === '<' || ch === '>') && next === '(') {
+      push('procsub', i + 2)
+      i += 1
+      continue
+    }
+    if (ch === '(' && next === '(') {
+      push('arith', i)
+      i += 1
+      continue
+    }
+    if (ch === '(') {
+      cut(i, i + 1, false)
+      push('paren', i + 1)
+      continue
+    }
+    if ((ch === 'c' || ch === 'e') && (i === 0 || WORD_BREAK.test(text[i - 1] ?? '')) && commandPosition(i)) {
+      // In a code frame the depth counts open `case` words: the `)` after a pattern closes no `$(` (#1696:
+      // `"$(case x in x) cat <<A;; esac …)"` read the `)` as the end and the heredoc as quoted text). Only in
+      // command position: `echo esac` is an argument and closes nothing (M3).
+      const word = /^(?:case|esac)(?=[ \t\n;&|<>()]|$)/.exec(text.slice(i, i + 5))?.[0]
+      const d = depth[depth.length - 1] ?? 0
+      if (word === 'case') depth[depth.length - 1] = d + 1
+      else if (word === 'esac' && d > 0) depth[depth.length - 1] = d - 1
+      if (word !== undefined) i += 3
+      continue
+    }
+    if (ch === ')') {
+      if ((depth[depth.length - 1] ?? 0) > 0) patternClose = i
+      else if (frame === 'subst' || frame === 'paren' || frame === 'procsub') pop(i)
+      continue
+    }
+    if (ch === '|') {
+      if (next === '|') {
+        cut(i, i + 2, false)
+        i += 1
+      } else {
+        cut(i, i + (next === '&' ? 2 : 1), true)
+        if (next === '&') i += 1
+      }
+      continue
+    }
+    if (ch === ';' || ch === '&') {
+      // `&&`, `;;`, a lone `&` end the command; `&>` / `>&` / `<&` are redirections, read with the stage.
+      if (ch === '&' && (next === '>' || text[i - 1] === '>' || text[i - 1] === '<')) continue
+      const width = next === ch ? 2 : 1
+      cut(i, i + width, false)
+      i += width - 1
+      continue
+    }
+    if (ch === '\n') {
+      cut(i, i + 1, false)
+      if (pending.length === 0) continue
+      const found = readBodies(i + 1)
+      if (typeof found !== 'number') return found
+      pending = []
+      // The bodies end at `found`, the start of the next command line; the code frame is unchanged.
+      const stage = stages[stages.length - 1]
+      if (stage !== null && stage !== undefined) stage.start = found
+      i = found - 1
+    }
+  }
+  // Operators on the last line with no newline after them have no body.
+  return frames.length === 1 ? null : { kind: 'fail-closed', reason: 'unbalanced' }
+
+  /**
+   * Whether the word at `at` stands where a command starts: at the text start, after `;`, `&`, `|`, `(`, `{`, a
+   * backtick, a newline or the `)` of a case pattern, or after a reserved word that takes a command (`then`, `do`, …). Reads back over the
+   * blanks and the one word before `at` only, so every character is read back at most once (linear).
+   */
+  function commandPosition(at: number): boolean {
+    let p = at - 1
+    while (p >= 0 && (text[p] === ' ' || text[p] === '\t')) p -= 1
+    if (p < 0 || p === patternClose || /[;&|({`\n]/.test(text[p] ?? '')) return true
+    let w = p
+    while (w >= 0 && /[a-z!]/.test(text[w] ?? '')) w -= 1
+    if (w >= 0 && !/[\s;&|({`]/.test(text[w] ?? '')) return false
+    return COMMAND_WORDS.has(text.slice(w + 1, p + 1))
+  }
+
+  /** Opens the construct a `$` or backtick at `at` starts; returns the index the loop continues from. */
+  function openDollar(at: number, context: 'code' | 'brace' | 'dqbrace'): number {
+    const ch = text[at]
+    const next = text[at + 1]
+    if (ch === '`') {
+      push('tick', at + 1)
+      return at
+    }
+    if (next === '(' && text[at + 2] === '(') {
+      push('arith', at)
+      return at + 2
+    }
+    if (next === '(') {
+      push('subst', at + 2)
+      return at + 1
+    }
+    if (next === '[') {
+      push('bracket', at)
+      return at + 1
+    }
+    if (next === '{') {
+      push(context === 'code' || context === 'brace' ? 'brace' : 'dqbrace', at)
+      return at + 1
+    }
+    if (next === "'" && context !== 'dqbrace') {
+      // `$'…'`: a backslash escapes the next character, `\'` included.
+      for (let j = at + 2; j < n; j += 1) {
+        if (text[j] === '\\') j += 1
+        else if (text[j] === "'") return j
+      }
+      return n
+    }
+    return at
+  }
+
+  /** The delimiter word after `<<` at `from`; null when there is none, 'unbalanced' for an open quote in it. */
+  function readOperator(from: number): { delimiter: string; quoted: boolean; tabs: boolean; end: number } | null | 'unbalanced' {
+    let j = from
+    const tabs = text[j] === '-'
+    if (tabs) j += 1
+    while (text[j] === ' ' || text[j] === '\t') j += 1
+    const parts: string[] = []
+    let quoted = false
+    for (; j < n; j += 1) {
+      const c = text[j] ?? ''
+      if (WORD_END.test(c)) break
+      // A substitution in the delimiter word (`<<$(x)`): the shells take it literally, this reading would end the
+      // word at its `(` — fail-closed instead of guessing (#1696 M4).
+      if ((c === '$' && text[j + 1] === '(') || c === '`') return null
+      if (c === '\\') {
+        // `\` + newline continues the line and quotes nothing: `<<EO\<LF>F` is the unquoted delimiter EOF.
+        if (text[j + 1] !== '\n') {
+          quoted = true
+          parts.push(text[j + 1] ?? '')
+        }
+        j += 1
+      } else if (c === "'" || c === '"') {
+        quoted = true
+        let k = j + 1
+        for (; k < n && text[k] !== c; k += 1) {
+          if (c === '"' && text[k] === '\\') k += 1
+        }
+        if (k >= n) return 'unbalanced'
+        parts.push(text.slice(j + 1, k))
+        j = k
+      } else parts.push(c)
+    }
+    const delimiter = parts.join('')
+    return delimiter === '' && !quoted ? null : { delimiter, quoted, tabs, end: j }
+  }
+
+  /**
+   * Reads the queued bodies from `from` in order: each runs to its closing line or to the end of the text. Returns
+   * the index past the last closing line, or the first finding. Each stage is judged at most once (its verdict is
+   * kept), so many heredocs feeding one stage cost one judgement.
+   */
+  function readBodies(from: number): number | HeredocFinding {
+    let at = from
+    for (const doc of pending) {
+      let hit = false
+      let closed = false
+      // An unquoted body joins a line that ends in an odd run of `\` with the next one, as the shell does: neither
+      // `foo\` + `EOF` closes the body nor does `$T_TO\` + `KEN` hide the name. A quoted body keeps every line.
+      let carried = ''
+      // Whether the current physical line continues an earlier one: `carried` alone cannot tell, because a continued
+      // line that was only `\` leaves it empty (#1696 R2: `<<-EOF`, `\`, `<tab>EOF` does not close in zsh).
+      let continued = false
+      while (at <= n) {
+        const nl = text.indexOf('\n', at)
+        const end = nl === -1 ? n : nl
+        let physical = text.slice(at, end)
+        at = nl === -1 ? n + 1 : nl + 1
+        // `<<-` strips the tabs at the start of the logical line only: a continued line keeps its own (#1696 M5).
+        if (doc.tabs && !continued) physical = physical.replace(/^\t+/, '')
+        if (!doc.quoted && nl !== -1 && oddSlashes(physical)) {
+          carried += physical.slice(0, -1)
+          continued = true
+          continue
+        }
+        const line = carried + physical
+        carried = ''
+        continued = false
+        if (line === doc.delimiter) {
+          closed = true
+          break
+        }
+        if (hit) continue
+        const name = secretIn(line)
+        if (name === undefined) continue
+        hit = true
+        if (!doc.quoted && judge(doc)) return { kind: 'body', name, delimiter: doc.delimiter }
+      }
+      // A literal body that never closes swallowed the rest of the text unread: if the shell closed it where this
+      // reading did not (a delimiter told apart differently), a secret behind it went unseen — fail-closed.
+      if (doc.quoted && hit && !closed) return { kind: 'fail-closed', reason: 'unbalanced' }
+    }
+    return Math.min(at, n)
+  }
+
+  function judge(doc: Pending): boolean {
+    const { stage } = doc
+    if (stage.verdict === undefined) {
+      const pipe = stage.pipe
+      stage.verdict = prints({
+        text: stage.end === -1 ? null : stageText(stage),
+        next: pipe === null ? undefined : pipe.end === -1 ? null : stageText(pipe),
+        nested: doc.nested,
+      })
+    }
+    return stage.verdict
+  }
+
+  function stageText(stage: Stage): string {
+    let out = ''
+    let from = stage.start
+    for (const [a, b] of stage.cuts) {
+      out += `${text.slice(from, a)} `
+      from = b
+    }
+    return out + text.slice(from, stage.end)
+  }
+}
+
+/** Whether a line ends in an odd run of backslashes (the last one escapes the newline). */
+function oddSlashes(line: string): boolean {
+  let count = 0
+  for (let j = line.length - 1; j >= 0 && line[j] === '\\'; j -= 1) count += 1
+  return count % 2 === 1
+}
+
+function newStage(start: number): Stage {
+  return { start, end: -1, pipe: null, cuts: [], verdict: undefined }
+}

package/mods/so-hud/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/so-hud/hooks/logic.ts

@@ -0,0 +1,182 @@
+import type { SoBeacon, SoProfile, SoSnapshot } from '../types/index'
+
+export function ownerQuestion(answer: string): boolean {
+  let fence: string | null = null
+  const plain = answer.split('\n').filter(line => {
+    const mark = /^\s{0,3}(`{3,}|~{3,})/.exec(line)?.[1]
+    if (mark) {
+      if (!fence) fence = mark
+      else if (mark[0] === fence[0] && mark.length >= fence.length) fence = null
+      return false
+    }
+    return fence === null
+  }).join('\n').trim()
+  return plain.endsWith('?') || /weiter mit|soll ich|welche option|freigabe für/i.test(plain.slice(-400))
+}
+export const tables = {
+  de: { red: 'rot', error: 'Fehler', off: 'aus', partial: 'teilweise gemessen', setup: 'nicht eingerichtet', norun: 'noch kein Lauf', measurement: 'Messung fehlgeschlagen', mirror: 'Vault-Spiegel fehlgeschlagen', peer: 'Peer im selben Working Copy', scope: 'Peer ohne bekannten Scope im selben Working Copy', context: 'Kontext', cold: 'Cache kalt' },
+  en: { red: 'red', error: 'error', off: 'off', partial: 'partially measured', setup: 'not configured', norun: 'no run yet', measurement: 'Measurement failed', mirror: 'Vault mirror failed', peer: 'Peer in the same working copy', scope: 'Peer with unknown scope in the same working copy', context: 'Context', cold: 'Cache cold' },
+} as const
+/** Bound each displayed field; replace terminal controls and line separators. */
+export function displayText(value: unknown, limit = 120): string {
+  const plain = String(value ?? '').replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, ' ')
+  return plain.length <= limit ? plain : `${plain.slice(0, limit - 1)}…`
+}
+const measurementProblems = new Set(['refresh-failed', 'collector-failed', 'invalid-snapshot'])
+function measurementFailure(problems: readonly string[]): string[] {
+  return problems.filter(p => measurementProblems.has(p))
+}
+export function time(at: string | null): string {
+  if (!at || !Number.isFinite(Date.parse(at))) return '?'
+  const d = new Date(at)
+  return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+}
+export function statusText(s: SoSnapshot | null, profile: SoProfile, language: keyof typeof tables = 'de', problems: readonly string[] = []): string {
+  const t = tables[language]
+  if (!s) {
+    const failed = measurementFailure(problems)
+    return displayText(`SO ${failed.length ? `${t.measurement} (${failed.join(', ')})` : t.setup} · ${profile}`)
+  }
+  const g = s.gate.last
+  const vault = s.vault
+  const bad = vault.last_run && (vault.last_run.aborted || (vault.last_run.failed ?? 0) > 0)
+  // enabled null has two causes: no vault-integration block (not configured) or an unreadable CLAUDE.md/AGENTS.md (unknown).
+  const vaultUnset = s.degraded.includes('config:unreadable') ? '?' : t.setup
+  // Enabled but never mirrored is a state, not an unknown; '?' stays for a run whose time does not parse.
+  const vaultOn = vault.last_run === null ? t.norun : time(vault.last_run?.at ?? null)
+  // A repo where no session ever wrote events is fresh, not partially measured (F13): nothing is missing there.
+  const partial = s.degraded.some(d => d !== 'events:absent')
+  return displayText([s.state.session_type, s.wave.number !== null ? `W${s.wave.number}/${s.state.total_waves ?? '?'}` : null,
+    s.wave.role, agentsText(s.agents),
+    g ? `Gate ${g.passed === true ? 'ok' : g.passed === false ? t.red : '?'} ${time(g.at)}` : null,
+    `${s.degraded.some(d => /discovery|registry/.test(d)) ? '?' : s.peers.length} Peer`, `Vault ${vault.enabled === false ? t.off : bad ? t.error : vault.enabled === true ? vaultOn : vaultUnset}`, profile,
+    partial ? t.partial : null].filter(Boolean).map(value => displayText(value)).join(' · '), 800)
+}
+/**
+ * The running agents of this session from the collector's live map (#1580, #1633): a number is measured, `null`
+ * is unknown (`? Agents`, a map older than the session says nothing). Shown not at all without a session
+ * (`no-session`: nothing to count for) or from a collector before #1580 that sends no `running` — never as 0.
+ */
+function agentsText(agents: SoSnapshot['agents'] | undefined): string | null {
+  const running = agents?.running
+  if (running === undefined || agents?.stale_reason === 'no-session') return null
+  const decayed = agents?.decayed
+  // Agents without a Stop past 24 h (a parallel collector change): counted apart, shown only when there are some.
+  const stale = typeof decayed === 'number' && Number.isSafeInteger(decayed) && decayed > 0 ? ` (+${decayed} ?)` : ''
+  return `${typeof running === 'number' && Number.isSafeInteger(running) && running >= 0 ? running : '?'} Agents${stale}`
+}
+export function findings(s: SoSnapshot | null, context: { percent?: number; tokens?: number }, lastRequest: string | null, now: number, problems: readonly string[] = []): string[] {
+  const failed = measurementFailure(problems)
+  const out: string[] = failed.length ? [`${tables.de.measurement}: ${failed.join(', ')}`] : []
+  if (s?.gate.last?.passed === false) out.push(`Gate rot: ${s.gate.last.variant ?? '?'} ${s.gate.last.check_failed === true ? 'check_failed' : s.gate.last.exit_code ?? '?'}`)
+  if (s?.peers.some(p => p.gleiches_working_copy)) out.push(s.peers.some(p => p.gleiches_working_copy && p.scope_paths === null) ? tables.de.scope : tables.de.peer)
+  if (s?.vault.enabled && s.vault.last_run && (s.vault.last_run.aborted || (s.vault.last_run.failed ?? 0) > 0)) out.push(`${tables.de.mirror}: ${s.vault.last_run.aborted ?? s.vault.last_run.failed}`)
+  if ((context.percent ?? -1) >= 80) out.push(`Kontext ${context.percent} %`)
+  if (lastRequest && now - Date.parse(lastRequest) >= 3_600_000 && (context.tokens ?? 0) >= 100_000) out.push(tables.de.cold)
+  return out.map(value => displayText(value))
+}
+export const validId = (v: unknown): v is string => typeof v === 'string' && /^[a-zA-Z0-9_-]{1,200}$/.test(v)
+export function validateBeacon(v: unknown): v is SoBeacon {
+  if (!v || typeof v !== 'object') return false
+  const b = v as SoBeacon
+  const date = (s: unknown) => typeof s === 'string' && Number.isFinite(Date.parse(s))
+  const nullableString = (s: unknown) => s === null || typeof s === 'string'
+  return b.schema_version === 1 && validId(b.session_id) && ['arbeitet', 'wartet', 'bereit', 'blockiert', 'unbekannt'].includes(b.zustand)
+    && date(b.seit) && date(b.aktualisiert_at) && (b.letzter_request_at === null || date(b.letzter_request_at))
+    && [b.name, b.repo_name, b.branch, b.modell].every(nullableString)
+    && (b.pid === null || Number.isSafeInteger(b.pid) && b.pid > 0)
+    && (b.welle === null || Number.isSafeInteger(b.welle) && b.welle > 0)
+    && (b.kontext_prozent === null || Number.isFinite(b.kontext_prozent) && b.kontext_prozent >= 0 && b.kontext_prozent <= 100)
+    && typeof b.heuristisch === 'boolean' && [null, 'dialog', 'freigabe', 'frage'].includes(b.warte_grund)
+    && (b.zustand === 'wartet' ? b.warte_grund !== null : b.warte_grund === null)
+    && b.heuristisch === (b.warte_grund === 'frage')
+}
+export function ageBeacon(b: SoBeacon, now: number, alive: boolean): SoBeacon {
+  return now - Date.parse(b.aktualisiert_at) > 120_000 && !alive
+    ? { ...b, zustand: 'unbekannt', warte_grund: null, heuristisch: false } : b
+}
+export function completeState(answer: string): Pick<SoBeacon, 'zustand' | 'warte_grund' | 'heuristisch'> {
+  return ownerQuestion(answer) ? { zustand: 'wartet', warte_grund: 'frage', heuristisch: true } : { zustand: 'bereit', warte_grund: null, heuristisch: false }
+}
+
+// ---- Which hooks the git steps before a push can fire (#1574 proposal 3) ----
+// Per step as rules.ts records it (`gitStep`), the hook names githooks(5) of git 2.56 lists for that command.
+// A ref update fires reference-transaction, an index write post-index-change; commit and fetch end in
+// `gc --auto` (pre-auto-gc); a step that reads the index may query a core.fsmonitor hook. Options a step may carry
+// are not seen here (`commit --amend` → post-rewrite, `--no-verify` skips pre-commit), so each entry is the union.
+const FIREABLE_HOOKS: ReadonlyMap<string, readonly string[]> = new Map<string, readonly string[]>([
+  ['add', ['post-index-change', 'fsmonitor-watchman']],
+  ['status', ['post-index-change', 'fsmonitor-watchman']],
+  ['diff', ['post-index-change', 'fsmonitor-watchman']],
+  ['ls-files', ['fsmonitor-watchman']],
+  ['commit', ['pre-commit', 'prepare-commit-msg', 'commit-msg', 'post-commit', 'post-rewrite', 'reference-transaction', 'post-index-change', 'pre-auto-gc', 'fsmonitor-watchman']],
+  ['fetch', ['reference-transaction', 'pre-auto-gc']],
+  ['checkout -- <paths>', ['post-checkout', 'post-index-change', 'fsmonitor-watchman']],
+  ...['log', 'show', 'log [signature]', 'show [signature]', 'rev-parse', 'branch --show-current', 'tag --list'].map((step): [string, readonly string[]] => [step, []]),
+])
+
+/**
+ * The hook names the git steps earlier on a push's line can fire; null when any step is not in the map, which
+ * means any hook may run (fail-closed). Steps outside rules.ts's LOCAL_GIT already ask there, so they need no entry.
+ */
+export function fireableHooks(steps: readonly string[] | undefined): ReadonlySet<string> | null {
+  const names = new Set<string>()
+  for (const step of steps ?? []) {
+    const fired = FIREABLE_HOOKS.get(step)
+    if (fired === undefined) return null
+    for (const name of fired) names.add(name)
+  }
+  return names
+}
+
+/**
+ * Whether a hook defined in config (`git config --null --get-regexp ^hook\.` output) runs on one of `names`
+ * (null: on any event): a `hook.<friendly-name>.event` naming one of them, or a friendly name that is one.
+ * `.enabled` is not honoured (a disabled hook still counts). null when the output does not parse or holds a
+ * `hook.*` key git 2.56 does not document (asks).
+ */
+export function configHooksFire(output: string, names: ReadonlySet<string> | null): boolean | null {
+  if (!output.endsWith('\0')) return null
+  let fires = false
+  for (const entry of output.slice(0, -1).split('\0')) {
+    const cut = entry.indexOf('\n')
+    const key = cut === -1 ? entry : entry.slice(0, cut)
+    if (key === 'hook.jobs') continue
+    const parts = /^hook\.(.+)\.(command|event|enabled|parallel|jobs)$/.exec(key)
+    if (!parts) return null
+    const [, friendly = '', variable] = parts
+    if (cut === -1 && (variable === 'event' || variable === 'command')) return null
+    const value = entry.slice(cut + 1).trim().toLowerCase()
+    if (variable === 'event' && value !== '' && (names === null || names.has(value))) fires = true
+    if (variable === 'command' && (names === null || names.has(friendly.toLowerCase()))) fires = true
+  }
+  return fires
+}
+
+// ---- Profile band and /profile (#1552). SSOT of the effects: docs/mods.md § Profiles. ----
+export const PROFILES: readonly SoProfile[] = ['locker', 'ausgewogen', 'streng']
+const PROFILE_EFFECT: Record<SoProfile, string> = {
+  locker: 'Regel-Fallen und Kollisionen nur Warnung.',
+  ausgewogen: 'Regel-Fallen abgelehnt, Kollision fragt.',
+  streng: 'Regel-Fallen und Kollisionen abgelehnt.',
+}
+const PROFILE_ALWAYS = 'Auf jedem Profil: Secrets ausgeben wird abgelehnt, Außenwirkung wird zweimal bestätigt (interaktiv).'
+/** Any value outside the three profiles falls back to the default `ausgewogen`, as the engine does for a stored value outside `options`. */
+export function profileOf(value: unknown): SoProfile {
+  return value === 'locker' || value === 'streng' ? value : 'ausgewogen'
+}
+/** The band's lines: the profile (marked when it is only the default), what it loosens or locks, what holds on every profile. */
+export function profileLines(profile: SoProfile, chosen: boolean): string[] {
+  return [`Profil: ${profile}${chosen ? '' : ' (Vorgabe, noch nicht gewählt)'}`, PROFILE_EFFECT[profile], PROFILE_ALWAYS]
+}
+/** /profile's output: readable alone in `claude -p "/profile"`, where no band is drawn. */
+export function profileText(profile: SoProfile, chosen: boolean): string {
+  return [...profileLines(profile, chosen), `Wechseln: im Band über dem Prompt (${PROFILES.join(', ')}) oder in /config, Eintrag strictness von so-hud.`].join('\n')
+}
+/** Whether settings hold an explicit strictness for this plugin under `pluginConfigs[<plugin>[@<marketplace>]].options`. */
+export function holdsProfile(settings: unknown, plugin: string): boolean {
+  const configs: unknown = (settings as { pluginConfigs?: unknown } | null)?.pluginConfigs
+  if (!configs || typeof configs !== 'object') return false
+  return Object.entries(configs).some(([key, entry]) => key.split('@')[0] === plugin
+    && (PROFILES as readonly unknown[]).includes((entry as { options?: { strictness?: unknown } } | null)?.options?.strictness))
+}