@rubytech/create-maxy-code 0.1.69 → 0.1.71

package/package.json

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

package/payload/platform/config/brand.json

@@ -15,6 +15,7 @@
   "cdpPort": 9222,
   "claudeSessionManagerPort": 19400,
   "commercialMode": false,
+  "vertical": null,
 
   "defaultColors": {
     "primary": "#7C8C72",

package/payload/platform/plugins/admin/hooks/__tests__/turn-completed-graph-write.test.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# Task 129/131/165/175/177 regression test for the Stop hook.
+# Task 129/131/165/175/177/195 regression test for the Stop hook.
 #
-# Contract:
+# Contract (post-195):
 #   - Every log emission goes through `POST /api/admin/log-ingest`. Hook
 #     stderr is silent on every path.
 #   - Every gated-off path emits one `trigger-skipped` line carrying a
@@ -11,14 +11,17 @@
 #     `conversationBytes=<n>` and exactly ONE POST to
 #     `/api/admin/claude-sessions`. The body carries the operator
 #     session id as `adminSessionId` and an `initialMessage` whose value
-#     is a JSON-stringified object with EXACTLY the four keys declared by
-#     the Task 177 envelope: turns, conversationId, accountId, occurredAt.
-#     `turns` is the chronologically-ordered list of conversation turns.
-#     No top-level operatorMessage. No top-level assistantReply.
-#     No leading instruction prose. No `Conversation id:` prose.
-#   - The hook emits one `[turn-recorder] envelope ...` log line before
-#     `spawn-request`, naming turnsCount / userTurns / assistantTurns /
-#     toolCallTurns.
+#     is the FILLED database-operator paragraph — the four-sentence
+#     template with `{schema}` replaced by `schema-base.md` (plus the
+#     brand-declared vertical when set) and `{conversation}` replaced by
+#     a flat `role: text` rendering of the envelope's `turns` array with
+#     inline `[tool: name(args)]` markers on assistant turns that called
+#     tools. The initialMessage is a plain string, not a JSON-stringified
+#     envelope; no instruction prose, no leading JSON.
+#   - The hook emits exactly one `[turn-recorder] envelope ...` line and
+#     one `[turn-recorder] substitution ...` line before `spawn-request`.
+#     The substitution line carries `schemaBytes`, `conversationBytes`,
+#     and `bodyBytes` so the per-spawn substitution is auditable.
 #   - The hook never writes the legacy `spawn-with-input` / `fired` stderr
 #     lines.
 #
@@ -219,57 +222,88 @@ else
   fail "case-5b expected exactly 1 recorder-spawn POST, got $RECORDER_LINES"
 fi
 
-# 5c. Envelope has exactly four keys (turns, conversationId, accountId,
-#     occurredAt). `turns` carries 4 entries in record order; each has
-#     role/text/ts. No `toolCalls` on turns where there were no tool_use
-#     blocks (omitted-when-empty rule).
+# 5c. (Task 195) initialMessage is the FILLED four-sentence paragraph.
+#     The template's `{schema}` is replaced by schema-base.md content;
+#     `{conversation}` is replaced by `role: text` lines for every turn.
+#     The string is plain text, not a JSON envelope. The template's
+#     opening sentence and closing sentence are present verbatim; the
+#     four operator/assistant texts each appear on their own line.
 RECORDER_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
 BODY_OK=$(printf '%s' "$RECORDER_BODY" | python3 -c '
-import sys, json, re
+import sys, json
 op = sys.argv[1]
-acct = sys.argv[2]
 try:
   outer = json.load(sys.stdin)
-  msg_str = outer.get("initialMessage")
-  if not isinstance(msg_str, str):
-    print("no:initialMessage-not-string:"+repr(type(msg_str).__name__))
+  msg = outer.get("initialMessage")
+  if not isinstance(msg, str):
+    print("no:initialMessage-not-string:"+repr(type(msg).__name__))
     sys.exit(0)
-  msg = json.loads(msg_str)
-  keys = set(msg.keys())
-  turns = msg.get("turns") or []
   conds = []
-  conds.append(("envelope-keys", keys == {"turns", "conversationId", "accountId", "occurredAt"}))
-  conds.append(("turns-len", len(turns) == 4))
-  conds.append(("conversationId", msg.get("conversationId") == op))
-  conds.append(("accountId", msg.get("accountId") == acct))
-  conds.append(("occurredAt-shape", bool(re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$", msg.get("occurredAt") or ""))))
-  conds.append(("no-operatorMessage", "operatorMessage" not in keys))
-  conds.append(("no-assistantReply", "assistantReply" not in keys))
-  if len(turns) >= 4:
-    conds.append(("t0-role", turns[0].get("role") == "user"))
-    conds.append(("t0-text", turns[0].get("text") == "New Real Agent session"))
-    conds.append(("t0-ts", turns[0].get("ts") == "2026-05-19T21:27:42.258Z"))
-    conds.append(("t0-no-toolCalls", "toolCalls" not in turns[0]))
-    conds.append(("t1-role", turns[1].get("role") == "assistant"))
-    conds.append(("t1-text", turns[1].get("text") == "Session noted. What would you like to work on?"))
-    conds.append(("t1-ts", turns[1].get("ts") == "2026-05-19T21:27:45.158Z"))
-    conds.append(("t1-no-toolCalls", "toolCalls" not in turns[1]))
-    conds.append(("t2-role", turns[2].get("role") == "user"))
-    conds.append(("t2-text", turns[2].get("text") == "you tell me"))
-    conds.append(("t3-role", turns[3].get("role") == "assistant"))
-    conds.append(("t3-text", turns[3].get("text") == "One question to anchor the next move: what is your name?"))
+  conds.append(("starts-with-template",
+                msg.startswith("You are an expert Neo4J graph operator.")))
+  conds.append(("ends-with-template",
+                msg.rstrip().endswith("do not emit it.")))
+  conds.append(("no-placeholder-schema", "{schema}" not in msg))
+  conds.append(("no-placeholder-conversation", "{conversation}" not in msg))
+  # schema-base.md content is interpolated.
+  conds.append(("contains-schema-base-header", "Schema Reference" in msg))
+  # The conversation lines appear in role: text format.
+  conds.append(("has-user-1", "\nuser: New Real Agent session" in msg))
+  conds.append(("has-asst-1",
+                "\nassistant: Session noted. What would you like to work on?" in msg))
+  conds.append(("has-user-2", "\nuser: you tell me" in msg))
+  conds.append(("has-asst-2",
+                "\nassistant: One question to anchor the next move: what is your name?"
+                in msg))
+  conds.append(("no-leading-json", not msg.lstrip().startswith("{")))
+  conds.append(("no-operatorMessage", "operatorMessage" not in msg))
+  conds.append(("no-assistantReply", "assistantReply" not in msg))
   conds.append(("outer-specialist", outer.get("specialist") == "database-operator"))
   conds.append(("outer-model", outer.get("model") == "haiku"))
   conds.append(("outer-adminSessionId", outer.get("adminSessionId") == op))
+  conds.append(("outer-channel", outer.get("channel") == "browser"))
   failed = [name for name, ok in conds if not ok]
-  print("yes" if not failed else "no:"+repr(failed)+"|turns="+repr(turns))
+  print("yes" if not failed else "no:"+repr(failed))
 except Exception as e:
   print("parse-fail:"+str(e))
-' "$OP_ID" "$ACCT_ID" 2>/dev/null)
+' "$OP_ID" 2>/dev/null)
 if [[ "$BODY_OK" == "yes" ]]; then
-  pass "case-5c envelope is { turns, conversationId, accountId, occurredAt }; turns is the 4-entry ordered list"
+  pass "case-5c initialMessage is the filled four-sentence paragraph; placeholders substituted; transcript rendered as role: text lines"
+else
+  fail "case-5c filled-prompt shape wrong ($BODY_OK)"
+fi
+
+# 5h. (Task 195) exactly one `substitution` log-ingest line carrying
+#     positive byte counts for schema / conversation / body.
+SUBST_LINE_COUNT=$(ingest_lines | grep -cE "^substitution sessionId=${OP_ID} schemaBytes=[1-9][0-9]* conversationBytes=[1-9][0-9]* bodyBytes=[1-9][0-9]*$" || true)
+if [[ "$SUBST_LINE_COUNT" -eq 1 ]]; then
+  pass "case-5h substitution log line emitted once with positive byte counts"
+else
+  fail "case-5h expected exactly 1 substitution line w/ positive bytes, got $SUBST_LINE_COUNT (lines: $(ingest_lines))"
+fi
+
+# 5i. (Task 195) substitution line lands between envelope and spawn-request.
+ALL_5I_LINES=$(ingest_lines)
+ENV_POS_5I=$(printf '%s\n' "$ALL_5I_LINES" | grep -nE "^envelope sessionId=${OP_ID}" | head -1 | cut -d: -f1)
+SUB_POS_5I=$(printf '%s\n' "$ALL_5I_LINES" | grep -nE "^substitution sessionId=${OP_ID}" | head -1 | cut -d: -f1)
+SPAWN_POS_5I=$(printf '%s\n' "$ALL_5I_LINES" | grep -nE "^spawn-request sessionId=${OP_ID}" | head -1 | cut -d: -f1)
+if [[ -n "$ENV_POS_5I" && -n "$SUB_POS_5I" && -n "$SPAWN_POS_5I" \
+      && "$ENV_POS_5I" -lt "$SUB_POS_5I" && "$SUB_POS_5I" -lt "$SPAWN_POS_5I" ]]; then
+  pass "case-5i envelope < substitution < spawn-request ordering preserved"
 else
-  fail "case-5c envelope shape wrong ($BODY_OK): $RECORDER_BODY"
+  fail "case-5i ordering wrong (env=$ENV_POS_5I sub=$SUB_POS_5I spawn=$SPAWN_POS_5I)"
+fi
+
+# 5j. (Task 195) `initialMessageBytes` on spawn-request equals `bodyBytes`
+#     on substitution — the two log lines are reading the same number.
+BODY_BYTES_5J=$(printf '%s\n' "$ALL_5I_LINES" | grep -E "^substitution sessionId=${OP_ID}" | head -1 \
+                 | sed -E 's/.*bodyBytes=([0-9]+).*/\1/')
+INIT_BYTES_5J=$(printf '%s\n' "$ALL_5I_LINES" | grep -E "^spawn-request sessionId=${OP_ID}" | head -1 \
+                 | sed -E 's/.*initialMessageBytes=([0-9]+).*/\1/')
+if [[ -n "$BODY_BYTES_5J" && "$BODY_BYTES_5J" == "$INIT_BYTES_5J" ]]; then
+  pass "case-5j substitution.bodyBytes == spawn-request.initialMessageBytes (=$BODY_BYTES_5J)"
+else
+  fail "case-5j bodyBytes ($BODY_BYTES_5J) does not match initialMessageBytes ($INIT_BYTES_5J)"
 fi
 
 # 5d. exactly ONE `spawn-request` log-ingest line
@@ -307,12 +341,12 @@ else
   pass "case-5g no legacy stderr emissions"
 fi
 
-# --- Case 6 (Task 177): multi-block assistant collapse -----------------
-# Two assistant JSONL records sharing `message.id`: first is thinking-only,
-# second carries the text. Walker collapses both into ONE `turns` entry
-# whose text is the text-record's text. Thinking records contribute no
-# text and do not establish the turn; `ts` is the first CONTRIBUTING
-# record's ts (here, the text record's ts).
+# --- Case 6 (Task 195): multi-block assistant collapse ----------------
+# Two assistant records sharing `message.id`: thinking-only then text.
+# The walker collapses both into ONE assistant turn whose text is the
+# text-record's text. The filled prompt's conversation portion has
+# exactly two transcript lines: `user: think then answer` and
+# `assistant: answer is 42`.
 MULTI_TRANSCRIPT=$(mktemp); TMPFILES+=("$MULTI_TRANSCRIPT")
 {
   printf '{"type":"user","timestamp":"2026-05-19T21:30:00.000Z","message":{"role":"user","content":"think then answer"}}\n'
@@ -331,23 +365,31 @@ MULTI_OK=$(printf '%s' "$MULTI_BODY" | python3 -c '
 import sys, json
 try:
   outer = json.load(sys.stdin)
-  msg = json.loads(outer.get("initialMessage"))
-  turns = msg.get("turns") or []
+  msg = outer.get("initialMessage")
+  if not isinstance(msg, str):
+    print("no:initialMessage-not-string")
+    sys.exit(0)
   conds = []
-  conds.append(("turns-len-2", len(turns) == 2))
-  if len(turns) >= 2:
-    conds.append(("t0-user", turns[0].get("role") == "user" and turns[0].get("text") == "think then answer"))
-    conds.append(("t1-assistant", turns[1].get("role") == "assistant"))
-    conds.append(("t1-text", turns[1].get("text") == "answer is 42"))
-    conds.append(("t1-ts-text-record", turns[1].get("ts") == "2026-05-19T21:30:02.000Z"))
-    conds.append(("t1-no-toolCalls", "toolCalls" not in turns[1]))
+  # Filled-prompt sanity.
+  conds.append(("starts-template", msg.startswith("You are an expert Neo4J graph operator.")))
+  conds.append(("no-placeholder-conv", "{conversation}" not in msg))
+  # Conversation lines.
+  conds.append(("has-user", "\nuser: think then answer" in msg))
+  conds.append(("has-asst", "\nassistant: answer is 42" in msg))
+  # Thinking content does NOT bleed in.
+  conds.append(("no-thinking-text", "considering..." not in msg))
+  # Exactly two transcript lines (one per turn) — no duplicate assistant.
+  user_lines = msg.count("\nuser: ")
+  asst_lines = msg.count("\nassistant: ")
+  conds.append(("one-user-line", user_lines == 1))
+  conds.append(("one-asst-line", asst_lines == 1))
   failed = [name for name, ok in conds if not ok]
-  print("yes" if not failed else "no:"+repr(failed)+"|turns="+repr(turns))
+  print("yes" if not failed else "no:"+repr(failed))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' 2>/dev/null)
 if [[ "$MULTI_OK" == "yes" ]]; then
-  pass "case-6 multi-block assistant collapses to one turn entry; ts is the first record's ts"
+  pass "case-6 multi-block assistant collapses to one transcript line; thinking content does not bleed in"
 else
   fail "case-6 multi-block collapse wrong ($MULTI_OK): $MULTI_BODY"
 fi
@@ -387,30 +429,35 @@ TOOL_OK=$(printf '%s' "$TOOL_BODY" | python3 -c '
 import sys, json
 try:
   outer = json.load(sys.stdin)
-  msg = json.loads(outer.get("initialMessage"))
-  turns = msg.get("turns") or []
+  msg = outer.get("initialMessage")
+  if not isinstance(msg, str):
+    print("no:initialMessage-not-string")
+    sys.exit(0)
   conds = []
-  # Expected 3 turns: user "please write a node", assistant tool_use (text=""),
-  # assistant "done". The user tool_result record carries no separate user turn.
-  conds.append(("turns-len-3", len(turns) == 3))
-  if len(turns) >= 3:
-    conds.append(("t0", turns[0].get("role") == "user" and turns[0].get("text") == "please write a node"))
-    conds.append(("t1-role", turns[1].get("role") == "assistant"))
-    conds.append(("t1-text-empty", turns[1].get("text") == ""))
-    conds.append(("t1-toolCalls-len", len(turns[1].get("toolCalls") or []) == 1))
-    tc = (turns[1].get("toolCalls") or [{}])[0]
-    conds.append(("tc-tool", tc.get("tool") == "mcp__memory__memory-write"))
-    conds.append(("tc-input", tc.get("input") == {"nodeType":"LocalBusiness","name":"Smalleys","nested":{"k":1}}))
-    conds.append(("tc-output", tc.get("output") == "ok: wrote LocalBusiness"))
-    conds.append(("t2", turns[2].get("role") == "assistant" and turns[2].get("text") == "done"))
-    conds.append(("t2-no-toolCalls", "toolCalls" not in turns[2]))
+  # The user turn carrying only a tool_result becomes no transcript line;
+  # so the filled prompt should have exactly ONE `user:` line.
+  conds.append(("one-user-line", msg.count("\nuser: ") == 1))
+  conds.append(("has-user-prompt", "\nuser: please write a node" in msg))
+  # Two assistant lines: one carrying the tool_use marker (with empty
+  # text body), one carrying "done".
+  conds.append(("two-asst-lines", msg.count("\nassistant: ") == 2))
+  conds.append(("has-asst-done", "\nassistant: done" in msg))
+  # Tool-call marker on the owning assistant turn — name and full JSON
+  # input round-trip inline.
+  conds.append(("has-tool-marker", "[tool: mcp__memory__memory-write(" in msg))
+  conds.append(("tool-marker-name", "\"name\": \"Smalleys\"" in msg or "\"name\":\"Smalleys\"" in msg))
+  conds.append(("tool-marker-nested", "\"nested\"" in msg))
+  conds.append(("tool-marker-nodeType", "\"nodeType\": \"LocalBusiness\"" in msg or "\"nodeType\":\"LocalBusiness\"" in msg))
+  # The tool_result content does NOT bleed in (the rendering chose
+  # input-only markers; output goes nowhere in the filled prompt).
+  conds.append(("no-output-leakage", "ok: wrote LocalBusiness" not in msg))
   failed = [name for name, ok in conds if not ok]
-  print("yes" if not failed else "no:"+repr(failed)+"|turns="+repr(turns))
+  print("yes" if not failed else "no:"+repr(failed))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' 2>/dev/null)
 if [[ "$TOOL_OK" == "yes" ]]; then
-  pass "case-7 tool_use + tool_result land as one toolCalls entry on owning assistant turn; no extra user turn"
+  pass "case-7 assistant tool_use renders as [tool: name(args)] marker on the owning turn; tool_result does not create a separate user line"
 else
   fail "case-7 tool pairing wrong ($TOOL_OK): $TOOL_BODY"
 fi
@@ -449,23 +496,29 @@ LONG_OK=$(printf '%s' "$LONG_BODY" | python3 -c '
 import sys, json
 try:
   outer = json.load(sys.stdin)
-  msg = json.loads(outer.get("initialMessage"))
-  turns = msg.get("turns") or []
+  msg = outer.get("initialMessage")
+  if not isinstance(msg, str):
+    print("no:initialMessage-not-string")
+    sys.exit(0)
+  user_lines = msg.count("\nuser: ")
+  asst_lines = msg.count("\nassistant: ")
   conds = []
-  conds.append(("turns-len-100", len(turns) == 100))
-  if len(turns) == 100:
-    conds.append(("first-user-0", turns[0].get("role") == "user" and turns[0].get("text") == "user msg 0"))
-    conds.append(("last-asst-49", turns[99].get("role") == "assistant" and turns[99].get("text") == "asst reply 49"))
-    # ts strictly non-decreasing
-    tss = [t.get("ts","") for t in turns]
-    conds.append(("ts-ordered", tss == sorted(tss)))
+  # No windowing — every one of the 100 turns appears as a transcript line.
+  conds.append(("100-user", user_lines == 50))
+  conds.append(("100-asst", asst_lines == 50))
+  conds.append(("first-user-0", "\nuser: user msg 0" in msg))
+  conds.append(("last-user-49", "\nuser: user msg 49" in msg))
+  conds.append(("last-asst-49", "\nassistant: asst reply 49" in msg))
+  # The filled prompt is large — schema + 100 transcript lines easily
+  # exceeds 5_000 bytes even with a tiny schema.
+  conds.append(("body-large", len(msg.encode("utf-8")) > 5000))
   failed = [name for name, ok in conds if not ok]
-  print("yes" if not failed else "no:"+repr(failed)+"|len="+str(len(turns)))
+  print("yes" if not failed else "no:"+repr(failed)+"|users="+str(user_lines)+"|assts="+str(asst_lines))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' 2>/dev/null)
 if [[ "$LONG_OK" == "yes" ]]; then
-  pass "case-8 100-turn transcript → turns.length === 100, oldest first, no truncation"
+  pass "case-8 100-turn transcript → 50 user lines + 50 assistant lines in filled prompt; no truncation"
 else
   fail "case-8 long-conversation wrong ($LONG_OK)"
 fi
@@ -522,24 +575,32 @@ run_hook "admin" "" "$ESC_ENVELOPE"
 ESC_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
 ESC_OK=$(printf '%s' "$ESC_BODY" | python3 -c '
 import sys, json
-EXPECTED_OP = "hello \"world\"\\nline2\nlast — café \U0001F98A"
-EXPECTED_ASST = "reply with backslash \\\\ and newline\nhere"
+# The user turn text contains literal quotes, a backslash-n (two chars),
+# a real newline, an em-dash, and a fox emoji. The assistant text has
+# two backslashes and a real newline.
+EXPECTED_OP_FRAG_1 = "hello \"world\""
+EXPECTED_OP_FRAG_2 = "last — café \U0001F98A"
+EXPECTED_ASST_FRAG = "reply with backslash \\\\ and newline"
 try:
   outer = json.load(sys.stdin)
-  msg = json.loads(outer.get("initialMessage"))
-  turns = msg.get("turns") or []
+  msg = outer.get("initialMessage")
+  if not isinstance(msg, str):
+    print("no:initialMessage-not-string")
+    sys.exit(0)
   conds = []
-  conds.append(("len-2", len(turns) == 2))
-  if len(turns) == 2:
-    conds.append(("op-text", turns[0].get("text") == EXPECTED_OP))
-    conds.append(("asst-text", turns[1].get("text") == EXPECTED_ASST))
+  conds.append(("op-quotes", EXPECTED_OP_FRAG_1 in msg))
+  conds.append(("op-emoji", EXPECTED_OP_FRAG_2 in msg))
+  conds.append(("asst-backslash", EXPECTED_ASST_FRAG in msg))
+  conds.append(("user-prefix", "\nuser: " in msg))
+  conds.append(("asst-prefix", "\nassistant: " in msg))
+  conds.append(("template-intact", "You are an expert Neo4J graph operator." in msg))
   failed = [name for name, ok in conds if not ok]
-  print("yes" if not failed else "no:"+repr(failed)+"|turns="+repr(turns))
+  print("yes" if not failed else "no:"+repr(failed))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' 2>/dev/null)
 if [[ "$ESC_OK" == "yes" ]]; then
-  pass "case-10 escaping: quotes/backslashes/newlines/non-ASCII round-trip cleanly through turns[*].text"
+  pass "case-10 escaping: quotes / backslashes / em-dash / emoji survive interpolation into the filled prompt"
 else
   fail "case-10 escaping wrong ($ESC_OK): $ESC_BODY"
 fi

package/payload/platform/plugins/admin/hooks/turn-completed-graph-write.sh

@@ -283,26 +283,140 @@ print(f"{len(turns)} {u} {a} {tc}")
 read -r TURNS_COUNT USER_TURNS ASST_TURNS TC_TURNS <<<"$ENVELOPE_COUNTS"
 emit_log "envelope sessionId=${ADMIN_SESSION_ID} turnsCount=${TURNS_COUNT} userTurns=${USER_TURNS} assistantTurns=${ASST_TURNS} toolCallTurns=${TC_TURNS}"
 
-# Compose the Sidebar-shape spawn body. Three overrides relative to a
-# plain Sidebar "New session" click: specialist, model, initialMessage.
-# `adminSessionId` is the loopback-bypass key the wrapper uses to resolve
-# the operator's senderId from the manager's /<sid>/meta.
-SPAWN_BODY=$(python3 -c '
+# Task 195 — substitute {schema} and {conversation} placeholders in the
+# database-operator agent body before spawning. The agent file on disk
+# carries the four-sentence template verbatim with both placeholders; the
+# hook renders the actual schema text and a flat `role: text` conversation
+# transcript here, then sends the filled paragraph as `initialMessage`.
+# The model's first input is the filled prompt — no JSON envelope, no
+# instruction prose, no placeholders.
+HOOK_DIR_RESOLVED="$(cd "$(dirname "$0")" && pwd)"
+PLATFORM_ROOT_RESOLVED="$(cd "${HOOK_DIR_RESOLVED}/../../.." && pwd)"
+SCHEMA_BASE_PATH="${PLATFORM_ROOT_RESOLVED}/plugins/memory/references/schema-base.md"
+BRAND_JSON_PATH="${PLATFORM_ROOT_RESOLVED}/config/brand.json"
+AGENT_BODY_PATH="${PLATFORM_ROOT_RESOLVED}/templates/specialists/agents/database-operator.md"
+
+if [ ! -f "$SCHEMA_BASE_PATH" ]; then
+  emit_log "spawn-failed sessionId=${ADMIN_SESSION_ID} reason=schema-base-missing path=${SCHEMA_BASE_PATH}"
+  exit 0
+fi
+if [ ! -f "$AGENT_BODY_PATH" ]; then
+  emit_log "spawn-failed sessionId=${ADMIN_SESSION_ID} reason=agent-body-missing path=${AGENT_BODY_PATH}"
+  exit 0
+fi
+
+# Brand-declared vertical (Task 193). Treated as null when brand.json is
+# absent, unparseable, lacks the field, or names a file that does not
+# exist — every one of those collapses to "schema-base only", never
+# loud-fails this hook. Task 193 itself is the loud-fail surface for
+# brand-config defects.
+VERTICAL_PATH=""
+if [ -f "$BRAND_JSON_PATH" ]; then
+  VERTICAL_NAME=$(python3 -c '
+import sys, json
+try:
+    with open(sys.argv[1]) as f:
+        b = json.load(f)
+    v = b.get("vertical")
+    print(v if isinstance(v, str) and v else "")
+except Exception:
+    print("")
+' "$BRAND_JSON_PATH")
+  if [ -n "$VERTICAL_NAME" ]; then
+    CANDIDATE="${PLATFORM_ROOT_RESOLVED}/plugins/memory/references/${VERTICAL_NAME}.md"
+    if [ -f "$CANDIDATE" ]; then
+      VERTICAL_PATH="$CANDIDATE"
+    fi
+  fi
+fi
+
+# One Python pass:
+#   - reads the agent file and strips the frontmatter to recover the
+#     paragraph (the literal four sentences with `{schema}` and
+#     `{conversation}` placeholders);
+#   - reads schema-base.md (and concatenates the vertical when set);
+#   - renders the envelope's `turns` array into a flat transcript — one
+#     line per turn, `role: text`, with inline `[tool: name(args)]`
+#     markers where the assistant called tools (so the model sees the
+#     tool-shape it has been calling without having to read JSON);
+#   - substitutes both placeholders in the paragraph;
+#   - emits one tab-separated line of byte counts, then the
+#     spawn-body JSON containing the filled paragraph as `initialMessage`.
+# The envelope rides through a tmpfile (not stdin) so the python script
+# can be sourced from the heredoc; the two stdin redirections would
+# otherwise collide and Python would see an empty envelope.
+ENVELOPE_FILE=$(mktemp)
+printf '%s' "$ENVELOPE" > "$ENVELOPE_FILE"
+COMBINED=$(python3 - \
+  "$AGENT_BODY_PATH" "$SCHEMA_BASE_PATH" "$VERTICAL_PATH" "$ADMIN_SESSION_ID" "$ENVELOPE_FILE" <<'PY'
 import sys, json
-sid = sys.argv[1]
-envelope_str = sys.argv[2]
-body = {
+
+agent_path, schema_path, vertical_path, sid, envelope_path = sys.argv[1:6]
+
+with open(agent_path, "r", encoding="utf-8") as f:
+    raw = f.read()
+parts = raw.split("---", 2)
+body_template = parts[2].lstrip("\n").rstrip() if len(parts) >= 3 else raw.rstrip()
+
+with open(schema_path, "r", encoding="utf-8") as f:
+    schema_text = f.read()
+if vertical_path:
+    with open(vertical_path, "r", encoding="utf-8") as f:
+        schema_text = schema_text.rstrip() + "\n\n" + f.read()
+
+with open(envelope_path, "r", encoding="utf-8") as f:
+    envelope = json.load(f)
+turns = envelope.get("turns") or []
+lines = []
+for t in turns:
+    role = t.get("role", "?")
+    text_t = t.get("text", "") or ""
+    marks = []
+    for tc in (t.get("toolCalls") or []):
+        tool = tc.get("tool", "?")
+        inp = tc.get("input")
+        try:
+            inp_s = json.dumps(inp, ensure_ascii=False) if inp is not None else ""
+        except Exception:
+            inp_s = str(inp)
+        marks.append(f"[tool: {tool}({inp_s})]")
+    if marks:
+        lines.append(f"{role}: {text_t} {' '.join(marks)}".rstrip())
+    else:
+        lines.append(f"{role}: {text_t}")
+# Wrap the transcript block in newlines so each turn lands on its own
+# line in the filled prompt — the template's `{conversation}` sits
+# mid-sentence, so the leading newline separates the first transcript
+# line from the surrounding prose, and the trailing newline separates
+# the last one from the closing `, using the tools at your disposal.`
+conversation_text = "\n" + "\n".join(lines) + "\n"
+
+filled = body_template.replace("{schema}", schema_text).replace("{conversation}", conversation_text)
+
+schema_bytes = len(schema_text.encode("utf-8"))
+conv_bytes = len(conversation_text.encode("utf-8"))
+body_bytes = len(filled.encode("utf-8"))
+
+spawn_body = {
   "adminSessionId": sid,
   "channel": "browser",
   "specialist": "database-operator",
   "model": "haiku",
-  "initialMessage": envelope_str,
+  "initialMessage": filled,
 }
-print(json.dumps(body))
-' "$ADMIN_SESSION_ID" "$ENVELOPE" 2>/dev/null)
 
-INITIAL_BYTES=$(printf '%s' "$ENVELOPE" | wc -c | tr -d ' ')
-emit_log "spawn-request sessionId=${ADMIN_SESSION_ID} specialist=database-operator initialMessageBytes=${INITIAL_BYTES}"
+print(f"{schema_bytes}\t{conv_bytes}\t{body_bytes}")
+print(json.dumps(spawn_body))
+PY
+)
+rm -f "$ENVELOPE_FILE"
+
+BYTES_LINE=$(printf '%s' "$COMBINED" | head -n1)
+SPAWN_BODY=$(printf '%s' "$COMBINED" | tail -n +2)
+IFS=$'\t' read -r SCHEMA_BYTES CONV_BYTES BODY_BYTES <<<"$BYTES_LINE"
+
+emit_log "substitution sessionId=${ADMIN_SESSION_ID} schemaBytes=${SCHEMA_BYTES} conversationBytes=${CONV_BYTES} bodyBytes=${BODY_BYTES}"
+emit_log "spawn-request sessionId=${ADMIN_SESSION_ID} specialist=database-operator initialMessageBytes=${BODY_BYTES}"
 
 SPAWN_RES_FILE=$(mktemp)
 SPAWN_HTTP=$(curl -sS -o "$SPAWN_RES_FILE" -w '%{http_code}' -X POST \

package/payload/platform/plugins/docs/references/admin-session.md

@@ -92,29 +92,32 @@ After every completed operator admin turn, the Stop hook `platform/plugins/admin
 Body overrides relative to a plain Sidebar click:
 - `specialist: 'database-operator'`
 - `model: 'haiku'`
-- `initialMessage: <json-envelope>` (string carrying a JSON-stringified object — see below)
+- `initialMessage: <filled-paragraph>` (the four-sentence database-operator template with `{schema}` and `{conversation}` substituted at hook time — see below)
 
 **Spawn body.** The hook POSTs `{adminSessionId, channel: 'browser', specialist: 'database-operator', model: 'haiku', initialMessage}` to `POST /api/admin/claude-sessions`. `adminSessionId` is the loopback-bypass key — the wrapper resolves the operator's real `senderId` from `GET <managerBase>/<adminSessionId>/meta` and forwards a Sidebar-shape body to the manager.
 
-**`initialMessage` JSON envelope (Task 177).** A single JSON object stringified to a string. The schema below is the authoritative contract — the database-operator agent file no longer carries it, so any change here is the only place the envelope shape moves:
+**`initialMessage` substitution contract (Task 195).** The agent body on disk is the user-specified four-sentence paragraph verbatim, with two placeholders `{schema}` and `{conversation}`:
 
 ```
-{
-  "turns": [
-    { "role": "user",      "text": "...", "ts": "<ISO-8601>" },
-    { "role": "assistant", "text": "...", "ts": "<ISO-8601>",
-      "toolCalls": [ { "tool": "...", "input": {...}, "output": ... } ] },
-    ...
-  ],
-  "conversationId": "<operator session_id>",
-  "accountId":      "<ACCOUNT_ID env, stamped on the manager systemd unit>",
-  "occurredAt":     "<hook fire time, ISO-8601 UTC, .000Z>"
-}
+You are an expert Neo4J graph operator. Here is the schema {schema}.
+Use your expert judgement to update the graph in reaction to the
+following conversation {conversation}, using the tools at your disposal.
+You are not user-facing and your text goes nowhere — do not emit it.
 ```
 
-`turns` is the operator's full conversation transcript, oldest first, newest last — every user / assistant message in the operator's JSONL from session start to the moment the recorder fired. No windowing, no truncation, no env knob. The walker collapses multi-record assistant messages on `message.id` (e.g. one `thinking` record + one `text` record from the same message become one `turns` entry with combined text). `toolCalls` is assistant-only and omitted on turns that called no tools. `toolCalls[].input` and `toolCalls[].output` are native JSON values, not re-stringified — `jq -r '.toolCalls[0].input.foo'` reaches the inner field directly. `tool_use` and `tool_result` blocks are paired by `tool_use_id` and attach to the assistant turn that owned the `tool_use`; the user record carrying only the `tool_result` does not create a separate user turn. Unanswered `tool_use` calls surface with `output: null`. No leading instruction prose — the agent file's system prompt teaches the model what to do with the payload. If `turns` is empty after the walker runs, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned. (Task 175's earlier `(operatorMessage, assistantReply)` pair contract was superseded — the pair asserted a temporal Q→A relationship the walker never enforced, so Task 177 replaced it with the ordered window.)
+At fire time the Stop hook substitutes both placeholders and sends the filled paragraph as `initialMessage` — a plain string, not a JSON envelope, no instruction prose, no leading object.
 
-The hook also emits one summary line per fire immediately before `spawn-request`: `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>`. `turnsCount` is monotone across spawns in the same operator session — a flat or decreasing series is the regression signature for "windowing crept back in".
+- `{schema}` ← the concatenated text of `platform/plugins/memory/references/schema-base.md` plus, when `brand.json#vertical` names a vertical file that exists in the same directory, that file's content joined with a blank-line separator (Task 193). When the brand declares `vertical: null`, the field is missing, or the named file is absent, the schema is `schema-base.md` alone — never loud-fail here; Task 193 owns the brand-config gate.
+- `{conversation}` ← a flat rendering of the envelope's `turns` array. Format: one line per turn, `role: text`, wrapped in leading and trailing newlines so each line lands on its own line in the filled prompt. Assistant turns that called tools carry inline `[tool: name(args)]` markers at the end of their line, with `args` being the call's input as a JSON literal. Tool outputs are not included — only the call shape the model has been emitting. The user record carrying only `tool_result` blocks does not create a separate transcript line; thinking-only records contribute nothing.
+
+The envelope walker still runs (so `[turn-recorder] envelope ...` continues to land for observability and the `trigger-skipped reason=conversation-empty` gate still fires on a turns-empty transcript), but its JSON shape never reaches the model.
+
+Walker semantics for `turns` (preserved from Task 177): oldest first, newest last; every user / assistant message in the operator's JSONL from session start to the moment the recorder fired; no windowing, no truncation, no env knob; multi-record assistant messages collapse on `message.id`; `tool_use` and `tool_result` blocks are paired by `tool_use_id` so the result attaches to the assistant turn that owned the call rather than fabricating a separate user turn; if `turns` is empty after the walker runs the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned. The Task 177 envelope shape — `{turns, conversationId, accountId, occurredAt}` — is now an internal hook structure; it is not what the model sees.
+
+The hook emits two summary lines per fire immediately before `spawn-request`:
+
+- `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` — the walker's output. `turnsCount` is monotone across spawns in the same operator session; a flat or decreasing series is the regression signature for "windowing crept back in".
+- `[turn-recorder] substitution sessionId=<op> schemaBytes=<n> conversationBytes=<n> bodyBytes=<n>` — the per-spawn substitution. `schemaBytes` covers schema-base plus any vertical concatenated. `bodyBytes` equals the trailing `initialMessageBytes` field on the next `spawn-request` line — the two log lines read the same number.
 
 **Manager-side specialist branches.** The recorder is the first specialist subagent that exercises the full specialist flag matrix:
 - The bundled `platform/templates/specialists/agents/database-operator.md` template is symlinked into `$CLAUDE_CONFIG_DIR/agents/database-operator.md` by the installer; without that link `claude --agent database-operator` silently falls back to the admin agent.
@@ -200,10 +203,11 @@ Three log-line shapes, all keyed on the same recorder `sessionId`, distinguish t
 ```
 
 - `[pty-spawn-tool-inventory]` (Task 178) measures the **framework** layer — the argv built and the MCP servers' published tools. Argv-tools count must be 11; mcp-listed-tools must be ≥ 11.
-- `[recorder-session-init]` (Task 183 — emitted by the JSONL tail in `claude-session-manager`) measures the **CLI/SDK** layer — what the SDK actually exposed to the model. The set difference `toolsArgvMissingFromExposed` is the Outcome A fingerprint:
+- `[recorder-session-init]` (Task 183 — emitted by the JSONL tail in `claude-session-manager`) measures the **CLI/SDK** layer — what the SDK actually exposed to the model. The `source=` field names the data path; `toolsArgvMissingFromExposed` is the Outcome A fingerprint:
+  - `source=system.init` / `command_permissions` / `deferred_tools_delta` ⇒ the SDK wrote an init record to the JSONL and the tail matched one of the three known shapes. The bridge-attached `--remote-control` mode writes `attachment.deferred_tools_delta`; the headless SDK init record (`system.subtype=init`) is what `claude -p --output-format=stream-json` modes write.
+  - `source=headless-argv-fallback` ⇒ Task 185 finding (2026-05-20): headless `claude --verbose` PTY mode (which the database-operator recorder uses) does **not** write any tool-list record to the JSONL — none of the three probe shapes ever appears. The tail falls back to the spawner's `--allowed-tools` argv as the exposed set, independently verified by `[pty-spawn-tool-inventory]`'s `exposed=` field. Treat this source identically to a positive JSONL match: the argv set is authoritative for headless spawns.
   - `toolsArgvMissingFromExposed=—` ⇒ all argv tools made it through; Outcome A is ruled out.
-  - Any non-`—` value enumerates the names the SDK dropped and is the diagnosis.
-  - `error=init-record-not-found probedTypes=system.init,command_permissions,deferred_tools_delta` ⇒ no init-shaped record was found in the JSONL by the time the first assistant turn landed. The miss itself is the observable; iterate the probe list against the live JSONL to learn the new record shape.
+  - Any non-`—` value enumerates the names the SDK dropped and is the diagnosis. Only meaningful when `source` is JSONL-derived; under `headless-argv-fallback` the exposed set equals argv by construction, so this field is always `—`.
 - `[recorder-turn]` measures the **model** layer — Haiku's verbatim words (`textHead`) and the tool names it actually called (`toolUseNames`). `toolUseNames=—` paired with `toolsArgvMissingFromExposed=—` is the Outcome B signature: tools present, model abstained.
 
 The three lines are emitted into `server.log` via the platform UI's `/api/admin/log-ingest` loopback route, so a single grep against `server.log` answers the question for any past, present, or future recorder spawn: