@rubytech/create-maxy-code 0.1.58 → 0.1.60

package/package.json

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

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

@@ -85,12 +85,12 @@ PY
 }
 
 run_hook() {
-  local role="$1"; local is_recorder="$2"; local stdin_json="$3"
+  local role="$1"; local specialist="$2"; local stdin_json="$3"
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   printf '%s' "$stdin_json" | \
     MAXY_SESSION_ROLE="$role" \
-    MAXY_IS_RECORDER="$is_recorder" \
+    MAXY_SPECIALIST="$specialist" \
     MAXY_UI_INTERNAL_PORT="$LISTENER_PORT" \
     bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
   HOOK_RC=$?
@@ -131,7 +131,7 @@ print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
 
 # --- Case 1: role != admin → trigger-skipped reason=role-not-admin -----
 : > "$REQ_LOG"
-run_hook "public" "0" "$ENVELOPE"
+run_hook "public" "" "$ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-1 rc=$HOOK_RC"
 [[ -z "$HOOK_STDERR" ]] || fail "case-1 stderr must be empty, got: $HOOK_STDERR"
 if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=role-not-admin$'; then
@@ -145,20 +145,20 @@ else
   pass "case-1 no recorder-spawn POST"
 fi
 
-# --- Case 2: MAXY_IS_RECORDER=1 → trigger-skipped reason=is-recorder ----
+# --- Case 2: MAXY_SPECIALIST=database-operator → trigger-skipped is-recorder ----
 : > "$REQ_LOG"
-run_hook "admin" "1" "$ENVELOPE"
+run_hook "admin" "database-operator" "$ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-2 rc=$HOOK_RC"
 [[ -z "$HOOK_STDERR" ]] || fail "case-2 stderr must be empty, got: $HOOK_STDERR"
 if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=is-recorder$'; then
-  pass "case-2 MAXY_IS_RECORDER=1 → trigger-skipped reason=is-recorder emitted"
+  pass "case-2 MAXY_SPECIALIST=database-operator → trigger-skipped reason=is-recorder emitted"
 else
   fail "case-2 expected trigger-skipped is-recorder, got: $(ingest_lines)"
 fi
 
 # --- Case 3: empty stdin → trigger-skipped reason=empty-stdin ------------
 : > "$REQ_LOG"
-run_hook "admin" "0" ""
+run_hook "admin" "" ""
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-3 rc=$HOOK_RC"
 if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=empty-stdin$'; then
   pass "case-3 empty stdin → trigger-skipped reason=empty-stdin emitted"
@@ -169,7 +169,7 @@ fi
 # --- Case 4: missing transcript_path → trigger-skipped missing-transcript -
 : > "$REQ_LOG"
 BAD_ENVELOPE=$(python3 -c 'import json,sys; print(json.dumps({"session_id": sys.argv[1]}))' "$OP_ID")
-run_hook "admin" "0" "$BAD_ENVELOPE"
+run_hook "admin" "" "$BAD_ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-4 rc=$HOOK_RC"
 if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=missing-transcript$"; then
   pass "case-4 missing transcript → trigger-skipped reason=missing-transcript emitted"
@@ -179,7 +179,7 @@ fi
 
 # --- Case 5: happy path -------------------------------------------------
 : > "$REQ_LOG"
-run_hook "admin" "0" "$ENVELOPE"
+run_hook "admin" "" "$ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-5 rc=$HOOK_RC stderr=$HOOK_STDERR"
 [[ -z "$HOOK_STDERR" ]] || fail "case-5 stderr must be empty, got: $HOOK_STDERR"
 
@@ -200,8 +200,10 @@ else
   fail "case-5b expected exactly 1 recorder-spawn POST, got $RECORDER_LINES"
 fi
 
-# 5c. recorder-spawn body has originatingSessionId == operator id; initialMessage
-#     equals "<instruction>\n\n<last-turn-text>" verbatim. No transcript prose.
+# 5c. Sidebar-shape body with three overrides (specialist, model,
+#     initialMessage); adminSessionId carries the operator's session id as
+#     the loopback-bypass lookup key. No senderId on the wire (the wrapper
+#     resolves it from the manager's /meta).
 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
@@ -212,30 +214,39 @@ try:
   b = json.load(sys.stdin)
   msg = b.get("initialMessage") or ""
   conds = (
-    # Task 134: no synthetic senderId marker — loopback bypass is
-    # method+path-scoped; the body only carries the recorder discriminators.
     "senderId" not in b,
     b.get("specialist") == "database-operator",
-    b.get("originatingSessionId") == op,
+    b.get("model") == "haiku",
+    b.get("adminSessionId") == op,
+    b.get("channel") == "browser",
     msg == INSTRUCTION + "\n\n" + EXPECTED_LAST,
     "Conversation id:" not in msg,
     "Conversation transcript:" not in msg,
+    "originatingSessionId" not in b,
   )
   print("yes" if all(conds) else "no:"+repr(conds)+"|msg="+repr(msg))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' "$OP_ID" 2>/dev/null)
 if [[ "$BODY_OK" == "yes" ]]; then
-  pass "case-5c recorder-spawn body carries originatingSessionId + verbatim instruction + last-turn text"
+  pass "case-5c body is Sidebar-shape with three overrides (specialist, model, initialMessage)"
 else
   fail "case-5c body shape wrong ($BODY_OK): $RECORDER_BODY"
 fi
 
-# 5d. no legacy stderr emissions
+# 5d. exactly ONE `spawn-request` log-ingest line
+SPAWN_REQ_COUNT=$(ingest_lines | grep -cE "^spawn-request sessionId=${OP_ID} specialist=database-operator initialMessageBytes=[0-9]+$" || true)
+if [[ "$SPAWN_REQ_COUNT" -eq 1 ]]; then
+  pass "case-5d exactly one spawn-request line emitted"
+else
+  fail "case-5d expected 1 spawn-request, got $SPAWN_REQ_COUNT (lines: $(ingest_lines))"
+fi
+
+# 5e. no legacy stderr emissions
 if echo "$HOOK_STDERR" | grep -qE 'spawn-with-input|spawn-with-stdin|turn-completed-graph-write fired'; then
-  fail "case-5d legacy stderr line emitted: $HOOK_STDERR"
+  fail "case-5e legacy stderr line emitted: $HOOK_STDERR"
 else
-  pass "case-5d no legacy stderr emissions"
+  pass "case-5e no legacy stderr emissions"
 fi
 
 # --- Case 6 (Task 131): transcript has no assistant/user text → ---------
@@ -248,7 +259,7 @@ import json, sys
 print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
 ' "$OP_ID" "$EMPTY_TRANSCRIPT")
 : > "$REQ_LOG"
-run_hook "admin" "0" "$EMPTY_ENVELOPE"
+run_hook "admin" "" "$EMPTY_ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-6 rc=$HOOK_RC"
 if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=last-turn-empty$"; then
   pass "case-6 empty last-turn text → trigger-skipped reason=last-turn-empty emitted"

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

@@ -4,41 +4,26 @@
 # text. The recorder is the only writer to the Neo4j graph; the admin agent
 # stays focused on the operator's request.
 #
-# Task 134 — the four-step per-turn process is:
-#   1. New admin session is spawned the SAME way a Sidebar "New session"
-#      click spawns one — same route (`POST /api/admin/claude-sessions`,
-#      the one Sidebar hits), same payload schema. The wrapper bypasses
-#      cookie auth on this exact path when the request originates from
-#      127.0.0.1; the body carries `originatingSessionId` and
-#      `specialist: 'database-operator'`, and the wrapper looks up the
-#      operator's senderId from `/<originatingSessionId>/meta`. The
-#      Task-122-era `/recorder-spawn` sibling route is gone.
-#   2. The spawned session's specialist is `database-operator`.
-#   3. The initial message is the OPERATOR'S LAST TURN, prefixed with the
-#      literal instruction
-#        "update the graph with any new or missing information or intent"
-#      followed by a blank line. No transcript tail, no `Conversation id:`
-#      prose — both removed in Task 131. The recorder reads only this one
-#      most-recent turn.
-#   4. When the recorder's turn ends (`stop_reason:"end_turn"` lands in
-#      the recorder JSONL), the manager posts `/<sid>/stop`, claude exits,
-#      the fs-watcher observes the PID-file removal, and the row leaves
-#      the index. No reaper involvement on the success path.
+# Task 147 — the recorder spawn is byte-for-byte equivalent to a Sidebar
+# "New session" body, with three overrides:
+#   - specialist:     "database-operator"
+#   - model:          "haiku"
+#   - initialMessage: "update the graph with any new or missing information
+#                     or intent\n\n<last-turn-text>"
+# It POSTs to the SAME route the Sidebar uses
+# (`POST /api/admin/claude-sessions`). The wrapper accepts the loopback
+# request without a cookie, resolves the operator's `senderId` from the
+# manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn
+# body. No recorder-only carving on the manager side.
 #
-# Task 129 — every emit goes through the platform's `/api/admin/log-ingest`
-# endpoint (loopback-only). Hook stderr is silent on the success path.
-# Every line carries the operator's `sessionId=<op>` so one grep against
-# `server.log` returns the whole chain. The `originatingSessionId` is
-# posted as a top-level field of the spawn body; the wrapper reads it,
-# resolves the operator's account from it, and forwards a Sidebar-shape
-# spawn body to the manager.
-#
-# Gating (emits a `trigger-skipped` line, no longer a silent exit 0):
-#   - MAXY_SESSION_ROLE must equal "admin"  → reason=role-not-admin
-#   - MAXY_IS_RECORDER must NOT equal "1"   → reason=is-recorder
-#   - Stop-hook stdin must be non-empty     → reason=empty-stdin
-#   - transcript_path must exist on disk    → reason=missing-transcript
-#   - a most-recent assistant or user turn  → reason=last-turn-empty
+# Gating (emits a `trigger-skipped` line via `/api/admin/log-ingest`;
+# stderr stays silent on the success path):
+#   - MAXY_SESSION_ROLE must equal "admin"        → reason=role-not-admin
+#   - MAXY_SPECIALIST must NOT equal              → reason=is-recorder
+#     "database-operator"   (recursion guard)
+#   - Stop-hook stdin must be non-empty           → reason=empty-stdin
+#   - transcript_path must exist on disk          → reason=missing-transcript
+#   - a most-recent assistant or user turn        → reason=last-turn-empty
 #     must be extractable from the JSONL
 #
 # Input: Claude Code's Stop hook stdin shape
@@ -46,12 +31,6 @@
 
 set -uo pipefail
 
-# UI listener port is stamped on the claude-session-manager systemd unit
-# as `Environment=MAXY_UI_INTERNAL_PORT=<port>` (Task 134). Absence is a
-# structural defect — historically the hook fell back to 19199 with no
-# listener on most devices and silently swallowed connection-refused. Now
-# it short-circuits with a named diagnostic to stderr (the only sink the
-# log-ingest endpoint itself depends on this var to reach).
 UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
 if [ -z "$UI_PORT" ]; then
   echo "[turn-recorder] spawn-failed sessionId=unknown reason=missing-env env=MAXY_UI_INTERNAL_PORT" >&2
@@ -60,10 +39,6 @@ fi
 UI_BASE="http://127.0.0.1:${UI_PORT}"
 LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
 
-# Emit one log line via the platform's log-ingest endpoint. Best-effort:
-# a failed POST does not break the hook — but the absence of the line is
-# itself a system-level defect per Task 129 §157. We do NOT fall back to
-# stderr, because stderr never reaches server.log.
 emit_log() {
   local line="$1"
   curl -sS -o /dev/null -X POST \
@@ -76,8 +51,6 @@ print(json.dumps({"tag": "turn-recorder", "level": "info", "line": sys.argv[1]})
     "$LOG_INGEST_URL" 2>/dev/null || true
 }
 
-# Parse stdin first so trigger-skipped lines can carry the operator
-# session id (when present). Stop-hook stdin is required.
 INPUT=""
 if [ -t 0 ]; then
   INPUT=""
@@ -98,20 +71,14 @@ except Exception:
 ADMIN_SESSION_ID="${PARSED%%	*}"
 TRANSCRIPT_PATH="${PARSED#*	}"
 
-# Gate ordering — each gate gets a distinct trigger-skipped reason so the
-# operator-ID-keyed grep can tell why a given turn did not record. Role
-# gate fires first because non-admin invocations may have no operator id
-# at all (the field is empty for public/recorder).
 if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
   emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=role-not-admin"
   exit 0
 fi
-# Task 131 — the recorder gate is now MAXY_IS_RECORDER (set to '1' by the
-# pty-spawner whenever a spawn carries `originatingSessionId`). The prior
-# MAXY_HIDDEN_SPAWN gate conflated UI visibility with recorder identity;
-# with hidden=false on recorder spawns now, the dedicated env var is the
-# only correct discriminator against hook-recursion.
-if [ "${MAXY_IS_RECORDER:-0}" = "1" ]; then
+# Recursion guard. The recorder spawn carries
+# `specialist=database-operator`; pty-spawner stamps MAXY_SPECIALIST on the
+# PTY env. Skip recording the recorder's own turn.
+if [ "${MAXY_SPECIALIST:-}" = "database-operator" ]; then
   emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=is-recorder"
   exit 0
 fi
@@ -124,14 +91,7 @@ if [ -z "$ADMIN_SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIP
   exit 0
 fi
 
-# Extract the operator's most-recent turn text from the JSONL. The single
-# rule (no fallbacks beyond the assistant→user pair) is:
-#   - the most-recent `assistant` record whose message.content yields any
-#     extractable text, OR
-#   - if no assistant record produces text, the most-recent `user` record
-#     that produces text.
-# Tool-call blocks, system records, and ephemeral admin-state records are
-# never the candidate. Empty output → reason=last-turn-empty.
+# Extract the operator's most-recent turn text from the JSONL.
 LAST_TURN_TEXT=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
 import sys, json
 
@@ -179,10 +139,6 @@ PY
 LAST_TURN_BYTES=$(printf '%s' "$LAST_TURN_TEXT" | wc -c | tr -d ' ')
 TRANSCRIPT_BYTES=$(wc -c <"$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ' || echo 0)
 
-# Step 0 — trigger line. First link in the chain the operator-ID-keyed
-# grep returns. Task 131: replaced `filteredRecords=<n>` with
-# `lastTurnBytes=<n>` because the hook no longer ships a filtered
-# transcript tail.
 emit_log "trigger sessionId=${ADMIN_SESSION_ID} turnIndex=0 transcriptBytes=${TRANSCRIPT_BYTES} lastTurnBytes=${LAST_TURN_BYTES}"
 
 if [ -z "$LAST_TURN_TEXT" ]; then
@@ -190,17 +146,10 @@ if [ -z "$LAST_TURN_TEXT" ]; then
   exit 0
 fi
 
-# Compose the recorder spawn body. Task 134:
-#   - `initialMessage` = literal instruction + "\n\n" + last-turn text.
-#     Verbatim instruction wording (no trailing qualifier, includes "new").
-#   - `originatingSessionId` carries the operator's session id; the
-#     wrapper looks up the operator's real senderId from
-#     `/<originatingSessionId>/meta` and forwards a Sidebar-shape spawn
-#     body to the manager. No synthetic `senderId: 'turn-recorder'`
-#     marker — the loopback bypass is method+path-scoped.
-#   - `specialist: 'database-operator'` discriminates the recorder spawn
-#     from a vanilla Sidebar click.
-#   - No `Conversation id:` prose; no transcript-tail JSON.
+# 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 '
 import sys, json
 sid = sys.argv[1]
@@ -208,13 +157,18 @@ last_turn = sys.argv[2]
 instruction = "update the graph with any new or missing information or intent"
 text = instruction + "\n\n" + last_turn
 body = {
+  "adminSessionId": sid,
+  "channel": "browser",
   "specialist": "database-operator",
+  "model": "haiku",
   "initialMessage": text,
-  "originatingSessionId": sid,
 }
 print(json.dumps(body))
 ' "$ADMIN_SESSION_ID" "$LAST_TURN_TEXT" 2>/dev/null)
 
+INITIAL_BYTES=$(printf '%s\n\n%s' "update the graph with any new or missing information or intent" "$LAST_TURN_TEXT" | wc -c | tr -d ' ')
+emit_log "spawn-request sessionId=${ADMIN_SESSION_ID} specialist=database-operator initialMessageBytes=${INITIAL_BYTES}"
+
 SPAWN_RES_FILE=$(mktemp)
 SPAWN_HTTP=$(curl -sS -o "$SPAWN_RES_FILE" -w '%{http_code}' -X POST \
   -H 'Content-Type: application/json' \
@@ -222,21 +176,12 @@ SPAWN_HTTP=$(curl -sS -o "$SPAWN_RES_FILE" -w '%{http_code}' -X POST \
   --data "$SPAWN_BODY" \
   "${UI_BASE}/api/admin/claude-sessions" 2>/dev/null || echo 000)
 
-# The wrapper emits the named `spawn-request` / `spawn-success` /
-# `input-delivered` lines itself. The hook only emits the hook-side
-# failure variant — `loopback-http` — and even then only when the wrapper
-# returned a non-2xx that is NOT one of the preflight reasons (those are
-# logged by the manager before the wrapper sees them).
 RES_BODY=$(cat "$SPAWN_RES_FILE" 2>/dev/null || true)
 rm -f "$SPAWN_RES_FILE"
 
 if [ "$SPAWN_HTTP" -lt 200 ] || [ "$SPAWN_HTTP" -ge 300 ]; then
   ERR_SHORT=$(printf '%s' "$RES_BODY" | tr -d '\r\n' | cut -c1-200)
-  if printf '%s' "$RES_BODY" | grep -q '"error":"tool-surface-missing"\|"error":"missing-originating-session-id"\|"error":"originating-session-id-required"\|"error":"originating-session-not-found"'; then
-    : # preflight or lookup already named the failure
-  else
-    emit_log "spawn-failed sessionId=${ADMIN_SESSION_ID} reason=loopback-http http=${SPAWN_HTTP} err=$(python3 -c 'import sys,json; print(json.dumps(sys.argv[1]))' "${ERR_SHORT}")"
-  fi
+  emit_log "spawn-failed sessionId=${ADMIN_SESSION_ID} reason=loopback-http http=${SPAWN_HTTP} err=$(python3 -c 'import sys,json; print(json.dumps(sys.argv[1]))' "${ERR_SHORT}")"
 fi
 
 exit 0

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

@@ -77,32 +77,33 @@ grep '\[client-acquire\]' ~/.${brand}/logs/claude-agent-stream-*.log
 
 The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/admin/claude-sessions.ts`](../../../ui/server/routes/admin/claude-sessions.ts) is the single canonical entry point for any caller — UI click handler or programmatic — that needs to open an admin PTY session with a first user prompt. Direct calls to the session-manager's `/spawn` and `/:id/input` are not allowed; the wrapper owns the spawn-then-input ordering, the per-spawn enrichment (`aboutOwner`, `dormantPlugins`, `activePlugins`, `specialistDomains`, `tunnelUrl`), and the `senderId` resolution from the admin session cookie. The session manager binds to `127.0.0.1` only so the wrapper is the sole authorised caller; any ad-hoc spawn that bypasses it duplicates this contract and is a bug.
 
-**Body schema.** `{channel?, permissionMode?, initialMessage?}` for operator-driven UI spawns (cookie path — `senderId` resolved from the admin session cookie, `hidden: false`, no `specialist`). The recorder hook posts the loopback variant: `{specialist:'database-operator', initialMessage, originatingSessionId, channel?}` — no synthetic `senderId` marker. The wrapper rejects nothing structurally — string fields are coerced or defaulted (`channel` → `'browser'`, `permissionMode` → undefined, `initialMessage` → null if empty/whitespace) and the session manager validates the rest downstream. The loopback branch refuses the request with `400 originating-session-id-required` if `originatingSessionId` is missing or non-UUID, and `404 originating-session-not-found` if the manager has no StoredSession for it.
+**Body schema.** `{channel?, permissionMode?, initialMessage?, specialist?, model?}` for the cookie path (Sidebar — `senderId` resolved from the admin session cookie, `hidden: false`). The Stop-hook loopback caller adds `adminSessionId` and uses three overrides: `specialist: 'database-operator'`, `model: 'haiku'`, plus `initialMessage`. The wrapper rejects nothing structurally on the cookie path — string fields are coerced or defaulted (`channel` → `'browser'`, `permissionMode` → undefined, `initialMessage` → null if empty/whitespace). The loopback path refuses with `400 admin-session-id-required` if `adminSessionId` is missing or non-UUID, and `404 admin-session-not-found` if the manager has no StoredSession for it.
 
-**Auth surfaces.** Two: `cookie` (Sidebar — `requireAdminSession` validates `session_key` from query/body/multipart and resolves `senderId` from the in-memory session store) and `loopback` (recorder hook — `requireAdminSessionUnlessLoopbackSpawn` skips cookie auth when method is `POST`, path is exactly `/api/admin/claude-sessions`, the TCP peer is `127.0.0.1`/`::1`, **and** the request carries no `x-forwarded-for` header; the handler then looks up the operator's `senderId` from `GET {managerBase}/<originatingSessionId>/meta`). The XFF check distinguishes a real in-process recorder hook from a browser request that traversed `maxy-edge`'s reverse proxy and arrived on loopback with `peer=127.0.0.1` — same idiom `requestIsTlsTerminated` uses to disambiguate proxied vs direct TLS. Without the XFF gate, every edge-proxied "+ New session" click would mis-fire the bypass and 400 with `originating-session-id-required` (Task 143). Same trust boundary the claude-session-manager itself relies on — both bind 127.0.0.1 only. The Task-122-era `POST /recorder-spawn` sibling route is gone (Task 134). One route, one shape, two surfaces.
+**Auth surfaces.** Two: `cookie` (Sidebar — `requireAdminSession` validates `session_key` and resolves `senderId` from the in-memory session store) and `loopback` (Stop hook — `requireAdminSessionOrLoopback` skips cookie auth when method is `POST`, path is exactly `/api/admin/claude-sessions`, and the TCP peer is `127.0.0.1`/`::1`; the handler then resolves the operator's `senderId` from `GET {managerBase}/<adminSessionId>/meta`). Both the manager and the UI server bind to `127.0.0.1` only for internal traffic, so the trust boundary is reachable only from a process running on the device. Task 147 — one route, one body shape (the loopback variant differs only by overrides), no `/recorder-spawn` sibling, no XFF disambiguation.
 
 **Forwarded endpoints.** Two upstream calls per spawn-with-message: `POST {managerBase}/spawn` (enriched body) returns `{sessionId}`; when `initialMessage` is set, the wrapper then issues `POST {managerBase}/<sessionId>/input { text: <initialMessage> }` synchronously so the PTY has its first turn stimulus before the operator types. The HTTP response streams the spawn upstream body straight through.
 
-**Callers.** `Sidebar.tsx`'s "+ New session" click handler (sends the current ISO-8601 UTC timestamp as `initialMessage` — see `platform.md` "Spawn lifecycle: PID-file driven"); the turn-recorder hook (loopback path — see "Turn-recorder" below); future programmatic spawns. Every caller routes through this wrapper. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=<cookie|loopback>` log line followed by `forward-spawn-done`.
+**Callers.** `Sidebar.tsx`'s "+ New session" click handler (sends no `initialMessage` — Task 146 made Claude Code's own label canonical, so no UI-side stimulus is injected); the turn-recorder hook (loopback path — see "Turn-recorder" below); future programmatic spawns. Every caller routes through this wrapper. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=<cookie|loopback>` log line followed by `forward-spawn-done`.
 
-## Turn-recorder: the four-step per-turn process
+## Turn-recorder: a Sidebar-equivalent spawn with three overrides
 
-After every completed operator admin turn, the Stop hook `platform/plugins/admin/hooks/turn-completed-graph-write.sh` dispatches one headless `database-operator` session to record any new or missing information from that turn into the Neo4j graph. Exactly four things happen — any deviation is a fault (2026-05-18 doctrine fix).
+After every completed operator admin turn, the Stop hook `platform/plugins/admin/hooks/turn-completed-graph-write.sh` dispatches one headless `database-operator` session that writes any new or missing information from the turn into the Neo4j graph. Task 147 — the recorder spawn is byte-for-byte equivalent to a Sidebar "New session" body, with three overrides:
 
-1. **A new admin session is spawned the SAME way a Sidebar "New session" click spawns one.** The hook POSTs to `POST /api/admin/claude-sessions` — the exact same route the Sidebar uses. The Hono wrapper bypasses cookie auth via `requireAdminSessionUnlessLoopbackSpawn` on this exact method+path when the TCP peer is `127.0.0.1` **and** the request carries no `x-forwarded-for` header (the recorder is in-process; the edge proxy unconditionally stamps XFF on every browser request — Task 143). The body the hook sends carries only `{specialist:'database-operator', initialMessage, originatingSessionId, channel:'browser'}` — no synthetic `senderId` marker (Task 134 removed it; the loopback bypass is method+path-scoped). The wrapper resolves the operator's real `senderId` from `originatingSessionId` via `GET <managerBase>/<originatingSessionId>/meta`, then forwards a Sidebar-shape body to the manager: real operator `senderId`, `hidden: false`, `channel: 'browser'`, `role: 'admin'`, plus `specialist` and `originatingSessionId`. `aboutOwner` resolves against the operator's account; the recorder appears in the operator's sidebar as a sibling session of the originating one. `userId` is not exposed via `/meta` and is left undefined — `aboutOwner` falls through to senderId-only resolution, which returns the operator's account profile and is adequate for the recorder's single-turn lifecycle.
-2. **The spawned session's specialist is `database-operator`.**
-3. **The initial message is the operator's last turn, prefixed by a literal instruction.** Format:
-   ```
-   update the graph with any new or missing information or intent
+- `specialist: 'database-operator'`
+- `model: 'haiku'`
+- `initialMessage: "update the graph with any new or missing information or intent\n\n<last-turn-text>"`
 
-   <last-turn-text>
-   ```
-   The instruction wording is verbatim, with no trailing qualifier. `<last-turn-text>` is the most recent `assistant` record's text content from the operator JSONL, or — if no assistant record yields text — the most recent `user` record's text. Tool-call blocks, system records, and ephemeral admin-state records are never the candidate. If neither yields text, the hook emits `trigger-skipped reason=last-turn-empty` and no recorder is spawned. No transcript tail. No `Conversation id:` prose. The structural carrier of the operator session id is the spawn-body field `originatingSessionId`, not anything inside the message.
-4. **On end_turn the recorder's PID file is removed.** When the recorder's JSONL gains an assistant message with `stop_reason: "end_turn"`, the manager posts `/<recorder-sid>/stop`, claude exits, the fs-watcher observes the PID-file removal and drops the row from the index. The reaper never fires on the success path; it exists only as the safety net for recorders that error without exiting.
+There is no recorder-only carving on the manager side: no preflight, no tool-surface gate, no `originatingSessionId` discriminator, no `MAXY_IS_RECORDER` env stamp, no recorder-only log surfaces. The PTY's own first-use error is the contract for tool absence.
 
-**Recorder discriminator inside the manager.** Recorder detection (auto-archive, reaper bypass, recorder-tally accumulation, the `MAXY_IS_RECORDER` env stamp for the Stop hook's recursion gate) keys on `originatingSessionId` presence — the one field set only for recorder spawns. The legacy `senderId === 'turn-recorder'` discriminator was retired in 2026-05-18 doctrine fix because the wrapper now resolves the operator's accountId for Sidebar-shape parity. The recorder's spawn env carries `MAXY_IS_RECORDER=1` (alongside `MAXY_SESSION_ROLE=admin` and `MAXY_HIDDEN_SPAWN=0`); the Stop hook gates on the dedicated `MAXY_IS_RECORDER` variable to break what would otherwise be an infinite recursion (the recorder's own end-of-turn re-firing the Stop hook).
+**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.
 
-**Observability.** Every recorder line carries `sessionId=<operator-sid>` so `grep -F "<op>" ~/.<brand>/logs/server.log` returns the four-step chain. The `trigger` line carries `lastTurnBytes=<n>` (2026-05-18 doctrine fix; replaces the prior `filteredRecords=<n>` from when the hook shipped a filtered transcript tail). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | last-turn-empty`. The wrapper's preflight rejections emit `[turn-recorder] spawn-failed sessionId=<op> reason=…` with `missing-originating-session-id | originating-session-not-found | manager-spawn`.
+**`<last-turn-text>`** is the most recent `assistant` record's text content from the operator JSONL, or — if no assistant record yields text — the most recent `user` record's text. Tool-call blocks, system records, and ephemeral admin-state records are never the candidate. If neither yields text, the hook emits `trigger-skipped reason=last-turn-empty` and no recorder is spawned.
+
+**End-of-turn auto-archive.** When any session whose specialist is `database-operator` gains an assistant message with `stop_reason: "end_turn"` in its JSONL, the manager posts `/<sid>/stop` against itself, claude exits, the fs-watcher observes the PID-file removal and drops the row from the index. The auto-archive log line is `auto-archive sessionId=<sid> specialist=database-operator reason=end-turn …`.
+
+**Hook recursion gate.** `pty-spawner` stamps `MAXY_SPECIALIST=<specialist>` on every PTY env. The Stop hook short-circuits when `MAXY_SPECIALIST=database-operator` so the recorder's own end-of-turn does not re-fire the hook.
+
+**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> lastTurnBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | last-turn-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
 
 ## Session identifiers (Task 135)
 

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

@@ -80,11 +80,11 @@ The row feed sits behind `requireAdminSession` like every other admin route, so
 
 The trade-off is a longer-lived connection per tab: the manager's per-process subscriber count rises with open tabs, and the SSE channel must survive proxy idle timeouts. The manager emits a 25-second keep-alive comment line on every connection (ignored by EventSource consumers, refreshes the proxy clock) and the browser-side store force-closes-and-reconnects on transport errors with exponential backoff capped at 30s.
 
-**Spawn lifecycle: PID-file driven.** Clicking "+ New session" spawns the PTY and waits for Claude Code's PID file to appear at `${CLAUDE_CONFIG_DIR}/sessions/<pid>.json`. The PID file lands at process init (for `entrypoint: cli` spawns) and carries the intrinsic `sessionId`, `bridgeSessionId`, `agent`, and `status` directly. The manager's filesystem watcher reports the create event; the spawn response includes the canonical `sessionId` from that file. URL capture still runs in parallel to populate the operator-facing iframe URL, but it no longer gates readiness. The JSONL transcript is written on the first operator turn (true on 2.1.143 and 2.1.128); the watcher fires a separate event for that, and `/list`, `/meta`, `/log` resolve any of four ids — `sessionId`, `bridgeSessionId`, `bridgeSuffix`, or numeric `pid` — to the same row. Every fresh spawn also injects a first user turn so the agent has the stimulus the CLI needs to emit its first reply: the Sidebar's POST body carries `initialMessage` set to a brand-stamped session label of the form `{{productName}} Session DD/MMM/YY HH:MM:SS` (local device time, 24-hour clock, three-letter month, two-digit year — e.g. `Maxy Session 18/May/26 13:15:45` or `Real Agent Session 18/May/26 13:15:45`), computed at click-time on the client. The server forwards it as `POST /<id>/input { text }` immediately after the spawn returns. The label is non-directive descriptive metadata — the agent reads it as "begin", not as a directive to do something — preserving the Task 104 minimum-information-opener invariant. The wrapper at `platform/ui/server/routes/admin/claude-sessions.ts` is the single canonical entry point for any programmatic admin spawn-with-prompt — see `admin-session.md` "Spawn-with-initialMessage wrapper" and `internals.md` "Programmatic spawn entry point". Resume flows are unaffected (the prior transcript is the stimulus). Out of scope here: the *content* of the agent's reply, which is owned by the orchestrator's greeting rules.
+**Spawn lifecycle: PID-file driven.** Clicking "+ New session" spawns the PTY and waits for Claude Code's PID file to appear at `${CLAUDE_CONFIG_DIR}/sessions/<pid>.json`. The PID file lands at process init (for `entrypoint: cli` spawns) and carries the intrinsic `sessionId`, `bridgeSessionId`, `agent`, and `status` directly. The manager's filesystem watcher reports the create event; the spawn response includes the canonical `sessionId` from that file. URL capture still runs in parallel to populate the operator-facing iframe URL, but it no longer gates readiness. The JSONL transcript is written on the first operator turn (true on 2.1.143 and 2.1.128); the watcher fires a separate event for that, and `/list`, `/meta`, `/log` resolve any of four ids — `sessionId`, `bridgeSessionId`, `bridgeSuffix`, or numeric `pid` — to the same row. The Sidebar POST body carries no `initialMessage` (Task 146): Claude Code's own `tail.aiTitle` is the canonical sidebar row label, and the wrapper does not inject any cold-start stimulus on operator-driven spawns. The wrapper at `platform/ui/server/routes/admin/claude-sessions.ts` is still the single canonical entry point for any programmatic admin spawn-with-prompt — see `admin-session.md` "Spawn-with-initialMessage wrapper" and `internals.md` "Programmatic spawn entry point" — and the turn-recorder loopback path still forwards an `initialMessage`. Resume flows are unaffected (the prior transcript is the stimulus).
 
-Immediately after the spawn POST returns, the Sidebar fires a `PATCH /api/admin/claude-sessions/<id>` with the same brand-stamped label as `displayName`, writing the manager's session sidecar deterministically. The sidebar row label resolution precedence is `sidecar.displayName → tail.aiTitle → 8-char id` (see `jsonl-enumerator.ts`), so the auto-stamped sidecar wins over Claude Code's `aiTitle` heuristic (which uniformly emits "New coding session" regardless of the first turn). A manual rename via the row's Rename modal overwrites the sidecar and continues to win — auto-stamp only fires on cold-start, never on resume. The auto-stamp PATCH logs `sidecar-displayname-stamped sessionId=<8-prefix> displayName=<value>` server-side when the sidecar was previously empty; manual renames log only the existing `rename sessionId=… from=… to=…` line. A 404 from the watcher-indexing race retries once after 250ms and then soft-fails (the session itself is unaffected; only the auto-label is missing — the row label falls back to the `aiTitle` / id chain).
+The sidebar row's displayed name is `tail.aiTitle` verbatim, parsed by `jsonl-enumerator.ts` from the JSONL Claude Code writes. Until Claude Code has written its title, the row label is null and the cell renders empty — no UI-stamped sidecar layer, no 8-char id fallback. When Claude Code later updates its title mid-session, the next `/list` or `/events` tick surfaces the new label. Task 146.
 
-**Stop vs. delete.** `POST /<id>/stop` sends SIGTERM, leaves the JSONL on disk for audit, and is idempotent against an already-dead row. `DELETE /<id>` removes the JSONL + sidecar + per-session subdir and returns 409 if the PTY is still alive (stop first). Any unknown id returns 404; nothing returns a silent 204 against an id the manager does not know.
+**Stop vs. delete.** `POST /<id>/stop` sends SIGTERM, leaves the JSONL on disk for audit, and is idempotent against an already-dead row. `DELETE /<id>` removes the JSONL + per-session subdir and returns 409 if the PTY is still alive (stop first). Any unknown id returns 404; nothing returns a silent 204 against an id the manager does not know.
 
 The metadata pane subscribes to the same /list projection. When an operator clicks End on an alive row, the DELETE returns 200 and the post-mutation refetch decides what happens next: a session that wrote a JSONL surfaces as a dehydrated `status: 'ended'` row (the pane swaps `End session` for `Purge JSONL` plus `Resume`), and a session that never wrote a JSONL (`Turns: 0`) leaves the list entirely (the pane shows a `Session ended without a transcript. Close this pane.` banner with a Close button and no destructive action). The manager's `/list` and `/meta` are the only authorities on post-End state; the client does not pre-empt either response with an optimistic mutation.
 

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

@@ -73,7 +73,7 @@ Brand decides which premium plugins ship. Maxy installs ship only `platform/plug
 | Plugin | Type | What it does | Public agent |
 |--------|------|-------------|-------------|
 | `teaching` | Skills | Interactive tutoring, lesson planning, and study pack generation from your knowledge base | Yes — all 3 skills serve students and parents |
-| `real-agent` | Bundle (10 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM (five value pillars: auto-respond, viewing lifecycle, pipeline mining, listings prospecting, maintenance & preferences), property brochures, social-share image cards, and A4 market reports. 3 specialist roles (negotiator, valuer, compliance) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching) |
+| `real-agent` | Bundle (12 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM (five value pillars: auto-respond, viewing lifecycle, pipeline mining, listings prospecting, maintenance & preferences), PropertyData market analytics (valuation, sold prices, £/sqft baselines, £/sqft growth, demand-rent, area risk, planning precedent, UPRN matching, property-type distribution), property brochures, social-share image cards, A4 market reports, and single-address preval packs (full UK address → 4-page A4 PDF covering valuation, area, and demand). 3 specialist roles (negotiator, valuer, compliance) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching) |
 | `writer-craft` | Skills + Agent | Manuscript review and writing craft — story architecture, reader engagement, prose craft, editorial practice, and multi-level review | No — writing craft serves the author |
 
 **How it works:** Every boot {{productName}} delivers the brand's premium plugins from staging into `platform/plugins/` and stamps `enabledPlugins` against what is actually on disk. No conversation needed — the brand's full set is active from the first turn after install. Updates and reinstalls re-deliver from staging.

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

@@ -116,7 +116,19 @@ Keys default to all 8 groups. Restrict at registration time to limit what the ag
 
 ## Security
 
-Never include API key values in responses. Identify teams by name only. When the user asks for a key value, explain that keys are encrypted and cannot be retrieved — they must be re-registered from Loop's dashboard.
+Never include API key values in responses. Identify teams by name only. When the user asks for a key value, explain that keys are encrypted and cannot be retrieved — they must be re-registered from Loop's dashboard. Keys are encrypted with AES-256-GCM; the encryption-key file lives at `~/<configDir>/.loop-encryption-key` (platform mode) or `~/.claude/.realagent-loop-encryption-key` (standalone mode), both mode `0600`.
+
+## Standalone mode (`~/.claude/` spawn)
+
+The same `mcp/dist/index.js` boots in two environments, selected by env flag:
+
+| Env var | Platform mode | Standalone mode |
+|---|---|---|
+| `LOOP_STANDALONE` | unset | `"1"` |
+| `ACCOUNT_ID` | platform tenant id | absent (defaults to `"local"`) |
+| `NEO4J_URI` etc. | required | unused |
+
+In standalone mode team keys live at `~/.claude/.realagent-loop-key.enc` as one AES-256-GCM-encrypted JSON blob keyed by accountId then teamName. Multi-team support is preserved. See `.docs/realagent-mcps-standalone-mode.md` for the full contract.
 
 ## When to use these tools
 

package/payload/platform/plugins/loop/mcp/dist/index.js

@@ -1,5 +1,5 @@
-import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
-initStderrTee("loop");
+// Logging-tee was a platform-wrapper concern; the host owns the stderr pipe
+// in both platform and standalone (Claude Code native) spawn paths.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -28,10 +28,10 @@ import { autoResponder } from "./tools/auto-responder.js";
 import { customerPreferences } from "./tools/customer-preferences.js";
 import { supplier } from "./tools/supplier.js";
 import { closeDriver } from "./lib/neo4j.js";
-const accountId = process.env.ACCOUNT_ID;
-if (!accountId) {
-    throw new Error("ACCOUNT_ID environment variable is required");
-}
+import { selectLoopKeyStore } from "./lib/key-store.js";
+// ACCOUNT_ID is the platform's tenant id; "local" is the single-tenant
+// standalone stand-in when spawned natively by Claude Code.
+const accountId = process.env.ACCOUNT_ID ?? "local";
 const server = new McpServer({
     name: "maxy-loop",
     version: "0.2.0",
@@ -40,7 +40,8 @@ const ALL_PERMISSIONS = z.enum([
     "properties", "people", "viewings", "feedback", "team",
     "marketing", "customer", "supplier",
 ]);
-console.error(`[loop] server started, account=${accountId}`);
+const store = selectLoopKeyStore();
+console.error(`[loop] server started, account=${accountId} backend=${store.backendName} path=${store.backendPath}`);
 // Helper: wrap a tool function in standard error handling
 function toolHandler(fn) {
     return async (params) => {