@rubytech/create-maxy 1.0.886 → 1.0.887

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.886",
+  "version": "1.0.887",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -52,7 +52,7 @@ Tools are available via the `admin` MCP server.
 
 `logs-read { type: "agent-stream" }` is the canonical name for the per-conversation tool-use/tool-result archive previously called `system`; both names work and the legacy alias is preserved.
 
-**Stream log is the primary diagnostic surface for an in-progress session.** Every stream log is named by sessionKey and exists from the first token. The parent-process console fan-out tee in [`platform/ui/app/lib/claude-agent/logging.ts`](../../ui/app/lib/claude-agent/logging.ts) appends every `[<tag>]`-prefixed `console.error` / `console.log` line to every active session's stream log alongside `server.log`. For diagnosing an in-session issue (WhatsApp inbound, Cloudflare action, persist write, baileys error), call `logs-read { sessionKey: "<…>" }` first — the stream log carries both the agent lifecycle AND the parent-process events that occurred during the session window. The `conversationId` parameter remains a legacy alias resolving to the same sessionKey-named file. `logs-read { type: "server" }` is the cross-session escape hatch for events outside any single session window.
+**Stream log is the primary diagnostic surface for an in-progress session.** Every stream log is named by sessionKey and the stream-log file exists from the first token. The first-token invariant is bound by `platform/scripts/__tests__/first-token-creates-stream-log.test.sh`: one operator turn, one token, `claude-agent-stream-<sessionKey>.log` exists and contains the token bytes after the byte returns to the operator. The parent-process console fan-out tee in [`platform/ui/app/lib/claude-agent/logging.ts`](../../ui/app/lib/claude-agent/logging.ts) appends every `[<tag>]`-prefixed `console.error` / `console.log` line to every active session's stream log alongside `server.log`. For diagnosing an in-session issue (WhatsApp inbound, Cloudflare action, persist write, baileys error), call `logs-read { sessionKey: "<…>" }` first — the stream log carries both the agent lifecycle AND the parent-process events that occurred during the session window. The `conversationId` parameter remains a legacy alias resolving to the same sessionKey-named file. `logs-read { type: "server" }` is the cross-session escape hatch for events outside any single session window.
 
 ## Skills
 

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

@@ -1,5 +1,13 @@
 # Troubleshooting
 
+## Stream-log file for a fresh session is absent or empty
+
+**Symptom:** Operator opens a new admin session, sends one turn, sees the agent reply, then `logs-read sessionKey=<…>` returns `file-not-found` or zero bytes.
+
+**Invariant:** For every new session, the stream-log file exists on disk and contains the token bytes from the moment the first token returns to the operator. The first-token invariant is bound by `platform/scripts/__tests__/first-token-creates-stream-log.test.sh`: one operator turn, one token, `claude-agent-stream-<sessionKey>.log` exists and contains the token bytes — pass iff file present and bytes present.
+
+**Diagnose if it ever recurs:** run `bash platform/scripts/__tests__/first-token-creates-stream-log.test.sh` from the install. Pass = invariant holds; any other exit = the writer-side existence contract is broken and one `[log-tee] missing-on-resolve sessionKey=<8> surface=<…>` line on `server.log` is the operator-visible signal (P0).
+
 ## Browser navigation to a local file (`file://`) used to time out for two minutes
 
 **Symptom:** Older versions of the platform's admin agent would attempt `browser_navigate file:///path/to.html`, hit Playwright's silent two-minute timeout, then guess fixed ports (8080 / 3000 / 8000 / 9000) and report `ERR_CONNECTION_REFUSED` for each before someone manually started a local HTTP server.

package/payload/platform/scripts/__tests__/first-token-creates-stream-log.test.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Task 1011 — the binding test for the first-token invariant.
+#
+# Invariant: for every new session, at the moment the first token is
+# emitted, the stream-log file for that session exists on disk and contains
+# that token's bytes. Tasks 1006/1008/1010 each shipped a partial slice;
+# this test fixes the invariant itself to one assertion.
+#
+# The .test.sh entrypoint is the operator-facing surface — runnable from a
+# bash prompt, from boot smoke, and from any CI runner that has `node` on
+# PATH. The contract assertions live in the vitest spec at:
+#   platform/ui/server/routes/admin/__tests__/first-token-creates-stream-log.test.ts
+#
+# That spec exercises the live chat-route handler, the live appendFileSync
+# writer, and a live filesystem (mkdtempSync tmpdir). The only seams
+# substituted are upstream of the writer: the agent SDK invocation, the
+# session-store identity lookups, and the Neo4j createConversation
+# roundtrip. None of those are the writer the invariant binds.
+#
+# Exit codes:
+#   0  test passed — file present, token bytes present
+#   1  test failed — file absent OR token bytes absent
+#   2  vitest binary not resolvable from platform/ui
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+UI_DIR="$(cd "$SCRIPT_DIR/../../ui" && pwd)"
+SPEC_REL="server/routes/admin/__tests__/first-token-creates-stream-log.test.ts"
+
+if [[ ! -f "$UI_DIR/$SPEC_REL" ]]; then
+  echo "FATAL: vitest spec missing at $UI_DIR/$SPEC_REL" >&2
+  exit 2
+fi
+
+cd "$UI_DIR"
+exec npx --no-install vitest run "$SPEC_REL" --reporter=verbose

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

@@ -172,12 +172,63 @@ case_every_per_session_type() {
   return 0
 }
 
+# Task 1010 — sk_<hex16> writer-side format from Task 1008 must resolve via
+# the underscore-bearing regex `^[a-zA-Z0-9_-]+$`. Pre-1010 the regex
+# rejected `_`, leaving every post-1008 stream log unretrievable.
+case_sk_underscore_prefix_resolves() {
+  local root="/tmp/maxy-prefix-test-7-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local logdir="$root/data/accounts/acct-test/logs"
+  local sk="sk_16e0eeb035cf52ef"
+  echo "sentinel-sk" > "$logdir/claude-agent-stream-${sk}.log"
+
+  local rc=0
+  local stdout
+  stdout=$("$script" "sk_16e0e" agent-stream 2>/dev/null) || rc=$?
+  cleanup_install_tree "$root"
+
+  [[ $rc -eq 0 ]] || { echo "  expected exit 0, got $rc"; return 1; }
+  [[ "$stdout" == *"sentinel-sk"* ]] || { echo "  missing sentinel"; return 1; }
+  return 0
+}
+
+# Task 1010 — shell metacharacters must still be rejected. The regex widen
+# adds `_` only; `;`, `*`, `$`, `?`, `[` etc. must still hit the reject path
+# and exit 2, otherwise user input would escape literal matching in the glob.
+# Also asserts the `[logs-read] regex-rejected` observability line lands in
+# server.log so the adherence runner can see writer/reader divergence.
+case_shell_metachar_still_rejected() {
+  local root="/tmp/maxy-prefix-test-8-$$"
+  local script
+  script=$(setup_install_tree "$root")
+  local server_log="$HOME/.$(basename "$root")/logs/server.log"
+  : > "$server_log"
+
+  local rc=0
+  "$script" "abc;rm" agent-stream >/dev/null 2>/tmp/prefix-stderr-8-$$ || rc=$?
+  local stderr
+  stderr=$(cat /tmp/prefix-stderr-8-$$)
+  rm -f /tmp/prefix-stderr-8-$$
+  local server_log_contents
+  server_log_contents=$(cat "$server_log" 2>/dev/null || echo "")
+  cleanup_install_tree "$root"
+
+  [[ $rc -eq 2 ]] || { echo "  expected exit 2, got $rc"; return 1; }
+  [[ "$stderr" == *"invalid characters"* ]] || { echo "  stderr missing 'invalid characters': $stderr"; return 1; }
+  [[ "$server_log_contents" == *"[logs-read] regex-rejected"* ]] || { echo "  server.log missing regex-rejected line: $server_log_contents"; return 1; }
+  [[ "$server_log_contents" == *"sample=;"* ]] || { echo "  server.log missing sample=;: $server_log_contents"; return 1; }
+  return 0
+}
+
 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
+run_case "Task 1010: sk_ underscore prefix resolves"     case_sk_underscore_prefix_resolves
+run_case "Task 1010: shell metacharacter still rejected" case_shell_metachar_still_rejected
 
 echo ""
 echo "================================================"

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

@@ -118,6 +118,16 @@ is_per_conversation_type() {
 SEARCH_TYPES="agent-stream error session public server mcp vnc"
 VALID_TYPES="agent-stream, system, session, error, heartbeat, public, server, mcp, vnc"
 
+# Authoritative sessionKey character set.
+# Writer-side (Task 1008) emits `sk_<hex16>` filenames; the underscore must
+# stay in this regex or every post-1008 file becomes unretrievable
+# (Task 1010). UUID v4 sessionKeys (legacy and current alternate format)
+# also pass. Widening past this set is unsafe: session_key is concatenated
+# into a glob below (`${prefix}${session_key}*.log`), so any character bash
+# treats as a metacharacter (`*`, `?`, `[`, `;`, `$`, etc.) would escape
+# literal matching.
+SESSIONKEY_REGEX='^[a-zA-Z0-9_-]+$'
+
 usage() {
   cat >&2 <<EOF
 Usage:
@@ -172,10 +182,20 @@ per_conversation_mode() {
   fi
 
   # Reject shell metacharacters in session_key — the prefix-match glob below
-  # would otherwise turn user input into a shell pattern. SessionKeys only
-  # contain [a-zA-Z0-9-].
-  if [[ ! "$session_key" =~ ^[a-zA-Z0-9-]+$ ]]; then
-    echo "Error: sessionKey contains invalid characters (allowed: a-z, A-Z, 0-9, -)" >&2
+  # would otherwise turn user input into a shell pattern. SessionKeys are
+  # `sk_<hex16>` (Task 1008) or UUID v4; both fit $SESSIONKEY_REGEX defined
+  # near the top of the script. Task 1010 widened this from `[a-zA-Z0-9-]`
+  # after the Task 1008 underscore-bearing format made every post-1008
+  # session unretrievable.
+  if [[ ! "$session_key" =~ $SESSIONKEY_REGEX ]]; then
+    # Observability: surface the rejection before the operator-visible error
+    # so the adherence runner can prove writer/reader divergence.
+    # Best-effort append; mirrors the missing-on-resolve idiom below.
+    local rej_ts bad_char
+    rej_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    bad_char=$(printf '%s' "$session_key" | tr -d 'a-zA-Z0-9_-' | head -c 1)
+    echo "${rej_ts} [logs-read] regex-rejected sessionKey-prefix=${session_key:0:12} regex=${SESSIONKEY_REGEX} sample=${bad_char}" >> "$SERVER_LOG" 2>/dev/null || true
+    echo "Error: sessionKey contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)" >&2
     exit 2
   fi