@rubytech/create-realagent-code 0.1.115 → 0.1.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/neo4j/schema.cypher

@@ -1100,3 +1100,76 @@ FOR (h:CloudflareHostname) REQUIRE (h.accountId, h.hostnameValue) IS UNIQUE;
 
 CREATE INDEX cloudflare_hostname_account IF NOT EXISTS
 FOR (h:CloudflareHostname) ON (h.accountId);
+
+// ----------------------------------------------------------
+// Estate-agent ontology (Task 358) — Listing-centric model
+// documented at platform/plugins/memory/references/schema-estate-agent.md.
+//
+// These declarations exist primarily so the memory-write validator's
+// parseLabelsFromSchemaCypher() registers each label on a fresh deploy
+// where no node of the label has yet landed — without them, the first
+// :Listing write from the listing-curator agent is rejected as "unknown
+// label" against an empty db.labels() set.
+//
+// Idempotency contracts mirror schema-estate-agent.md:
+//   :Listing / :Viewing / :Offer — (accountId, sourceSystem, sourceId)
+//   :Property                    — (accountId, slug)
+//   :ImageObject                 — (accountId, listingSlug, url) for the
+//                                  estate-agent variant, (accountId, name,
+//                                  contentUrl) for the brand-asset variant.
+//                                  Because the two writers use different
+//                                  natural keys, only an accountId index is
+//                                  declared at the schema level — uniqueness
+//                                  is enforced at write time by the curator
+//                                  / brand-asset writer's MERGE clause.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT listing_account_source_unique IF NOT EXISTS
+FOR (l:Listing) REQUIRE (l.accountId, l.sourceSystem, l.sourceId) IS UNIQUE;
+
+CREATE INDEX listing_account IF NOT EXISTS
+FOR (l:Listing) ON (l.accountId);
+
+CREATE INDEX listing_status IF NOT EXISTS
+FOR (l:Listing) ON (l.status);
+
+CREATE INDEX listing_type IF NOT EXISTS
+FOR (l:Listing) ON (l.listingType);
+
+CREATE VECTOR INDEX listing_embedding IF NOT EXISTS
+FOR (l:Listing) ON (l.embedding)
+OPTIONS {
+  indexConfig: {
+    `vector.dimensions`: 768,
+    `vector.similarity_function`: 'cosine'
+  }
+};
+
+CREATE CONSTRAINT property_account_slug_unique IF NOT EXISTS
+FOR (p:Property) REQUIRE (p.accountId, p.slug) IS UNIQUE;
+
+CREATE INDEX property_account IF NOT EXISTS
+FOR (p:Property) ON (p.accountId);
+
+CREATE CONSTRAINT viewing_account_source_unique IF NOT EXISTS
+FOR (v:Viewing) REQUIRE (v.accountId, v.sourceSystem, v.sourceId) IS UNIQUE;
+
+CREATE INDEX viewing_account IF NOT EXISTS
+FOR (v:Viewing) ON (v.accountId);
+
+CREATE CONSTRAINT offer_account_source_unique IF NOT EXISTS
+FOR (o:Offer) REQUIRE (o.accountId, o.sourceSystem, o.sourceId) IS UNIQUE;
+
+CREATE INDEX offer_account IF NOT EXISTS
+FOR (o:Offer) ON (o.accountId);
+
+CREATE INDEX image_object_account IF NOT EXISTS
+FOR (i:ImageObject) ON (i.accountId);
+
+// :PostalAddress (schema:PostalAddress) — shared address nodes documented in
+// schema-base.md. Address rows are deliberately accountId-free (one address
+// can be shared across customers / orders / listings); writers MERGE on the
+// formatted address triple. Declared here so a fresh deploy registers the
+// label before the first :PostalAddress write lands.
+CREATE INDEX postal_address_postcode IF NOT EXISTS
+FOR (a:PostalAddress) ON (a.postalCode);

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

@@ -1,5 +1,6 @@
 ---
 name: admin
+surface: platform
 description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, file-attach, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform."
 tools:
   - name: system-status
@@ -136,6 +137,7 @@ Tools are available via the `admin` MCP server.
 - `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/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) when no read-only investigation tool has fired since the latest real user turn in the session JSONL. The structural fix for the failure class where the agent fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
 - `hooks/session-end-retrospective.sh` — **Stop hook.** Fires on every assistant end_turn but exits 0 with `trigger-skipped reason=<role-not-admin|is-specialist|empty-stdin|missing-transcript|no-intent-match>` on every path EXCEPT when the operator's latest real-user message carries an end-intent token (`/end`, `/archive`, `end session`, `archive this session`, case-insensitive, must match the whole message or a standalone line — not embedded in prose). On that path the hook blocks (exit 2 + structured retrospective instruction on stderr per Stop-hook contract) and emits `[session-retrospective] gate-blocked sessionId=<id> reason=sentinel-absent` until the admin agent calls the `session-retrospective-mark-complete` MCP sentinel tool. Completion is recognised by greping the operator's own JSONL (`transcript_path` on the Stop envelope) for a `tool_use` block whose `name` equals that exact string — never by parsing prose ([[feedback_no_stdout_parsing_for_control_flow]], [[feedback_doctrine_paragraph_is_not_a_gate]]). The sentinel-grep doubles as the re-entry guard: every Stop after the sentinel call sees it and exits 0 with `gate-released sessionId=<id>`. Recursion guard: any session whose `MAXY_SPECIALIST` env is set (specialist subagent dispatched via Task tool) skips the gate. The Sidebar archive button POSTs `/:sessionId/archive` directly to the manager which kills the PTY — no Stop fires after that, so clicking archive is the operator's current escape hatch (opt-out remains deferred per the task spec). All emits go through `POST /api/admin/log-ingest`; the only stderr writer is the gate-blocked path (the instruction block the agent reads). The retrospective itself runs as one or more additional turns inside the operator's existing admin session — Task-tool delegation to `database-operator` is the existing IDENTITY.md "Recording" route, not a parallel admin session ([[feedback_deterministic_means_remove_llm]]).
+- `hooks/signal-detector-stop.sh` — **Stop hook.** Task 303 — gbrain port. Fires on every admin-agent end_turn alongside `session-end-retrospective.sh` (both registered on the Stop matcher). Inspects the operator's JSONL transcript and decides whether to dispatch the `signal-detector` specialist for background brain-compounding. Throttle gates: ≥3 new real-user turns since the most recent in-transcript Task call with `subagent_type=signal-detector` (overridable via `MAXY_SIGNAL_DETECTOR_MIN_NEW_TURNS`) AND ≥30 000 ms since the latest real-user message's `timestamp` (overridable via `MAXY_SIGNAL_DETECTOR_MIN_IDLE_MS`). Below either threshold → exit 0 with `trigger-skipped reason=below-{turn,idle}-threshold`. Recursion guard mirrors `session-end-retrospective.sh`: any session with `MAXY_SPECIALIST` set on the PTY env is skipped, plus the in-transcript Task-call grep means the very next Stop after the agent's dispatch turn sees the call and exits 0 (`reason=already-dispatched`). Gate-blocked path emits exit 2 + stderr directive `[system: signal-detector-stop-hook]` per Stop-hook contract; the admin IDENTITY.md "Stop-hook system directives" section binds the agent's response shape (perform one `Task` dispatch, emit a single-space ack, stop). First-fire bootstrap: idempotently copies the template from `$MAXY_PLATFORM_ROOT/templates/specialists/agents/signal-detector.md` into `$ACCOUNT_DIR/specialists/agents/` and appends the AGENTS.md routing line so the specialist is available platform-core without onboarding-flow surgery. All emits go through `POST /api/admin/log-ingest` under tag `signal-detector-hook`. Operator-channel doctrine: by design, only the admin agent's stop fires this hook (public/visitor channels never do — high-value signal flows through the operator, not the visitor).
 - `hooks/turn-completed-graph-write.sh` — **Dormant since Task 214** — the Stop-hook registration is no longer written to account settings.json; admin delegates graph writes to `database-operator` via the Task tool. The script, envelope walker, loopback `/api/admin/claude-sessions` 127.0.0.1 bypass, `[turn-recorder]` emitters, recorder-auto-archive subscriber, and `initialMessage` envelope spec are preserved as reusable infrastructure for any future autonomous post-turn flow. Historical contract (still describes the dormant path): Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `conversationId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 
 ## Session identifiers (Task 135)

package/payload/platform/plugins/admin/hooks/signal-detector-stop.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# Stop hook — gbrain signal-detector dispatch. Task 303.
+#
+# Fires on every admin-agent assistant end_turn. Inspects the operator's
+# JSONL transcript and decides whether to invoke the `signal-detector`
+# specialist to extract entity mentions and original-thinking candidates
+# from the conversation slice since the last dispatch.
+#
+# Trigger logic (must clear both gates to fire):
+#   - >= MIN_NEW_TURNS new real-user messages since the most recent
+#     in-transcript Task dispatch with subagent_type='signal-detector'
+#     (default 3 — overridable via MAXY_SIGNAL_DETECTOR_MIN_NEW_TURNS).
+#   - >= MIN_IDLE_MS milliseconds since the latest real-user message's
+#     `timestamp` (default 30_000 — overridable via
+#     MAXY_SIGNAL_DETECTOR_MIN_IDLE_MS). Captures "operator paused, not
+#     mid-thought".
+#
+# Recursion guard. The dispatch resolves through a Task tool call carrying
+# `subagent_type=signal-detector`; once such a call appears in the transcript
+# after the latest real-user message, the gate has already fired for this
+# turn and must NOT re-fire. Same shape as
+# session-end-retrospective.sh's sentinel grep
+# ([[feedback_no_stdout_parsing_for_control_flow]] /
+# [[feedback_doctrine_paragraph_is_not_a_gate]]) — control flow gates on a
+# structural tool_use, never on prose.
+#
+# Specialist auto-install on first fire. The template ships at
+# `$MAXY_TEMPLATES_DIR/specialists/agents/signal-detector.md` (or
+# `$ACCOUNT_DIR/../templates/...` via PLATFORM_ROOT). On the first fire
+# that decides to dispatch, the hook idempotently copies the template into
+# `$ACCOUNT_DIR/specialists/agents/` and appends the AGENTS.md routing line
+# if absent — so signal-detector is platform-core (no operator install
+# step) without surgery on the onboarding flow.
+#
+# Gating (emits via `/api/admin/log-ingest`; stderr stays silent on every
+# skip path; the gate-blocked path is the only stderr emitter, by Stop-hook
+# contract — exit 2 + stderr is how the agent receives the dispatch
+# directive):
+#   - MAXY_SESSION_ROLE must equal "admin"            → reason=role-not-admin
+#   - MAXY_SPECIALIST must be empty                   → reason=is-specialist
+#   - Stop-hook stdin must be non-empty               → reason=empty-stdin
+#   - transcript_path must exist on disk              → reason=missing-transcript
+#   - new real-user turns since last fire < MIN_NEW   → reason=below-turn-threshold
+#   - idle_ms < MIN_IDLE_MS                           → reason=below-idle-threshold
+#   - latest real-user message older than the latest  → reason=already-dispatched
+#     signal-detector dispatch
+#
+# Blocks:
+#   - gate-blocked sessionId=<id> reason=dispatching newTurns=<n> idleMs=<n>
+#
+# Input: Claude Code's Stop hook stdin shape
+#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
+
+set -uo pipefail
+
+MIN_NEW_TURNS="${MAXY_SIGNAL_DETECTOR_MIN_NEW_TURNS:-3}"
+MIN_IDLE_MS="${MAXY_SIGNAL_DETECTOR_MIN_IDLE_MS:-30000}"
+
+UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
+if [ -z "$UI_PORT" ]; then
+  echo "[signal-detector-hook] trigger-skipped sessionId=unknown reason=missing-env env=MAXY_UI_INTERNAL_PORT" >&2
+  exit 0
+fi
+UI_BASE="http://127.0.0.1:${UI_PORT}"
+LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
+
+emit_log() {
+  local line="$1"
+  curl -sS -o /dev/null -X POST \
+    -H 'Content-Type: application/json' \
+    --max-time 2 \
+    --data "$(python3 -c '
+import sys, json
+print(json.dumps({"tag": "signal-detector-hook", "level": "info", "line": sys.argv[1]}))
+' "$line")" \
+    "$LOG_INGEST_URL" 2>/dev/null || true
+}
+
+INPUT=""
+if [ -t 0 ]; then
+  INPUT=""
+else
+  INPUT=$(cat)
+fi
+
+PARSED=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    sid = d.get("session_id", "") or ""
+    tpath = d.get("transcript_path", "") or ""
+    print(f"{sid}\t{tpath}")
+except Exception:
+    print("\t")
+' 2>/dev/null)
+SESSION_ID="${PARSED%%	*}"
+TRANSCRIPT_PATH="${PARSED#*	}"
+SESSION_ID_REPORTED="${SESSION_ID:-unknown}"
+
+if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=role-not-admin"
+  exit 0
+fi
+# Recursion guard. A specialist subagent (database-operator, signal-detector
+# itself, etc.) stamps `MAXY_SPECIALIST` on its PTY env. Skip — the hook
+# only fires on the operator's own admin session, never on a subagent's
+# own stop.
+if [ -n "${MAXY_SPECIALIST:-}" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=is-specialist specialist=${MAXY_SPECIALIST}"
+  exit 0
+fi
+if [ -z "$INPUT" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=empty-stdin"
+  exit 0
+fi
+if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=missing-transcript"
+  exit 0
+fi
+
+# Single Python pass over the transcript. Returns three tab-separated
+# fields:
+#   1. count of real-user messages whose timestamp is more recent than the
+#      latest in-transcript Task dispatch with subagent_type=signal-detector
+#      (or, when no such dispatch exists yet, the total real-user count)
+#   2. idle_ms — milliseconds between the latest real-user message's
+#      timestamp and now (hook fire time)
+#   3. excerpt — the latest real-user message's text, truncated to 2000
+#      chars and base64-encoded so newlines and quotes survive the shell
+#      round-trip
+INSPECTION=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
+import os, json, base64
+from datetime import datetime, timezone
+
+def is_real_user(rec):
+    if not isinstance(rec, dict) or rec.get("type") != "user":
+        return False
+    msg = rec.get("message")
+    if not isinstance(msg, dict) or msg.get("role") != "user":
+        return False
+    content = msg.get("content")
+    if isinstance(content, str):
+        return True
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") != "tool_result":
+                return True
+        return False
+    return True
+
+def extract_user_text(rec):
+    msg = rec.get("message", {}) or {}
+    content = msg.get("content")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        out = []
+        for b in content:
+            if isinstance(b, dict) and b.get("type") == "text":
+                t = b.get("text")
+                if isinstance(t, str):
+                    out.append(t)
+        return "".join(out)
+    return ""
+
+def latest_signal_detector_dispatch_index(records):
+    """Return the index of the most recent assistant tool_use of `Task`
+    whose `subagent_type` is `signal-detector`, or -1 if none."""
+    for i in range(len(records) - 1, -1, -1):
+        rec = records[i]
+        if not isinstance(rec, dict) or rec.get("type") != "assistant":
+            continue
+        msg = rec.get("message", {}) or {}
+        if msg.get("role") != "assistant":
+            continue
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for b in content:
+            if not isinstance(b, dict) or b.get("type") != "tool_use":
+                continue
+            if b.get("name") != "Task":
+                continue
+            inp = b.get("input", {})
+            if isinstance(inp, dict) and inp.get("subagent_type") == "signal-detector":
+                return i
+    return -1
+
+path = os.environ["TRANSCRIPT_PATH"]
+records = []
+try:
+    with open(path, "r", encoding="utf-8") as f:
+        for raw in f:
+            raw = raw.strip()
+            if not raw:
+                continue
+            try:
+                records.append(json.loads(raw))
+            except Exception:
+                continue
+except Exception:
+    # Fail-open — print empty fields, the bash side will treat as missing.
+    print("0\t0\t")
+    raise SystemExit(0)
+
+last_dispatch_idx = latest_signal_detector_dispatch_index(records)
+
+# Count real-user messages after last_dispatch_idx (exclusive); when
+# last_dispatch_idx is -1, count from the start.
+new_user_count = 0
+latest_user_ts = None
+latest_user_text = ""
+start = last_dispatch_idx + 1
+for i in range(start, len(records)):
+    rec = records[i]
+    if is_real_user(rec):
+        new_user_count += 1
+        ts = rec.get("timestamp") or ""
+        if isinstance(ts, str) and ts:
+            latest_user_ts = ts
+            latest_user_text = extract_user_text(rec).strip()
+
+if latest_user_ts is None:
+    print(f"{new_user_count}\t0\t")
+    raise SystemExit(0)
+
+try:
+    # JSONL timestamps from Claude Code are ISO 8601 with Z suffix.
+    parsed = datetime.fromisoformat(latest_user_ts.replace("Z", "+00:00"))
+    now = datetime.now(timezone.utc)
+    idle_ms = max(0, int((now - parsed).total_seconds() * 1000))
+except Exception:
+    idle_ms = 0
+
+excerpt = latest_user_text[:2000]
+b64 = base64.b64encode(excerpt.encode("utf-8")).decode("ascii")
+print(f"{new_user_count}\t{idle_ms}\t{b64}")
+PY
+)
+NEW_TURNS="${INSPECTION%%	*}"
+REMAINING="${INSPECTION#*	}"
+IDLE_MS="${REMAINING%%	*}"
+EXCERPT_B64="${REMAINING#*	}"
+
+# Throttle gates.
+if [ "$NEW_TURNS" -eq 0 ] 2>/dev/null; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=already-dispatched newTurns=0"
+  exit 0
+fi
+if [ "$NEW_TURNS" -lt "$MIN_NEW_TURNS" ] 2>/dev/null; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=below-turn-threshold newTurns=${NEW_TURNS} threshold=${MIN_NEW_TURNS}"
+  exit 0
+fi
+if [ "$IDLE_MS" -lt "$MIN_IDLE_MS" ] 2>/dev/null; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=below-idle-threshold idleMs=${IDLE_MS} threshold=${MIN_IDLE_MS}"
+  exit 0
+fi
+
+# Specialist auto-install. The template lives under
+# `$PLATFORM_ROOT/templates/specialists/agents/signal-detector.md`. The
+# installer / seeder copies templates to per-account dirs at onboarding;
+# this fallback heals an account that pre-dates the template's existence
+# without forcing the operator to re-run onboarding.
+PLATFORM_ROOT_FALLBACK="${MAXY_PLATFORM_ROOT:-}"
+ACCOUNT_DIR_LOCAL="${ACCOUNT_DIR:-}"
+SPECIALIST_TARGET="${ACCOUNT_DIR_LOCAL}/specialists/agents/signal-detector.md"
+if [ -n "$ACCOUNT_DIR_LOCAL" ] && [ ! -f "$SPECIALIST_TARGET" ] && [ -n "$PLATFORM_ROOT_FALLBACK" ]; then
+  TEMPLATE_SRC="${PLATFORM_ROOT_FALLBACK}/templates/specialists/agents/signal-detector.md"
+  if [ -f "$TEMPLATE_SRC" ]; then
+    mkdir -p "$(dirname "$SPECIALIST_TARGET")" 2>/dev/null
+    cp "$TEMPLATE_SRC" "$SPECIALIST_TARGET" 2>/dev/null
+    AGENTS_MD="${ACCOUNT_DIR_LOCAL}/agents/admin/AGENTS.md"
+    if [ -f "$AGENTS_MD" ]; then
+      if ! grep -q "specialists:signal-detector" "$AGENTS_MD" 2>/dev/null; then
+        printf '%s\n' "- **specialists:signal-detector**: Background brain-compounder dispatched only by the admin-agent Stop hook (\`platform/plugins/admin/hooks/signal-detector-stop.sh\`). Never invoke manually." >> "$AGENTS_MD"
+      fi
+    fi
+    emit_log "bootstrap-installed sessionId=${SESSION_ID} target=${SPECIALIST_TARGET}"
+  fi
+fi
+
+EXCERPT_PREVIEW=$(printf '%s' "$EXCERPT_B64" | base64 --decode 2>/dev/null | head -c 200 | tr '\n' ' ')
+emit_log "gate-blocked sessionId=${SESSION_ID} reason=dispatching newTurns=${NEW_TURNS} idleMs=${IDLE_MS} preview=$(printf '%s' "$EXCERPT_PREVIEW" | sed 's/[\"]//g' | head -c 80)"
+
+# Emit the dispatch directive on stderr per Stop-hook contract. The admin
+# IDENTITY.md "Stop-hook system directives" section names this token prefix
+# and the binding response shape — agent must perform the single Agent
+# dispatch and emit an empty acknowledgement on return, nothing else.
+EXCERPT_DECODED=$(printf '%s' "$EXCERPT_B64" | base64 --decode 2>/dev/null)
+
+cat >&2 <<DIRECTIVE
+[system: signal-detector-stop-hook]
+Dispatch the signal-detector specialist NOW using the Task tool. Do not respond to the operator; this is a background brain-compounding task and the operator does not see this turn. After the specialist returns its one-line summary, emit a single space character and stop.
+
+Agent dispatch parameters:
+  subagent_type: signal-detector
+  prompt: |
+    accountId: ${ACCOUNT_ID:-<unset>}
+    sessionId: ${SESSION_ID}
+    newUserTurnsSinceLastRun: ${NEW_TURNS}
+    idleMsBeforeFire: ${IDLE_MS}
+
+    The operator's latest turn (truncated to 2000 chars):
+    ${EXCERPT_DECODED}
+
+    Resolve the operator's most recent :Message in this conversation via memory-search (filter by conversationId from your MCP server env), then write :MENTIONS edges and :Idea nodes per your specialist body. Return one line in the documented output shape.
+DIRECTIVE
+
+exit 2

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

@@ -1,5 +1,6 @@
 ---
 name: docs
+surface: platform
 description: "Comprehensive user guide and platform documentation for Maxy. Load references when users ask how-to, setup, or troubleshooting questions. Also contains platform architecture references for admin use."
 metadata: {"platform":{"always":true,"embed":["public","admin"],"pluginKey":"docs"}}
 ---

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

@@ -79,7 +79,7 @@ PreToolUse hook `platform/plugins/admin/hooks/askuserquestion-investigate-gate.s
 
 ## 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` are not allowed; the wrapper owns 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.
+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` are not allowed; the wrapper owns 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. `dormantPlugins` is `installed − enabledPlugins` with one exclusion: PLUGIN.md frontmatter `surface: platform` (admin, docs) marks platform-shell plugins that ship with every install and are never opt-in features, so they never surface in the `<dormant-plugins>` nudge.
 
 **Body schema.** `{channel?, permissionMode?, initialMessage?, specialist?, model?}` for the cookie path (Sidebar — `senderId` resolved from the admin session cookie, `hidden: false`). `permissionMode` accepts one of five values matching Claude Code's CLI: `'default'`, `'acceptEdits'`, `'plan'`, `'auto'`, `'bypassPermissions'`. 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.
 

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

@@ -85,7 +85,7 @@ Every PTY spawn injects an `--append-system-prompt` block composed of these sent
 | `<about-owner>` | upstream `loadUserProfile` + `formatProfileSummary` (UI process) | sentinel renders the prose body with `NOTHING (operator-data source unavailable: \`<reason>\`)` on line one; spawn proceeds |
 | `<specialist-domains>` | `<accountDir>/specialists/agents/*.md` frontmatter (UI process) | sentinel omitted when set is empty |
 | `<plugin-manifest>` | enabled plugins' PLUGIN.md frontmatter + skill SKILL.md frontmatter (UI process) | sentinel omitted when set is empty |
-| `<dormant-plugins>` | installed-minus-enabled set from `platform/plugins/` and `account.json` | sentinel omitted when set is empty |
+| `<dormant-plugins>` | installed-minus-enabled set from `platform/plugins/` and `account.json`, excluding plugins whose PLUGIN.md frontmatter sets `surface: platform` (platform-shell — ships with every install, never opt-in). Absent `surface` field defaults to `feature` (dormant-eligible). | sentinel omitted when set is empty |
 
 Diagnostic line per spawn (`~/.<brand>/logs/server.log`):
 

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

@@ -77,6 +77,9 @@ tools:
   - name: profile-delete
     publicAllowlist: false
     adminAllowlist: true
+  - name: memory-signals-recent
+    publicAllowlist: false
+    adminAllowlist: true
   - name: graph-prune-denylist-add
     publicAllowlist: false
     adminAllowlist: true
@@ -162,6 +165,10 @@ Graph hygiene is **agent-directed, case by case** — no autonomous rule engine,
 
 **Why soft-delete.** On 2026-04-20 an autonomous orphan-delete rule wiped 19 nodes in one `graph-prune-run` call; properties were unrecoverable (Neo4j Community has no PITR, no APOC). The cron, the `graph-prune-run` tool, and the rule engine have been removed. An earlier fix added the `:Trashed` label primitive so every soft-delete caller (`memory-delete`, `contact-delete`, the admin `/graph` page's trash button) runs the same shared `trashNode` helper — relationships preserved, unique keys snapshotted into `_trashedKeys`, audit lines `[trash:marked] by=<surface>` for cross-cut provenance.
 
+## Signal-detector diagnostic — `memory-signals-recent`
+
+Read-only window into the writes the `signal-detector` specialist has produced under this account. Returns recent `:MENTIONS` edges (`:Message-[:MENTIONS]->Entity`) and `:Idea` nodes interleaved by `observedAt`. Default window is 24 hours; pass `windowHours` (max 720) and `limit` (max 200) to scan a longer arc. Use this when the operator asks "what has the brain captured today?", "show me recent mentions of X", or "what ideas did I leave on the table this week?". The signal-detector specialist itself is dispatched only by the admin-agent Stop hook at `platform/plugins/admin/hooks/signal-detector-stop.sh` — never by operator intent and never via `<specialist-domains>` routing. Task 303.
+
 ## Conversational Memory
 
 The owner's profile and preferences accumulate organically from conversation — never from questionnaires. Run `skill-load skillName=conversational-memory` for full guidance on when to observe preferences, how to handle remember/forget requests, and how to answer "what do you know about me?" transparently with confidence scores and evidence trail.

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

@@ -31,6 +31,7 @@ import { memoryReadAttachment } from "./tools/memory-read-attachment.js";
 import { memoryEditAttachment } from "./tools/memory-edit-attachment.js";
 import { memoryRenameAttachment } from "./tools/memory-rename-attachment.js";
 import { profileRead } from "./tools/profile-read.js";
+import { memorySignalsRecent } from "./tools/memory-signals-recent.js";
 import { profileUpdate } from "./tools/profile-update.js";
 import { profileDelete } from "./tools/profile-delete.js";
 import { graphPruneDenylistAdd } from "./tools/graph-prune-denylist-add.js";
@@ -1678,6 +1679,37 @@ if (!readOnly) {
             };
         }
     });
+    // memory-signals-recent: read-only diagnostic for the signal-detector
+    // specialist's writes. Returns recent :MENTIONS edges
+    // (:Message-[:MENTIONS]->Entity) and :Idea nodes filtered by
+    // r.createdByAgent='signal-detector'. The admin agent uses this to
+    // answer "what has the brain captured today?" without touching cypher.
+    // The signal-detector specialist itself is dispatched only by the
+    // admin-agent Stop hook — never by operator intent. Task 303.
+    server.tool("memory-signals-recent", "Read the most recent signal-detector writes for this account: entity mentions extracted from operator messages, and original-thinking :Idea nodes. " +
+        "Default window is the last 24 hours. " +
+        "Use this when the operator asks 'what has the brain captured today?', 'show me recent mentions of X', or 'what ideas did I leave on the table this week?'.", {
+        windowHours: z.number().int().optional().describe("Hours back from now. Default 24. Capped at 720 (30 days)."),
+        limit: z.number().int().optional().describe("Max rows returned. Default 50, max 200."),
+    }, async ({ windowHours, limit }) => {
+        try {
+            if (!accountId)
+                return refuseNoAccount("memory-signals-recent");
+            const result = await memorySignalsRecent({ accountId, windowHours, limit });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-signals-recent failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
     // -------------------------------------------------------------------------
     // Deny-list maintenance + conversation-memory expunge.
     //