@rubytech/create-maxy-code 0.1.40 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.40",
+  "version": "0.1.43",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"
@@ -13,7 +13,7 @@
     "build": "tsc",
     "bundle": "node scripts/bundle.js",
     "test": "npm run build && node --test 'dist/__tests__/*.test.js'",
-    "prepublishOnly": "bash ../../platform/scripts/verify-skill-tool-surface.sh && node ../../platform/scripts/check-no-task-id-leaks.mjs && node ../../platform/scripts/check-skill-load-coverage.mjs && node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && npm run bundle && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
+    "prepublishOnly": "bash ../../platform/scripts/verify-skill-tool-surface.sh && node ../../platform/scripts/check-no-task-id-leaks.mjs && node ../../platform/scripts/check-no-esm-require.mjs && node ../../platform/scripts/check-skill-load-coverage.mjs && node ../../platform/ui/scripts/check-route-wiring.mjs && node ../../platform/ui/scripts/check-edge-admin-routes.mjs && npm run build && node --test 'dist/__tests__/*.test.js' && chmod +x dist/index.js && npm run bundle && bash ../../platform/scripts/smoke-boot-services.sh && node ../../platform/ui/scripts/check-bundle-node-imports.mjs --dir=./payload/server/public/assets"
   },
   "files": [
     "dist",

package/payload/platform/lib/mcp-stderr-tee/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@maxy/mcp-stderr-tee",
+  "version": "0.1.0",
+  "private": true,
+  "type": "commonjs",
+  "main": "dist/index.js"
+}

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

@@ -1,37 +1,71 @@
 #!/usr/bin/env bash
 # Stop hook — fires on every completed admin-agent turn and dispatches one
-# background PTY against `specialists:database-operator` with the just-
-# completed turn payload as stdin. The hidden PTY is the only writer to the
-# Neo4j graph; the admin agent stays focused on the operator's request.
+# background PTY against `specialists:database-operator`. The hidden PTY is
+# the only writer to the Neo4j graph; the admin agent stays focused on the
+# operator's request.
+#
+# Pipeline (Task 094 redesign):
+#   1. /spawn (no stdinPayload) — manager awaits its watcher's PID-file
+#      event before returning. Response carries the recorder's intrinsic
+#      sessionId.
+#   2. POST /<recorder-sessionId>/input — body is the database-operator
+#      prompt followed by the filtered JSONL tail of the just-completed
+#      turn (user / assistant / tool-call records only; queue-operation,
+#      auto_mode, deferred_tools_delta, hook_*, last-prompt, skill_listing,
+#      mcp_instructions_delta, permission-mode are dropped).
+#   3. When the recorder's Stop hook fires, this hook runs again INSIDE
+#      the recorder PTY; the MAXY_HIDDEN_SPAWN gate exits early so no
+#      recursion. The recorder's PTY exits naturally; its Stop is then
+#      driven by POST /<sessionId>/stop from the same hook invocation
+#      that posted /input.
 #
 # Gating:
-#   - MAXY_SESSION_ROLE must equal "admin" (skip public PTYs)
-#   - MAXY_HIDDEN_SPAWN must equal "0" (skip recursive fires from the
-#     hidden database-operator PTY itself; without this gate every
-#     recorder turn would spawn another recorder forever)
+#   - MAXY_SESSION_ROLE must equal "admin"
+#   - MAXY_HIDDEN_SPAWN must equal "0" (skip recursive fires)
 #
 # Input: Claude Code's Stop hook stdin shape
 #   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
 #
-# Output: one log line per fire on the user-facing session's stderr
-#   `turn-completed-graph-write fired conversationId=<8> tail-bytes=<n> ms=<n>`
-#
-# Failure modes are silent (exit 0) — this hook is observability + write
-# orchestration; a failure here must never break the operator's session.
+# Failure modes are silent (exit 0) — a failure here must never break the
+# operator's session.
 
 set -uo pipefail
 
 START_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
 
-# Gate 1: only fire on admin foreground PTYs.
 if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
   exit 0
 fi
 if [ "${MAXY_HIDDEN_SPAWN:-0}" = "1" ]; then
+  # Recorder PTY's own Stop hook. Read its session_id and ask the manager
+  # to SIGTERM the recorder so it does not idle in the active recents list
+  # after its single turn completes. Keep the JSONL — it's the audit trail.
+  if [ -t 0 ]; then
+    exit 0
+  fi
+  REC_INPUT=$(cat)
+  if [ -z "$REC_INPUT" ]; then
+    exit 0
+  fi
+  REC_SESSION_ID=$(printf '%s' "$REC_INPUT" | python3 -c '
+import sys, json
+try:
+  d = json.load(sys.stdin)
+  print(d.get("session_id", "") or "")
+except Exception:
+  print("")
+' 2>/dev/null)
+  if [ -z "$REC_SESSION_ID" ]; then
+    exit 0
+  fi
+  REC_PORT="${CLAUDE_SESSION_MANAGER_PORT:-19400}"
+  curl -sS -X POST \
+    --max-time 5 \
+    "http://127.0.0.1:${REC_PORT}/${REC_SESSION_ID}/stop" >/dev/null 2>&1
+  echo "[recorder] self-stop sessionId=${REC_SESSION_ID:0:8}" >&2
   exit 0
 fi
 
-# Gate 2: stdin must be a JSON envelope. Fail-open on parse failure.
 if [ -t 0 ]; then
   exit 0
 fi
@@ -40,8 +74,6 @@ if [ -z "$INPUT" ]; then
   exit 0
 fi
 
-# Extract session_id and transcript_path via python3 (grep on JSON is
-# fragile when values carry escaped quotes).
 PARSED=$(printf '%s' "$INPUT" | python3 -c '
 import sys, json
 try:
@@ -52,63 +84,121 @@ try:
 except Exception:
     print("\t")
 ' 2>/dev/null)
-SESSION_ID="${PARSED%%	*}"
+ADMIN_SESSION_ID="${PARSED%%	*}"
 TRANSCRIPT_PATH="${PARSED#*	}"
 
-if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+if [ -z "$ADMIN_SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
   exit 0
 fi
 
-# Read last 64 KiB of the transcript — enough for one completed turn
-# including a moderate tool transcript, bounded so the POST body never
-# balloons. tail -c is portable across BSD and GNU.
-TAIL_BYTES=$(wc -c < "$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ')
-TAIL_BYTES="${TAIL_BYTES:-0}"
-TURN_TAIL=$(tail -c 65536 "$TRANSCRIPT_PATH" 2>/dev/null)
+# Filter the JSONL tail down to records the database-operator cares about:
+# user prompts, assistant messages, and tool calls. Drop ephemeral
+# admin-state records that bloat the prompt without graph value.
+FILTERED_TAIL=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
+import sys, json
+DROP = {
+  'queue-operation', 'auto_mode', 'deferred_tools_delta',
+  'last-prompt', 'skill_listing', 'mcp_instructions_delta',
+  'permission-mode',
+}
+def keep(rec):
+  t = rec.get('type') if isinstance(rec, dict) else None
+  if not isinstance(t, str): return False
+  if t in DROP: return False
+  if t.startswith('hook_'): return False
+  if t in ('user', 'assistant', 'message'): return True
+  if 'tool' in t.lower(): return True
+  return False
+
+path = sys.argv[1]
+# Read whole file; admin transcripts are bounded by Claude Code's own
+# compaction so the read cost is reasonable. Take the last 200 records
+# from the kept set so a long transcript doesn't blow the prompt budget.
+out = []
+try:
+  with open(path, 'r', encoding='utf-8') as f:
+    for line in f:
+      line = line.strip()
+      if not line: continue
+      try: rec = json.loads(line)
+      except Exception: continue
+      if keep(rec): out.append(rec)
+except Exception:
+  pass
+out = out[-200:]
+print(json.dumps(out, separators=(',', ':')))
+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 — environment override or compile-time default. The
-# installer's systemd unit stamps CLAUDE_SESSION_MANAGER_PORT so this
-# resolves to the brand's loopback port at runtime.
 MANAGER_PORT="${CLAUDE_SESSION_MANAGER_PORT:-19400}"
+MANAGER_BASE="http://127.0.0.1:${MANAGER_PORT}"
 
-# Build the /spawn body. The recorder gets the raw transcript tail in
-# stdinPayload; the recorder agent parses the JSONL records itself
-# (admin-agent JSONL is more authoritative than any post-hoc summary the
-# hook could synthesise).
+# Spawn the recorder PTY. Manager blocks on its watcher's PID-file event
+# and returns the recorder's intrinsic sessionId in the response body.
 SPAWN_BODY=$(python3 -c '
-import sys, json
-sid = sys.argv[1]
-tail = sys.argv[2]
+import json, sys
 body = {
-    "senderId": "turn-recorder",
-    "role": "admin",
-    "channel": "browser",
-    "hidden": True,
-    "specialist": "database-operator",
-    "stdinPayload": json.dumps({
-        "conversationId": sid,
-        "occurredAt": __import__("datetime").datetime.utcnow().isoformat() + "Z",
-        "transcriptTail": tail,
-    }),
+  "senderId": "turn-recorder",
+  "role": "admin",
+  "channel": "browser",
+  "hidden": True,
+  "specialist": "database-operator",
 }
 print(json.dumps(body))
-' "$SESSION_ID" "$TURN_TAIL" 2>/dev/null)
+')
 
-if [ -z "$SPAWN_BODY" ]; then
+SPAWN_RES=$(curl -sS -X POST \
+  -H 'Content-Type: application/json' \
+  --max-time 10 \
+  --data "$SPAWN_BODY" \
+  "${MANAGER_BASE}/spawn" 2>/dev/null)
+
+RECORDER_SESSION_ID=$(printf '%s' "$SPAWN_RES" | python3 -c '
+import sys, json
+try:
+  d = json.load(sys.stdin)
+  print(d.get("sessionId", "") or "")
+except Exception:
+  print("")
+' 2>/dev/null)
+
+if [ -z "$RECORDER_SESSION_ID" ]; then
+  echo "turn-completed-graph-write spawn-failed conversationId=${ADMIN_SESSION_ID:0:8}" >&2
   exit 0
 fi
 
-# Fire-and-forget POST. The manager returns 200 on URL capture (~2 s);
-# we do not wait for it. curl is preferred (universally present on
-# Linux/macOS) — failure is silent.
+# Compose the input message: prompt prefix + filtered transcript JSON.
+INPUT_BODY=$(python3 -c '
+import sys, json
+sid = sys.argv[1]
+tail_json = sys.argv[2]
+prompt = (
+  "You are the database-operator specialist. Record the following completed turn "
+  "into the Neo4j graph. The transcript is a JSON array of filtered records "
+  "from the admin agent (user prompts, assistant responses, tool calls). "
+  f"Conversation id: {sid}.\n\nTranscript:\n{tail_json}\n"
+)
+print(json.dumps({"text": prompt}))
+' "$ADMIN_SESSION_ID" "$FILTERED_TAIL" 2>/dev/null)
+
+if [ -z "$INPUT_BODY" ]; then
+  exit 0
+fi
+
+INPUT_BYTES=$(printf '%s' "$INPUT_BODY" | wc -c | tr -d ' ')
+
 curl -sS -X POST \
   -H 'Content-Type: application/json' \
   --max-time 5 \
-  --data "$SPAWN_BODY" \
-  "http://127.0.0.1:${MANAGER_PORT}/spawn" >/dev/null 2>&1 &
+  --data "$INPUT_BODY" \
+  "${MANAGER_BASE}/${RECORDER_SESSION_ID}/input" >/dev/null 2>&1
+
+echo "[recorder] input-posted sessionId=${RECORDER_SESSION_ID:0:8} bytes=${INPUT_BYTES} filtered-from-records=${FILTERED_COUNT}" >&2
 
 END_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
 ELAPSED=$((END_MS - START_MS))
-echo "turn-completed-graph-write fired conversationId=${SESSION_ID:0:8} tail-bytes=${TAIL_BYTES} ms=${ELAPSED}" >&2
+echo "turn-completed-graph-write fired conversationId=${ADMIN_SESSION_ID:0:8} recorderSessionId=${RECORDER_SESSION_ID:0:8} filtered=${FILTERED_COUNT} ms=${ELAPSED}" >&2
 
 exit 0

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

@@ -87,6 +87,12 @@ The manager also runs a boot-time self-test that renders a fixture compose call
 
 LOUD-FAIL output is `startup-self-test system-prompt-sentinels=fail missing=<tag>` followed by an immediate process exit. Catches IDENTITY-promise-vs-emitter drift at boot rather than at the first real spawn.
 
+### Pre-publish boot smoke
+
+`platform/scripts/smoke-boot-services.sh` runs inside `prepublishOnly` of the installer (`packages/create-maxy-code/`). For every service in its `SERVICES` list it builds a synthetic install dir (`brand.json`, empty `plugins/`, a single `account.json` with `agents/admin/{IDENTITY,SOUL}.md`), spawns `node dist/index.js`, waits up to 5 s for the canonical `[claude-session-manager] boot port=…` line, SIGTERMs, and fails publish if any `^\[.*\] fatal ` line appears in stdout/stderr. Catches the class of regressions tsc and vitest miss because they evaluate TS source rather than the compiled ESM module (e.g. a stray `require()` in an ESM-typed package: tsc allows it because `@types/node` declares `require` globally, and Vite's vitest loader shims it, but native Node ESM throws `ReferenceError: require is not defined` at boot).
+
+Companion lint: `platform/scripts/check-no-esm-require.mjs` rejects `require(` calls in any `.ts/.tsx/.js` file inside a package with `"type": "module"`, also wired into `prepublishOnly`. Allowlist lives at the top of the script.
+
 ## Service Management
 
 {{productName}} runs via systemd and starts automatically on boot. You don't need to start it manually. To check if it's running, ask {{productName}} "Check system status."

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

@@ -70,15 +70,17 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
-The admin interface is a three-pane layout: a sidebar on the left with navigation (Sessions, People, Agents, Projects, Tasks, Artefacts) and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu, holding the surface side-by-side with the conversation so the chat stays live while you work in it. At the very top of the sidebar — above the nav rows — a borderless row holds two controls: a "+ New session" button on the left that spawns a fresh Claude Code session, and a Mode trigger on the right showing the current permission mode (Ask, Accept edits, Plan, or Auto). The sidebar's vertical order is: new-session strip first, then the nav (Sessions, People, Agents, Projects, Tasks, Artefacts), then the sessions list, then the footer. Both controls render as plain text-plus-icon affordances with no surrounding rectangle. The "+ New session" button is a text-width hit target — its clickable area is exactly the icon plus label, not the whole row — and shows no hover fill; the only hover feedback is the pointer cursor. The Mode trigger is pushed flush to the right edge of the row. Clicking the Mode trigger opens a popover downward from the row whose header reads "Mode" and lists the four permission modes with the current selection check-marked. The sidebar's nav rows swap the list view in place: Sessions shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Each recent session row carries a small status dot (filled sage for alive, hollow circle for ended) so you can read the live state at a glance without parsing the subtitle. The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list, because the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable: type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood; clicking a second project swaps the focus rather than stacking on top. The chat and artefact divider is drag-resizable: drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat and artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On every viewport the chat header reads left to right as a triptych: a dedicated sidebar toggle (the panel-right icon, which swaps to panel-right-open when the sidebar is showing), the brand mark next to the title in the centre, and the menu burger on the right. This header toggle is the sole sidebar-toggle button; the sidebar itself no longer carries a duplicate. Tap the sidebar toggle to show or hide the sidebar: on phones (<720px) it slides the drawer in or out, on wider screens it collapses or expands the sidebar column. The brand mark in the centre is decorative; clicks go through the dedicated toggle so the affordance is unambiguous. The drawer animation only fires on tap (220ms slide in or out); resizing your window across the 720px boundary snaps the layout without animation, so you never see a half-open flash. At ≤640px the session metadata pane stacks each label above its value instead of the desktop two-column grid, and the row of action buttons (Open in new tab / Open JSONL / Rename / Pin / Archive / End or Purge) collapses behind a single Actions trigger that opens a popover upward from the foot of the pane. Breakpoint summary: >1280px = full sidebar + chat + artefact pane (drag-resizable divider); 1280px→1080px = sidebar narrows; 1080px→820px = artefact pane hides (Browser/Data/Graph open as full-window pages instead); 820px→720px = sidebar collapses to 56px icon rail; ≤720px = sidebar becomes off-canvas drawer (vertical stack of nav, recents list, foot, the same shape as the desktop sidebar, just on top of the chat instead of beside it).
+The admin interface is a three-pane layout: a sidebar on the left with navigation (Sessions, People, Agents, Projects, Tasks, Artefacts) and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu, holding the surface side-by-side with the conversation so the chat stays live while you work in it. At the very top of the sidebar — above the nav rows — a borderless row holds two controls: a "+ New session" button on the left that spawns a fresh Claude Code session, and a Mode trigger on the right showing the current permission mode (Ask, Accept edits, Plan, or Auto). The sidebar's vertical order is: new-session strip first, then the nav (Sessions, People, Agents, Projects, Tasks, Artefacts), then the sessions list, then the footer. Both controls render as plain text-plus-icon affordances with no surrounding rectangle. The "+ New session" button is a text-width hit target — its clickable area is exactly the icon plus label, not the whole row — and shows no hover fill; the only hover feedback is the pointer cursor. The Mode trigger is pushed flush to the right edge of the row. Clicking the Mode trigger opens a popover downward from the row whose header reads "Mode" and lists the four permission modes with the current selection check-marked. The sidebar's nav rows swap the list view in place: Sessions shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Each recent session row carries a three-state indicator: three pulsing dots when the session is busy (currently processing a turn), a solid sage dot when it is idle (live PTY waiting for input), and a hollow ring when it is archived (PTY exited, JSONL on disk for audit). The list itself splits into three views via a segmented control above the rows: **Active** shows every live session, **Archived** shows every JSONL on disk whose PTY has exited, and **All** shows both. The view choice persists across reloads. An "Include subagents" toggle inside the Active view surfaces specialist spawns (the database-operator recorder, premium-plugin agents, anything spawned with a `--agent` flag) which are hidden by default so the list reflects what you started directly. Each row also carries a small uppercase badge — `admin` for operator-driven sessions, the specialist name (for example `db-op`) for background work — so the source of any row is unambiguous at a glance. The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list, because the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable: type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood; clicking a second project swaps the focus rather than stacking on top. The chat and artefact divider is drag-resizable: drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat and artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On every viewport the chat header reads left to right as a triptych: a dedicated sidebar toggle (the panel-right icon, which swaps to panel-right-open when the sidebar is showing), the brand mark next to the title in the centre, and the menu burger on the right. This header toggle is the sole sidebar-toggle button; the sidebar itself no longer carries a duplicate. Tap the sidebar toggle to show or hide the sidebar: on phones (<720px) it slides the drawer in or out, on wider screens it collapses or expands the sidebar column. The brand mark in the centre is decorative; clicks go through the dedicated toggle so the affordance is unambiguous. The drawer animation only fires on tap (220ms slide in or out); resizing your window across the 720px boundary snaps the layout without animation, so you never see a half-open flash. At ≤640px the session metadata pane stacks each label above its value instead of the desktop two-column grid, and the row of action buttons (Open in new tab / Open JSONL / Rename / Pin / Archive / End or Purge) collapses behind a single Actions trigger that opens a popover upward from the foot of the pane. Breakpoint summary: >1280px = full sidebar + chat + artefact pane (drag-resizable divider); 1280px→1080px = sidebar narrows; 1080px→820px = artefact pane hides (Browser/Data/Graph open as full-window pages instead); 820px→720px = sidebar collapses to 56px icon rail; ≤720px = sidebar becomes off-canvas drawer (vertical stack of nav, recents list, foot, the same shape as the desktop sidebar, just on top of the chat instead of beside it).
 
 Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.
 
-**Session lifecycle and reconcile model.** The sidebar Sessions list and the ConversationsModal share one fetch loop (`useAdminSessions`). Every fetch is operator-triggered: first load on mount (`ensureLoaded`), the refresh button on the sessions group head, and a single `refetch` appended to every mutation in `session-actions` (resume, end, purge, archive, unarchive). There is no idle ticker; the UI does not call `/api/admin/claude-sessions` between operator actions, so the DevTools console stays quiet while you are not clicking anything. Each fetch emits exactly one line: `[admin-ui] sessions-poll outcome=<unchanged|changed|error> count=<n> cacheKey=<8>`. The format is held from the prior polling shape so existing log greps still match; the rate just drops to one per user action. Byte-identical responses skip the `setSessions` commit (projection-equality gate) so AdminShell does not re-render when the list has not changed.
+**Session lifecycle and reconcile model.** The sidebar Sessions list is driven by a single Server-Sent Events feed at `/api/admin/claude-sessions/events`. The session manager watches the two directories Claude Code writes (`${CLAUDE_CONFIG_DIR}/sessions/<pid>.json` for live state, `${CLAUDE_CONFIG_DIR}/projects/<slug>/<sid>.jsonl` for transcripts) and emits `row-created`, `row-updated`, `row-archived`, or `row-removed` deltas to every connected browser tab. On connect the manager replays the current row index so a freshly-opened tab catches up without polling, then streams deltas as files change on disk. Two open tabs see the same list within ~300ms of any spawn, status flip, or exit; no refresh button required for state to be current. The legacy `/list` fetch and `useAdminSessions` hook stay mounted to serve the ConversationsModal and the post-action reconcile path in `session-actions`, but the sidebar's visible rows come from the row store, not from `/list`. Each EventSource open emits `[admin-events] client-connected ip=<…> seeded-rows=<n>` server-side and `[admin-ui] session-row-store connected events-received=<n>` in the browser console; transport drops log `[admin-ui] session-row-store reconnect attempt=<n>` until the EventSource reattaches.
 
-The trade-off is staleness for PTY exits that happen outside this UI: a Claude Code crash, an `ssh` kill of the brand process, or a sibling tab spawning a new session stays invisible in the current tab until you click the refresh button or perform another mutation. Two open tabs can show different lists until both refresh. The accepted view is that every lifecycle event in this dashboard originates from a click in this dashboard, so a missing ticker cannot deliver information the operator did not already cause.
+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: optimistic, then reconcile.** Clicking "+ New session" returns a usable row inside a couple of seconds, even when you don't immediately type. The manager spawns the PTY, captures the `/remote-control` URL, registers the row under the URL's bridge suffix, and returns 200; the row is visible in the sidebar at that point with `claudeSessionId: null`. Claude Code writes its per-session JSONL transcript only when you submit the first turn (true on 2.1.143 and 2.1.128), so the intrinsic session id (the JSONL basename) is null until then. When you type, the manager observes the JSONL appearing on disk and promotes the row to the intrinsic id without changing its sidebar position; subsequent route calls accept either the bridge suffix or the intrinsic id and resolve to the same row. If you close an idle session without typing, the row leaves the list cleanly and no JSONL is created. There is no 5-second timeout that kills an otherwise-healthy claude — operator typing latency is unbounded by design.
+**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.
+
+**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.
 
 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.
 
@@ -122,3 +124,15 @@ When your public agent sends a message to someone — via email, WhatsApp, Teleg
 - **SMS:** a brief suffix is appended when the message is AI-composed
 
 Messages you write yourself (e.g. typing directly in WhatsApp) are not marked — the disclosure applies only to content composed by the AI agent.
+
+## Session Slot Safeguards
+
+{{productName}} runs each chat — yours and every visitor's — as a separate `claude` process on your Pi. Three safeguards keep these processes from piling up:
+
+- **Specialist cap.** Background specialists (`database-operator`, `content-producer`, etc.) are limited to three running at once. If you ask for a fourth while three are still working, the oldest idle one is shut down first. If all three are actively running, the request is rejected with `specialist-cap-reached`.
+- **Operator reserve.** Two slots are always held back for *you* — your own chats and one-off tasks. Specialist work that would consume the last reserved slot is rejected with `operator-slots-reserved`. Your interactive chats are never blocked.
+- **Idle reaper.** Every 30 seconds the platform looks for specialist processes that started, then went silent without producing any output. After two minutes of silence the platform shuts them down.
+
+All three are tunable via env vars (`CLAUDE_SESSION_MANAGER_SPECIALIST_CAP`, `CLAUDE_SESSION_MANAGER_OPERATOR_RESERVE`, `CLAUDE_SESSION_MANAGER_TOTAL_PTY_CAP`, `CLAUDE_SESSION_MANAGER_RECORDER_IDLE_TTL_MS`); developer details in `.docs/platform.md` § "Claude Session Manager — PTY Slot Safeguards".
+
+If you suspect background processes are piling up, run `grep '\[reaper\]' ~/.{brand}/logs/server.log | tail -50` — each tick logs how many rows it scanned and reaped.

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

@@ -141,6 +141,8 @@ initStderrTee("your-plugin-name");
 
 After this, every `console.error("[your-tool]...")` from any tool in the plugin appears as `[<iso-ts>] [mcp:your-plugin-name] [your-tool]...` in the per-conversation stream log `claude-agent-stream-{conversationId}.log`, alongside the usual agent events. The raw per-server file `mcp-your-plugin-name-stderr-{date}.log` is still produced for deep-dive grep.
 
+**Premium plugins.** Source lives at `premium-plugins/<bundle>/plugins/<name>/mcp/src/` — deeper than platform plugins, so the source-relative import to `platform/lib/mcp-stderr-tee/dist/index.js` uses more `../` segments. The bundler rewrites the compiled output to the canonical `../../../../lib/mcp-stderr-tee/dist/index.js` at staging time and ships `platform/lib/mcp-stderr-tee/{dist,package.json}` into `premium-plugins/<bundle>/lib/mcp-stderr-tee/` so the import resolves at deployed depth. The bundler fails loudly if `platform/lib/mcp-stderr-tee/package.json` is missing (it must pin `type` so install-location parent walks cannot mis-classify the dist file) or if any lib referenced by a rewritten import has no source dist.
+
 **How the tee decides which file to write to:** the platform sets `STREAM_LOG_PATH` as an environment variable on every MCP server spawn, pointing to the conversation-scoped stream log. The MCP server does not know about conversations — it just trusts `STREAM_LOG_PATH`. Multiple concurrent conversations produce multiple concurrent MCP server processes, each teeing to its own file; no cross-conversation leakage.
 
 **`STREAM_LOG_PATH` reaches every Claude Code child.** The platform now sets `STREAM_LOG_PATH` on the parent `claude` spawn env itself (not only on MCP server envs), so the bundled Bun runtime inherits it and every Bash-tool subprocess the CLI spawns sees it too. Opt-in shell scripts — currently `setup-tunnel.sh`, `reset-tunnel.sh`, and `list-cf-domains.sh` under `platform/plugins/cloudflare/scripts/` — read the variable, guard against a missing value with a loud exit, and tee subprocess output line-by-line into the same per-conversation file. Each spawn writes one `[spawn-env] STREAM_LOG_PATH=set pid=… conversationId=… site=…` line so the env-propagation is auditable per session. The chat UI tails the same file for lines matching `^\[([^\]]+)\] \[([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] ` — any lowercase scope shape participates on first write (earlier platform fixes generalised from the pre-592 enum `setup-tunnel|reset-tunnel`) — and emits them as `script_stream` SSE events; see `.docs/web-chat.md` for the contract. Inner-layer helpers that a.sh wrapper spawns (e.g. `list-cf-domains.ts` via `node --experimental-strip-types`) must write phase lines directly to `STREAM_LOG_PATH` rather than relying on stderr propagation; the build-gate `platform/ui/scripts/check-stream-log-contract.mjs` enforces this and is the definitive reference for the three allowed patterns (tee-wrapped, direct-write, or explicit stderr-only marker).

package/payload/platform/scripts/check-no-esm-require.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Build-time gate: reject `require(` calls in TS/JS files that belong to a
+// package whose package.json declares `"type": "module"`. Such calls compile
+// fine under `tsc` (because `@types/node` declares `require` globally) and
+// pass vitest (Vite shims `require` in its loader), but throw
+// `ReferenceError: require is not defined` at runtime in native ESM.
+//
+// Live repro: Task 094 introduced `const { mkdirSync } = require('node:fs')`
+// in claude-session-manager/src/fs-watcher.ts. tsc + vitest were green; the
+// installed service crash-looped on boot at every admin request. See Task 099.
+//
+// Scope: walks every directory under REPO_ROOT containing a package.json with
+// `"type": "module"`, and scans .ts/.tsx/.js (NOT .cjs / .mjs / node_modules /
+// dist / payload / build) for `require(`. Comments are skipped. An explicit
+// allowlist names files where `require` is intentional (e.g. vitest tests that
+// load CJS-only modules via `vi.hoisted`).
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+
+const SCANNABLE_EXTS = new Set(['.ts', '.tsx', '.js'])
+const SKIP_DIR_NAMES = new Set([
+  'node_modules', 'dist', 'build', '.next', 'payload', '.git', 'coverage',
+  // Worktree checkouts under .claude/worktrees/** are siblings of the live tree
+  // and their own gate runs scan them; the top-level gate must not double-scan.
+  'worktrees',
+])
+
+// Files where `require()` is intentional. Each entry is a path relative to
+// REPO_ROOT. Add with a one-line comment explaining why the call is required
+// in an ESM package; if the reason no longer applies, delete the entry.
+const ALLOWLIST = new Set([
+  // vitest hoists this fixture BEFORE the test module's own ESM imports are
+  // resolved; `vi.hoisted` runs in CJS context where `require` is the only
+  // available loader. The module under test is pure ESM.
+  'platform/ui/server/routes/admin/__tests__/files-delete-cascade.test.ts',
+])
+
+const REQUIRE_CALL_RE = /\brequire\s*\(/
+
+/** Walk REPO_ROOT and collect every directory containing a package.json that
+ *  declares `"type": "module"`. The walk skips SKIP_DIR_NAMES (node_modules,
+ *  dist, etc.) to keep the cost bounded. */
+function findEsmPackageRoots(root) {
+  const roots = []
+  function walk(dir) {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    const hasPkg = entries.some((e) => e.isFile() && e.name === 'package.json')
+    if (hasPkg) {
+      const pkgPath = join(dir, 'package.json')
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        if (pkg.type === 'module') roots.push(dir)
+      } catch {
+        // malformed package.json — not this gate's job
+      }
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      if (SKIP_DIR_NAMES.has(e.name)) continue
+      walk(join(dir, e.name))
+    }
+  }
+  walk(root)
+  return roots
+}
+
+function collectFiles(root) {
+  const out = []
+  function walk(dir) {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      const full = join(dir, e.name)
+      if (e.isDirectory()) {
+        if (SKIP_DIR_NAMES.has(e.name)) continue
+        walk(full)
+        continue
+      }
+      if (!e.isFile()) continue
+      const dot = e.name.lastIndexOf('.')
+      if (dot < 0) continue
+      const ext = e.name.slice(dot)
+      if (!SCANNABLE_EXTS.has(ext)) continue
+      out.push(full)
+    }
+  }
+  walk(root)
+  return out
+}
+
+function isCommentLine(line) {
+  const t = line.trimStart()
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')
+}
+
+const esmRoots = findEsmPackageRoots(REPO_ROOT)
+const violations = []
+
+for (const root of esmRoots) {
+  for (const file of collectFiles(root)) {
+    const rel = relative(REPO_ROOT, file).split(sep).join('/')
+    if (ALLOWLIST.has(rel)) continue
+    const lines = readFileSync(file, 'utf-8').split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (!REQUIRE_CALL_RE.test(line)) continue
+      if (isCommentLine(line)) continue
+      violations.push({ file: rel, lineNumber: i + 1, line: line.trim() })
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error(`[check-no-esm-require] ${violations.length} require() call(s) in ESM package(s):`)
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.lineNumber}  ${v.line}`)
+  }
+  console.error('')
+  console.error('require() throws ReferenceError at runtime in native ESM.')
+  console.error('Replace with a top-of-file `import` statement, or add an explicit')
+  console.error('ALLOWLIST entry in platform/scripts/check-no-esm-require.mjs with a')
+  console.error('one-line comment explaining why the call is required.')
+  process.exit(1)
+}
+
+console.log(`[check-no-esm-require] scanned ${esmRoots.length} ESM package(s); 0 violations`)