oh-my-opencode 4.5.12 → 4.7.0

package/.agents/skills/opencode-qa/scripts/db-session-by-text.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# db-session-by-text.sh - find opencode message TEXT by content.
+#
+# Message text lives inside the `part` table as JSON blobs
+# (json_extract(data,'$.text') for text parts). The `part` table holds the bulk
+# of the DB (tens of GB of tool output), so an UNBOUNDED text scan is refused.
+# You MUST scope the search to a bounded, recent set of sessions:
+#   --session ses_...    one session (indexed, instant)
+#   --recent N           the N most-recent sessions (default 25)
+#   --since "<window>"   sessions created within a window (e.g. "7 days"),
+#                        capped at the 200 most-recent in that window
+#
+# All bounded modes use `part.session_id IN (SELECT id FROM session ORDER BY
+# time_created DESC LIMIT ...)`, which drives the part_session_idx on exactly
+# the newest sessions. (A naive JOIN with `WHERE session.time_created >= X`
+# scans oldest-first and can take ~50s; the IN-subquery form returns in ~20ms.)
+#
+# Usage:
+#   db-session-by-text.sh --session ses_3a4e... "ULTRAWORK"
+#   db-session-by-text.sh --recent 50 "permission denied"
+#   db-session-by-text.sh --since "7 days" --limit 50 "TODO"
+#   db-session-by-text.sh --self-test
+#
+# Output: JSON array of {session_id, part_id, snippet} (snippet = first 120
+# chars of the matching text part).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+oqa_text_scoped() {
+  local sid needle limit esc_id esc_txt
+  sid="$1"; needle="$2"; limit="${3:-50}"
+  esc_id="$(oqa_sql_escape "$sid")"
+  esc_txt="$(oqa_sql_escape "$needle")"
+  oqa_db_query "SELECT
+      p.session_id AS session_id,
+      p.id         AS part_id,
+      substr(json_extract(p.data,'\$.text'),1,120) AS snippet
+    FROM part p
+    WHERE p.session_id='$esc_id'
+      AND json_extract(p.data,'\$.type')='text'
+      AND json_extract(p.data,'\$.text') LIKE '%$esc_txt%'
+    LIMIT $limit"
+}
+
+oqa_text_recent() {
+  local n needle limit esc_txt
+  n="$1"; needle="$2"; limit="${3:-50}"
+  case "$n" in (*[!0-9]*|"") n=25 ;; esac
+  esc_txt="$(oqa_sql_escape "$needle")"
+  oqa_db_query "SELECT
+      p.session_id AS session_id,
+      p.id         AS part_id,
+      substr(json_extract(p.data,'\$.text'),1,120) AS snippet
+    FROM part p
+    WHERE p.session_id IN (SELECT id FROM session ORDER BY time_created DESC LIMIT $n)
+      AND json_extract(p.data,'\$.type')='text'
+      AND json_extract(p.data,'\$.text') LIKE '%$esc_txt%'
+    LIMIT $limit"
+}
+
+oqa_text_since() {
+  local window needle limit esc_win esc_txt
+  window="$1"; needle="$2"; limit="${3:-50}"
+  esc_win="$(oqa_sql_escape "$window")"
+  esc_txt="$(oqa_sql_escape "$needle")"
+  # Cap at the 200 most-recent sessions inside the window and drive
+  # part_session_idx via an IN-subquery (newest-first) to stay fast.
+  oqa_db_query "SELECT
+      p.session_id AS session_id,
+      p.id         AS part_id,
+      substr(json_extract(p.data,'\$.text'),1,120) AS snippet
+    FROM part p
+    WHERE p.session_id IN (
+        SELECT id FROM session
+        WHERE time_created >= (strftime('%s','now','-$esc_win') * 1000)
+        ORDER BY time_created DESC LIMIT 200)
+      AND json_extract(p.data,'\$.type')='text'
+      AND json_extract(p.data,'\$.text') LIKE '%$esc_txt%'
+    LIMIT $limit"
+}
+
+oqa_text_main() {
+  local sid="" window="" recent="" limit=50 needle=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --session) sid="$2"; shift 2 ;;
+      --recent)  recent="$2"; shift 2 ;;
+      --since)   window="$2"; shift 2 ;;
+      --limit)   limit="$2"; shift 2 ;;
+      *)         needle="$1"; shift ;;
+    esac
+  done
+  if [ -z "$needle" ]; then
+    oqa_log "error: missing search text"; return 2
+  fi
+  if [ -n "$sid" ]; then
+    oqa_text_scoped "$sid" "$needle" "$limit"; return 0
+  fi
+  if [ -n "$recent" ]; then
+    oqa_text_recent "$recent" "$needle" "$limit"; return 0
+  fi
+  if [ -n "$window" ]; then
+    oqa_text_since "$window" "$needle" "$limit"; return 0
+  fi
+  oqa_log "error: refusing an unbounded global text scan over the multi-GB part table."
+  oqa_log "       scope it with --session <ses_id>, --recent <N>, or --since \"<N days|hours>\"."
+  return 2
+}
+
+oqa_self_test() {
+  oqa_require opencode jq || return 1
+  local fails=0
+
+  # 1) scoped: find a recent session with text parts, derive a needle from one.
+  local sid needle out n
+  sid="$(oqa_db_query "SELECT session_id AS s FROM part WHERE json_extract(data,'\$.type')='text' ORDER BY rowid DESC LIMIT 1" | jq -r '.[0].s // empty')"
+  if [ -z "$sid" ]; then oqa_log "FAIL: no text parts found"; return 1; fi
+  needle="$(oqa_db_query "SELECT substr(json_extract(data,'\$.text'),1,8) AS t FROM part WHERE session_id='$(oqa_sql_escape "$sid")' AND json_extract(data,'\$.type')='text' AND length(json_extract(data,'\$.text'))>=8 LIMIT 1" | jq -r '.[0].t // empty')"
+  if [ -z "$needle" ]; then oqa_log "FAIL: could not derive a text needle"; return 1; fi
+  out="$(oqa_text_main --session "$sid" "$needle")"
+  n="$(printf '%s' "$out" | jq 'length')"
+  if [ "${n:-0}" -ge 1 ]; then oqa_pass "scoped text search found $n row(s) in $sid"; else oqa_log "FAIL: scoped search empty for '$needle' in $sid"; fails=$((fails+1)); fi
+
+  # 2) unbounded refusal: no --session/--since must exit 2.
+  oqa_text_main "$needle" >/dev/null 2>&1
+  if [ "$?" -eq 2 ]; then oqa_pass "unbounded global scan refused (exit 2)"; else oqa_log "FAIL: unbounded scan was not refused"; fails=$((fails+1)); fi
+
+  # 3) bounded --recent search completes well under a hard 30s budget, even in
+  #    the worst case (no early match) because the IN-subquery caps the scan to
+  #    the newest N sessions and drives part_session_idx.
+  local t0 t1
+  t0=$(date +%s)
+  oqa_text_main --recent 25 --limit 5 "oqa_no_match_$(date +%s)_zzz" >/dev/null 2>&1
+  t1=$(date +%s)
+  if [ $((t1 - t0)) -le 30 ]; then
+    oqa_pass "bounded --recent 25 worst-case search completed in $((t1-t0))s (<=30s)"
+  else
+    oqa_log "FAIL: bounded --recent search took $((t1-t0))s (>30s)"; fails=$((fails+1))
+  fi
+  # also prove --recent returns real matches for the derived needle
+  out="$(oqa_text_main --recent 25 --limit 5 "$needle" 2>/dev/null)"
+  n="$(printf '%s' "$out" | jq 'length')"
+  if [ "${n:-0}" -ge 1 ]; then oqa_pass "bounded --recent 25 found $n row(s) for '$needle'"; else oqa_log "FAIL: --recent found no rows for '$needle'"; fails=$((fails+1)); fi
+
+  [ "$fails" -eq 0 ] && { oqa_pass "db-session-by-text"; return 0; }
+  oqa_log "db-session-by-text had $fails failure(s)"; return 1
+}
+
+case "${1:-}" in
+  --self-test) oqa_self_test; exit $? ;;
+  -h|--help|"")
+    sed -n '2,24p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    [ -z "${1:-}" ] && exit 2 || exit 0 ;;
+  *)
+    oqa_require opencode jq || exit 1
+    oqa_text_main "$@" ;;
+esac

package/.agents/skills/opencode-qa/scripts/export-roundtrip.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# export-roundtrip.sh - export a session as clean JSON and verify it round-trips.
+#
+# `opencode export <id>` prints a human line ("Exporting session: ...") to
+# STDERR and the JSON document to STDOUT, so suppress stderr before piping to jq.
+# The JSON shape is { info: {id, slug, projectID, directory, title, tokens,
+# time, ...}, messages: [...] }.
+#
+# Usage:
+#   export-roundtrip.sh ses_3a4e22ad5ffebMKLt0tL7exPjZ   # prints clean JSON
+#   export-roundtrip.sh --self-test
+#
+# Tip: redirect to a file for archival: export-roundtrip.sh <id> > session.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+oqa_export() {
+  # stderr carries the "Exporting session:" banner; drop it for clean JSON.
+  opencode export "$1" 2>/dev/null
+}
+
+oqa_self_test() {
+  oqa_require opencode jq || return 1
+  local id out got title msgtype
+  id="$(oqa_db_query "SELECT id FROM session ORDER BY time_created DESC LIMIT 1" | jq -r '.[0].id // empty')"
+  if [ -z "$id" ]; then oqa_log "FAIL: no sessions to export"; return 1; fi
+
+  out="$(oqa_export "$id")"
+  # 1) stdout must be valid JSON (stderr banner excluded).
+  if ! printf '%s' "$out" | jq -e . >/dev/null 2>&1; then
+    oqa_log "FAIL: export stdout is not valid JSON for $id"; return 1
+  fi
+  # 2) the info.id must round-trip.
+  got="$(printf '%s' "$out" | jq -r '.info.id // empty')"
+  if [ "$got" != "$id" ]; then
+    oqa_log "FAIL: export .info.id '$got' != '$id'"; return 1
+  fi
+  # 3) info.title is a string and messages is an array.
+  title="$(printf '%s' "$out" | jq -r '.info.title|type' 2>/dev/null)"
+  msgtype="$(printf '%s' "$out" | jq -r '.messages|type' 2>/dev/null)"
+  if [ "$title" = "string" ] && { [ "$msgtype" = "array" ] || [ "$msgtype" = "null" ]; }; then
+    oqa_pass "export round-trips $id (info.id matches, valid JSON)"
+    return 0
+  fi
+  oqa_log "FAIL: unexpected shape (title=$title messages=$msgtype)"; return 1
+}
+
+case "${1:-}" in
+  --self-test) oqa_self_test; exit $? ;;
+  -h|--help|"")
+    sed -n '2,16p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    [ -z "${1:-}" ] && exit 2 || exit 0 ;;
+  *)
+    oqa_require opencode jq || exit 1
+    oqa_export "$1" ;;
+esac

package/.agents/skills/opencode-qa/scripts/lib/common.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# common.sh - shared helpers for opencode-qa scripts.
+#
+# Source it from a sibling script:
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   . "$SCRIPT_DIR/lib/common.sh"
+#
+# SAFETY MODEL (read this):
+#   - DB-read helpers (oqa_db_path / oqa_db_query) hit the LIVE opencode DB
+#     READ-ONLY. That is safe and intended for session investigation.
+#   - Anything that SPAWNS opencode (serve / run / tui) must run under an
+#     ISOLATED XDG sandbox (oqa_mk_isolated_xdg) so QA never writes junk
+#     sessions into the real ~/.local/share/opencode DB.
+#   - oqa_cleanup runs on EXIT and tears down servers, tmux sessions, curl
+#     watchers, and every temp dir created via the helpers.
+
+# No `set -e`: these scripts deliberately probe failure paths (401, refused).
+set -uo pipefail
+
+OQA_TMPDIRS=()
+OQA_TMUX_SESSIONS=()
+OQA_CURL_PIDS=()
+OQA_SERVER_PID=""
+
+oqa_log()  { printf '%s\n' "$*" >&2; }
+oqa_pass() { printf 'PASS: %s\n' "$*"; }
+oqa_fail() { printf 'FAIL: %s\n' "$*" >&2; return 1; }
+
+# oqa_require <bin>...  -> 0 if all present, else 1 (names the missing ones).
+oqa_require() {
+  local missing=0 b
+  for b in "$@"; do
+    if ! command -v "$b" >/dev/null 2>&1; then
+      oqa_log "missing dependency: $b"
+      missing=1
+    fi
+  done
+  return "$missing"
+}
+
+# Absolute path of the active opencode DB (resolves channel / OPENCODE_DB).
+oqa_db_path() {
+  opencode db path 2>/dev/null | head -1
+}
+
+# Escape a value for safe embedding inside a single-quoted SQL literal.
+oqa_sql_escape() {
+  local s="${1//\'/\'\'}"
+  printf '%s' "$s"
+}
+
+# Run a read-only SQL query against the active DB; emit JSON rows.
+# Usage: oqa_db_query "SELECT ... LIMIT 5"
+oqa_db_query() {
+  opencode db "$1" --format json 2>/dev/null
+}
+
+# Create an isolated XDG sandbox so a spawned opencode never touches the real
+# DB. Sets globals OQA_XDG_ROOT + OQA_PROJ and exports XDG_*; registers the
+# root for cleanup.
+#
+# IMPORTANT: call this DIRECTLY, never via $(...). Command substitution runs in
+# a subshell, which would discard the exports and the cleanup registration.
+#   oqa_mk_isolated_xdg            # good
+#   root="$OQA_XDG_ROOT"           # read the global afterwards
+oqa_mk_isolated_xdg() {
+  local root
+  root="$(mktemp -d -t oqa-xdg.XXXXXX)" || return 1
+  OQA_TMPDIRS+=("$root")
+  mkdir -p "$root/data" "$root/config" "$root/cache" "$root/state" "$root/proj"
+  export OQA_XDG_ROOT="$root"
+  export XDG_DATA_HOME="$root/data"
+  export XDG_CONFIG_HOME="$root/config"
+  export XDG_CACHE_HOME="$root/cache"
+  export XDG_STATE_HOME="$root/state"
+  export OQA_PROJ="$root/proj"
+  # keep the sandbox offline + fast
+  export OPENCODE_DISABLE_AUTOUPDATE=1
+  export OPENCODE_DISABLE_MODELS_FETCH=1
+}
+
+# Print a free TCP port on 127.0.0.1.
+oqa_free_port() {
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1",0)); print(s.getsockname()[1]); s.close()'
+  elif command -v bun >/dev/null 2>&1; then
+    bun -e 'const s=Bun.listen({hostname:"127.0.0.1",port:0,socket:{data(){}}});console.log(s.port);s.stop()'
+  else
+    # last resort: a high random port (small race window)
+    printf '%s' "$(( (RANDOM % 20000) + 40000 ))"
+  fi
+}
+
+# Poll an HTTP url until it accepts a connection (any status) or times out.
+# Usage: oqa_wait_http <url> [user:pass] [timeout_s]
+oqa_wait_http() {
+  local url="$1" auth="${2:-}" timeout="${3:-25}" deadline
+  deadline=$(( $(date +%s) + timeout ))
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    if [ -n "$auth" ]; then
+      curl -s -o /dev/null -u "$auth" "$url" && return 0
+    else
+      curl -s -o /dev/null "$url" && return 0
+    fi
+    sleep 0.2
+  done
+  return 1
+}
+
+# Start an isolated, password-protected headless server.
+# Sets globals OQA_SERVER_URL / OQA_SERVER_PASS / OQA_SERVER_PORT / OQA_SERVER_PID.
+# Returns 1 if it never becomes ready.
+#
+# IMPORTANT: call this DIRECTLY, never via $(...). The PID + exports must land
+# in the caller's shell so oqa_cleanup can kill the server on exit.
+#   oqa_start_server || { oqa_log "no server"; exit 1; }
+#   url="$OQA_SERVER_URL"
+oqa_start_server() {
+  oqa_mk_isolated_xdg || return 1
+  local port pass
+  port="$(oqa_free_port)"
+  pass="oqa-${RANDOM}${RANDOM}"
+  OPENCODE_SERVER_PASSWORD="$pass" opencode serve --port "$port" --hostname 127.0.0.1 \
+    >"$XDG_STATE_HOME/serve.log" 2>&1 &
+  OQA_SERVER_PID=$!
+  export OQA_SERVER_PORT="$port"
+  export OQA_SERVER_PASS="$pass"
+  export OQA_SERVER_URL="http://127.0.0.1:$port"
+  if ! oqa_wait_http "$OQA_SERVER_URL/global/health" "opencode:$pass" 30; then
+    oqa_log "server failed to start; log follows:"
+    cat "$XDG_STATE_HOME/serve.log" >&2 2>/dev/null || true
+    return 1
+  fi
+}
+
+# Teardown everything the helpers created. Safe to call multiple times.
+oqa_cleanup() {
+  if [ -n "${OQA_SERVER_PID:-}" ]; then
+    kill "$OQA_SERVER_PID" 2>/dev/null || true
+    sleep 0.3
+    kill -9 "$OQA_SERVER_PID" 2>/dev/null || true
+    OQA_SERVER_PID=""
+  fi
+  local s p d
+  for s in "${OQA_TMUX_SESSIONS[@]:-}"; do
+    [ -n "$s" ] && tmux kill-session -t "$s" 2>/dev/null || true
+  done
+  for p in "${OQA_CURL_PIDS[@]:-}"; do
+    [ -n "$p" ] && kill "$p" 2>/dev/null || true
+  done
+  for d in "${OQA_TMPDIRS[@]:-}"; do
+    [ -n "$d" ] && rm -rf "$d" 2>/dev/null || true
+  done
+  OQA_TMPDIRS=()
+  OQA_TMUX_SESSIONS=()
+  OQA_CURL_PIDS=()
+}
+trap oqa_cleanup EXIT
+
+# ---- self-check ------------------------------------------------------------
+# Run: bash scripts/lib/common.sh --self-check
+oqa__self_check() {
+  local fails=0
+
+  if oqa_require opencode sqlite3 curl jq tmux; then
+    oqa_pass "dependencies present (opencode sqlite3 curl jq tmux)"
+  else
+    oqa_log "FAIL: missing dependencies"; fails=$((fails+1))
+  fi
+
+  local dbp; dbp="$(oqa_db_path)"
+  if [ -n "$dbp" ] && [ -f "$dbp" ]; then
+    oqa_pass "oqa_db_path -> $dbp"
+  else
+    oqa_log "FAIL: oqa_db_path returned '$dbp'"; fails=$((fails+1))
+  fi
+
+  local esc; esc="$(oqa_sql_escape "a'b'c")"
+  if [ "$esc" = "a''b''c" ]; then
+    oqa_pass "oqa_sql_escape quotes single quotes"
+  else
+    oqa_log "FAIL: oqa_sql_escape -> '$esc'"; fails=$((fails+1))
+  fi
+
+  local port; port="$(oqa_free_port)"
+  if [ "$port" -gt 0 ] 2>/dev/null; then
+    oqa_pass "oqa_free_port -> $port"
+  else
+    oqa_log "FAIL: oqa_free_port -> '$port'"; fails=$((fails+1))
+  fi
+
+  # isolation + trap teardown: an inner shell creates a sandbox (calling the
+  # helper DIRECTLY so the cleanup registration survives) and exits; the EXIT
+  # trap must remove it. We pass the sandbox path out via a marker file.
+  local marker isodir
+  marker="$(mktemp -t oqa-marker.XXXXXX)"
+  bash -c '. "'"${BASH_SOURCE[0]}"'"; oqa_mk_isolated_xdg; printf "%s" "$OQA_XDG_ROOT" > "'"$marker"'"'
+  isodir="$(cat "$marker" 2>/dev/null)"; rm -f "$marker"
+  if [ -n "$isodir" ] && [ ! -d "$isodir" ]; then
+    oqa_pass "isolated XDG sandbox auto-removed on exit ($isodir)"
+  else
+    oqa_log "FAIL: sandbox not cleaned: '$isodir' (exists=$([ -d "$isodir" ] && echo yes || echo no))"; fails=$((fails+1))
+  fi
+
+  if [ "$fails" -eq 0 ]; then
+    oqa_pass "common.sh self-check"
+    return 0
+  fi
+  oqa_log "common.sh self-check had $fails failure(s)"
+  return 1
+}
+
+if [ "${1:-}" = "--self-check" ]; then
+  oqa__self_check
+  exit $?
+fi

package/.agents/skills/opencode-qa/scripts/server-smoke.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# server-smoke.sh - boot an ISOLATED opencode HTTP server and verify the core
+# API surface end to end. Uses an isolated XDG sandbox + a random password, so
+# it never touches the real ~/.local/share/opencode DB, and tears the server
+# down on exit.
+#
+# Checks:
+#   1. GET /global/health            -> {"healthy":true,"version":...}
+#   2. GET /doc                      -> OpenAPI spec with >=100 paths
+#   3. GET /session (no credentials) -> HTTP 401 (auth is enforced)
+#
+# Usage:
+#   server-smoke.sh              # run the smoke test
+#   server-smoke.sh --self-test  # same thing (alias for the QA sweep)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+oqa_server_smoke() {
+  oqa_require opencode curl jq || return 1
+  if ! oqa_start_server; then
+    oqa_log "FAIL: server did not become ready"; return 1
+  fi
+  local url="$OQA_SERVER_URL" auth="opencode:$OQA_SERVER_PASS" fails=0
+
+  local healthy version
+  healthy="$(curl -s -u "$auth" "$url/global/health" | jq -r '.healthy // false')"
+  version="$(curl -s -u "$auth" "$url/global/health" | jq -r '.version // "?"')"
+  if [ "$healthy" = "true" ]; then
+    oqa_pass "GET /global/health healthy=true version=$version ($url)"
+  else
+    oqa_log "FAIL: /global/health healthy=$healthy"; fails=$((fails+1))
+  fi
+
+  local npaths
+  npaths="$(curl -s -u "$auth" "$url/doc" | jq '.paths | length' 2>/dev/null)"
+  if [ "${npaths:-0}" -ge 100 ]; then
+    oqa_pass "GET /doc lists $npaths documented paths (>=100)"
+  else
+    oqa_log "FAIL: /doc path count=$npaths"; fails=$((fails+1))
+  fi
+
+  local code
+  code="$(curl -s -o /dev/null -w '%{http_code}' "$url/session?directory=$OQA_PROJ")"
+  if [ "$code" = "401" ]; then
+    oqa_pass "unauthenticated GET /session rejected with HTTP 401"
+  else
+    oqa_log "FAIL: unauthenticated /session returned $code (expected 401)"; fails=$((fails+1))
+  fi
+
+  if [ "$fails" -eq 0 ]; then
+    oqa_pass "server-smoke"
+    return 0
+  fi
+  oqa_log "server-smoke had $fails failure(s)"; return 1
+}
+
+case "${1:-}" in
+  -h|--help)
+    sed -n '2,18p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 0 ;;
+  *)
+    oqa_server_smoke; exit $? ;;
+esac

package/.agents/skills/opencode-qa/scripts/sse-hook-probe.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# sse-hook-probe.sh - QA opencode's event stream (the plumbing behind hooks).
+#
+# opencode publishes lifecycle events over Server-Sent Events at GET /event
+# (per-instance) and GET /global/event. Plugins observe the same events via the
+# `event` hook, so confirming an event on the wire is how you prove a hook
+# would have fired.
+#
+# Two modes:
+#   (default / --self-test)  Spawn an ISOLATED server and assert the stream
+#                            opens with a `server.connected` event. No real DB
+#                            is touched. This proves the SSE plumbing works.
+#   --attach <url>           Watch an ALREADY-RUNNING server's /event stream for
+#                            a specific event type (default: server.connected).
+#                            Use this against your real server to verify a hook
+#                            or action. Pair it with a prompt in another shell:
+#                              curl -X POST -u opencode:$PASS \
+#                                -H 'Content-Type: application/json' \
+#                                -d '{"parts":[{"type":"text","text":"hi"}]}' \
+#                                "<url>/session/<ses_id>/prompt_async?directory=<dir>"
+#                            then watch for e.g. message.part.updated.
+#
+# --attach options:
+#   --password <p>   server password (user defaults to "opencode")
+#   --user <u>       server username (default: opencode)
+#   --directory <d>  instance directory (default: $PWD)
+#   --event <type>   event type to wait for (default: server.connected)
+#   --timeout <s>    seconds to wait (default: 15)
+#
+# Usage:
+#   sse-hook-probe.sh --self-test
+#   sse-hook-probe.sh --attach http://127.0.0.1:4096 --password secret \
+#       --directory "$PWD" --event message.part.updated --timeout 30
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+# Watch an SSE stream for an event type. Args: url auth directory event timeout
+# Returns 0 if seen, 1 otherwise. Always kills its curl watcher.
+oqa_sse_watch() {
+  local url="$1" auth="$2" dir="$3" want="$4" timeout="${5:-15}"
+  local out cpid found="" deadline
+  out="$(mktemp -t oqa-sse.XXXXXX)"; OQA_TMPDIRS+=("$out")
+  if [ -n "$auth" ]; then
+    curl -sN -u "$auth" "$url/event?directory=$dir" >"$out" 2>/dev/null &
+  else
+    curl -sN "$url/event?directory=$dir" >"$out" 2>/dev/null &
+  fi
+  cpid=$!; OQA_CURL_PIDS+=("$cpid")
+  deadline=$(( $(date +%s) + timeout ))
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    if grep -q "\"$want\"" "$out" 2>/dev/null; then found=1; break; fi
+    kill -0 "$cpid" 2>/dev/null || break
+    sleep 0.2
+  done
+  kill "$cpid" 2>/dev/null || true
+  if [ -n "$found" ]; then
+    printf 'first matching event: '
+    grep -m1 "\"$want\"" "$out" | sed 's/^data: //' | jq -c '{type: .type}' 2>/dev/null || true
+    return 0
+  fi
+  oqa_log "stream head (no '$want' within ${timeout}s):"; head -5 "$out" >&2
+  return 1
+}
+
+oqa_self_test() {
+  oqa_require opencode curl jq || return 1
+  if ! oqa_start_server; then oqa_log "FAIL: server did not start"; return 1; fi
+  if oqa_sse_watch "$OQA_SERVER_URL" "opencode:$OQA_SERVER_PASS" "$OQA_PROJ" "server.connected" 15; then
+    oqa_pass "SSE /event opened and delivered server.connected"
+    return 0
+  fi
+  oqa_log "FAIL: did not observe server.connected"; return 1
+}
+
+oqa_attach_mode() {
+  local url="" user="opencode" pass="" dir="$PWD" event="server.connected" timeout=15
+  shift # drop --attach
+  url="$1"; shift || true
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --password) pass="$2"; shift 2 ;;
+      --user)     user="$2"; shift 2 ;;
+      --directory) dir="$2"; shift 2 ;;
+      --event)    event="$2"; shift 2 ;;
+      --timeout)  timeout="$2"; shift 2 ;;
+      *) oqa_log "unknown option: $1"; shift ;;
+    esac
+  done
+  [ -n "$url" ] || { oqa_log "error: --attach requires a URL"; return 2; }
+  local auth=""; [ -n "$pass" ] && auth="$user:$pass"
+  oqa_log "watching $url/event?directory=$dir for '$event' (<=${timeout}s)"
+  if oqa_sse_watch "$url" "$auth" "$dir" "$event" "$timeout"; then
+    oqa_pass "observed '$event' on $url"
+    return 0
+  fi
+  oqa_log "FAIL: '$event' not observed"; return 1
+}
+
+case "${1:-}" in
+  --attach) oqa_attach_mode "$@"; exit $? ;;
+  -h|--help)
+    sed -n '2,34p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 0 ;;
+  *) oqa_self_test; exit $? ;;
+esac