#!/usr/bin/env bash # logs-read.sh — Shell counterpart to the logs-read MCP tool. # # On rc-spawn / claude.ai-code installs the per-session evidence is the Claude # Code JSONL transcript under the configDir, NOT a per-account stream log. # So the bare mode (Task 585) accepts a claude.ai `session_` (or its # bare suffix, or the intrinsic / a uuid prefix), maps it to the local # via sessions/.json (or the .meta.json bridgeIds, or a # content scan), and prints one timestamp-ordered timeline merging the parent # transcript with every subagents/agent-*.jsonl — flagging each subagent # is_error tool_result inline (agentType + failing tool + error text). An # explicit still reads the legacy per-account stream log. # # Modes: # logs-read.sh Merged JSONL session+subagent timeline # logs-read.sh Legacy per-account stream-log read # logs-read.sh --scan-subagent-errors [N] List subagent transcripts with is_error # results (silent-failure audit; N = most- # recent N transcripts, default all) # logs-read.sh --tail [type] [lines] Tail most recent file of type # logs-read.sh --grep [type] Legacy grep across log files # # Types: agent-stream (canonical, per-session tool-use/tool-result archive; # `system` is kept as a backwards-compatible alias), session, error, # heartbeat, public, server, mcp, vnc, mem, chat-attempts # For per-session types (agent-stream/system/session/error/public): sessionKey # is required in the first mode. For platform-scoped types (server/vnc/ # heartbeat/mem): the id is ignored. chat-attempts is --tail-only: # cross-grep of edge.log + server.log for the chat-ingress quartet within # the most recent N minutes. # # Every invocation writes a one-line trailer describing files searched, # matches returned, and files rejected — empty output never leaves a reader # guessing why. On a miss the script appends a one-line # `[log-tee] missing-on-resolve sessionKey=<8> surface=logs-read-sh # reason=...` entry to server.log so the writer-side existence contract is # the authoritative signal. # # Exit codes: # 0 Success (output produced) # 1 No matches / file not found (clean, not an error) # 2 Usage error or missing directory set -euo pipefail # --- Resolve PLATFORM_ROOT from script location --- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PLATFORM_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" # --- Resolve account logs directory --- # Phase 0: single account, resolved by glob. Errors if missing. # Accounts live at {installDir}/data/accounts/ — outside the platform/ wipe zone. INSTALL_DIR="$(dirname "$PLATFORM_ROOT")" # --- Resolve server log (platform-scoped, not account-scoped) --- # Convention: configDir = ".${installDir}" (e.g. installDir "maxy" → configDir ".maxy") INSTALL_DIR_NAME=$(basename "$INSTALL_DIR") CONFIG_DIR="$HOME/.$INSTALL_DIR_NAME" SERVER_LOG="$CONFIG_DIR/logs/server.log" VNC_LOG="$CONFIG_DIR/logs/vnc-boot.log" # Task 1593 — the standing memory sampler (rss-sampler.sh) writes its persistent # log directly under the configDir (persistDir == CONFIG_DIR), NOT under logs/. # `--tail mem` surfaces it so the approach-to-OOM diagnostic is one SSH command. MEM_LOG="$CONFIG_DIR/rss-sampler.log" # --- Resolve the Claude Code state tree (Task 585) --- # rc-spawn per-session evidence is NOT under data/accounts//logs/ — it is # the Claude Code JSONL transcript tree under the configDir. The session # manager exports CLAUDE_CONFIG_DIR for the spawned `claude` processes; an # operator shell usually has it unset, so derive the brand-isolated default # ($CONFIG_DIR/.claude) and honour an explicit override (mirrors # jsonl-path.ts's claudeStateRoot). Layout consumed by the and scan # modes: # projects//.jsonl — parent transcript # projects///subagents/agent-.jsonl — child transcripts # projects///subagents/agent-.meta.json — {agentType,...} # projects//.meta.json — sidecar (carries bridgeIds) # sessions/.json — {sessionId, bridgeSessionId} CLAUDE_TREE="${CLAUDE_CONFIG_DIR:-$CONFIG_DIR/.claude}" PROJECTS_ROOT="$CLAUDE_TREE/projects" SESSIONS_DIR="$CLAUDE_TREE/sessions" # --- Resolve account log dirs (best-effort; required only by stream-log modes) --- # On rc-spawn installs data/accounts// exists but carries no logs/ subdir, # so this array is legitimately empty. The per-session JSONL mode and the # --scan-subagent-errors mode do NOT touch it; the stream-log tail/grep/ # explicit-type modes call require_account_logs() before iterating it, which # preserves their original exit-2 "missing directory" contract. ACCOUNTS_DIR="$INSTALL_DIR/data/accounts" ACCOUNT_LOG_DIRS=() if [[ -d "$ACCOUNTS_DIR" ]]; then shopt -s nullglob for _adir in "$ACCOUNTS_DIR"/*/; do [[ -d "${_adir}logs" ]] && ACCOUNT_LOG_DIRS+=("${_adir}logs") done shopt -u nullglob fi MULTI_ACCOUNT=$(( ${#ACCOUNT_LOG_DIRS[@]} > 1 ? 1 : 0 )) # Stream-log modes require at least one account log dir; the JSONL mode # and the scan mode do not. Called at the entry of the stream-log readers so # the configDir-only modes never dead-end on a missing data/accounts tree. require_account_logs() { if [[ ! -d "$ACCOUNTS_DIR" ]]; then echo "Error: accounts directory does not exist: $ACCOUNTS_DIR" >&2 exit 2 fi if [[ ${#ACCOUNT_LOG_DIRS[@]} -eq 0 ]]; then echo "Error: no account log directories found in $ACCOUNTS_DIR" >&2 exit 2 fi } # Account ID suffix for headers — only shown when multiple accounts exist. account_suffix() { if [[ $MULTI_ACCOUNT -eq 1 ]]; then local path="$1" path="${path%/}" if [[ "$path" == */logs ]]; then local acct_id acct_id=$(basename "$(dirname "$path")") echo " [${acct_id:0:8}]" else local acct_id acct_id=$(basename "$(dirname "$(dirname "$path")")") echo " [${acct_id:0:8}]" fi fi } # --- Prefix map (mirrors MCP tool exactly) --- # Per-conversation types: stream log + its siblings (stderr, sse, public). # `agent-stream` is the canonical name for the per-conversation # tool-use/tool-result archive; `system` is kept as a backwards-compatible # alias. prefix_for_type() { case "$1" in agent-stream|system) echo "claude-agent-stream-" ;; error) echo "claude-agent-stderr-" ;; session) echo "sse-events-" ;; public) echo "public-agent-stream-" ;; mcp) echo "mcp-" ;; *) echo "" ;; esac } # Which types are per-conversation (the first mode's convId argument applies) is_per_conversation_type() { case "$1" in agent-stream|system|error|session|public) return 0 ;; *) return 1 ;; esac } SEARCH_TYPES="agent-stream error session public server mcp vnc" VALID_TYPES="agent-stream, system, session, error, heartbeat, public, server, mcp, vnc, mem, chat-attempts" # chat-attempts cross-grep prefixes. One row per chat-ingress # checkpoint emitted across edge.log + server.log: edge-side inbound/outcome, # admin-auth gate verdict, chat-route handler entry. Absence of a row at any # checkpoint localises the failure to one stage of the ingress pipeline. CHAT_ATTEMPT_GREP='\[edge-admin\] inbound|\[edge-admin\] outcome|\[admin-auth\] outcome|\[chat-route\] entered' # Authoritative sessionKey character set. # Writer-side emits `sk_` filenames; the underscore must # stay in this regex or every post-1008 file becomes unretrievable #. UUID v4 sessionKeys (legacy and current alternate format) # also pass. Widening past this set is unsafe: session_key is concatenated # into a glob below (`${prefix}${session_key}*.log`), so any character bash # treats as a metacharacter (`*`, `?`, `[`, `;`, `$`, etc.) would escape # literal matching. SESSIONKEY_REGEX='^[a-zA-Z0-9_-]+$' usage() { cat >&2 < Merged JSONL session+subagent timeline logs-read.sh Legacy per-account stream-log read logs-read.sh --scan-subagent-errors [N] List subagent transcripts carrying an is_error result (silent-failure audit) logs-read.sh --tail [type] [lines] Tail most recent log of type logs-read.sh --tail chat-attempts [min] Cross-grep edge.log + server.log for the chat-ingress quartet logs-read.sh --grep [type] Legacy grep across log files Types: $VALID_TYPES Default type: agent-stream | Default lines: 50 | Default chat-attempts minutes: 5 A bare reads the Claude Code JSONL transcript tree under the configDir (CLAUDE_CONFIG_DIR, default \$HOME/./.claude): it accepts a claude.ai session_, its bare suffix, or the intrinsic (or a uuid prefix), and prints the parent transcript merged with every subagent transcript, flagging subagent is_error results inline. An explicit keeps the legacy per-account stream-log read. Per-session stream-log types (agent-stream, system, session, error, public) require sessionKey; platform-scoped types (server, vnc, heartbeat, mem) ignore the id. chat-attempts is --tail-only — it aggregates the four ingress checkpoints ([edge-admin] inbound, [admin-auth] outcome, [chat-route] entered, [edge-admin] outcome) into one timeline. EOF exit 2 } validate_type() { local t="$1" case "$t" in agent-stream|system|session|error|heartbeat|public|server|mcp|vnc|mem|chat-attempts) return 0 ;; *) echo "Error: invalid type '$t'. Valid types: $VALID_TYPES" >&2; exit 2 ;; esac } # chat-attempts cross-grep mode. Combines edge.log + server.log # lines matching the chat-ingress quartet, filtered to the last N minutes, # sorted chronologically. Default window: 5 minutes (matches the typical # "agent doesn't respond" report window — operator sees the silence, # screenshots the chat, then runs this within a few minutes). # # Output preserves source-file prefix so operators can see whether the line # came from the edge process (edge.log) or maxy-ui (server.log). On a # successful chat POST the timeline reads: # # [edge-admin] inbound method=POST path=/api/admin/chat token=present … (edge.log) # [admin-auth] outcome=accept … (server.log) # [chat-route] entered route=admin method=POST cacheKey=… … (server.log) # [edge-admin] outcome method=POST path=/api/admin/chat status=200 … (edge.log) # # Any missing row in that sequence is itself diagnostic. Three-strike rule: # zero edge inbound = browser/network problem; inbound present + admin-auth # missing = handler unreachable; admin-auth=reject = auth failure; entered # missing after accept = Hono routing regression; outcome missing = upstream # proxy crash. chat_attempts_mode() { local minutes="${1:-5}" if ! [[ "$minutes" =~ ^[0-9]+$ ]]; then echo "Error: minutes must be a number, got '$minutes'" >&2 exit 2 fi local EDGE_LOG="$CONFIG_DIR/logs/edge.log" local since_epoch since_epoch=$(date -u -v-"${minutes}"M +%s 2>/dev/null || date -u -d "${minutes} minutes ago" +%s 2>/dev/null || true) if [[ -z "$since_epoch" ]]; then echo "Error: could not compute time window — neither BSD nor GNU date available" >&2 exit 2 fi # Each log line carries an ISO-8601 timestamp at the head (server.log via # pino, edge.log via console — both written line-buffered with leading # `YYYY-MM-DDTHH:MM:SS` then either `.sssZ` or a space). awk filters to # the time window; sed prefixes the source filename so the timeline # remains attributable; sort -k1 keeps chronological order. local filter_awk=' BEGIN { since = '"$since_epoch"' } { ts = substr($0, 1, 19) gsub("T", " ", ts) cmd = "date -u -j -f \"%Y-%m-%d %H:%M:%S\" \"" ts "\" +%s 2>/dev/null || date -u -d \"" ts "\" +%s 2>/dev/null" cmd | getline epoch close(cmd) if (epoch >= since) print } ' local hits=0 local tmp tmp=$(mktemp -t chat-attempts.XXXXXX) trap 'rm -f "$tmp"' EXIT if [[ -f "$EDGE_LOG" ]]; then grep -E "$CHAT_ATTEMPT_GREP" "$EDGE_LOG" 2>/dev/null | awk "$filter_awk" | sed 's|^|edge.log |' >> "$tmp" || true fi if [[ -f "$SERVER_LOG" ]]; then grep -E "$CHAT_ATTEMPT_GREP" "$SERVER_LOG" 2>/dev/null | awk "$filter_awk" | sed 's|^|server.log|' >> "$tmp" || true fi hits=$(wc -l < "$tmp" | tr -d ' ') if [[ "$hits" -eq 0 ]]; then echo "# chat-attempts (last ${minutes} min) — no events" >&2 echo "-- trailer: type=chat-attempts window_min=${minutes} matches=0 searched=edge.log,server.log" >&2 exit 1 fi echo "# chat-attempts (last ${minutes} min — chronological)" echo "" # Sort by the timestamp column that begins immediately after the source-file # prefix. Prefix is "edge.log " or "server.log" — both 10 chars before the # timestamp begins, so column 11 onward is the chronological key. sort -k1.11 "$tmp" echo "" >&2 echo "-- trailer: type=chat-attempts window_min=${minutes} matches=${hits} searched=edge.log,server.log" >&2 exit 0 } # --- Per-session mode: prefix-match {prefix}{sessionKey-prefix}*.log --- # # one filename shape per session: {prefix}{sessionKey}.log. # The operator types an 8-char-or-greater sessionKey prefix; we glob # `${prefix}${session_key}*.log` across every account log dir. The earlier # full vs preflush two-shape contract is gone: sessionKey is the single # identifier on disk, mounted from turn 1. # # Three trailer outcomes: # single hit → exit 0 (success) # zero hits → exit 1 + appends `[log-tee] missing-on-resolve sessionKey=<8> # surface=logs-read-sh reason=...` to server.log so # the writer-side existence contract is the # authoritative signal. # 2+ hits → exit 1 + reason=ambiguous-prefix candidates=[...]; never picks # # MIRROR — keep these three sites in lockstep: # - platform/ui/app/lib/logs-read-resolve.ts (TS helper, exact-match) # - platform/plugins/admin/mcp/src/index.ts (MCP tool, exact-match) per_conversation_mode() { local session_key="$1" local filter_type="${2:-agent-stream}" if [[ -z "$session_key" ]]; then echo "Error: sessionKey cannot be empty" >&2 exit 2 fi # Reject shell metacharacters in session_key — the prefix-match glob below # would otherwise turn user input into a shell pattern. SessionKeys are # `sk_` or UUID v4; both fit $SESSIONKEY_REGEX defined # near the top of the script. widened this from `[a-zA-Z0-9-]` # after the underscore-bearing format made every post-1008 # session unretrievable. if [[ ! "$session_key" =~ $SESSIONKEY_REGEX ]]; then # Observability: surface the rejection before the operator-visible error # so the adherence runner can prove writer/reader divergence. # Best-effort append; mirrors the missing-on-resolve idiom below. local rej_ts bad_char rej_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)" bad_char=$(printf '%s' "$session_key" | tr -d 'a-zA-Z0-9_-' | head -c 1) echo "${rej_ts} [logs-read] regex-rejected sessionKey-prefix=${session_key:0:12} regex=${SESSIONKEY_REGEX} sample=${bad_char}" >> "$SERVER_LOG" 2>/dev/null || true echo "Error: sessionKey contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)" >&2 exit 2 fi validate_type "$filter_type" # Platform-scoped types shortcut to their fixed files regardless of id. case "$filter_type" in server|vnc|heartbeat|mcp|mem) echo "# note: type=$filter_type is platform-scoped; sessionKey ignored — showing fixed file" >&2 tail_mode "$filter_type" "50" return ;; esac # Explicit-type per-session reads come from the per-account stream logs; # preserve the original exit-2 contract when that tree is absent. require_account_logs local prefix prefix=$(prefix_for_type "$filter_type") if [[ -z "$prefix" ]]; then echo "Error: no prefix mapping for type '$filter_type'" >&2 exit 2 fi local glob="${prefix}${session_key}*.log" local searched=0 local -a hits=() local -a hit_dirs=() shopt -s nullglob for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do searched=$((searched + 1)) for f in "$log_dir"/${prefix}${session_key}*.log; do hits+=("$f") hit_dirs+=("$log_dir") done done shopt -u nullglob if [[ ${#hits[@]} -gt 1 ]]; then local -a candidate_names=() local cf for cf in "${hits[@]}"; do candidate_names+=("$(basename "$cf")") done local joined joined=$(IFS=','; printf '%s' "${candidate_names[*]}") echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched matches=${#hits[@]} reason=ambiguous-prefix candidates=[${joined}]" >&2 exit 1 fi if [[ ${#hits[@]} -eq 1 ]]; then local hit_path="${hits[0]}" local match_dir="${hit_dirs[0]}" echo "## $(basename "$hit_path") ($filter_type)$(account_suffix "$match_dir")" cat "$hit_path" echo "" >&2 echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched matched=1" >&2 exit 0 fi # missing-on-resolve emission. Best-effort; never fails the # invocation when server.log is unwritable. local miss_ts miss_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)" echo "${miss_ts} [log-tee] missing-on-resolve sessionKey=${session_key:0:8} surface=logs-read-sh reason=\"file-not-found type=${filter_type}\"" >> "$SERVER_LOG" 2>/dev/null || true echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched found=0 tried=[${glob}] reason=file-not-found" >&2 exit 1 } # --- Legacy grep mode (backward compatibility with sessionKey-tagged lines) --- grep_mode() { local session_key="$1" local filter_type="${2:-}" if [[ -z "$session_key" ]]; then echo "Error: session key cannot be empty" >&2 exit 2 fi # grep mode reads per-account stream logs; preserve its missing-dir contract. require_account_logs if [[ -n "$filter_type" ]]; then validate_type "$filter_type" fi local types_to_search if [[ -n "$filter_type" && "$filter_type" != "heartbeat" ]]; then types_to_search="$filter_type" else types_to_search="$SEARCH_TYPES" fi local found=0 local files_searched=0 local files_rejected=0 for log_type in $types_to_search; do if [[ "$log_type" == "server" ]]; then if [[ -f "$SERVER_LOG" ]]; then files_searched=$((files_searched + 1)) local result if result=$(grep -F "$session_key" "$SERVER_LOG" 2>/dev/null); then if [[ -n "$result" ]]; then [[ $found -gt 0 ]] && echo "" echo "## server.log (server)" echo "$result" found=$((found + 1)) fi fi else files_rejected=$((files_rejected + 1)) fi continue fi if [[ "$log_type" == "vnc" ]]; then if [[ -f "$VNC_LOG" ]]; then files_searched=$((files_searched + 1)) local result if result=$(grep -F "$session_key" "$VNC_LOG" 2>/dev/null); then if [[ -n "$result" ]]; then [[ $found -gt 0 ]] && echo "" echo "## vnc-boot.log (vnc)" echo "$result" found=$((found + 1)) fi fi else files_rejected=$((files_rejected + 1)) fi continue fi local prefix prefix=$(prefix_for_type "$log_type") [[ -z "$prefix" ]] && continue for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do shopt -s nullglob local files=("$log_dir"/${prefix}*.log) shopt -u nullglob IFS=$'\n' files=($(printf '%s\n' "${files[@]}" | sort)); unset IFS for filepath in "${files[@]}"; do files_searched=$((files_searched + 1)) local file file=$(basename "$filepath") local result if result=$(grep -F "$session_key" "$filepath" 2>/dev/null); then if [[ -n "$result" ]]; then [[ $found -gt 0 ]] && echo "" echo "## $file ($log_type)$(account_suffix "$log_dir")" echo "$result" found=$((found + 1)) fi fi done done done if [[ $found -eq 0 ]]; then echo "No log lines found for session key \"$session_key\"." >&2 echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=0" >&2 exit 1 fi echo "" >&2 echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=$found" >&2 exit 0 } tail_mode() { local log_type="${1:-agent-stream}" local lines="${2:-50}" # chat-attempts is cross-grep + time-windowed, not single-file # tail. Dispatch before validate_type's numeric `lines` check (which would # be wrong here — argument 2 is `minutes`, not `lines`). if [[ "$log_type" == "chat-attempts" ]]; then chat_attempts_mode "${lines:-5}" return fi validate_type "$log_type" if ! [[ "$lines" =~ ^[0-9]+$ ]]; then echo "Error: lines must be a number, got '$lines'" >&2 exit 2 fi if [[ "$log_type" == "heartbeat" ]]; then require_account_logs local hb_file="" for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do local candidate="${log_dir}/check-due-events.log" if [[ -f "$candidate" ]]; then if [[ -z "$hb_file" ]] || [[ "$candidate" -nt "$hb_file" ]]; then hb_file="$candidate" fi fi done if [[ -z "$hb_file" ]]; then echo "No heartbeat log found yet. The platform cron may not have run." exit 1 fi echo "# check-due-events.log$(account_suffix "$hb_file")" echo "" tail -n "$lines" "$hb_file" exit 0 fi if [[ "$log_type" == "server" ]]; then if [[ ! -f "$SERVER_LOG" ]]; then echo "No server log found at $SERVER_LOG" exit 1 fi echo "# server.log" echo "" tail -n "$lines" "$SERVER_LOG" exit 0 fi if [[ "$log_type" == "vnc" ]]; then if [[ ! -f "$VNC_LOG" ]]; then echo "No vnc-boot log found at $VNC_LOG" exit 1 fi echo "# vnc-boot.log" echo "" tail -n "$lines" "$VNC_LOG" exit 0 fi # Task 1593 — the standing memory sampler log. Platform-scoped fixed file # (like server/vnc): the sessionKey is ignored. Filter with `grep op=mem-...` # per the diagnostic path in troubleshooting.md. if [[ "$log_type" == "mem" ]]; then if [[ ! -f "$MEM_LOG" ]]; then echo "No mem sampler log found at $MEM_LOG" exit 1 fi echo "# rss-sampler.log (mem)" echo "" tail -n "$lines" "$MEM_LOG" exit 0 fi # Reached only for per-session stream-log types (agent-stream/error/session/ # public/mcp); these live under the per-account log dirs. require_account_logs local prefix prefix=$(prefix_for_type "$log_type") local all_files=() for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do shopt -s nullglob local files=("$log_dir"/${prefix}*.log) shopt -u nullglob all_files+=("${files[@]}") done if [[ ${#all_files[@]} -eq 0 ]]; then echo "No log file found for type '$log_type'" exit 1 fi # Sort by mtime descending — most recent first. Per-conversation filenames # no longer sort chronologically by name (UUID suffix), so mtime is the # only reliable "most recently active" ordering. local match match=$(ls -t "${all_files[@]}" | head -1) local match_name match_name=$(basename "$match") echo "# ${match_name}$(account_suffix "$match")" echo "" tail -n "$lines" "$match" exit 0 } # === rc-spawn JSONL retrieval (Task 585) =================================== # The bare mode and --scan-subagent-errors read the Claude Code JSONL # transcript tree under the configDir, not the per-account stream logs. # python3 is the JSON dependency, deliberately not node: the systemd unit # PATH includes /usr/bin but not nvm's node bin, and python3 is already # required by setup-account.sh / seed-neo4j.sh, so this survives a minimal # non-interactive SSH PATH. argv[1] selects the mode (timeline|scan); the # program is fed via -c so logs-read.sh stays a single self-contained file. JSONL_PY=$(cat <<'PY' import sys, os, re, json, glob, collections MODE = sys.argv[1] if len(sys.argv) > 1 else '' UUID_RE = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.I) HEXPREFIX_RE = re.compile(r'^[0-9a-f]{8,}$', re.I) def clip(s, n): if not isinstance(s, str): s = '' if s is None else str(s) s = s.replace('\n', ' ').strip() return s if len(s) <= n else s[:n-1] + '…' def load_jsonl(path): rows = [] try: with open(path, 'r', errors='replace') as f: for line in f: line = line.strip() if not line: continue try: rows.append(json.loads(line)) except Exception: continue except OSError: pass return rows def load_json(path): try: with open(path, 'r', errors='replace') as f: return json.load(f) except Exception: return None def parent_jsonl_exact(projects_root, uuid): for p in glob.glob(os.path.join(projects_root, '*', uuid + '.jsonl')): return p for p in glob.glob(os.path.join(projects_root, '*', 'archive', uuid + '.jsonl')): return p return None def parent_jsonls_by_prefix(projects_root, prefix): out = set() for p in glob.glob(os.path.join(projects_root, '*', prefix + '*.jsonl')): if UUID_RE.match(os.path.basename(p)[:-6]): out.add(p) return sorted(out) def agent_type(af): o = load_json(af[:-len('.jsonl')] + '.meta.json') if isinstance(o, dict) and isinstance(o.get('agentType'), str) and o['agentType']: return o['agentType'] return None def fmt_input(d): if isinstance(d, dict): for k in ('command', 'file_path', 'pattern', 'path', 'description', 'prompt'): v = d.get(k) if isinstance(v, str) and v: return '%s=%s' % (k, v) try: return json.dumps(d, ensure_ascii=False) except Exception: return str(d) return '' if d is None else str(d) def result_text(block, row): c = block.get('content') if isinstance(c, str) and c.strip(): return c if isinstance(c, list): parts = [x.get('text') if isinstance(x, dict) else x for x in c] joined = ' '.join(p for p in parts if isinstance(p, str)) if joined.strip(): return joined tur = row.get('toolUseResult') return tur if isinstance(tur, str) else '' # Map a claude.ai session key to the local intrinsic + its parent JSONL. # Order: (a) the key already IS a uuid (or a hex prefix of one) on disk; # (b) a sessions/.json whose bridgeSessionId matches (live/recent); # (c) a .meta.json whose bridgeIds carries the suffix (persistent, so an # ENDED session whose PID file was deleted still resolves); (d) content grep # of top-level transcripts (last resort). Returns (uuid, parent_path, via) or # (None, None, reason). def resolve_uuid(projects_root, sessions_dir, key): suffix = key[len('session_'):] if key.startswith('session_') else key candidates = [key] if key == suffix else [key, suffix] for c in candidates: p = parent_jsonl_exact(projects_root, c) if p: return (os.path.basename(p)[:-6], p, 'uuid-exact') if HEXPREFIX_RE.match(c): hits = parent_jsonls_by_prefix(projects_root, c) if len(hits) == 1: return (os.path.basename(hits[0])[:-6], hits[0], 'uuid-prefix') if len(hits) > 1: return (None, None, 'ambiguous-prefix candidates=%d' % len(hits)) for pf in glob.glob(os.path.join(sessions_dir, '*.json')): o = load_json(pf) if not isinstance(o, dict): continue sid, bsid = o.get('sessionId'), o.get('bridgeSessionId') if not (isinstance(sid, str) and sid): continue if isinstance(bsid, str) and bsid and ( bsid == key or bsid == 'session_' + suffix or bsid.replace('session_', '') == suffix ): return (sid, parent_jsonl_exact(projects_root, sid), 'pid-bridge') for mf in glob.glob(os.path.join(projects_root, '*', '*.meta.json')): o = load_json(mf) if isinstance(o, dict) and isinstance(o.get('bridgeIds'), list) and suffix in o['bridgeIds']: uuid = os.path.basename(mf)[:-len('.meta.json')] if UUID_RE.match(uuid): return (uuid, parent_jsonl_exact(projects_root, uuid), 'bridgeids') # Match the verbatim key (the full session_ the operator passed, or # the bare token) — not a loose bare-suffix substring, which could collide # with unrelated body text. Refuse on multiple matches rather than silently # pick the wrong session (faithfulness over a best-effort guess). matches = [] for p in glob.glob(os.path.join(projects_root, '*', '*.jsonl')): if not UUID_RE.match(os.path.basename(p)[:-6]): continue try: with open(p, 'r', errors='replace') as f: blob = f.read() except OSError: continue if key in blob: matches.append(p) if len(matches) == 1: return (os.path.basename(matches[0])[:-6], matches[0], 'content-grep') if len(matches) > 1: return (None, None, 'ambiguous-content-match candidates=%d' % len(matches)) return (None, None, 'not-found') def subagent_dir(projects_root, uuid): for d in glob.glob(os.path.join(projects_root, '*', uuid, 'subagents')): return d return None # Append (ts, source, kind, text) tuples for one transcript. tool_use_id is # matched back to the assistant tool_use that issued it, so an is_error # tool_result names the failing tool. is_sub distinguishes a subagent's # failure (the task's target, flagged 'SUBAGENT ERROR' and counted) from the # parent session's own tool error (shown plainly, never counted as a subagent # error). Returns the count of SUBAGENT errors found (0 for the parent). # A harness rejection is a call that NEVER REACHED its tool: the CLI refused the # model's arguments, so no MCP dispatch happened and no plugin line exists # anywhere (not in server.log, not in mcp--.log, not in # mcp-lifeline). Rendering it as a plain tool error reads as "the tool is broken" # when the tool was never called -- the confusion that produced a false # customer-facing fault report (task 1692). # # InputValidationError has two sub-classes and BOTH are rejections, because # neither dispatches. The label says 'never dispatched', not 'malformed', because # only the first is malformed: # A. "...could not be parsed as JSON" -- args unparseable; the tool_use block # carries __unparsedToolInput. 52 of 170 measured 2026-07-16. # B. "...failed due to the following issue(s)" -- the JSON parsed fine and # violated the schema (wrong type, missing required). No __unparsedToolInput. # 118 of 170, so the majority; calling it 'malformed' would be wrong. # # This is the ONLY class relabelled. Deliberately NOT covered, all of which keep # rendering as '‼ tool error': # 'Error: No such tool available:' / 'Unknown skill:' -- different fault, and # the missing-tool case already has a PostToolUse hook (mcp-tool-missing.sh) # 'MCP error -32602' -- reached the server; its SDK rejected it # every unwrapped is_error payload -- the tool ran and returned a failure # # The wrapper alone is NOT a rejection discriminator: measured # 2026-07-16 across 733 SiteDesk transcripts it wraps mostly built-in tools that # RAN and failed ('File has not been read yet' x60, 'File has been modified # since read' x16). Match the error class, not the wrapper. def is_rejection(text): if not isinstance(text, str): return False return text.lstrip().startswith('InputValidationError:') def collect_events(path, source, events, is_sub, rejects=None): rows = load_jsonl(path) id2tool = {} for r in rows: if not isinstance(r, dict): continue msg = r.get('message') if isinstance(r.get('message'), dict) else {} content = msg.get('content') if isinstance(content, list): for b in content: if isinstance(b, dict) and b.get('type') == 'tool_use' and b.get('id'): id2tool[b['id']] = b.get('name') n_err = 0 for r in rows: if not isinstance(r, dict): continue ts = r.get('timestamp') or '' t = r.get('type') msg = r.get('message') if isinstance(r.get('message'), dict) else {} content = msg.get('content') if t == 'assistant': if isinstance(content, list): for b in content: if not isinstance(b, dict): continue if b.get('type') == 'text' and isinstance(b.get('text'), str) and b['text'].strip(): events.append((ts, source, 'text', 'assistant: ' + clip(b['text'], 160))) elif b.get('type') == 'tool_use': events.append((ts, source, 'tool', 'tool_use: %s(%s)' % (b.get('name'), clip(fmt_input(b.get('input')), 120)))) elif isinstance(content, str) and content.strip(): events.append((ts, source, 'text', 'assistant: ' + clip(content, 160))) elif t == 'user': if isinstance(content, list): for b in content: if isinstance(b, dict) and b.get('type') == 'tool_result' and b.get('is_error'): tool = id2tool.get(b.get('tool_use_id')) body = result_text(b, r) if is_rejection(body): # Not a tool failure: the call never ran. Never # counted as a subagent error for the same reason. flag = '‼ REJECTED (never dispatched)' if rejects is not None: rejects[tool or '?'] += 1 else: flag = '‼ SUBAGENT ERROR' if is_sub else '‼ tool error' if is_sub: n_err += 1 events.append((ts, source, 'error', '%s tool=%s error="%s"' % (flag, tool or '?', clip(body, 200)))) elif isinstance(content, str) and content.strip(): events.append((ts, source, 'text', 'user: ' + clip(content, 160))) return n_err def version_timeline(path): """Task 1724 — every JSONL row carries the CLI `version` that wrote it, and this reader dropped the field. A version change mid-session means the binary was re-executed (a resume): in the 1724 incident the 2.1.210 -> 2.1.212 flip at the resume boundary was the single most load-bearing fact in the whole investigation, and no platform instrument showed it — it was found by hand. Records every TRANSITION rather than the distinct set, so a flip back (A -> B -> A) is still visible; collapsing to a set would hide it.""" out = [] last = None for r in load_jsonl(path): if not isinstance(r, dict): continue v = r.get('version') if not isinstance(v, str) or not v or v == last: continue out.append((v, r.get('timestamp') or '-')) last = v return out def timeline(projects_root, sessions_dir, key): uuid, parent_path, via = resolve_uuid(projects_root, sessions_dir, key) if not uuid: sys.stderr.write('-- trailer: key=%s resolved=no reason=%s\n' % (key, via)) return 1 events = [] rejects = collections.Counter() if parent_path and os.path.exists(parent_path): collect_events(parent_path, 'parent', events, False, rejects) sdir = subagent_dir(projects_root, uuid) sub_count = err_count = 0 if sdir: for af in sorted(glob.glob(os.path.join(sdir, 'agent-*.jsonl'))): sub_count += 1 err_count += collect_events(af, agent_type(af) or os.path.basename(af)[:-6], events, True, rejects) events.sort(key=lambda e: e[0]) print('# session %s (resolved via %s)' % (uuid, via)) print('# parent: %s' % (parent_path or '(no parent transcript on disk)')) print('# subagents: %d subagent-errors: %d' % (sub_count, err_count)) # Task 1724 — the CLI version that wrote each row. One version is the normal # case and prints flat; a change means the binary was re-executed mid-session, # which is worth a loud line because it silently moves every tool's behaviour. vers = version_timeline(parent_path) if parent_path and os.path.exists(parent_path) else [] if len(vers) == 1: print('# cli: %s' % vers[0][0]) elif len(vers) > 1: print('# cli: %s (%d change(s) — the binary was re-executed mid-session)' % (' -> '.join('%s @ %s' % (v, ts) for v, ts in vers), len(vers) - 1)) # Repetition is the diagnostic fact: one fat-fingered call is a typo, N # identical ones against a single tool is a wedged loop. Counting it here # makes that one greppable line instead of N unrelated ones. if rejects: top = ' '.join('%s x%d' % (t, n) for t, n in rejects.most_common()) print('# rejections: %d (%s)' % (sum(rejects.values()), top)) print('') for ts, source, _kind, text in events: print('%s [%s] %s' % (ts or ('-' * 24), source, text)) sys.stderr.write('-- trailer: key=%s resolved=%s uuid=%s subagents=%d errors=%d\n' % (key, via, uuid, sub_count, err_count)) return 0 def scan(projects_root, limit): files = glob.glob(os.path.join(projects_root, '*', '*', 'subagents', 'agent-*.jsonl')) if limit > 0: files = sorted(files, key=os.path.getmtime, reverse=True)[:limit] files = sorted(files) findings = [] for af in files: rows = load_jsonl(af) id2tool = {} for r in rows: if not isinstance(r, dict): continue msg = r.get('message') if isinstance(r.get('message'), dict) else {} content = msg.get('content') if isinstance(content, list): for b in content: if isinstance(b, dict) and b.get('type') == 'tool_use' and b.get('id'): id2tool[b['id']] = b.get('name') errs = [] for r in rows: if not isinstance(r, dict): continue msg = r.get('message') if isinstance(r.get('message'), dict) else {} content = msg.get('content') if isinstance(content, list): for b in content: if isinstance(b, dict) and b.get('type') == 'tool_result' and b.get('is_error'): body = result_text(b, r) # A rejection is not a subagent failure: the subagent did # not fail, a call was never dispatched. Counting it here # would re-create the conflation the timeline just fixed. if is_rejection(body): continue errs.append((id2tool.get(b.get('tool_use_id')), body)) if errs: parent_uuid = os.path.basename(os.path.dirname(os.path.dirname(af))) findings.append((af, agent_type(af), parent_uuid, errs)) print('# subagent-error scan: %d transcript(s) scanned, %d with errors' % (len(files), len(findings))) print('') for af, atype, parent_uuid, errs in findings: print('‼ %s agentType=%s parent=%s' % (os.path.basename(af), atype or '?', parent_uuid[:8])) for tool, etext in errs: low = (etext or '').lower() extra = ' [exit-127 / command-not-found]' if ('command not found' in low or 'exit code 127' in low) else '' print(' tool=%s error="%s"%s' % (tool or '?', clip(etext, 200), extra)) sys.stderr.write('-- trailer: scan scanned=%d with_errors=%d\n' % (len(files), len(findings))) return 0 if MODE == 'timeline': sys.exit(timeline(sys.argv[2], sys.argv[3], sys.argv[4])) elif MODE == 'scan': lim = 0 if len(sys.argv) > 3 and sys.argv[3]: try: lim = int(sys.argv[3]) except ValueError: lim = 0 sys.exit(scan(sys.argv[2], lim)) else: sys.stderr.write('jsonl helper: unknown mode %r\n' % MODE) sys.exit(2) PY ) # Best-effort missing-on-resolve marker, mirroring per_conversation_mode so the # writer-side existence contract still records a miss on server.log. emit_missing_on_resolve() { local key="$1" reason="$2" ts ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)" echo "${ts} [log-tee] missing-on-resolve sessionKey=${key:0:8} surface=logs-read-sh reason=\"${reason}\"" >> "$SERVER_LOG" 2>/dev/null || true } # Bare mode: resolve the claude.ai session key against the configDir # Claude tree and print a merged parent+subagent timeline with every subagent # is_error tool_result flagged inline. jsonl_timeline_mode() { local key="$1" if [[ -z "$key" ]]; then echo "Error: sessionKey cannot be empty" >&2 exit 2 fi if [[ ! "$key" =~ $SESSIONKEY_REGEX ]]; then echo "Error: sessionKey contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)" >&2 exit 2 fi if ! command -v python3 >/dev/null 2>&1; then echo "Error: python3 is required to read the JSONL session timeline" >&2 exit 2 fi if [[ ! -d "$PROJECTS_ROOT" ]]; then echo "Error: Claude project tree not found at $PROJECTS_ROOT" >&2 echo " (set CLAUDE_CONFIG_DIR if this install uses a non-default config dir)" >&2 emit_missing_on_resolve "$key" "projects-root-missing" exit 1 fi local rc=0 python3 -c "$JSONL_PY" timeline "$PROJECTS_ROOT" "$SESSIONS_DIR" "$key" || rc=$? [[ $rc -ne 0 ]] && emit_missing_on_resolve "$key" "jsonl-not-resolved" exit $rc } # Standing scan: list every subagents/agent-*.jsonl carrying an is_error # tool_result, so a silently-failed delivery (e.g. exit-127 / command-not-found # on a nonexistent tool name) is discoverable without reproduction. Optional N # limits the scan to the N most-recently-modified subagent transcripts. scan_subagent_errors_mode() { local limit="${1:-}" if [[ -n "$limit" && ! "$limit" =~ ^[0-9]+$ ]]; then echo "Error: scan limit must be a number, got '$limit'" >&2 exit 2 fi if ! command -v python3 >/dev/null 2>&1; then echo "Error: python3 is required for the subagent-error scan" >&2 exit 2 fi if [[ ! -d "$PROJECTS_ROOT" ]]; then echo "Error: Claude project tree not found at $PROJECTS_ROOT" >&2 exit 1 fi python3 -c "$JSONL_PY" scan "$PROJECTS_ROOT" "${limit:-}" exit $? } if [[ $# -eq 0 ]]; then usage fi case "$1" in --tail) shift tail_mode "${1:-agent-stream}" "${2:-50}" ;; --grep) shift [[ $# -eq 0 ]] && usage grep_mode "$1" "${2:-}" ;; --scan-subagent-errors) shift scan_subagent_errors_mode "${1:-}" ;; --help|-h) usage ;; -*) echo "Error: unknown option '$1'" >&2 usage ;; *) # Bare resolves the configDir JSONL timeline (Task 585). An explicit # keeps the legacy per-account stream-log read unchanged. if [[ -n "${2:-}" ]]; then per_conversation_mode "$1" "$2" else jsonl_timeline_mode "$1" fi ;; esac