@rubytech/create-maxy 1.0.884 → 1.0.886

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -83,7 +83,7 @@ Premium plugins are one-off purchases that grant permanent ownership. They are n
 
 Some premium plugins are **bundles** — a single purchase that delivers multiple sub-plugins, each independently activatable. For example, Real Agency delivers 11 sub-plugins covering different aspects of estate agency work. You can enable all of them or just the ones you need (e.g., "Enable estate-sales" for just the sales skills). Enabling or disabling individual sub-plugins does not affect the others.
 
-When a bundle is delivered (automatically at session start, or explicitly via `premium-deliver`), every sub-plugin in its manifest is enabled by default — you don't need to enable each one by hand. Sub-plugins you don't want active can be turned off individually with "disable <name>". Standalone premium plugins behave the same way: delivery implies enablement. If you ask {{productName}} about a tool from a plugin you haven't purchased, {{productName}} responds with a structured `<tool-surface-error>` envelope naming the missing plugin and the remedy, rather than improvising with a generic alternative.
+Every admin session start reconciles your `enabledPlugins` against what is actually on disk: any purchased sub-plugin present in `platform/plugins/` is enabled, so you don't need to enable each one by hand. This holds whether the bundle was delivered just now (fresh purchase via `premium-deliver`) or has been on disk from a prior install. Sub-plugins you don't want active can be turned off individually with "disable <name>". Standalone premium plugins behave the same way: presence on disk implies enablement. If you ask {{productName}} about a tool from a plugin you haven't purchased, {{productName}} responds with a structured `<tool-surface-error>` envelope naming the missing plugin and the remedy, rather than improvising with a generic alternative.
 
 **Public agent embedding:** Premium plugins marked as public-eligible have their full content (skills and reference knowledge) embedded in public agent prompts. This means a public agent for a Real Agency member can handle buyer enquiries, book viewings, deliver coaching content, and onboard new applicants — all powered by the premium plugin's domain knowledge. Plugins marked admin-only (listings, vendors, leads, business) are only available to the account owner's admin agent.
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -73,7 +73,7 @@ tail -200 ~/.maxy/logs/maxy-ui.log | rg '\[remote-auth\].*resolvedKind='
 **Agent searches the filesystem after uploading a zip.** If you uploaded a zip and the agent burns several turns running `find` / `Glob` instead of unzipping, that is the symptom of the recovery-retry attachment-context regression (now closed by the recovery context preservation contract in `.docs/agents.md`). Greppable confirmation is the `[context-overflow-recovery] retry … attachmentsCarried=<n>` line in the conversation stream log. If you see `[context-overflow-recovery] WARN attachment-context-lost`, the regression has returned — surface to support.
 
 
-**A turn rendered in chat is missing on next page-refresh.** Pre-the 2026-05-07 mandate this was a class of silent failure — Neo4j persists were wrapped in a no-op error catch and a write that threw left the artefact "rendered then disappeared on resume". The 2026-05-07 mandate makes JSONL canonical: the resume route reads the SDK transcript file at `~/.claude/projects/<project-key>/<sessionId>.jsonl` first, supplements from Neo4j, and triggers async heal-on-resume writes for any turn the JSONL has but Neo4j does not. So a refreshed conversation always renders what the SDK saw, regardless of write outcome. If a heal write itself fails, the chat shows a top-of-conversation banner naming the count; if every heal succeeds the resume is silent and the missing rows are quietly restored to Neo4j. Greppable post-deploy invariants in the per-conversation stream log (`logs/claude-agent-stream-<conversationId>.log`): `[admin-resume] reason=<…> source=<jsonl|jsonl-missing|neo4j-only>` (one per resume), `[admin-persist] convId=<8> writer=<…> outcome=<ok|fail|skip>` (per persist site), `[admin-persist-heal] convId=<8> turnIndex=<n> outcome=<ok|fail>` (per heal write). To force-audit a specific conversation against its Neo4j projection without re-executing it, run `tsx platform/scripts/admin-persist-audit.ts --conversation-id=<uuid> --account-id=<uuid> --session-id=<uuid>` — non-zero exit + per-divergence `[admin-persist-audit] expected=<message|component> missing reason=neo4j-row-absent` lines name what would have been silently lost pre-mandate.
+**A turn rendered in chat is missing on next page-refresh.** Pre-the 2026-05-07 mandate this was a class of silent failure — Neo4j persists were wrapped in a no-op error catch and a write that threw left the artefact "rendered then disappeared on resume". The 2026-05-07 mandate makes JSONL canonical: the resume route reads the SDK transcript file at `~/.claude/projects/<project-key>/<sessionId>.jsonl` first, supplements from Neo4j, and triggers async heal-on-resume writes for any turn the JSONL has but Neo4j does not. So a refreshed conversation always renders what the SDK saw, regardless of write outcome. If a heal write itself fails, the chat shows a top-of-conversation banner naming the count; if every heal succeeds the resume is silent and the missing rows are quietly restored to Neo4j. Greppable post-deploy invariants in the per-session stream log (`logs/claude-agent-stream-<sessionKey>.log`): `[admin-resume] reason=<…> source=<jsonl|jsonl-missing|neo4j-only>` (one per resume), `[admin-persist] convId=<8> writer=<…> outcome=<ok|fail|skip>` (per persist site), `[admin-persist-heal] convId=<8> turnIndex=<n> outcome=<ok|fail>` (per heal write). To force-audit a specific conversation against its Neo4j projection without re-executing it, run `tsx platform/scripts/admin-persist-audit.ts --conversation-id=<uuid> --account-id=<uuid> --session-id=<uuid>` — non-zero exit + per-divergence `[admin-persist-audit] expected=<message|component> missing reason=neo4j-row-absent` lines name what would have been silently lost pre-mandate.
 **Wrong Claude account answering on a multi-brand device.** On a host running both Maxy and Real Agent, each brand's admin agent reads its own `~/${brand.configDir}/.claude/.credentials.json`; there is no longer a shared `~/.claude/` thrashing them against one another. If a brand reports auth failures or appears to be operating against the wrong subscription, check three things:
 1. `grep "\[claude-auth\] init" ~/.${brand}/logs/server.log | tail -1` — the resolved path must end with `~/.${brand}/.claude/.credentials.json`. If a `[claude-auth] WARN cross-brand-path-detected` line is present, the runtime is still pointing at `~/.claude/`; the brand main service did not pick up the `Environment=CLAUDE_CONFIG_DIR=` setting (re-run the brand installer to refresh the unit file).
 2. `diff <(jq .claudeAiOauth.accessToken ~/.maxy/.claude/.credentials.json) <(jq .claudeAiOauth.accessToken ~/.realagent/.claude/.credentials.json)` — must be non-empty after each brand's operator has run `claude /login` against distinct Anthropic accounts; if it's empty, both brands are still logged in to the same account (operator action, not a code bug).

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

@@ -1,19 +1,18 @@
 #!/usr/bin/env bash
-# Task 998 — bash harness for logs-read.sh prefix-match resolution.
+# Task 1006 — prefix-match harness for logs-read.sh.
 #
-# 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
+# Task 998 introduced 8-char-prefix resolution; Task 1006 collapses the
+# writer's two-shape contract to one (`claude-agent-stream-<sessionKey>.log`).
+# The prefix match still applies, now against a single basename shape.
 #
-# Companion to platform/scripts/logs-read.test.sh (Task 671's two-shape
-# resolution harness).
+# Cases:
+#   1. 8-char prefix resolves a full sessionKey-named file.
+#   2. Multiple matches → ambiguous-prefix, exit 1, never picks silently.
+#   3. More-specific prefix disambiguates.
+#   4. Zero matches → exit 1 with file-not-found trailer.
+#   5. Full 36-char sessionKey still resolves (regression boundary).
+#   6. Every per-session type (agent-stream, session, error, public)
+#      resolves under prefix-match.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -26,9 +25,6 @@ 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"
@@ -58,281 +54,130 @@ run_case() {
   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-$$"
+case_8char_prefix_resolves_full() {
+  local root="/tmp/maxy-prefix-test-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-$$
+  local sk="abcd1234-5678-90ab-cdef-1234567890ab"
+  echo "sentinel-1" > "$logdir/claude-agent-stream-${sk}.log"
 
+  local rc=0
+  local stdout
+  stdout=$("$script" "abcd1234" agent-stream 2>/dev/null) || rc=$?
   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
+  [[ $rc -eq 0 ]] || { echo "  expected exit 0, got $rc"; return 1; }
+  [[ "$stdout" == *"sentinel-1"* ]] || { echo "  missing sentinel"; return 1; }
   return 0
 }
 
-# --- Case 2: Multiple matches on Pass 1 → ambiguous-prefix, exit 1 ---
-case_ambiguous_prefix() {
-  local root="/tmp/maxy-logs-read-prefix-2-$$"
+case_ambiguous_prefix_refuses() {
+  local root="/tmp/maxy-prefix-test-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-$$
-
+  echo "a" > "$logdir/claude-agent-stream-abcd1111.log"
+  echo "b" > "$logdir/claude-agent-stream-abcd2222.log"
+
+  local rc=0
+  "$script" "abcd" agent-stream >/dev/null 2>/tmp/prefix-stderr-2-$$ || rc=$?
+  local stderr
+  stderr=$(cat /tmp/prefix-stderr-2-$$)
+  rm -f /tmp/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
+  [[ $rc -eq 1 ]] || { echo "  expected exit 1, got $rc"; return 1; }
+  [[ "$stderr" == *"ambiguous-prefix"* ]] || { echo "  stderr missing ambiguous-prefix: $stderr"; return 1; }
   return 0
 }
 
-# --- Case 3: more-specific prefix disambiguates ---
-case_more_specific_disambiguates() {
-  local root="/tmp/maxy-logs-read-prefix-3-$$"
+case_more_specific_prefix_resolves() {
+  local root="/tmp/maxy-prefix-test-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-$$
+  echo "a" > "$logdir/claude-agent-stream-abcd1111.log"
+  echo "b" > "$logdir/claude-agent-stream-abcd2222.log"
 
+  local rc=0
+  local stdout
+  stdout=$("$script" "abcd1111" agent-stream 2>/dev/null) || rc=$?
   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
+  [[ $rc -eq 0 ]] || { echo "  expected exit 0, got $rc"; return 1; }
+  [[ "$stdout" == *"a"* ]] || { echo "  missing sentinel"; return 1; }
   return 0
 }
 
-# --- Case 4: zero matches → tried=[<glob>, <glob>] file-not-found ---
-case_zero_matches() {
-  local root="/tmp/maxy-logs-read-prefix-4-$$"
+case_zero_match_miss() {
+  local root="/tmp/maxy-prefix-test-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-$$
-
+  local rc=0
+  "$script" "nomatch1" agent-stream >/dev/null 2>/tmp/prefix-stderr-4-$$ || rc=$?
+  local stderr
+  stderr=$(cat /tmp/prefix-stderr-4-$$)
+  rm -f /tmp/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
+  [[ $rc -eq 1 ]] || { echo "  expected exit 1, got $rc"; return 1; }
+  [[ "$stderr" == *"file-not-found"* ]] || { echo "  stderr missing file-not-found"; return 1; }
   return 0
 }
 
-# --- Case 5: full 36-char UUID still resolves (regression boundary) ---
-case_full_uuid_regression() {
-  local root="/tmp/maxy-logs-read-prefix-5-$$"
+case_full_sessionkey_resolves() {
+  local root="/tmp/maxy-prefix-test-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-$$
+  local sk="11111111-2222-3333-4444-555555555555"
+  echo "sentinel-5" > "$logdir/claude-agent-stream-${sk}.log"
 
+  local rc=0
+  local stdout
+  stdout=$("$script" "$sk" agent-stream 2>/dev/null) || rc=$?
   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
+  [[ $rc -eq 0 ]] || { echo "  expected exit 0, got $rc"; return 1; }
+  [[ "$stdout" == *"sentinel-5"* ]] || { echo "  missing sentinel"; return 1; }
   return 0
 }
 
-# --- Case 6: preflush-only file, prefix-match (Pass 2) ---
-case_preflush_prefix_match() {
-  local root="/tmp/maxy-logs-read-prefix-6-$$"
+case_every_per_session_type() {
+  local root="/tmp/maxy-prefix-test-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
+  local sk="abcdef00-0000-0000-0000-000000000000"
+  echo "stream" > "$logdir/claude-agent-stream-${sk}.log"
+  echo "err"    > "$logdir/claude-agent-stderr-${sk}.log"
+  echo "sse"    > "$logdir/sse-events-${sk}.log"
+  echo "pub"    > "$logdir/public-agent-stream-${sk}.log"
+
+  local ok=1
+  for type in agent-stream error session public; do
+    local out
+    out=$("$script" "abcdef00" "$type" 2>/dev/null) || ok=0
+    case "$type" in
+      agent-stream) [[ "$out" == *"stream"* ]] || ok=0 ;;
+      error)        [[ "$out" == *"err"* ]]    || ok=0 ;;
+      session)      [[ "$out" == *"sse"* ]]    || ok=0 ;;
+      public)       [[ "$out" == *"pub"* ]]    || ok=0 ;;
+    esac
   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
+  [[ $ok -eq 1 ]] || { echo "  one or more per-session types failed to resolve"; return 1; }
   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
+run_case "8-char prefix resolves full sessionKey file"   case_8char_prefix_resolves_full
+run_case "ambiguous prefix refuses to pick"              case_ambiguous_prefix_refuses
+run_case "more-specific prefix disambiguates"            case_more_specific_prefix_resolves
+run_case "zero matches → file-not-found"                 case_zero_match_miss
+run_case "full 36-char sessionKey resolves"              case_full_sessionkey_resolves
+run_case "every per-session type resolves"               case_every_per_session_type
 
 echo ""
 echo "================================================"

package/payload/platform/scripts/check-no-conversation-id-leaks.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Task 1007 build-time gate: prevents NEW files from gaining a `conversationId` /
+// `sessionId` reference while the 146-file rename slice is in progress.
+//
+// The legacy identifiers are being collapsed into the single canonical
+// `sessionKey`. This sprint shipped the schema-side load-bearing pieces
+// (backfill, new index, boot-time adherence probe) plus the core lib rename.
+// The mechanical tail (routes, MCP plugin parameters, UI props, WhatsApp,
+// tests, specialist templates) is split across follow-up tasks 1009 and 1010.
+//
+// During the transition window, every file currently containing the legacy
+// identifiers is named in `conversation-id-allowlist.txt`. Each follow-up
+// rename PR removes file paths from the allowlist as those files are migrated.
+// This gate fails if:
+//   (a) a file NOT in the allowlist contains any of the four legacy tokens, or
+//   (b) the allowlist references a path that no longer exists (stale entry).
+//
+// Once tasks 1009 and 1010 land, the allowlist is empty; the gate then enforces
+// the task's outcome contract (zero hits anywhere outside .tasks/archive/).
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, relative, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+const ALLOWLIST_PATH = join(SCRIPT_DIR, 'conversation-id-allowlist.txt')
+
+const SCAN_ROOTS = [
+  join(REPO_ROOT, 'platform'),
+  join(REPO_ROOT, 'packages'),
+  join(REPO_ROOT, 'brands'),
+  join(REPO_ROOT, '.docs'),
+  join(REPO_ROOT, '.claude', 'skills'),
+]
+
+const ALLOWED_EXTS = new Set([
+  '.sh', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.md', '.cypher', '.json',
+])
+const SKIP_DIR_NAMES = new Set([
+  'node_modules', 'dist', 'build', '.next', 'payload',
+])
+const SKIP_PATH_FRAGMENTS = ['.tasks/archive/']
+
+// Whole-word matches only — avoids hits inside longer identifiers like
+// `agentSessionId` (Claude Agent SDK per-process session, intentionally kept)
+// and `conversationIdentity` (ConversationArchive hash key, unrelated).
+const LEGACY_TOKEN_RE = /\b(?:conversationId|sessionId|CONVERSATION_ID|SESSION_ID)\b/
+
+// Comment-line skip — matches the convention in check-no-task-id-leaks.mjs.
+// Comments that *describe* the legacy field (inside the migration code itself,
+// or inline docstrings explaining the rename) are not new executing code
+// introducing the token, so they don't trip the gate.
+function isCommentLine(line) {
+  const trimmed = line.replace(/^\s+/, '')
+  if (trimmed.startsWith('#')) return true
+  if (trimmed.startsWith('//')) return true
+  if (trimmed.startsWith('/*')) return true
+  if (trimmed.startsWith('*')) return true
+  if (trimmed.startsWith('{/*')) return true
+  return false
+}
+
+function loadAllowlist() {
+  if (!existsSync(ALLOWLIST_PATH)) return new Set()
+  const text = readFileSync(ALLOWLIST_PATH, 'utf-8')
+  return new Set(
+    text.split('\n')
+      .map(l => l.trim())
+      .filter(l => l && !l.startsWith('#'))
+  )
+}
+
+function shouldScanFile(filePath) {
+  const name = basename(filePath)
+  const ext = name.includes('.') ? '.' + name.split('.').pop() : ''
+  if (!ALLOWED_EXTS.has(ext)) return false
+  const rel = relative(REPO_ROOT, filePath)
+  for (const frag of SKIP_PATH_FRAGMENTS) {
+    if (rel.includes(frag)) return false
+  }
+  return true
+}
+
+function* walk(root) {
+  let entries
+  try { entries = readdirSync(root) } catch { return }
+  for (const name of entries) {
+    if (SKIP_DIR_NAMES.has(name)) continue
+    const full = join(root, name)
+    let st
+    try { st = statSync(full) } catch { continue }
+    if (st.isDirectory()) {
+      yield* walk(full)
+    } else if (st.isFile()) {
+      yield full
+    }
+  }
+}
+
+const allowlist = loadAllowlist()
+const newLeaks = []
+const hitFiles = new Set()
+
+for (const root of SCAN_ROOTS) {
+  if (!existsSync(root)) continue
+  for (const file of walk(root)) {
+    if (!shouldScanFile(file)) continue
+    let content
+    try { content = readFileSync(file, 'utf-8') } catch { continue }
+    if (!LEGACY_TOKEN_RE.test(content)) continue
+    const rel = relative(REPO_ROOT, file)
+    const lines = content.split('\n')
+    // For non-allowlisted files: only flag hits in non-comment lines. For
+    // allowlisted files: any hit counts (so the allowlist accurately tracks
+    // the surface still using the legacy name, comments and code alike).
+    if (allowlist.has(rel)) {
+      hitFiles.add(rel)
+      continue
+    }
+    let firstLine = 0, firstText = ''
+    for (let i = 0; i < lines.length; i++) {
+      if (!LEGACY_TOKEN_RE.test(lines[i])) continue
+      if (isCommentLine(lines[i])) continue
+      firstLine = i + 1
+      firstText = lines[i].trim().slice(0, 120)
+      break
+    }
+    if (firstLine > 0) {
+      newLeaks.push({ file: rel, line: firstLine, content: firstText })
+    }
+  }
+}
+
+// Stale allowlist entries: files in the allowlist that no longer have a hit
+// (renamed already, or no longer exist) — remove them.
+const staleAllowlistEntries = [...allowlist].filter(p => !hitFiles.has(p))
+
+let failed = false
+
+if (newLeaks.length > 0) {
+  failed = true
+  console.error(`check-no-conversation-id-leaks: ${newLeaks.length} NEW file(s) introduced legacy identifier(s):`)
+  for (const leak of newLeaks) {
+    console.error(`  ${leak.file}:${leak.line}: ${leak.content}`)
+  }
+  console.error('')
+  console.error('The single canonical identifier is `sessionKey`. New code must use it.')
+  console.error('Legacy tokens: conversationId, sessionId, CONVERSATION_ID, SESSION_ID.')
+  console.error('Follow-up tasks 1009 + 1010 are migrating existing files off the allowlist.')
+}
+
+if (staleAllowlistEntries.length > 0) {
+  failed = true
+  console.error('')
+  console.error(`check-no-conversation-id-leaks: ${staleAllowlistEntries.length} stale allowlist entry(ies) — remove from platform/scripts/conversation-id-allowlist.txt:`)
+  for (const entry of staleAllowlistEntries) {
+    console.error(`  ${entry}`)
+  }
+}
+
+if (failed) process.exit(1)
+
+console.error(`check-no-conversation-id-leaks: ok (${allowlist.size} files in transition allowlist; 0 new leaks)`)