@rubytech/create-maxy-code 0.1.146 → 0.1.148

package/payload/platform/plugins/admin/hooks/__tests__/post-turn-graph-pass.test.sh

@@ -0,0 +1,472 @@
+#!/usr/bin/env bash
+# Task 419 — post-turn-graph-pass Stop hook test suite.
+#
+# Modeled on session-end-retrospective.test.sh. A local Python HTTP server
+# stands in for the admin server:
+#   POST /api/admin/log-ingest        → records every line emit_log sent.
+#   GET  /api/admin/post-turn-context → returns the contents of $CTX_FILE,
+#                                       or 500 if $CTX_FILE is missing/empty.
+# Both kinds of request are appended to $REQ_LOG so assertions can see
+# every POST body AND whether the GET was attempted at all.
+#
+# Contract under test:
+#   - Role/specialist gates: exit 0, single trigger-skipped log line, no
+#     stderr directive.
+#   - MAXY_UI_INTERNAL_PORT unset: exit 0, no stderr directive. The hook
+#     emits its missing-env diagnostic on its own stderr channel because
+#     /api/admin/log-ingest is unreachable; that loud-fail is acceptable.
+#   - Empty stdin / missing-transcript: exit 0, single trigger-skipped log
+#     line, no stderr directive.
+#   - Dispatch path (admin + populated JSONL): exit 2, stderr begins with
+#     `[system: post-turn-graph-pass-stop-hook]` and contains
+#     `<conversation>` + `<prior-writes>` blocks, with conversationId
+#     interpolated from CONVERSATION_NODE_ID.
+#   - Prior-writes fetch fails (context endpoint 500): exit 2, dispatch
+#     still fires, `<prior-writes>` block resolves to `(none)`.
+#   - CONVERSATION_NODE_ID unset: exit 2, prompt names
+#     `conversationId: <unset>`, and no GET to /api/admin/post-turn-context
+#     is attempted.
+#   - Multi-block assistant turn: conversation walk concatenates `text`
+#     blocks; `tool_use` blocks dropped.
+#   - User turn whose only content is `tool_result` blocks: skipped in
+#     the conversation walk.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/post-turn-graph-pass.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+OP_ID='aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb'
+CONV_ID='conv-deadbeef-0001'
+
+TMPFILES=()
+LISTENER_PIDS=()
+cleanup_test_state() {
+  for pid in "${LISTENER_PIDS[@]:-}"; do
+    if [[ -n "$pid" ]]; then
+      kill "$pid" 2>/dev/null || true
+      wait "$pid" 2>/dev/null || true
+    fi
+  done
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+}
+trap cleanup_test_state EXIT
+
+PASS=0
+FAIL=0
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+start_listener() {
+  REQ_LOG=$(mktemp); TMPFILES+=("$REQ_LOG")
+  CTX_FILE=$(mktemp); TMPFILES+=("$CTX_FILE")
+  : > "$CTX_FILE"
+  LISTENER_PORT=$((39700 + RANDOM % 100))
+  python3 - "$LISTENER_PORT" "$REQ_LOG" "$CTX_FILE" <<'PY' &
+import sys, http.server, json
+port = int(sys.argv[1])
+log_path = sys.argv[2]
+ctx_path = sys.argv[3]
+
+class H(http.server.BaseHTTPRequestHandler):
+  def log_message(self, *a, **k): pass
+  def do_POST(self):
+    n = int(self.headers.get('Content-Length','0') or 0)
+    body = self.rfile.read(n).decode('utf-8','replace')
+    with open(log_path, 'a', encoding='utf-8') as f:
+      f.write('POST\t' + self.path + '\t' + body + '\n')
+    self.send_response(200)
+    self.send_header('Content-Type','application/json')
+    self.end_headers()
+    self.wfile.write(json.dumps({"ok": True}).encode('utf-8'))
+  def do_GET(self):
+    with open(log_path, 'a', encoding='utf-8') as f:
+      f.write('GET\t' + self.path + '\t\n')
+    if self.path.startswith('/api/admin/post-turn-context'):
+      try:
+        with open(ctx_path, 'r', encoding='utf-8') as f:
+          body = f.read()
+      except FileNotFoundError:
+        body = ''
+      if not body.strip():
+        self.send_response(500)
+        self.end_headers()
+        return
+      self.send_response(200)
+      self.send_header('Content-Type','application/json')
+      self.end_headers()
+      self.wfile.write(body.encode('utf-8'))
+    else:
+      self.send_response(404)
+      self.end_headers()
+
+http.server.HTTPServer(('127.0.0.1', port), H).serve_forever()
+PY
+  LISTENER_PIDS+=("$!")
+  for _ in $(seq 1 20); do
+    if curl -sS --max-time 1 -X POST "http://127.0.0.1:${LISTENER_PORT}/ping" -d '{}' >/dev/null 2>&1; then
+      break
+    fi
+    sleep 0.1
+  done
+  : > "$REQ_LOG"
+}
+
+run_hook() {
+  # Args: role, specialist, ui_port, conversation_node_id, stdin_json
+  local role="$1"; local specialist="$2"; local ui_port="$3"
+  local conv="$4"; local stdin_json="$5"
+  local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+  local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+  local env_cmd=(env)
+  env_cmd+=("MAXY_SESSION_ROLE=${role}")
+  env_cmd+=("MAXY_SPECIALIST=${specialist}")
+  if [[ -n "$ui_port" ]]; then
+    env_cmd+=("MAXY_UI_INTERNAL_PORT=${ui_port}")
+  fi
+  if [[ -n "$conv" ]]; then
+    env_cmd+=("CONVERSATION_NODE_ID=${conv}")
+  fi
+  env_cmd+=("ACCOUNT_ID=acct-test-0001")
+  printf '%s' "$stdin_json" | "${env_cmd[@]}" bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
+  HOOK_RC=$?
+  HOOK_STDERR=$(cat "$stderr_file")
+  HOOK_STDOUT=$(cat "$stdout_file")
+  sleep 0.1
+}
+
+ingest_lines() {
+  grep -E '^POST\s+/api/admin/log-ingest\s+' "$REQ_LOG" 2>/dev/null | python3 -c '
+import sys, json
+for raw in sys.stdin:
+  try:
+    parts = raw.rstrip("\n").split("\t", 2)
+    if len(parts) < 3: continue
+    body = parts[2]
+    d = json.loads(body)
+    if isinstance(d, dict) and isinstance(d.get("line"), str):
+      print(d["line"])
+  except Exception:
+    pass
+' || true
+}
+
+context_get_count() {
+  grep -E '^GET\s+/api/admin/post-turn-context' "$REQ_LOG" 2>/dev/null | wc -l | tr -d ' '
+}
+
+envelope_for() {
+  python3 -c '
+import json, sys
+print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
+' "$1" "$2"
+}
+
+write_simple_transcript() {
+  # write_simple_transcript <outfile> <user_text> <assistant_text>
+  local out="$1"; shift
+  python3 - "$out" "$@" <<'PY'
+import sys, json
+out = sys.argv[1]
+records = []
+i = 2
+while i + 1 < len(sys.argv):
+    u, a = sys.argv[i], sys.argv[i+1]
+    records.append({
+        "type": "user",
+        "timestamp": "2026-05-24T10:00:00.000Z",
+        "message": {"role": "user", "content": u},
+    })
+    records.append({
+        "type": "assistant",
+        "timestamp": "2026-05-24T10:00:01.000Z",
+        "message": {
+            "id": "msg_a",
+            "role": "assistant",
+            "content": [{"type": "text", "text": a}],
+        },
+    })
+    i += 2
+with open(out, "w", encoding="utf-8") as f:
+    for r in records:
+        f.write(json.dumps(r) + "\n")
+PY
+}
+
+# ---------------------------------------------------------------------------
+# Case 1: role != admin → trigger-skipped reason=role-not-admin, no directive
+# ---------------------------------------------------------------------------
+start_listener
+TRANSCRIPT_BASIC=$(mktemp); TMPFILES+=("$TRANSCRIPT_BASIC")
+write_simple_transcript "$TRANSCRIPT_BASIC" "hello" "hi there"
+ENV_BASIC=$(envelope_for "$OP_ID" "$TRANSCRIPT_BASIC")
+: > "$REQ_LOG"
+run_hook "public" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-1 rc=$HOOK_RC"
+if printf '%s' "$HOOK_STDERR" | grep -q '\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-1 stderr must not contain dispatch directive"
+fi
+if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=role-not-admin$"; then
+  pass "case-1 role=public → trigger-skipped reason=role-not-admin"
+else
+  fail "case-1 expected role-not-admin, got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 2: MAXY_SPECIALIST set → trigger-skipped reason=is-specialist
+# ---------------------------------------------------------------------------
+: > "$REQ_LOG"
+run_hook "admin" "database-operator" "$LISTENER_PORT" "$CONV_ID" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-2 rc=$HOOK_RC"
+if printf '%s' "$HOOK_STDERR" | grep -q '\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-2 stderr must not contain dispatch directive"
+fi
+if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=is-specialist specialist=database-operator$"; then
+  pass "case-2 specialist=database-operator → trigger-skipped reason=is-specialist"
+else
+  fail "case-2 expected is-specialist, got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 3: MAXY_UI_INTERNAL_PORT unset → exit 0, no dispatch directive.
+#         The hook prints a missing-env line on its own stderr (loud-fail);
+#         that's expected — /log-ingest is unreachable without the port.
+# ---------------------------------------------------------------------------
+: > "$REQ_LOG"
+run_hook "admin" "" "" "$CONV_ID" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-3 rc=$HOOK_RC"
+if printf '%s' "$HOOK_STDERR" | grep -q '\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-3 stderr must not contain dispatch directive"
+fi
+if [[ "$(ingest_lines | wc -l | tr -d ' ')" == "0" ]]; then
+  pass "case-3 missing MAXY_UI_INTERNAL_PORT → exit 0, no dispatch"
+else
+  fail "case-3 expected no ingest lines (port unset), got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 4: empty stdin → trigger-skipped reason=empty-stdin
+# ---------------------------------------------------------------------------
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" ""
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-4 rc=$HOOK_RC"
+if printf '%s' "$HOOK_STDERR" | grep -q '\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-4 stderr must not contain dispatch directive"
+fi
+if ingest_lines | grep -qE '^trigger-skipped sessionId=unknown reason=empty-stdin$'; then
+  pass "case-4 empty stdin → trigger-skipped reason=empty-stdin"
+else
+  fail "case-4 expected empty-stdin, got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 5: transcript_path missing on disk → trigger-skipped reason=missing-transcript
+# ---------------------------------------------------------------------------
+MISSING_PATH="/tmp/post-turn-graph-pass-does-not-exist-$$.jsonl"
+rm -f "$MISSING_PATH"
+ENV_MISSING=$(envelope_for "$OP_ID" "$MISSING_PATH")
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_MISSING"
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-5 rc=$HOOK_RC"
+if printf '%s' "$HOOK_STDERR" | grep -q '\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-5 stderr must not contain dispatch directive"
+fi
+if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=missing-transcript$"; then
+  pass "case-5 missing transcript_path → trigger-skipped reason=missing-transcript"
+else
+  fail "case-5 expected missing-transcript, got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 6: Dispatch path — admin + populated JSONL → exit 2, dispatch directive
+#         on stderr with <conversation> + <prior-writes>, conversationId interpolated.
+# ---------------------------------------------------------------------------
+cat > "$CTX_FILE" <<'JSON'
+{"writes":[{"elementId":"4:abc:1","labels":["KnowledgeDocument"],"properties":{"title":"prior note"}}]}
+JSON
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 2 ]] || fail "case-6 expected rc=2, got $HOOK_RC"
+if ! printf '%s' "$HOOK_STDERR" | head -n 1 | grep -q '^\[system: post-turn-graph-pass-stop-hook\]'; then
+  fail "case-6 stderr must begin with [system: post-turn-graph-pass-stop-hook]"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q '<conversation>'; then
+  fail "case-6 stderr missing <conversation> block"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q '<prior-writes>'; then
+  fail "case-6 stderr missing <prior-writes> block"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q "conversationId: ${CONV_ID}"; then
+  fail "case-6 stderr must interpolate conversationId=${CONV_ID}"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q '\[user: hello\]'; then
+  fail "case-6 stderr must carry the user turn '[user: hello]'"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q '\[assistant: hi there\]'; then
+  fail "case-6 stderr must carry the assistant turn '[assistant: hi there]'"
+fi
+if ! printf '%s' "$HOOK_STDERR" | grep -q 'KnowledgeDocument'; then
+  fail "case-6 stderr <prior-writes> must include fetched labels (KnowledgeDocument)"
+fi
+if ingest_lines | grep -qE "^dispatch sessionId=${OP_ID} conversationId=${CONV_ID} "; then
+  pass "case-6 dispatch path → exit 2 + directive with conversation, prior-writes, conversationId"
+else
+  fail "case-6 expected dispatch log line, got: $(ingest_lines)"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 7: Prior-writes fetch fails (context endpoint 500) → exit 2, dispatch
+#         still fires, <prior-writes> resolves to `(none)`.
+# ---------------------------------------------------------------------------
+: > "$CTX_FILE"
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 2 ]] || fail "case-7 expected rc=2, got $HOOK_RC"
+if ! printf '%s' "$HOOK_STDERR" | grep -q '<prior-writes>'; then
+  fail "case-7 stderr missing <prior-writes> block"
+fi
+# Extract the prior-writes block and check it contains only `(none)`.
+PRIOR_BODY=$(printf '%s' "$HOOK_STDERR" | awk '/<prior-writes>/{flag=1;next}/<\/prior-writes>/{flag=0}flag' | tr -d '[:space:]')
+if [[ "$PRIOR_BODY" == "(none)" ]]; then
+  pass "case-7 context endpoint 500 → dispatch still fires, prior-writes = (none)"
+else
+  fail "case-7 expected prior-writes=(none), got [$PRIOR_BODY]"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 8: CONVERSATION_NODE_ID unset → exit 2, prompt names
+#         `conversationId: <unset>`, no GET to /api/admin/post-turn-context.
+# ---------------------------------------------------------------------------
+cat > "$CTX_FILE" <<'JSON'
+{"writes":[]}
+JSON
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "" "$ENV_BASIC"
+[[ "$HOOK_RC" -eq 2 ]] || fail "case-8 expected rc=2, got $HOOK_RC"
+if ! printf '%s' "$HOOK_STDERR" | grep -q 'conversationId: <unset>'; then
+  fail "case-8 stderr must contain 'conversationId: <unset>'"
+fi
+GET_COUNT=$(context_get_count)
+if [[ "$GET_COUNT" == "0" ]]; then
+  pass "case-8 CONVERSATION_NODE_ID unset → no GET /api/admin/post-turn-context attempted"
+else
+  fail "case-8 expected zero context GETs, got: $GET_COUNT"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 9: Multi-block assistant turn → conversation walk concatenates text
+#         blocks; tool_use blocks dropped.
+# ---------------------------------------------------------------------------
+T_MULTI=$(mktemp); TMPFILES+=("$T_MULTI")
+python3 - "$T_MULTI" <<'PY'
+import sys, json
+out = sys.argv[1]
+records = [
+    {
+        "type": "user",
+        "timestamp": "2026-05-24T10:00:00.000Z",
+        "message": {"role": "user", "content": "go"},
+    },
+    {
+        "type": "assistant",
+        "timestamp": "2026-05-24T10:00:01.000Z",
+        "message": {
+            "id": "msg_a",
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "part-one "},
+                {"type": "tool_use", "id": "tu_1", "name": "Read", "input": {}},
+                {"type": "text", "text": "part-two"},
+            ],
+        },
+    },
+]
+with open(out, "w", encoding="utf-8") as f:
+    for r in records:
+        f.write(json.dumps(r) + "\n")
+PY
+ENV_MULTI=$(envelope_for "$OP_ID" "$T_MULTI")
+cat > "$CTX_FILE" <<'JSON'
+{"writes":[]}
+JSON
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_MULTI"
+[[ "$HOOK_RC" -eq 2 ]] || fail "case-9 expected rc=2, got $HOOK_RC"
+if ! printf '%s' "$HOOK_STDERR" | grep -q '\[assistant: part-one part-two\]'; then
+  fail "case-9 expected concatenated assistant text '[assistant: part-one part-two]'"
+fi
+if printf '%s' "$HOOK_STDERR" | grep -q '"tool_use"'; then
+  fail "case-9 tool_use block must not appear in dispatch stderr"
+fi
+if printf '%s' "$HOOK_STDERR" | grep -q '\[assistant: part-one part-two\]'; then
+  pass "case-9 multi-block assistant turn → text concatenated, tool_use dropped"
+fi
+
+# ---------------------------------------------------------------------------
+# Case 10: User turn whose only content is tool_result blocks → skipped in
+#          the conversation walk (no `[user: ...]` line for that record).
+# ---------------------------------------------------------------------------
+T_TRONLY=$(mktemp); TMPFILES+=("$T_TRONLY")
+python3 - "$T_TRONLY" <<'PY'
+import sys, json
+out = sys.argv[1]
+records = [
+    {
+        "type": "user",
+        "timestamp": "2026-05-24T10:00:00.000Z",
+        "message": {"role": "user", "content": "real user turn"},
+    },
+    {
+        "type": "assistant",
+        "timestamp": "2026-05-24T10:00:01.000Z",
+        "message": {
+            "id": "msg_a",
+            "role": "assistant",
+            "content": [{"type": "text", "text": "assistant reply"}],
+        },
+    },
+    {
+        "type": "user",
+        "timestamp": "2026-05-24T10:00:02.000Z",
+        "message": {
+            "role": "user",
+            "content": [
+                {"type": "tool_result", "tool_use_id": "tu_x", "content": "tool plumbing payload"},
+            ],
+        },
+    },
+]
+with open(out, "w", encoding="utf-8") as f:
+    for r in records:
+        f.write(json.dumps(r) + "\n")
+PY
+ENV_TRONLY=$(envelope_for "$OP_ID" "$T_TRONLY")
+: > "$REQ_LOG"
+run_hook "admin" "" "$LISTENER_PORT" "$CONV_ID" "$ENV_TRONLY"
+[[ "$HOOK_RC" -eq 2 ]] || fail "case-10 expected rc=2, got $HOOK_RC"
+CONV_BLOCK=$(printf '%s' "$HOOK_STDERR" | awk '/<conversation>/{flag=1;next}/<\/conversation>/{flag=0}flag')
+if ! printf '%s' "$CONV_BLOCK" | grep -q '\[user: real user turn\]'; then
+  fail "case-10 conversation block must include real user turn"
+fi
+if printf '%s' "$CONV_BLOCK" | grep -q 'tool plumbing payload'; then
+  fail "case-10 tool_result-only user record must not appear in conversation walk"
+fi
+# The heredoc indents the conversation block; match leading whitespace.
+TR_LINES=$(printf '%s\n' "$CONV_BLOCK" | grep -cE '\[user:' || true)
+if [[ "$TR_LINES" == "1" ]]; then
+  pass "case-10 tool_result-only user record skipped in conversation walk"
+else
+  fail "case-10 expected exactly one [user: ...] line, got $TR_LINES"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo
+echo "post-turn-graph-pass tests: $PASS passed, $FAIL failed"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/session-end-retrospective.test.sh

@@ -294,7 +294,7 @@ write_transcript "$T_RELEASE" \
   "assistant|hello|" \
   "user|/end|" \
   "assistant|running retrospective|" \
-  "assistant||tool_use:session-retrospective-mark-complete"
+  "assistant||tool_use:mcp__admin__session-retrospective-mark-complete"
 ENV_REL=$(envelope_for "$OP_ID" "$T_RELEASE")
 : > "$REQ_LOG"
 run_hook "admin" "" "$ENV_REL"
@@ -325,7 +325,7 @@ fi
 T_OTHER=$(mktemp); TMPFILES+=("$T_OTHER")
 write_transcript "$T_OTHER" \
   "user|/end|" \
-  "assistant||tool_use:session-retrospective-mark-complete"
+  "assistant||tool_use:mcp__admin__session-retrospective-mark-complete"
 # Active gate inspects only T_ACTIVE (no sentinel inside).
 T_ACTIVE=$(mktemp); TMPFILES+=("$T_ACTIVE")
 write_transcript "$T_ACTIVE" "user|/end|"

package/payload/platform/plugins/admin/hooks/session-end-retrospective.sh

@@ -20,7 +20,10 @@
 #
 # Sentinel detection. Completion is recognised by greping the operator's
 # own JSONL (transcript_path on the Stop envelope) for a `tool_use` block
-# whose `name` is exactly `session-retrospective-mark-complete`. The
+# whose `name` is exactly `mcp__admin__session-retrospective-mark-complete`
+# — that is the prefixed form Claude Code writes for MCP tools in the
+# JSONL; the unprefixed name only appears in the operator-facing
+# instruction text below. The
 # sentinel-grep doubles as the re-entry guard: every Stop that fires after
 # the agent's sentinel call sees the sentinel and exits 0 with
 # `gate-released`, so the agent's wrap-up turn never re-blocks.
@@ -128,12 +131,12 @@ fi
 #   1. The latest end-intent token in the most recent real-user message,
 #      or empty if no real user message matches.
 #   2. Whether any `tool_use` block in the transcript names the sentinel
-#      tool `session-retrospective-mark-complete`.
+#      tool `mcp__admin__session-retrospective-mark-complete`.
 # Output one line: <intent-token-or-empty>\t<sentinel-present-yes|no>
 INSPECTION=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
 import os, json
 
-SENTINEL_TOOL = "session-retrospective-mark-complete"
+SENTINEL_TOOL = "mcp__admin__session-retrospective-mark-complete"
 INTENT_TOKENS = ("/end", "/archive", "end session", "archive this session")
 
 def is_real_user(rec):

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

@@ -866,11 +866,11 @@ if (!readOnly) {
             };
         }
     });
-    server.tool("memory-update", "Update properties on an existing node in the knowledge graph. Finds the node by element ID, verifies account ownership, sets the provided properties, and recomputes the embedding. For :Person / :Organization / :Concept / :Project / :LocalBusiness, pass rewriteCompiledTruth=true to recompute the admin compiledTruth summary; when the label is in the public-twin set (:Organization / :Concept / :Project / :LocalBusiness) and the admin pass changes the truth, the public-twin compiledTruthPublic auto-rewrites in the same call. Pass compiledTruthPublic to override the public twin directly via chat. Direct writes to compiledTruth / compiledTruthUpdatedAt / compiledTruthSource / compiledTruthPublic / compiledTruthPublicUpdatedAt / compiledTruthPublicSource via the properties bag are refused — use the dedicated arguments.", {
+    server.tool("memory-update", "Update properties on an existing node in the knowledge graph. Finds the node by element ID, verifies account ownership, sets the provided properties, and recomputes the embedding. For :Person / :Organization / :Concept / :Project / :LocalBusiness, pass rewriteCompiledTruth=true to recompute the admin compiledTruth summary; when the label is in the public-twin set (:Organization / :Concept / :Project / :LocalBusiness) and the admin pass changes the truth, the public-twin compiledTruthPublic auto-rewrites in the same call. Pair rewriteCompiledTruth=true with operatorHint to feed the rewriter an operator correction from chat for the admin twin — the resulting write is stamped compiledTruthSource='operator', the 7-day cooldown does not block it, and the public-twin auto-fire is skipped. Pair rewriteCompiledTruth=true with publicOperatorHint to do the same for the public twin — the public rewriter is invoked with the hint folded into the public-mode prompt regardless of whether the admin pass changed the truth, the public-cooldown is bypassed, and the write is stamped compiledTruthPublicSource='operator'. Direct writes to compiledTruth / compiledTruthUpdatedAt / compiledTruthSource / compiledTruthPublic / compiledTruthPublicUpdatedAt / compiledTruthPublicSource via the properties bag are refused — the rewriter is the only writer.", {
         nodeId: z.string().describe("Element ID of the node to update (from memory-search results)"),
         properties: z
             .record(z.string(), z.unknown())
-            .describe("Properties to set or overwrite. Restricted keys (embedding, accountId, createdAt) are ignored. Compiled-truth fields are system-managed and rejected loudly here — use rewriteCompiledTruth or the compiledTruthPublic argument."),
+            .describe("Properties to set or overwrite. Restricted keys (embedding, accountId, createdAt) are ignored. Compiled-truth fields are system-managed and rejected loudly here — use rewriteCompiledTruth (optionally with operatorHint or publicOperatorHint)."),
         rewriteCompiledTruth: z
             .boolean()
             .optional()
@@ -879,11 +879,15 @@ if (!readOnly) {
             .boolean()
             .optional()
             .describe("Bypass the 7-day cooldown that protects operator-edited compiledTruth and compiledTruthPublic fields from automatic rewriter passes. Set only when the operator explicitly asks for a refresh."),
-        compiledTruthPublic: z
+        operatorHint: z
             .string()
             .optional()
-            .describe("Operator override for the public-facing compiled-truth twin. Writes the supplied string verbatim, stamps source='operator', and resets the public-twin cooldown. Length cap: 2000 characters. Only valid on :Organization / :Concept / :Project / :LocalBusiness (:Person has no public twin)."),
-    }, async ({ nodeId, properties, rewriteCompiledTruth, forceRewrite, compiledTruthPublic }) => {
+            .describe("Operator correction for the admin twin, supplied via chat. Only valid with rewriteCompiledTruth=true. Folded into the rewriter prompt with precedence over the timeline; the resulting write is stamped compiledTruthSource='operator', the 7-day cooldown does not block this pass, and the public-twin auto-fire is skipped so admin-side corrections do not leak unreviewed to the public surface. Cap: 1000 characters."),
+        publicOperatorHint: z
+            .string()
+            .optional()
+            .describe("Operator correction for the public twin, supplied via chat. Only valid with rewriteCompiledTruth=true AND a public-twin label (:Organization / :Concept / :Project / :LocalBusiness — :Person has no public twin). Folded into the public-mode rewriter prompt with precedence over the timeline; the public rewriter fires regardless of whether the admin pass changed the truth, the public-cooldown is bypassed, and the write is stamped compiledTruthPublicSource='operator'. Cap: 1000 characters."),
+    }, async ({ nodeId, properties, rewriteCompiledTruth, forceRewrite, operatorHint, publicOperatorHint }) => {
         if (!accountId)
             return refuseNoAccount("memory-update");
         try {
@@ -898,13 +902,15 @@ if (!readOnly) {
                 },
                 rewriteCompiledTruth,
                 forceRewrite,
-                compiledTruthPublic,
+                operatorHint,
+                publicOperatorHint,
             });
             const rewriterLine = (() => {
                 if (!result.rewriter)
                     return "";
                 if (result.rewriter.kind === "ok") {
-                    return `\nAdmin compiled-truth rewritten: ${result.rewriter.charsBefore} → ${result.rewriter.charsAfter} chars.`;
+                    const sourceFragment = result.rewriter.source === "operator" ? " (operator-attributed)" : "";
+                    return `\nAdmin compiled-truth rewritten${sourceFragment}: ${result.rewriter.charsBefore} → ${result.rewriter.charsAfter} chars.`;
                 }
                 if (result.rewriter.kind === "refused") {
                     return result.rewriter.reason === "operator-edit-cooldown"
@@ -920,7 +926,8 @@ if (!readOnly) {
                 if (!result.publicRewriter)
                     return "";
                 if (result.publicRewriter.kind === "ok") {
-                    return `\nPublic compiled-truth rewritten: ${result.publicRewriter.charsBefore} → ${result.publicRewriter.charsAfter} chars.`;
+                    const sourceFragment = result.publicRewriter.source === "operator" ? " (operator-attributed)" : "";
+                    return `\nPublic compiled-truth rewritten${sourceFragment}: ${result.publicRewriter.charsBefore} → ${result.publicRewriter.charsAfter} chars.`;
                 }
                 if (result.publicRewriter.kind === "refused") {
                     return result.publicRewriter.reason === "operator-edit-cooldown"
@@ -932,21 +939,11 @@ if (!readOnly) {
                 }
                 return `\nPublic rewriter LLM call failed (cause=${result.publicRewriter.cause}); compiledTruthPublic unchanged.`;
             })();
-            const overrideLine = (() => {
-                if (!result.publicOverride)
-                    return "";
-                if (result.publicOverride.kind === "applied") {
-                    return `\ncompiledTruthPublic overridden by operator: ${result.publicOverride.chars} chars.`;
-                }
-                return result.publicOverride.reason === "wrong-label"
-                    ? `\ncompiledTruthPublic override refused: label is not in the public-twin set (:Organization / :Concept / :Project / :LocalBusiness).`
-                    : `\ncompiledTruthPublic override refused: exceeds 2000 character cap.`;
-            })();
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node updated: [${result.labels.join(", ")}] (ID: ${result.nodeId})${rewriterLine}${publicRewriterLine}${overrideLine}`,
+                        text: `Node updated: [${result.labels.join(", ")}] (ID: ${result.nodeId})${rewriterLine}${publicRewriterLine}`,
                     },
                 ],
             };
@@ -2348,6 +2345,11 @@ server.tool("memory-typed-edge-pass", "Run the typed-edge auto-extraction pass o
         return refuseNoAccount("memory-typed-edge-pass");
     const dbSession = getSession();
     try {
+        // Cast: the McpServer instance is `any`-typed at the module level (see
+        // file-top comment on TS2589), so `args` infers as the loose
+        // ShapeOutput<ZodRawShapeCompat> instead of the Zod schema above.
+        // Runtime shape is enforced by the schema; this re-asserts the typed
+        // contract at the consumer boundary. Task 404.
         const result = await memoryTypedEdgePass(args, dbSession, accountId);
         return {
             content: [{