@rubytech/create-maxy-code 0.1.223 → 0.1.225

package/payload/platform/scripts/logs-read.sh

@@ -1,14 +1,22 @@
 #!/usr/bin/env bash
 # logs-read.sh — Shell counterpart to the logs-read MCP tool.
 #
-# stream logs are per-session, not per-day or per-conversation.
-# The primary mode reads a single {prefix}-{sessionKey}.log file — the
-# operator types a sessionKey prefix and the surface returns the bytes from
-# first [spawn] to final [process-exit] without filtering. sessionKey is
-# the single identifier on disk; the earlier full vs preflush split is gone.
+# 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 <key> mode (Task 585) accepts a claude.ai `session_<id>` (or its
+# bare suffix, or the intrinsic <uuid> / a uuid prefix), maps it to the local
+# <uuid> via sessions/<pid>.json (or the <uuid>.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 <key> <type> still reads the legacy per-account stream log.
 #
 # Modes:
-#   logs-read.sh <sessionKey-or-prefix> [type]  Read {prefix}-{sessionKey}.log
+#   logs-read.sh <sessionKey>                   Merged JSONL session+subagent timeline
+#   logs-read.sh <sessionKey> <type>            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 <sessionKey> [type]     Legacy grep across log files
 #
@@ -50,32 +58,54 @@ CONFIG_DIR="$HOME/.$INSTALL_DIR_NAME"
 SERVER_LOG="$CONFIG_DIR/logs/server.log"
 VNC_LOG="$CONFIG_DIR/logs/vnc-boot.log"
 
+# --- Resolve the Claude Code state tree (Task 585) ---
+# rc-spawn per-session evidence is NOT under data/accounts/<id>/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 <key> and scan
+# modes:
+#   projects/<slug>/<uuid>.jsonl                           — parent transcript
+#   projects/<slug>/<uuid>/subagents/agent-<hex>.jsonl     — child transcripts
+#   projects/<slug>/<uuid>/subagents/agent-<hex>.meta.json — {agentType,...}
+#   projects/<slug>/<uuid>.meta.json                       — sidecar (carries bridgeIds)
+#   sessions/<pid>.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/<id>/ exists but carries no logs/ subdir,
+# so this array is legitimately empty. The per-session JSONL <key> 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"
-if [[ ! -d "$ACCOUNTS_DIR" ]]; then
-  echo "Error: accounts directory does not exist: $ACCOUNTS_DIR" >&2
-  exit 2
-fi
-
-# Glob for account dirs — may be >1 on multi-account devices
-shopt -s nullglob
-ACCOUNT_DIRS=("$ACCOUNTS_DIR"/*/)
-shopt -u nullglob
-if [[ ${#ACCOUNT_DIRS[@]} -eq 0 ]]; then
-  echo "Error: no account directories found in $ACCOUNTS_DIR" >&2
-  exit 2
-fi
-
-# Build array of account log directories that actually exist.
 ACCOUNT_LOG_DIRS=()
-for _adir in "${ACCOUNT_DIRS[@]}"; do
-  [[ -d "${_adir}logs" ]] && ACCOUNT_LOG_DIRS+=("${_adir}logs")
-done
-if [[ ${#ACCOUNT_LOG_DIRS[@]} -eq 0 ]]; then
-  echo "Error: no account log directories found in $ACCOUNTS_DIR" >&2
-  exit 2
+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 <key> 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
@@ -139,7 +169,10 @@ SESSIONKEY_REGEX='^[a-zA-Z0-9_-]+$'
 usage() {
   cat >&2 <<EOF
 Usage:
-  logs-read.sh <sessionKey-or-prefix> [type]  Read {prefix}-{sessionKey}.log
+  logs-read.sh <sessionKey>                   Merged JSONL session+subagent timeline
+  logs-read.sh <sessionKey> <type>            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
@@ -148,9 +181,14 @@ Usage:
 Types: $VALID_TYPES
 Default type: agent-stream | Default lines: 50 | Default chat-attempts minutes: 5
 
-Per-session types (agent-stream, system, session, error, public) require
-sessionKey in the first mode — the log file is named {prefix}-{sessionKey}.log.
-Platform-scoped types (server, vnc, heartbeat) ignore the id.
+A bare <sessionKey> reads the Claude Code JSONL transcript tree under the
+configDir (CLAUDE_CONFIG_DIR, default \$HOME/.<brand>/.claude): it accepts a
+claude.ai session_<id>, its bare suffix, or the intrinsic <uuid> (or a uuid
+prefix), and prints the parent transcript merged with every subagent
+transcript, flagging subagent is_error results inline. An explicit <type>
+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) 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.
@@ -305,6 +343,10 @@ per_conversation_mode() {
       ;;
   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
@@ -369,6 +411,9 @@ grep_mode() {
     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
@@ -479,6 +524,7 @@ tail_mode() {
   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"
@@ -520,6 +566,10 @@ tail_mode() {
     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")
 
@@ -550,6 +600,349 @@ tail_mode() {
   exit 0
 }
 
+# === rc-spawn JSONL retrieval (Task 585) ===================================
+# The bare <key> 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
+
+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 <uuid> + its parent JSONL.
+# Order: (a) the key already IS a uuid (or a hex prefix of one) on disk;
+# (b) a sessions/<pid>.json whose bridgeSessionId matches (live/recent);
+# (c) a <uuid>.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_<suffix> 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).
+def collect_events(path, source, events, is_sub):
+    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'))
+                        flag = '‼ SUBAGENT ERROR' if is_sub else '‼ tool error'
+                        events.append((ts, source, 'error', '%s  tool=%s  error="%s"' % (flag, tool or '?', clip(result_text(b, r), 200))))
+                        if is_sub:
+                            n_err += 1
+            elif isinstance(content, str) and content.strip():
+                events.append((ts, source, 'text', 'user: ' + clip(content, 160)))
+    return n_err
+
+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 = []
+    if parent_path and os.path.exists(parent_path):
+        collect_events(parent_path, 'parent', events, False)
+    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)
+    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))
+    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'):
+                        errs.append((id2tool.get(b.get('tool_use_id')), result_text(b, r)))
+        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 <key> 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 <key> 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
@@ -564,6 +957,10 @@ case "$1" in
     [[ $# -eq 0 ]] && usage
     grep_mode "$1" "${2:-}"
     ;;
+  --scan-subagent-errors)
+    shift
+    scan_subagent_errors_mode "${1:-}"
+    ;;
   --help|-h)
     usage
     ;;
@@ -572,6 +969,12 @@ case "$1" in
     usage
     ;;
   *)
-    per_conversation_mode "$1" "${2:-}"
+    # Bare <key> resolves the configDir JSONL timeline (Task 585). An explicit
+    # <key> <type> 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

package/payload/platform/scripts/setup-account.sh

@@ -44,15 +44,22 @@ mkdir -p "$ACCOUNT_DIR/agents/admin" "$ACCOUNT_DIR/agents/public" "$ACCOUNT_DIR/
 [ -d "$ACCOUNT_DIR/.git" ] || git init -q "$ACCOUNT_DIR"
 
 # ------------------------------------------------------------------
-# 2. Write project-level .claude/settings.json (HOOKS ONLY)
+# 2. Write project-level .claude/settings.json (permissions + hooks)
 # ------------------------------------------------------------------
-# Task 453: no `permissions.allow` block. The previous short-prefix
-# allowlist (mcp__memory__*, mcp__contacts__*, …) never matched the
-# plugin-manifest long-prefix tool names Claude Code actually emits
-# (mcp__plugin_memory_memory__…), so every Task-subagent plugin call
-# was denied at use-time. Permission enforcement comes from each agent's
-# frontmatter `tools:` list (native CC permission surface) and from the
-# PreToolUse approval hooks below for review-gated tools.
+# Task 453 removed `permissions.allow` because its short-prefix entries
+# (mcp__memory__*, mcp__contacts__*, …) never matched the plugin-manifest
+# long-prefix tool names Claude Code actually emits (mcp__plugin_memory_memory__…),
+# so every Task-subagent plugin call was denied at use-time.
+#
+# Task 583 reinstates a `permissions` block — but as wildcard
+# `allow: ["*"]` plus `defaultMode: "bypassPermissions"`. The wildcard
+# bypasses the prefix-matching defect Task 453 was avoiding (a list of one
+# entry that matches everything cannot mismatch), and `bypassPermissions`
+# short-circuits Stage 1 of the local matcher so claude.ai/code sessions
+# never fall through to the Anthropic remote auto-classifier (which routes
+# Agent dispatch to `ask` and surfaces a permission prompt no unattended
+# operator clicks). Per-agent frontmatter `tools:` lists remain the
+# permission surface for what each subagent is allowed to invoke.
 #
 # Hook commands use $PLATFORM_ROOT (set by claude-agent.ts at spawn time)
 # to locate scripts relative to the platform installation, not the account dir.
@@ -61,6 +68,11 @@ HOOKS_PATH="\$PLATFORM_ROOT/plugins/admin/hooks"
 WRITER_CRAFT_HOOKS_PATH="\$PLATFORM_ROOT/../premium-plugins/writer-craft/hooks"
 cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
 {
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "allow": ["*"],
+    "deny": []
+  },
   "hooks": {
     "PreToolUse": [
       {

package/payload/platform/services/claude-session-manager/dist/system-prompt.d.ts

@@ -99,7 +99,6 @@ export type AppendBlockResult = {
     reason: 'host-unresolved' | 'identity-unresolved';
     detail: string;
 };
-export declare const ATTACHMENT_CEILING_BYTES = 31457280;
 export declare function composeAppendSystemPrompt(host: HostContext, sources: IdentitySources, extras?: ComposeExtras): AppendBlockResult;
 export type IdentityForbiddenViolation = {
     class: string;

package/payload/platform/services/claude-session-manager/dist/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"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"}

package/payload/platform/services/claude-session-manager/dist/system-prompt.js

@@ -4,10 +4,12 @@
 //
 //   <host> ... </host>                    — hostname, LAN IPv4, admin URL,
 //                                            tunnel URL (or "none")
-//   <attachment-ceiling> ... </attachment-ceiling>
-//                                          — 30 MiB SendUserFile ceiling and
-//                                            the tunnel-link workaround for
-//                                            oversize files
+//   <file-delivery> ... </file-delivery>
+//                                          — how a produced file reaches the
+//                                            operator: write under output/,
+//                                            then state its location (Artefacts
+//                                            panel / operator file share). There
+//                                            is no send-to-chat tool.
 //   <identity> ... </identity>            — verbatim contents of
 //                                            <accountDir>/agents/<role>/IDENTITY.md
 //   <soul> ... </soul>                    — verbatim contents of
@@ -57,7 +59,6 @@
 // inline-coded so an operator can grep for it.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-export const ATTACHMENT_CEILING_BYTES = 31_457_280; // 30 MiB, mirrors the SDK uploader
 function readIdentityFile(path) {
     let content;
     try {
@@ -152,9 +153,9 @@ function renderAppendBlock(host, identityContent, soulContent, extras) {
         `admin-url: ${host.adminUrl}`,
         `tunnel-url: ${tunnelLine}`,
         '</host>',
-        '<attachment-ceiling>',
-        'SendUserFile and any inline attachment surface accept at most 30 MiB per file. Never call SendUserFile with a file whose on-disk size exceeds 30 MiB; there is no oversize delivery route, so tell the operator the file is too large to deliver and offer to split or compress it under the ceiling. The tool returns "N files delivered to user" even when the byte upload silently fails, so that string is not evidence of delivery — the operator\'s visible download chip is.',
-        '</attachment-ceiling>',
+        '<file-delivery>',
+        'Files you produce are not auto-delivered into the conversation — there is no working send-to-chat tool on this surface, and a bare on-disk path is unreachable from the chat. To deliver a file: write it under the output/ directory in your working directory (any depth), then in your reply tell the operator its exact location — it appears in the Artefacts panel (open the maxy sidebar to download it) and lives at the full output/ path, reachable on the operator file share (e.g. Samba) if one is set up. Always state the complete path, never a vague "in the output directory".',
+        '</file-delivery>',
         '<identity>',
         identityContent,
         '</identity>',
@@ -382,8 +383,8 @@ export function runSystemPromptSelfTest() {
     const required = [
         '<host>',
         '</host>',
-        '<attachment-ceiling>',
-        '</attachment-ceiling>',
+        '<file-delivery>',
+        '</file-delivery>',
         '<identity>',
         '</identity>',
         '<soul>',