@rubytech/create-maxy-code 0.1.49 → 0.1.51

package/package.json

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

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

@@ -105,7 +105,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
-- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_HIDDEN_SPAWN=0` so it never recurses into the hidden recorder PTY or fires on public sessions. POSTs a hidden `/spawn` against the `database-operator` specialist (structurally identical to a user-facing admin specialist spawn — same argv, same OAuth path), then POSTs the filtered transcript to `/<sessionId>/input` as the recorder's first operator turn. The manager's recorder-auto-archive subscriber stops the PTY as soon as the recorder's JSONL contains an assistant message with `stop_reason === "end_turn"`. Hidden rows do not surface in `/list` by default.
+- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_HIDDEN_SPAWN=0` so it never recurses into the hidden recorder PTY or fires on public sessions. Task 122 redesign: the hook makes ONE HTTP call to `POST /api/admin/claude-sessions/recorder-spawn` (loopback-only, `senderId='turn-recorder'`, bypasses admin-session auth on 127.0.0.1). The wrapper owns the spawn-with-initial-message sequence for every caller — Sidebar single-line stimulus and recorder multi-line instruction both flow through one function, so the multi-line submit path lives in one place instead of being re-implemented in bash. The manager's `POST /:id/input` wraps multi-line `text` in DEC bracketed-paste markers (`\e[200~ ... \e[201~\r`) so the TUI submits it as one turn; single-line text keeps the typed-keystroke path. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. Hidden rows do not surface in `/list` by default.
 
 ## Failure-report breadcrumbs
 

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

@@ -1,19 +1,26 @@
 #!/usr/bin/env bash
 # Regression test for the Stop-hook gate that fires the database-operator
-# per completed admin-agent turn (Task 114 redesign: normal admin session +
-# /input POST, replacing Task 106's `--print` + stdin-EOT shape which is
-# incompatible with OAuth).
+# per completed admin-agent turn.
+#
+# Task 122 redesign: the hook routes through the admin wrapper's
+# loopback-only recorder route (POST /api/admin/claude-sessions/recorder-spawn)
+# in ONE HTTP call. The wrapper internally calls /spawn then /<id>/input on
+# the claude-session-manager — the multi-line submit path is owned by the
+# wrapper, not duplicated in bash.
 #
 # Behaviour verified:
 #   1. MAXY_SESSION_ROLE!=admin → exit 0, no POST attempt, no log line.
 #   2. MAXY_HIDDEN_SPAWN=1     → exit 0, no POST attempt, no log line.
 #   3. Empty stdin            → exit 0 silently.
 #   4. Missing transcript_path → exit 0 silently.
-#   5. Happy path             → exactly ONE POST to /spawn (no stdinPayload
-#      field) and exactly ONE POST to /<id>/input whose `text` carries the
-#      Task 114 instruction string and the filtered transcript, plus the
-#      `[turn-recorder] spawn-with-input sessionId=<8> bytes=<n> filtered-from-records=<n> input-http=200`
-#      log line.
+#   5. Happy path             → exactly ONE POST to
+#      /api/admin/claude-sessions/recorder-spawn whose body carries
+#      senderId='turn-recorder', specialist='database-operator', and an
+#      initialMessage containing the Task 114 instruction + the filtered
+#      transcript. The hook still emits the
+#      `[turn-recorder] spawn-with-input sessionId=<8> bytes=<n>
+#       filtered-from-records=<n> input-http=200` log envelope unchanged
+#      (Task 122 keeps the envelope so existing greps survive).
 
 set -u
 
@@ -50,7 +57,7 @@ run_hook() {
   printf '%s' "$stdin_json" | \
     MAXY_SESSION_ROLE="$role" \
     MAXY_HIDDEN_SPAWN="$hidden" \
-    CLAUDE_SESSION_MANAGER_PORT="${MANAGER_PORT:-19400}" \
+    MAXY_UI_INTERNAL_PORT="${UI_PORT:-19199}" \
     bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
   local rc=$?
   HOOK_RC="$rc"
@@ -94,7 +101,7 @@ elif [[ -n "$HOOK_STDERR" ]]; then fail "case-4 expected empty stderr, got: $HOO
 else pass "case-4 missing transcript_path → silent (rc=0)"
 fi
 
-# --- Case 5: happy path → one /spawn (no stdinPayload) + one /<id>/input
+# --- Case 5: happy path → exactly ONE POST to /api/admin/claude-sessions/recorder-spawn
 REQ_LOG=$(mktemp); TMPFILES+=("$REQ_LOG")
 LISTENER_PORT=39406
 python3 - "$LISTENER_PORT" "$REQ_LOG" <<'PY' &
@@ -111,7 +118,7 @@ class H(http.server.BaseHTTPRequestHandler):
     self.send_response(200)
     self.send_header('Content-Type','application/json')
     self.end_headers()
-    if self.path == '/spawn':
+    if self.path.endswith('/recorder-spawn'):
       self.wfile.write(json.dumps({"sessionId":"rec00001-feedfeed"}).encode('utf-8'))
     else:
       self.wfile.write(json.dumps({"ok": True}).encode('utf-8'))
@@ -130,9 +137,9 @@ done
 # Clear the request log of the ping write.
 : > "$REQ_LOG"
 
-MANAGER_PORT="$LISTENER_PORT"
+UI_PORT="$LISTENER_PORT"
 run_hook "admin" "0" "$ENVELOPE"
-unset MANAGER_PORT
+unset UI_PORT
 
 # Give the listener time to flush.
 sleep 0.1
@@ -150,69 +157,61 @@ fi
 
 # Assert: no legacy spawn-with-stdin log line.
 if echo "$HOOK_STDERR" | grep -q 'spawn-with-stdin'; then
-  fail "case-5b legacy spawn-with-stdin line must not be emitted in Task 114"
+  fail "case-5b legacy spawn-with-stdin line must not be emitted"
 else
   pass "case-5b legacy spawn-with-stdin log line absent"
 fi
 
-# Assert: listener saw exactly one /spawn POST and exactly one /<id>/input POST.
-SPAWN_LINES=$(grep -c '^/spawn	' "$REQ_LOG" || true)
-INPUT_LINES=$(grep -cE '^/[A-Za-z0-9_-]+/input	' "$REQ_LOG" || true)
+# Assert: exactly ONE POST to the wrapper recorder-spawn route, and no
+# direct /spawn or /<id>/input POSTs (the wrapper-internal calls do not
+# touch this test listener — the listener mocks the wrapper, not the
+# manager).
+RECORDER_LINES=$(grep -cE '^/api/admin/claude-sessions/recorder-spawn	' "$REQ_LOG" || true)
+LEGACY_SPAWN_LINES=$(grep -cE '^/spawn	' "$REQ_LOG" || true)
+LEGACY_INPUT_LINES=$(grep -cE '^/[A-Za-z0-9_-]+/input	' "$REQ_LOG" || true)
 STOP_LINES=$(grep -cE '^/[A-Za-z0-9_-]+/stop	' "$REQ_LOG" || true)
-if [[ "$SPAWN_LINES" -ne 1 ]]; then
-  fail "case-5c expected exactly 1 /spawn POST, got $SPAWN_LINES (log: $(cat "$REQ_LOG"))"
+if [[ "$RECORDER_LINES" -ne 1 ]]; then
+  fail "case-5c expected exactly 1 /api/admin/claude-sessions/recorder-spawn POST, got $RECORDER_LINES (log: $(cat "$REQ_LOG"))"
 else
-  pass "case-5c exactly one /spawn POST observed"
+  pass "case-5c exactly one recorder-spawn POST observed"
 fi
-if [[ "$INPUT_LINES" -ne 1 ]]; then
-  fail "case-5d expected exactly 1 /<id>/input POST, got $INPUT_LINES"
+if [[ "$LEGACY_SPAWN_LINES" -ne 0 ]]; then
+  fail "case-5d hook must not POST /spawn directly any more, got $LEGACY_SPAWN_LINES"
 else
-  pass "case-5d exactly one /<id>/input POST observed"
+  pass "case-5d no direct /spawn POST"
 fi
-if [[ "$STOP_LINES" -ne 0 ]]; then
-  fail "case-5e expected ZERO /<id>/stop POSTs from the hook (auto-archive is in-manager), got $STOP_LINES"
+if [[ "$LEGACY_INPUT_LINES" -ne 0 ]]; then
+  fail "case-5e hook must not POST /<id>/input directly any more, got $LEGACY_INPUT_LINES"
 else
-  pass "case-5e zero /<id>/stop POSTs"
+  pass "case-5e no direct /<id>/input POST"
 fi
-
-# Assert: the /spawn body has no stdinPayload field.
-SPAWN_BODY=$(grep '^/spawn	' "$REQ_LOG" | head -1 | cut -f2-)
-if [[ -z "$SPAWN_BODY" ]]; then
-  fail "case-5f /spawn body was empty"
+if [[ "$STOP_LINES" -ne 0 ]]; then
+  fail "case-5f hook must not POST /<id>/stop, got $STOP_LINES"
 else
-  HAS_STDIN=$(printf '%s' "$SPAWN_BODY" | python3 -c '
-import sys, json
-try:
-  b = json.load(sys.stdin)
-  print("yes" if "stdinPayload" in b else "no")
-except Exception:
-  print("parse-fail")
-' 2>/dev/null)
-  if [[ "$HAS_STDIN" != "no" ]]; then
-    fail "case-5f /spawn body must NOT carry stdinPayload, got: $SPAWN_BODY"
-  else
-    pass "case-5f /spawn body has no stdinPayload field"
-  fi
+  pass "case-5f no /<id>/stop POSTs"
 fi
 
-# Assert: the /input body's `text` carries the Task 114 instruction and the
-# transcript section header.
-INPUT_BODY=$(grep -E '^/[A-Za-z0-9_-]+/input	' "$REQ_LOG" | head -1 | cut -f2-)
-INPUT_OK=$(printf '%s' "$INPUT_BODY" | python3 -c '
+# Assert: recorder-spawn body carries senderId, specialist, and a multi-line
+# initialMessage with the Task 114 instruction + transcript section header.
+RECORDER_BODY=$(grep -E '^/api/admin/claude-sessions/recorder-spawn	' "$REQ_LOG" | head -1 | cut -f2-)
+BODY_OK=$(printf '%s' "$RECORDER_BODY" | python3 -c '
 import sys, json
 try:
   b = json.load(sys.stdin)
-  t = b.get("text", "")
-  has_instr = "update the graph with any missing information or intent that can be derived from this conversation" in t
-  has_tx = "Conversation transcript:" in t
-  print("yes" if (has_instr and has_tx) else "no")
+  senderOK = b.get("senderId") == "turn-recorder"
+  specOK = b.get("specialist") == "database-operator"
+  msg = b.get("initialMessage", "") or ""
+  hasInstr = "update the graph with any missing information or intent that can be derived from this conversation" in msg
+  hasTx = "Conversation transcript:" in msg
+  hasMultiline = "\n" in msg
+  print("yes" if (senderOK and specOK and hasInstr and hasTx and hasMultiline) else "no")
 except Exception:
   print("parse-fail")
 ' 2>/dev/null)
-if [[ "$INPUT_OK" != "yes" ]]; then
-  fail "case-5g /input body missing instruction or transcript header: $INPUT_BODY"
+if [[ "$BODY_OK" != "yes" ]]; then
+  fail "case-5g recorder-spawn body shape wrong: $RECORDER_BODY"
 else
-  pass "case-5g /input body carries Task 114 instruction + transcript"
+  pass "case-5g recorder-spawn body carries senderId, specialist, multi-line initialMessage"
 fi
 
 # Assert: final fired log line still emitted.

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

@@ -4,16 +4,15 @@
 # The hidden recorder is the only writer to the Neo4j graph; the admin agent
 # stays focused on the operator's request.
 #
-# Pipeline (Task 114 redesign — replaces Task 106's `--print` + stdin-EOT
-# shape, which is incompatible with the OAuth subscription the manager runs
-# on):
-#   1. /spawn with `hidden=true, specialist=database-operator` — the manager
-#      produces a structurally normal admin specialist session (same argv,
-#      same OAuth path) and returns its sessionId.
-#   2. POST /<sessionId>/input with `<instruction>\n\nConversation transcript:\n<filtered JSON>`.
-#   3. The manager's recorder-auto-archive subscriber stops the PTY as soon
-#      as the recorder's JSONL contains an assistant message with
-#      `stop_reason === "end_turn"`. The hook does not need to follow up.
+# Task 122 redesign — the hook now makes ONE HTTP call to the admin
+# wrapper's loopback recorder route (`POST /api/admin/claude-sessions/recorder-spawn`)
+# instead of curling /spawn and /<id>/input directly against the
+# claude-session-manager. The wrapper owns the spawn-with-initial-message
+# sequence for every caller (Sidebar and recorder alike), which keeps the
+# multi-line submit path in one place. The wrapper bypasses admin-session
+# auth on this route because the request originates from 127.0.0.1 and
+# the body carries `senderId: 'turn-recorder'` — same trust boundary the
+# claude-session-manager itself relies on.
 #
 # Gating:
 #   - MAXY_SESSION_ROLE must equal "admin"
@@ -100,65 +99,59 @@ PY
 
 FILTERED_COUNT=$(printf '%s' "$FILTERED_TAIL" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(len(d) if isinstance(d,list) else 0)' 2>/dev/null || echo 0)
 
-MANAGER_PORT="${CLAUDE_SESSION_MANAGER_PORT:-19400}"
-MANAGER_BASE="http://127.0.0.1:${MANAGER_PORT}"
+# UI server runs on MAXY_UI_INTERNAL_PORT (default 19199). The recorder
+# route is loopback-only; no admin-session credentials are required.
+UI_PORT="${MAXY_UI_INTERNAL_PORT:-19199}"
+UI_BASE="http://127.0.0.1:${UI_PORT}"
 
+# Compose the recorder spawn body in one shot. `initialMessage` carries
+# the instruction + conversation id + filtered transcript as a single
+# multi-line string; the wrapper hands it to manager POST /<id>/input,
+# which now wraps multi-line text in bracketed-paste markers so the TUI
+# submits it as one turn (Task 122 root cause).
 SPAWN_BODY=$(python3 -c '
-import json
+import sys, json
+sid = sys.argv[1]
+tail_json = sys.argv[2]
+instruction = "update the graph with any missing information or intent that can be derived from this conversation"
+text = (
+  f"{instruction}\n\n"
+  f"Conversation id: {sid}\n"
+  f"Conversation transcript:\n{tail_json}\n"
+)
 body = {
   "senderId": "turn-recorder",
-  "role": "admin",
-  "channel": "browser",
-  "hidden": True,
   "specialist": "database-operator",
+  "initialMessage": text,
 }
 print(json.dumps(body))
-' 2>/dev/null)
+' "$ADMIN_SESSION_ID" "$FILTERED_TAIL" 2>/dev/null)
 
-SPAWN_RES=$(curl -sS -X POST \
+INPUT_BYTES=$(printf '%s' "$SPAWN_BODY" | python3 -c 'import sys,json; b=json.load(sys.stdin); print(len(b.get("initialMessage","").encode("utf-8")))' 2>/dev/null || echo 0)
+
+SPAWN_RES_FILE=$(mktemp)
+INPUT_HTTP=$(curl -sS -o "$SPAWN_RES_FILE" -w '%{http_code}' -X POST \
   -H 'Content-Type: application/json' \
   --max-time 10 \
   --data "$SPAWN_BODY" \
-  "${MANAGER_BASE}/spawn" 2>/dev/null)
+  "${UI_BASE}/api/admin/claude-sessions/recorder-spawn" 2>/dev/null || echo 000)
 
-RECORDER_SESSION_ID=$(printf '%s' "$SPAWN_RES" | python3 -c '
+RECORDER_SESSION_ID=$(python3 -c '
 import sys, json
 try:
-  d = json.load(sys.stdin)
+  with open(sys.argv[1], "r", encoding="utf-8") as f:
+    d = json.load(f)
   print(d.get("sessionId", "") or "")
 except Exception:
   print("")
-' 2>/dev/null)
+' "$SPAWN_RES_FILE" 2>/dev/null)
+rm -f "$SPAWN_RES_FILE"
 
 if [ -z "$RECORDER_SESSION_ID" ]; then
-  echo "turn-completed-graph-write spawn-failed conversationId=${ADMIN_SESSION_ID:0:8}" >&2
+  echo "turn-completed-graph-write spawn-failed conversationId=${ADMIN_SESSION_ID:0:8} http=${INPUT_HTTP}" >&2
   exit 0
 fi
 
-# Compose the input prompt and POST it to /<sessionId>/input. The instruction
-# string is fixed (Task 114). The transcript is appended as a JSON array so
-# the recorder reads it as a single user turn.
-INPUT_BODY=$(python3 -c '
-import sys, json
-sid = sys.argv[1]
-tail_json = sys.argv[2]
-instruction = "update the graph with any missing information or intent that can be derived from this conversation"
-text = (
-  f"{instruction}\n\n"
-  f"Conversation id: {sid}\n"
-  f"Conversation transcript:\n{tail_json}\n"
-)
-print(json.dumps({"text": text}))
-' "$ADMIN_SESSION_ID" "$FILTERED_TAIL" 2>/dev/null)
-
-INPUT_BYTES=$(printf '%s' "$INPUT_BODY" | python3 -c 'import sys,json; b=json.load(sys.stdin); print(len(b.get("text","").encode("utf-8")))' 2>/dev/null || echo 0)
-
-INPUT_HTTP=$(curl -sS -o /tmp/turn-recorder-input.out -w '%{http_code}' -X POST \
-  -H 'Content-Type: application/json' \
-  --max-time 10 \
-  --data "$INPUT_BODY" \
-  "${MANAGER_BASE}/${RECORDER_SESSION_ID}/input" 2>/dev/null || echo 000)
-
 echo "[turn-recorder] spawn-with-input sessionId=${RECORDER_SESSION_ID:0:8} bytes=${INPUT_BYTES} filtered-from-records=${FILTERED_COUNT} input-http=${INPUT_HTTP}" >&2
 
 END_MS=$(python3 -c 'import time; print(int(time.time()*1000))')

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

@@ -30,7 +30,8 @@ Load these when users ask about Maxy features or need guidance:
 Load these when performing admin tasks or diagnosing platform behaviour:
 
 - **Platform architecture** → `references/platform.md` — how the platform works, agent types, the plugin model
-- **Platform internals** → `references/internals.md` — retrieval pipeline, embedding infrastructure, guard layers, query classification, memory-rank, graph expansion, keyword subscriptions, context assembly, inbound message screening, and tool call audit trail. Load when answering architecture questions, assessing whether a capability exists, diagnosing retrieval behaviour, or reviewing security and privacy features.
+- **Platform internals** → `references/internals.md` — retrieval pipeline, embedding infrastructure, guard layers, query classification, memory-rank, graph expansion, keyword subscriptions, context assembly, inbound message screening, tool call audit trail, programmatic spawn entry point and recorder auto-archive lifecycle. Load when answering architecture questions, assessing whether a capability exists, diagnosing retrieval behaviour, or reviewing security and privacy features.
+- **Admin session** → `references/admin-session.md` — signed sessionKey + PIN-rebind survival contract, SDK-resume across `systemctl restart`, and the single-entry `POST /api/admin/claude-sessions` wrapper that owns every programmatic admin spawn-with-initialMessage. Load when diagnosing admin session continuity, designing a programmatic admin spawn, or reviewing the turn-recorder lifecycle.
 - **Cloudflare** → `references/cloudflare.md` — dashboard-first tunnel setup, the `cloudflared`-CLI-only tool surface, single-recovery-path (re-login) for every wrong-account failure.
 - **Deployment** → `references/deployment.md` — Pi setup, Cloudflare tunnel, start script
 
@@ -48,5 +49,6 @@ Load these when performing admin tasks or diagnosing platform behaviour:
 - references/troubleshooting.md
 - references/platform.md
 - references/internals.md
+- references/admin-session.md
 - references/cloudflare.md
 - references/deployment.md

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

@@ -73,6 +73,16 @@ grep -E '\[session-rehydrate-from-token\]|\[client-acquire\] reason=pin-rebind'
 grep '\[client-acquire\]' ~/.${brand}/logs/claude-agent-stream-*.log
 ```
 
+## Spawn-with-`initialMessage` wrapper
+
+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. The turn-recorder hook adds `senderId: 'turn-recorder'`, `specialist`, and `hidden` so the row never surfaces in the sidebar (post-Task 122). 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.
+
+**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> }` fire-and-forget 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 post-Task 122; future programmatic spawns. Every caller routes here. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in` log line followed by `forward-spawn-done`.
+
 ## Out of scope
 
 - Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.

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

@@ -468,6 +468,10 @@ A boot gate refuses to start the manager when any admin-allowlisted tool `mcp__<
 
 **Per-spawn signals (server.log).** Every spawn emits `pty-spawn-mcp-config servers=<N> tools=<M> bytes=<B> path=<…>` once, plus one `pty-spawn-agents-dir role=<admin|public> path=<…>` per added directory. The diagnostic one-liner is `grep -E 'pty-spawn-mcp-config|pty-spawn-agents-dir|mcp-config-allowlist-coverage|boot-failed reason=mcp-allowlist' ~/.<brand>/logs/server.log | tail -50`.
 
+**Programmatic spawn entry point.** Every admin PTY spawn that needs a first user prompt — UI click, turn-recorder hook, future automation — routes through the single wrapper at [`platform/ui/server/routes/admin/claude-sessions.ts`](../../../ui/server/routes/admin/claude-sessions.ts). The wrapper owns the spawn → input ordering, the per-spawn enrichment (owner profile, dormant/active plugins, specialist domains, tunnel URL), and the `senderId` resolution; it forwards to the session manager's `POST /spawn` then `POST /<sessionId>/input` on `127.0.0.1`. No caller composes those two manager endpoints directly. The recorder branch sets `senderId: 'turn-recorder'`. See `admin-session.md` "Spawn-with-initialMessage wrapper" for the body schema and caller list.
+
+**Recorder auto-archive (lifecycle, not user-initiated).** The session manager's `attachRecorderAutoArchive` ([`platform/services/claude-session-manager/src/http-server.ts:178`](../../../services/claude-session-manager/src/http-server.ts)) wires every spawn whose `senderId === 'turn-recorder'` to a JSONL watcher: as soon as the recorder's JSONL contains `"stop_reason":"end_turn"`, the manager calls `stopSession`, the PTY exits, the PID file is removed, and `fs-watcher.ts:275-297` demotes the row to `state: 'archived'`. This is the lifecycle archive path — the row stays in place, the JSONL stays on disk, no directory move. It is structurally distinct from the user-initiated `POST /api/admin/claude-sessions/:id/archive` route, which actually `mv`s the JSONL between `<slugDir>` and `<slugDir>/archive/`; that path is the operator pruning their visible session list, not the recorder's per-turn cleanup.
+
 ## Tool Call Audit Trail
 
 Every tool invocation by the admin agent produces a durable `ToolCall` node in the knowledge graph, linked to the `Conversation` that triggered it. This covers all admin agent tool calls — the full history of what the agent did, when, and in what context.

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

@@ -80,7 +80,7 @@ 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 the current ISO-8601 UTC timestamp (e.g. `2026-05-18T13:15:45.398Z`), computed at click-time on the client. The server forwards it as `POST /<id>/input { text }` immediately after the spawn returns. The timestamp is the minimum-information opener — it has no instructional meaning, so the agent reads it as "begin", not as a directive to do something. 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. 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 the current ISO-8601 UTC timestamp (e.g. `2026-05-18T13:15:45.398Z`), computed at click-time on the client. The server forwards it as `POST /<id>/input { text }` immediately after the spawn returns. 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". The timestamp is the minimum-information opener — it has no instructional meaning, so the agent reads it as "begin", not as a directive to do something. 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.
 
 **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.
 

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

@@ -174,6 +174,30 @@ Loop covers five value pillars with API surface. Each pillar has both read and w
 - `loop-customer-preferences` (action=write)
 - `loop-supplier` (action=maintenance-complete, board-complete, maintenance-submit-quote)
 
+## Time presentation
+
+**Every datetime field in a Loop response is UTC, returned without a timezone marker.** The Loop V2 API stores and returns instants as bare `YYYY-MM-DDTHH:MM:SS` strings whose true zone is UTC. Presenting them verbatim is silent misrepresentation: a viewing whose `dateOfAppointment` is `12:00:00` is `12:00Z`, which is `13:00 BST` between late March and late October in the UK. Off-by-one-hour viewing times have already misled an operator (Task 126).
+
+**Convert before any datetime appears in agent output.** The operator's zone comes from the `Person.timezone` property on the operator's `Person` node; Real Agent UK accounts default to `Europe/London` when that property is absent. The conversion is non-negotiable — there is no case where a Loop datetime is presented to the operator in its raw UTC form. State the converted local time, and where ambiguous (cross-DST scheduling, calendar invites), name the zone explicitly (`13:00 BST`, `09:30 GMT`).
+
+The tools whose responses carry one or more datetime fields — and therefore require this conversion before any field value reaches the operator — are exhaustive:
+
+- `loop-viewing-search` — `dateOfAppointment`, `dateOfAppointmentEnd`
+- `loop-viewing-detail` — `dateCreated`, `dateOfAppointment`, `dateOfAppointmentEnd`, `dateBuyerFeedbackGiven`, `dateSellerFeedbackGiven`, `dateDone`
+- `loop-feedback-get` — `viewingDateOfAppointment`
+- `loop-people-search` — renters list: `dateRequired`
+- `loop-people-detail` — `dateCreated`; nested `viewings[].dateOfAppointment(+End)`, `offers[].dateReceived`, `applications[].dateReceived`, `applications[].proposedStartDate`, `property.dateCreated` (sellers/landlords), `dateRequired` (renters)
+- `loop-property-search` — `dateCreated`
+- `loop-property-detail` — `dateCreated`, `dateInstructed`, `dateUnderOffer`, `dateLaunched`, `dateExchanged`, `dateCompleted`, `dateWithdrawn`, `dateFirstAvailable`, `leaseExpiryDate`
+- `loop-property-listed` — `dateLaunched`, `dateFirstAvailable`, `leaseExpiryDate`
+- `loop-property-sold` — `dateLaunched`, `leaseExpiryDate`, `images[].dateUpdated`
+- `loop-marketing-match` — `dateCreated`, `dateInstructed`, `dateUnderOffer`, `dateLaunched`, `dateExchanged`, `dateCompleted`, `dateWithdrawn`, `dateFirstAvailable`, `viewings[].dateOfAppointment(+End)`, `applications[].dateReceived`, `applications[].proposedStartDate`, `marketListings[].dateListed`, `images[].dateUpdated`
+- `loop-auto-responder` — `enquiry.dateMoving`
+- `loop-team-availability` — `start`, `end`
+- `loop-supplier` — `dateCreated`, `dateDone`, `dateReported`, `dateQuoteBy`, `dateCompleted`, `dateApproved`
+
+Tools not listed (`loop-key-*`, `loop-team-info`, `loop-customer-preferences`, `loop-marketing-enquiry`, `loop-marketing-match-batch`, `loop-marketing-match-request`, `loop-viewing-create`, `loop-viewing-update`, `loop-feedback-submit`, `loop-property-viewing`, `loop-property-callback`, `loop-property-information`) either have no datetime in response or are write-only acknowledgements. The enumeration is grounded in the vendored swagger snapshot at `mcp/src/__tests__/loop-swagger.snapshot.json`; the pinning test at `mcp/src/__tests__/plugin-md-time-doctrine.test.ts` blocks silent drift.
+
 ### Team-key prerequisite
 
 Every Loop tool routes through one or more team keys. If `loop-key-list` returns nothing for the account, surface the registration prompt before attempting any other Loop call — every downstream tool will fail otherwise. If a call returns `Team "X" does not have <group> permission`, the key was scoped to fewer than 8 endpoint groups; re-register with the full permissions array (`["properties","people","viewings","feedback","team","marketing","customer","supplier"]`).

package/payload/platform/plugins/loop/mcp/src/__tests__/plugin-md-time-doctrine.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Anti-regression: PLUGIN.md must carry the "Time presentation" doctrine
+ * paragraph and enumerate every Loop tool whose response contains a
+ * datetime field. The doctrine is the agent's only signal that Loop
+ * returns bare UTC strings without a zone marker — silent drop of this
+ * section recurs the off-by-one-hour viewing-time failure (Task 126).
+ *
+ * The expected tool list is derived live from the vendored swagger
+ * snapshot, so if Loop adds a new datetime-bearing endpoint and we miss
+ * mapping it in PLUGIN.md, the test fails and names the orphan.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_MD = resolve(__dirname, '../../../PLUGIN.md');
+const SWAGGER_PATH = resolve(__dirname, 'loop-swagger.snapshot.json');
+
+interface SwaggerDoc {
+  paths: Record<string, Record<string, { responses?: Record<string, { content?: Record<string, { schema?: unknown }> }> }>>;
+  components?: { schemas?: Record<string, unknown> };
+}
+
+const swagger = JSON.parse(readFileSync(SWAGGER_PATH, 'utf-8')) as SwaggerDoc;
+const plugin = readFileSync(PLUGIN_MD, 'utf-8');
+
+// Swagger path → tool name. Every response-bearing GET path that surfaces
+// a datetime field must map to exactly one tool here. Add a row when Loop
+// publishes a new datetime endpoint that we expose.
+const PATH_TO_TOOL: Record<string, string> = {
+  '/residential/sales/viewings': 'loop-viewing-search',
+  '/residential/lettings/viewings': 'loop-viewing-search',
+  '/residential/sales/viewings/{id}': 'loop-viewing-detail',
+  '/residential/lettings/viewings/{id}': 'loop-viewing-detail',
+  '/feedback/residential/sales/viewings/{id}': 'loop-feedback-get',
+  '/feedback/residential/lettings/viewings/{id}': 'loop-feedback-get',
+  '/people/renters': 'loop-people-search',
+  '/people/{id}': 'loop-people-detail',
+  '/people/buyers/{id}': 'loop-people-detail',
+  '/people/sellers/{id}': 'loop-people-detail',
+  '/people/landlords/{id}': 'loop-people-detail',
+  '/people/renters/{id}': 'loop-people-detail',
+  '/property/residential/sales/{id}': 'loop-property-detail',
+  '/property/residential/lettings/{id}': 'loop-property-detail',
+  '/property/residential/sales': 'loop-property-search',
+  '/property/residential/lettings': 'loop-property-search',
+  '/property/residential/sales/listed/{channel}': 'loop-property-listed',
+  '/property/residential/lettings/listed/{channel}': 'loop-property-listed',
+  '/property/residential/sales/{id}/preview/{previewHash}': 'loop-property-detail',
+  '/property/residential/lettings/{id}/preview/{previewHash}': 'loop-property-detail',
+  '/property/residential/sold/{channel}': 'loop-property-sold',
+  '/marketing/matching/{id}': 'loop-marketing-match',
+  '/marketing/rentals/matching/{id}': 'loop-marketing-match',
+  '/marketing/enquiries/auto-responder/{id}/{key}': 'loop-auto-responder',
+  '/team/{agentId}/availability/{searchDate}': 'loop-team-availability',
+  '/supplier/board-contractor/{code}/{jobid}/job-list': 'loop-supplier',
+  '/supplier/maintenance/{quoteCode}/{jobid}/job-list': 'loop-supplier',
+  '/supplier/maintenance/{quoteCode}/{jobId}/quote-list': 'loop-supplier',
+};
+
+function resolveRef(ref: string): unknown {
+  const parts = ref.replace('#/', '').split('/');
+  let cur: unknown = swagger;
+  for (const p of parts) cur = cur && typeof cur === 'object' ? (cur as Record<string, unknown>)[p] : null;
+  return cur;
+}
+
+function hasDateField(node: unknown, depth = 0, visited = new WeakSet<object>()): boolean {
+  if (!node || typeof node !== 'object' || depth > 12) return false;
+  if (visited.has(node as object)) return false;
+  visited.add(node as object);
+  const n = node as Record<string, unknown>;
+  if (typeof n.$ref === 'string') return hasDateField(resolveRef(n.$ref), depth + 1, visited);
+  if (n.format === 'date-time' || n.format === 'date') return true;
+  if (n.properties && typeof n.properties === 'object') {
+    for (const v of Object.values(n.properties as Record<string, unknown>)) {
+      if (hasDateField(v, depth + 1, visited)) return true;
+    }
+  }
+  if (n.items && hasDateField(n.items, depth + 1, visited)) return true;
+  if (Array.isArray(n.allOf)) {
+    for (const v of n.allOf) if (hasDateField(v, depth + 1, visited)) return true;
+  }
+  return false;
+}
+
+function toolsRequiringDoctrine(): Set<string> {
+  const tools = new Set<string>();
+  for (const [path, methods] of Object.entries(swagger.paths)) {
+    const op = methods.get;
+    if (!op || !op.responses) continue;
+    const anyDate = Object.values(op.responses).some(r =>
+      Object.values(r.content || {}).some(sw => hasDateField(sw.schema)),
+    );
+    if (!anyDate) continue;
+    const tool = PATH_TO_TOOL[path];
+    if (tool) tools.add(tool);
+    else throw new Error(`Swagger GET ${path} returns a datetime but has no PATH_TO_TOOL mapping — add it and list the tool in PLUGIN.md "Time presentation".`);
+  }
+  return tools;
+}
+
+describe('PLUGIN.md time-presentation doctrine', () => {
+  it('contains the Time presentation section', () => {
+    expect(plugin).toMatch(/^## Time presentation$/m);
+  });
+
+  it('names UTC, Person.timezone, and the Europe/London default', () => {
+    expect(plugin).toMatch(/UTC/);
+    expect(plugin).toMatch(/Person\.timezone/);
+    expect(plugin).toMatch(/Europe\/London/);
+  });
+
+  it('forbids raw UTC presentation', () => {
+    // Must state conversion is required before any datetime appears in output.
+    expect(plugin).toMatch(/Convert before any datetime appears in agent output/);
+  });
+
+  it('enumerates every tool whose Loop response carries a datetime field', () => {
+    const required = toolsRequiringDoctrine();
+    const missing: string[] = [];
+    for (const tool of required) {
+      // Each tool must appear in the doctrine section as a bullet item.
+      const re = new RegExp(`^- \`${tool.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}\``, 'm');
+      if (!re.test(plugin)) missing.push(tool);
+    }
+    expect(missing, `PLUGIN.md "Time presentation" must list: ${missing.join(', ')}`).toEqual([]);
+  });
+});

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

@@ -300,8 +300,7 @@ eagerTool(server, "session-name", "Set a human-readable name on the current conv
         // created (deferred persistence). Surface the deferral
         // so the silent no-op is observable to the agent. The agent should
         // re-call session-name on a later turn (post-flush) if the chosen
-        // title needs to land — autoLabelSession may set its own name first
-        // (gated by message usefulness), and a re-call overrides it.
+        // title needs to land.
         const text = affected > 0
             ? `Session named: "${params.name}"`
             : `Session not yet bound — Conversation will be created at the first completed turn. Re-call session-name on a later turn to apply this title.`;