@rubytech/create-maxy 1.0.880 → 1.0.883

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

@@ -0,0 +1,341 @@
+#!/usr/bin/env bash
+# Task 998 — bash harness for logs-read.sh prefix-match resolution.
+#
+# Covers the contract from the task brief:
+#   1. 8-char prefix → resolves full-UUID file (the original bug)
+#   2. Multiple matches → reason=ambiguous-prefix, exit 1, never picks
+#   3. More-specific prefix disambiguates
+#   4. Zero matches → reason=file-not-found-in-either-shape with glob patterns
+#   5. Full 36-char UUID still resolves (regression boundary)
+#   6. Preflush prefix match
+#   7. Preflush ambiguity (Pass 1 zero, Pass 2 multiple)
+#   8. Every per-conversation type (agent-stream, session, error, public)
+#      resolves under prefix-match
+#
+# Companion to platform/scripts/logs-read.test.sh (Task 671's two-shape
+# resolution harness).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOGS_READ="$SCRIPT_DIR/../logs-read.sh"
+if [[ ! -x "$LOGS_READ" ]]; then
+  echo "FATAL: $LOGS_READ not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+# logs-read.sh resolves PLATFORM_ROOT from its own location; mirror the
+# logs-read.test.sh convention by symlinking the script into an ephemeral
+# install tree per case.
+setup_install_tree() {
+  local root="$1"
+  mkdir -p "$root/platform/scripts"
+  mkdir -p "$root/data/accounts/acct-test/logs"
+  mkdir -p "$HOME/.$(basename "$root")/logs"
+  ln -sf "$LOGS_READ" "$root/platform/scripts/logs-read.sh"
+  echo "$root/platform/scripts/logs-read.sh"
+}
+
+cleanup_install_tree() {
+  local root="$1"
+  rm -rf "$root"
+  rm -rf "$HOME/.$(basename "$root")"
+}
+
+run_case() {
+  local name="$1"
+  shift
+  echo ""
+  echo "=== CASE: $name ==="
+  if "$@"; then
+    PASS=$((PASS + 1))
+    echo "PASS: $name"
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: $name"
+  fi
+}
+
+# --- Case 1: 8-char prefix resolves a full-UUID file (original bug) ---
+case_prefix_resolves_full() {
+  local root="/tmp/maxy-logs-read-prefix-1-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  local full_uuid="3483269d-c793-4a07-98cc-556d936f2f4d"
+  local filename="claude-agent-stream-${full_uuid}.log"
+  echo "prefix-match-sentinel" > "$logdir/$filename"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "3483269d" system 2>/tmp/logs-read-prefix-stderr-1-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-1-$$)
+  rm -f /tmp/logs-read-prefix-stderr-1-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 0 ]]; then echo "  expected exit 0, got $rc"; return 1; fi
+  if [[ "$stdout" != *"prefix-match-sentinel"* ]]; then
+    echo "  stdout missing sentinel: $stdout"; return 1
+  fi
+  if [[ "$stderr" != *"matched_shape=full"* ]]; then
+    echo "  stderr missing matched_shape=full: $stderr"; return 1
+  fi
+  if [[ "$stdout" != *"$filename"* ]]; then
+    echo "  header missing matched filename: $stdout"; return 1
+  fi
+  return 0
+}
+
+# --- Case 2: Multiple matches on Pass 1 → ambiguous-prefix, exit 1 ---
+case_ambiguous_prefix() {
+  local root="/tmp/maxy-logs-read-prefix-2-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  echo "A" > "$logdir/claude-agent-stream-aaaaaaaa-1111-A.log"
+  echo "B" > "$logdir/claude-agent-stream-aaaaaaaa-2222-B.log"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "aaaaaaaa" system 2>/tmp/logs-read-prefix-stderr-2-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-2-$$)
+  rm -f /tmp/logs-read-prefix-stderr-2-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 1 ]]; then echo "  expected exit 1, got $rc"; return 1; fi
+  if [[ "$stderr" != *"reason=ambiguous-prefix"* ]]; then
+    echo "  stderr missing reason=ambiguous-prefix: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"matches=2"* ]]; then
+    echo "  stderr missing matches=2: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"claude-agent-stream-aaaaaaaa-1111-A.log"* ]]; then
+    echo "  stderr missing candidate A: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"claude-agent-stream-aaaaaaaa-2222-B.log"* ]]; then
+    echo "  stderr missing candidate B: $stderr"; return 1
+  fi
+  # Body must NOT contain either sentinel — refusal means no body emitted.
+  if [[ -n "$stdout" ]]; then
+    echo "  stdout non-empty on ambiguous refusal: $stdout"; return 1
+  fi
+  return 0
+}
+
+# --- Case 3: more-specific prefix disambiguates ---
+case_more_specific_disambiguates() {
+  local root="/tmp/maxy-logs-read-prefix-3-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  echo "ONE" > "$logdir/claude-agent-stream-aaaaaaaa-1111-A.log"
+  echo "TWO" > "$logdir/claude-agent-stream-aaaaaaaa-2222-B.log"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "aaaaaaaa-1111" system 2>/tmp/logs-read-prefix-stderr-3-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-3-$$)
+  rm -f /tmp/logs-read-prefix-stderr-3-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 0 ]]; then echo "  expected exit 0, got $rc"; return 1; fi
+  if [[ "$stdout" != *"ONE"* ]]; then echo "  stdout missing ONE: $stdout"; return 1; fi
+  if [[ "$stdout" == *"TWO"* ]]; then echo "  stdout contained TWO: $stdout"; return 1; fi
+  if [[ "$stderr" != *"matched_shape=full"* ]]; then
+    echo "  stderr missing matched_shape=full: $stderr"; return 1
+  fi
+  return 0
+}
+
+# --- Case 4: zero matches → tried=[<glob>, <glob>] file-not-found ---
+case_zero_matches() {
+  local root="/tmp/maxy-logs-read-prefix-4-$$"
+  local script
+  script=$(setup_install_tree "$root")
+
+  local stdout stderr rc=0
+  stdout=$("$script" "xxxxxxxx" system 2>/tmp/logs-read-prefix-stderr-4-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-4-$$)
+  rm -f /tmp/logs-read-prefix-stderr-4-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 1 ]]; then echo "  expected exit 1, got $rc"; return 1; fi
+  if [[ "$stderr" != *"reason=file-not-found-in-either-shape"* ]]; then
+    echo "  stderr missing reason=file-not-found-in-either-shape: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"tried=[claude-agent-stream-xxxxxxxx*.log, claude-agent-stream-preflush-xxxxxxxx*.log]"* ]]; then
+    echo "  stderr missing tried=[<glob>, <glob>]: $stderr"; return 1
+  fi
+  return 0
+}
+
+# --- Case 5: full 36-char UUID still resolves (regression boundary) ---
+case_full_uuid_regression() {
+  local root="/tmp/maxy-logs-read-prefix-5-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  local full_uuid="3483269d-c793-4a07-98cc-556d936f2f4d"
+  local filename="claude-agent-stream-${full_uuid}.log"
+  echo "regression-sentinel" > "$logdir/$filename"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "$full_uuid" system 2>/tmp/logs-read-prefix-stderr-5-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-5-$$)
+  rm -f /tmp/logs-read-prefix-stderr-5-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 0 ]]; then echo "  expected exit 0, got $rc"; return 1; fi
+  if [[ "$stdout" != *"regression-sentinel"* ]]; then
+    echo "  stdout missing sentinel: $stdout"; return 1
+  fi
+  if [[ "$stderr" != *"matched_shape=full"* ]]; then
+    echo "  stderr missing matched_shape=full: $stderr"; return 1
+  fi
+  return 0
+}
+
+# --- Case 6: preflush-only file, prefix-match (Pass 2) ---
+case_preflush_prefix_match() {
+  local root="/tmp/maxy-logs-read-prefix-6-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  # Preflush filename uses sessionKey:0:12; mimic with a 12-char slice.
+  echo "preflush-prefix-sentinel" > "$logdir/claude-agent-stream-preflush-bbbbbbbb-ccc.log"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "bbbbbbbb" system 2>/tmp/logs-read-prefix-stderr-6-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-6-$$)
+  rm -f /tmp/logs-read-prefix-stderr-6-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 0 ]]; then echo "  expected exit 0, got $rc"; return 1; fi
+  if [[ "$stdout" != *"preflush-prefix-sentinel"* ]]; then
+    echo "  stdout missing sentinel: $stdout"; return 1
+  fi
+  if [[ "$stderr" != *"matched_shape=preflush"* ]]; then
+    echo "  stderr missing matched_shape=preflush: $stderr"; return 1
+  fi
+  return 0
+}
+
+# --- Case 7: preflush ambiguity (Pass 1 zero, Pass 2 multiple) ---
+case_preflush_ambiguity() {
+  local root="/tmp/maxy-logs-read-prefix-7-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  echo "P1" > "$logdir/claude-agent-stream-preflush-cccccccc-111.log"
+  echo "P2" > "$logdir/claude-agent-stream-preflush-cccccccc-222.log"
+
+  local stdout stderr rc=0
+  stdout=$("$script" "cccccccc" system 2>/tmp/logs-read-prefix-stderr-7-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-7-$$)
+  rm -f /tmp/logs-read-prefix-stderr-7-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 1 ]]; then echo "  expected exit 1, got $rc"; return 1; fi
+  if [[ "$stderr" != *"reason=ambiguous-prefix"* ]]; then
+    echo "  stderr missing reason=ambiguous-prefix: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"matches=2"* ]]; then
+    echo "  stderr missing matches=2: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"claude-agent-stream-preflush-cccccccc-111.log"* ]]; then
+    echo "  stderr missing preflush candidate 1: $stderr"; return 1
+  fi
+  if [[ "$stderr" != *"claude-agent-stream-preflush-cccccccc-222.log"* ]]; then
+    echo "  stderr missing preflush candidate 2: $stderr"; return 1
+  fi
+  return 0
+}
+
+# --- Case 8: every per-conversation type resolves under prefix-match ---
+# Parameterised over the four prefix_for_type values:
+#   agent-stream → claude-agent-stream-
+#   session      → sse-events-
+#   error        → claude-agent-stderr-
+#   public       → public-agent-stream-
+case_all_types_prefix_match() {
+  local root="/tmp/maxy-logs-read-prefix-8-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  local full_uuid="7d49ef21-1234-4567-89ab-cdef01234567"
+
+  echo "sentinel-agent-stream" > "$logdir/claude-agent-stream-${full_uuid}.log"
+  echo "sentinel-session"      > "$logdir/sse-events-${full_uuid}.log"
+  echo "sentinel-error"        > "$logdir/claude-agent-stderr-${full_uuid}.log"
+  echo "sentinel-public"       > "$logdir/public-agent-stream-${full_uuid}.log"
+
+  local pairs=(
+    "agent-stream|sentinel-agent-stream"
+    "session|sentinel-session"
+    "error|sentinel-error"
+    "public|sentinel-public"
+  )
+  local fail=0
+  local pair t expected_sentinel
+  for pair in "${pairs[@]}"; do
+    t="${pair%%|*}"
+    expected_sentinel="${pair##*|}"
+    local stdout stderr rc=0
+    stdout=$("$script" "7d49ef21" "$t" 2>/tmp/logs-read-prefix-stderr-8-$$) || rc=$?
+    stderr=$(cat /tmp/logs-read-prefix-stderr-8-$$)
+    rm -f /tmp/logs-read-prefix-stderr-8-$$
+    if [[ $rc -ne 0 ]]; then echo "  [$t] expected exit 0, got $rc — stderr: $stderr"; fail=1; continue; fi
+    if [[ "$stdout" != *"$expected_sentinel"* ]]; then
+      echo "  [$t] missing sentinel '$expected_sentinel': $stdout"; fail=1
+    fi
+    if [[ "$stderr" != *"matched_shape=full"* ]]; then
+      echo "  [$t] stderr missing matched_shape=full: $stderr"; fail=1
+    fi
+  done
+
+  cleanup_install_tree "$root"
+  [[ $fail -eq 0 ]]
+}
+
+# --- Case 9: conv_id with shell metacharacters is rejected ---
+case_metacharacter_rejected() {
+  local root="/tmp/maxy-logs-read-prefix-9-$$"
+  local script
+  script=$(setup_install_tree "$root")
+
+  local stdout stderr rc=0
+  # Use a backslash-escaped wildcard to feed it as a literal argument.
+  stdout=$("$script" "ab*cd" system 2>/tmp/logs-read-prefix-stderr-9-$$) || rc=$?
+  stderr=$(cat /tmp/logs-read-prefix-stderr-9-$$)
+  rm -f /tmp/logs-read-prefix-stderr-9-$$
+
+  cleanup_install_tree "$root"
+
+  if [[ $rc -ne 2 ]]; then echo "  expected exit 2 (usage), got $rc"; return 1; fi
+  if [[ "$stderr" != *"invalid characters"* ]]; then
+    echo "  stderr missing invalid-characters guard: $stderr"; return 1
+  fi
+  return 0
+}
+
+run_case "8-char prefix resolves full-UUID file"        case_prefix_resolves_full
+run_case "ambiguous prefix → refused, candidates listed" case_ambiguous_prefix
+run_case "more-specific prefix disambiguates"            case_more_specific_disambiguates
+run_case "zero matches → file-not-found-in-either-shape" case_zero_matches
+run_case "full 36-char UUID still resolves"              case_full_uuid_regression
+run_case "preflush file resolves by prefix"              case_preflush_prefix_match
+run_case "preflush ambiguity refused"                    case_preflush_ambiguity
+run_case "every per-conversation type prefix-matches"    case_all_types_prefix_match
+run_case "shell metacharacters rejected"                 case_metacharacter_rejected
+
+echo ""
+echo "================================================"
+echo " Passed: $PASS / Failed: $FAIL"
+echo "================================================"
+[[ $FAIL -eq 0 ]]

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

@@ -144,25 +144,42 @@ validate_type() {
   esac
 }
 
-# --- Per-conversation mode: read {prefix}{convId}.log, with preflush fallback ---
+# --- Per-conversation mode: prefix-match {prefix}{convId-prefix}*.log ---
 #
-# Task 671: writer (Task 650) emits logs under two filename shapes —
+# Task 671 — two filename shapes the writer emits:
 #   FULL:     {prefix}{conversationId}.log      (post 1→2-user-turn flush)
 #   PREFLUSH: {prefix}preflush-{id:0:12}.log    (pre-flush, first turn; the
 #                                                 slice is of the sessionKey)
-# This mode tries FULL across every account dir first; if zero FULL hits,
-# falls back to PREFLUSH across every dir. If BOTH exist in the same dir,
-# FULL wins and the preflush sibling is logged to server.log as stale
-# (promotion-race housekeeping signal).
 #
-# Identity note: for the abrupt-exit case this fallback exists to solve,
+# Task 998 — operator surface accepts any unambiguous prefix of the id.
+# The writer's filename is canonical (full 36-char UUID) but every agent
+# line surfaces the 8-char id (`conversationId=3483269d…`). Pass 1 and
+# Pass 2 each glob `${prefix}${conv_id}*.log` so an 8-char operator input
+# resolves a full-UUID file. Three trailer outcomes:
+#   single hit  → exit 0 + matched_shape=full|preflush  (existing success)
+#   zero hits   → exit 1 + reason=file-not-found-in-either-shape (existing miss)
+#   2+ hits     → exit 1 + reason=ambiguous-prefix candidates=[...]; never picks
+#
+# Stale-preflush housekeeping (Task 671): on a single FULL hit, glob the
+# preflush pattern in the same dir and emit `[logs-read] stale-preflush-detected`
+# to server.log for each sibling. Best-effort — retrieval doesn't fail if
+# server.log is unwritable.
+#
+# Identity note: the preflush fallback exists for the abrupt-exit case where
 # the operator passes the sessionKey (no conversationId was ever assigned).
-# For post-flush retrievals the operator passes the conversationId and the
-# FULL file is expected to exist.
+# For post-flush retrievals the operator passes the conversationId (or any
+# unambiguous prefix of it) and the FULL file is expected to exist.
 #
-# MIRROR: keep the two-shape contract in sync with:
-#   - platform/ui/app/lib/logs-read-resolve.ts (canonical TS helper + tests)
-#   - platform/plugins/admin/mcp/src/index.ts (conversationId branch)
+# MIRROR — intentional divergence (Task 998):
+#   - platform/ui/app/lib/logs-read-resolve.ts (canonical TS helper) —
+#     EXACT-MATCH on `${prefix}${conversationId}.log`.
+#   - platform/plugins/admin/mcp/src/index.ts (conversationId branch) —
+#     EXACT-MATCH, same shape.
+# Both serve agents that always hold the full conversationId. This shell
+# counterpart is the operator surface; operators read 8-char ids from agent
+# lines and type them at the SSH prompt. Do not "fix" the divergence by
+# adding prefix-match to TS/MCP — it would mask agent bugs that pass
+# partial ids.
 per_conversation_mode() {
   local conv_id="$1"
   local filter_type="${2:-agent-stream}"
@@ -172,6 +189,14 @@ per_conversation_mode() {
     exit 2
   fi
 
+  # Reject shell metacharacters in conv_id — the prefix-match glob below
+  # would otherwise turn user input into a shell pattern. UUIDs and
+  # sessionKeys only contain [a-zA-Z0-9-].
+  if [[ ! "$conv_id" =~ ^[a-zA-Z0-9-]+$ ]]; then
+    echo "Error: conversationId 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 convId.
@@ -190,56 +215,98 @@ per_conversation_mode() {
     exit 2
   fi
 
-  # Build the two filenames the two-shape contract expects.
-  local full_name="${prefix}${conv_id}.log"
-  local preflush_name="${prefix}preflush-${conv_id:0:12}.log"
+  # Glob patterns the two-shape contract expects (Task 998: prefix match).
+  local full_glob="${prefix}${conv_id}*.log"
+  local preflush_glob="${prefix}preflush-${conv_id:0:12}*.log"
 
-  local found=0
   local searched=0
   local matched_shape=""
 
-  # Pass 1: FULL across every log dir. Records stale preflush siblings.
+  # Pass 1: FULL prefix glob across every log dir; aggregate hits.
+  local -a full_hits=()
+  local -a full_dirs=()
+  shopt -s nullglob
   for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
-    local full_path="$log_dir/$full_name"
     searched=$((searched + 1))
-    if [[ ! -f "$full_path" ]]; then
-      continue
-    fi
-    [[ $found -gt 0 ]] && echo ""
-    echo "## $(basename "$full_path") ($filter_type)$(account_suffix "$log_dir")"
+    for f in "$log_dir"/${prefix}${conv_id}*.log; do
+      full_hits+=("$f")
+      full_dirs+=("$log_dir")
+    done
+  done
+  shopt -u nullglob
+
+  # Pass 1 ambiguous → refuse, never silently pick.
+  if [[ ${#full_hits[@]} -gt 1 ]]; then
+    local -a candidate_names=()
+    local cf
+    for cf in "${full_hits[@]}"; do
+      candidate_names+=("$(basename "$cf")")
+    done
+    local joined
+    joined=$(IFS=','; printf '%s' "${candidate_names[*]}")
+    echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched matches=${#full_hits[@]} reason=ambiguous-prefix candidates=[${joined}]" >&2
+    exit 1
+  fi
+
+  local found=0
+
+  # Pass 1 single hit → emit body, run stale-preflush detection in matched dir.
+  if [[ ${#full_hits[@]} -eq 1 ]]; then
+    local full_path="${full_hits[0]}"
+    local match_dir="${full_dirs[0]}"
+    echo "## $(basename "$full_path") ($filter_type)$(account_suffix "$match_dir")"
     cat "$full_path"
-    found=$((found + 1))
+    found=1
     matched_shape="full"
-    # Stale-preflush detection: if the post-flush rename left the preflush
-    # sibling on disk, emit a housekeeping signal to server.log. Best-effort
-    # — retrieval must not fail if server.log is unwritable.
-    local stale_path="$log_dir/$preflush_name"
-    if [[ -f "$stale_path" ]]; then
+
+    shopt -s nullglob
+    local stale_path
+    for stale_path in "$match_dir"/${prefix}preflush-${conv_id:0:12}*.log; do
       local stale_ts
       stale_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
       echo "${stale_ts} [logs-read] stale-preflush-detected path=${stale_path}" >> "$SERVER_LOG" 2>/dev/null || true
-    fi
-  done
+    done
+    shopt -u nullglob
+  fi
 
-  # Pass 2: PREFLUSH across every dir. Only runs if zero FULL hits.
+  # Pass 2: PREFLUSH prefix glob, only if Pass 1 had zero hits.
   if [[ $found -eq 0 ]]; then
+    local -a preflush_hits=()
+    local -a preflush_dirs=()
+    shopt -s nullglob
     for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
-      local preflush_path="$log_dir/$preflush_name"
       searched=$((searched + 1))
-      if [[ ! -f "$preflush_path" ]]; then
-        continue
-      fi
-      [[ $found -gt 0 ]] && echo ""
-      echo "## $(basename "$preflush_path") ($filter_type)$(account_suffix "$log_dir")"
+      for f in "$log_dir"/${prefix}preflush-${conv_id:0:12}*.log; do
+        preflush_hits+=("$f")
+        preflush_dirs+=("$log_dir")
+      done
+    done
+    shopt -u nullglob
+
+    if [[ ${#preflush_hits[@]} -gt 1 ]]; then
+      local -a candidate_names=()
+      local pf
+      for pf in "${preflush_hits[@]}"; do
+        candidate_names+=("$(basename "$pf")")
+      done
+      local joined
+      joined=$(IFS=','; printf '%s' "${candidate_names[*]}")
+      echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched matches=${#preflush_hits[@]} reason=ambiguous-prefix candidates=[${joined}]" >&2
+      exit 1
+    fi
+
+    if [[ ${#preflush_hits[@]} -eq 1 ]]; then
+      local preflush_path="${preflush_hits[0]}"
+      echo "## $(basename "$preflush_path") ($filter_type)$(account_suffix "${preflush_dirs[0]}")"
       cat "$preflush_path"
-      found=$((found + 1))
+      found=1
       matched_shape="preflush"
-    done
+    fi
   fi
 
   # Trailer: empty output never leaves the reader guessing why.
   if [[ $found -eq 0 ]]; then
-    echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched found=0 tried=[${full_name}, ${preflush_name}] reason=file-not-found-in-either-shape" >&2
+    echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched found=0 tried=[${full_glob}, ${preflush_glob}] reason=file-not-found-in-either-shape" >&2
     exit 1
   fi
   echo "" >&2

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

@@ -22,6 +22,10 @@ CONV_ID="8c264cfb-441f-48bf-9811-9fa3ad3b51dc"
 PREFLUSH_SLICE="8c264cfb-441"
 FULL_NAME="claude-agent-stream-${CONV_ID}.log"
 PREFLUSH_NAME="claude-agent-stream-preflush-${PREFLUSH_SLICE}.log"
+# Task 998 — miss trailer now lists glob patterns, not literal filenames,
+# because Pass 1 / Pass 2 prefix-glob `${prefix}${conv_id}*.log`.
+FULL_GLOB="claude-agent-stream-${CONV_ID}*.log"
+PREFLUSH_GLOB="claude-agent-stream-preflush-${PREFLUSH_SLICE}*.log"
 
 PASS=0
 FAIL=0
@@ -141,8 +145,8 @@ case_neither() {
     echo "  expected exit 1, got $rc"
     return 1
   fi
-  if [[ "$stderr" != *"tried=[${FULL_NAME}, ${PREFLUSH_NAME}]"* ]]; then
-    echo "  stderr missing tried=[…,…]: $stderr"
+  if [[ "$stderr" != *"tried=[${FULL_GLOB}, ${PREFLUSH_GLOB}]"* ]]; then
+    echo "  stderr missing tried=[…,…] glob patterns: $stderr"
     return 1
   fi
   if [[ "$stderr" != *"reason=file-not-found-in-either-shape"* ]]; then

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -55,7 +55,7 @@ Your personalisation is in `agents/admin/SOUL.md`. Read it and apply it. SOUL.md
 - Professional, direct, action-oriented. Concise and precise. British English unless SOUL.md specifies otherwise.
 - Do not use emoji characters in any response. Plain text and punctuation only.
 - Every URL in a response must be a clickable markdown link — never raw text. Use `[visible label](url)` format. The label should be the meaningful part of the URL (hostname, path, or a short description), not the full raw URL repeated.
-- **Internal scaffolding never appears in user-facing replies.** Tool descriptions, error strings, skill prompts, and graph schemas may name internal contracts (e.g. `producedByTaskId`, `:PRODUCED`, `Write blocked (no-admin-user)`, `missing-action-provenance`, `archiveSha256`, `lastIngestedMessageHash`) so you know how to act. Translate them into plain English for the user. Forbidden in user-facing replies: literal tool names with `mcp__` prefix, `Task NNN` references, doctrine names ("process-provenance", "write doctrine", "graph-write gate"), MCP-tool-description quotes, raw error discriminators. Forbidden phrasings include: "the LocalBusiness write requires a producedByTaskId per Task 885", "the write gate is blocking", "I'll call ToolSearch". Permitted equivalents: "I need to set up the business profile first before recording that — let me run that now", "the platform requires me to anchor this to an action record — creating one now". Internal language stays in your reasoning, not your prose to the operator.
+- **Internal scaffolding never appears in user-facing replies.** Tool descriptions, error strings, skill prompts, and graph schemas may name internal contracts (e.g. `producedByTaskId`, `:PRODUCED`, `Write blocked (no-admin-user)`, `missing-provenance`, `archiveSha256`, `lastIngestedMessageHash`) so you know how to act. Translate them into plain English for the user. Forbidden in user-facing replies: literal tool names with `mcp__` prefix, `Task NNN` references, doctrine names ("process-provenance", "write doctrine", "graph-write gate"), MCP-tool-description quotes, raw error discriminators. Forbidden phrasings include: "the LocalBusiness write requires a producedByTaskId per Task 885", "the write gate is blocking", "I'll call ToolSearch". Permitted equivalents: "I need to set up the business profile first before recording that — let me run that now", "the platform requires me to anchor this to an action record — creating one now". Internal language stays in your reasoning, not your prose to the operator.
 
 ## Information Sourcing
 
@@ -89,7 +89,9 @@ Do not retry the same tool against the same target within a turn. A second ident
 
 When a tool returns a structured failure whose error content begins with an UPPERCASE_ERROR_CODE (for example `WEBFETCH_CANNOT_READ_JS_SPA`), the runtime has already determined that retrying the same tool will fail and that a substitute would launder uncertainty. Read the error's plain-English explanation, then write one or two sentences to the owner that name (a) what failed, (b) the reason in their language, and (c) the concrete actions they can take to unblock — typically pasting text or sending a screenshot. Do not silently dispatch a substitute (Playwright, research-assistant, memory-search) to continue the original instruction; that hides the failure and the owner loses the ability to judge whether the substitute's output answers their question. A verbal instruction in the current conversation is not consent — only an explicit standing policy recorded in account configuration counts, and no such mechanism exists today. Until one exists, every structured tool failure becomes a question for the owner. Wait for direction before resuming.
 
-**Post-deterministic-error reply contract — never re-solicit held values.** When a Cloudflare form failure surfaces in the chat relay, the trailing fenced `json` block labelled "Held by deterministic tools (do not re-solicit)" is the route's structured payload. It carries `inputsAlreadyHeld` (the FQDNs already submitted: `admin`, `public`, `apex`) and `discoveryResults` (the discovery snapshot the route was holding: `tunnels`, `domains`). The next reply structurally consumes this payload — restate the held values verbatim, name the literal error, and decide between two actions: (a) if the `<deployment>` block's `bundleMtime` post-dates this failure's timestamp, the deterministic path has been redeployed with a fix — re-invoke the same path immediately; (b) otherwise surface the literal error plus the next deterministic step from the relevant SKILL (`setup-tunnel.sh`, `reset-tunnel.sh`, `dashboard-guide.md`). Asking the operator for a hostname, tunnel name, or apex that already appears in `inputsAlreadyHeld` or `discoveryResults` is a doctrine violation — the structured payload is the answer set; the deterministic path holds the values; the chat relay is for restatement, not re-entry.
+**Post-deterministic-error reply contract — restate, never re-solicit.** On `cloudflare-setup` error, the route returns either a literal error envelope or a deterministic re-invoke; the reply restates the literal error verbatim and stops. The envelope's `inputsAlreadyHeld` (FQDNs already submitted: `admin`, `public`, `apex`) and `discoveryResults` (tunnels + domains snapshot) are the answer set — asking the operator for a hostname, tunnel name, or apex that appears there is a doctrine violation. Retry-on-redeployment is decided by the route, not by the reply.
+
+**Post-action restatement contract.** When a `<post-action>` block appears in your system prompt, it carries the literal terminal outcome of the chain's most-recent action card (`actionId`, `outcome ∈ {completed, failed}`, `phase`, `at`). The next free-text reply restates that outcome verbatim and stops. Do not narrate, predict, or recompute the status — the route closed the audit Task and the block IS the answer.
 
 ## Cypher schema
 
@@ -129,6 +131,8 @@ Operationalises the CONCISE prerogative for clarification. Three rules:
 
 **Bundled-SKILL access contract.** Plugin skills and references live in the bundled npm package, not on disk under `<accountDir>/agents/admin/plugins/`. Load them with `mcp__admin__plugin-read` only — the `<plugin-manifest>` `Skills:` and `References:` lines name the exact `pluginName` and file path to pass. `Read`, `Glob`, and `Bash` against those paths will fail with `File does not exist`, and the runtime agent-loop-stop interceptor cannot distinguish a generic-error retry from a tool-routing mistake. Subagents inherit this contract via the parent system prompt — never dispatch an `Agent` subagent with a `Read` directive against a bundled SKILL path.
 
+**Plain-English precision pass.** Load `admin/skills/plainly/SKILL.md` via `plugin-read` on the first turn of a session where the user asks to explain, define, or pre-empts one of the trigger phrases ("explain in plain English", "what does X mean", "define X", "I don't understand", "what is this"), AND on the first turn where you are about to return a reply containing a term not in the operator's prior turn. Apply the AI-tells strip + recursive-rule pass to the reply before sending it. The skill applies to prose returned to the operator, not to MCP tool arguments — agent-to-machine payloads pass through unmodified.
+
 Plugins provide domain-specific tools that query their own data stores directly. `memory-search` is a general-purpose semantic search across the entire knowledge graph — it finds nodes by vector similarity, which means results are ranked by semantic closeness to the query, not by domain relevance. A query containing the word "email" will surface product documentation *about* email features before it surfaces actual Email nodes whose content is unrelated to the query wording.
 
 When the user's intent maps to a specific plugin's domain, use that plugin's tools — not `memory-search`. The `<plugin-manifest>` groups tools by plugin and describes each plugin's purpose and retrieval paths. The `<specialist-domains>` block within it lists every specialist-owned tool by name. Match user intent to a tool in these registries first; fall back to `memory-search` only when the query genuinely spans multiple domains or no tool in the manifest matches the intent.

package/payload/platform/templates/agents/public/IDENTITY.md

@@ -48,3 +48,9 @@ When you need to clarify intent before acting, follow two rules.
 1. **One-sided questions only.** Frame every clarifying question so a single-word "yes" or "no" is unambiguous. Never pose two opposing framings joined by "or" — "Should I book this, or not?", "Want a quote, or shall I take a message?". "Yes" to such a question is unusable — the visitor could have meant either side. Pick one side and ask it plainly: "Shall I take a message?" — not "take a message, or leave it?".
 
 2. **No menu when the signal is clear.** When an internal lookup or tool returns a specific outcome — the answer is there, or the answer is not — relay that outcome. Do not offer the visitor a menu of next steps when only one makes sense. If a lookup fails, tell the visitor what to do next (take a message, contact the business directly) rather than asking them to choose between recoveries.
+
+## Plain-English precision pass
+
+Load `admin/skills/plainly/SKILL.md` via `plugin-read` on the first text-producing turn of every session. Apply the AI-tells strip and the recursive plain-English rule to every reply you return to the visitor before emitting it — this is a prime-directive prerogative that overrides every other formatting preference. Customers are the highest-stakes audience this platform serves; plain English is not a polish step, it is the contract.
+
+The skill applies to prose returned to the visitor and to text content passed through `render-component`. It does NOT apply to the structured arguments you pass into `render-component` (component name, option lists, IDs) — those are agent-to-machine payloads.

package/payload/platform/templates/specialists/agents/content-producer.md

@@ -96,3 +96,9 @@ Return to the admin agent:
 ## Tool failure discipline
 
 When a tool returns an error, surface the failure and its diagnostic context before taking another action. Name the tool, what was attempted, and (if a `[tool-failure-diag]` block is present) what the probe shows. Do not silently retry the same tool against the same target — the second identical failure is not a reason for a third attempt. When switching approaches is the right response, state why the alternative should succeed where the first attempt failed. Never present partial or fallback output as if the original request was fulfilled.
+
+## Plain-English precision pass
+
+Load `admin/skills/plainly/SKILL.md` via `plugin-read` on the first turn of every session. Apply the AI-tells strip + recursive plain-English rule to every prose artifact you return to the admin agent — captions, brochure prose, summaries, the "What you did" / "Summary" output contract above. This is a prime-directive prerogative; do not wait for admin to ask.
+
+**Receiving-endpoint carve-out.** Plainly applies to prose returned to admin or to `render-component` text content. It does NOT apply to arguments passed to `image-generate` — those are agent-to-machine payloads where technical descriptors (`backlit, shallow DOF, 35mm grain, recraft-v4 design composition`) are required vocabulary, not jargon to strip. Pass image prompts through verbatim.

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -191,3 +191,9 @@ When two nodes represent the same real-world entity (two `:Person` rows for the
 ## Tool failure discipline
 
 When a tool returns an error, surface the failure and its diagnostic context before taking another action. Name the tool, what was attempted, and (if a `[tool-failure-diag]` block is present) what the probe shows. Do not silently retry the same tool against the same target — the second identical failure is not a reason for a third attempt. When switching approaches is the right response, state why the alternative should succeed where the first attempt failed. Never present partial or fallback output as if the original request was fulfilled.
+
+## Plain-English precision pass
+
+Load `admin/skills/plainly/SKILL.md` via `plugin-read` on the first turn of every session. Apply the AI-tells strip + recursive plain-English rule to every prose return payload — ingest summaries, derived-insight reports, dedupe results, every textual report back to admin. This is a prime-directive prerogative; do not wait for admin to ask.
+
+**Receiving-endpoint carve-out.** Plainly applies to prose returned to admin. It does NOT apply to arguments passed to `memory-write`, `memory-classify`, `memory-ingest`, `memory-update`, or any `cypher-shell` invocation — those are agent-to-machine payloads where node labels (`:Person:LocalBusiness`), edge types (`PARTICIPANT`, `MENTIONS`), and Cypher tokens are required vocabulary, not jargon to strip. Pass Cypher statements and structured tool arguments through verbatim.

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -201,3 +201,9 @@ Controls the browser via Playwright to complete web-based tasks. The browser is
 ## Tool failure discipline
 
 When a tool returns an error (email send, WhatsApp send, browser navigate, Telegram, scheduling, Cloudflare, Anthropic key), surface the failure before taking any other action. Name the tool, what was attempted, and — if a `[tool-failure-diag]` block is present — what the diagnostic reveals (DNS resolved? TCP connected? HTTP status? internal timeout?). Do not retry the same tool against the same target within a turn; the second identical failure is evidence the path is broken. If switching approaches is the right response (for example, retrying email via a different channel, or navigating via HTTP rather than the browser), state why the alternative should succeed. Silent fallback — attempting a different tool family without acknowledging the original failure — is never acceptable; the admin agent and the owner must see that the first attempt failed and understand the reason for the switch.
+
+## Plain-English precision pass
+
+Load `admin/skills/plainly/SKILL.md` via `plugin-read` on the first turn of every session. Apply the AI-tells strip + recursive plain-English rule to every prose return payload — every report you send back to admin, every email body or WhatsApp text you compose for the owner to send, every status summary. This is a prime-directive prerogative; do not wait for admin to ask.
+
+**Receiving-endpoint carve-out.** Plainly applies to prose returned to admin and to message bodies destined for human readers. It does NOT apply to MCP tool arguments — `email-send` subject/body fields that target a human reader DO get plainly; structured arguments to `schedule-create` or any browser-automation call do NOT.