@rubytech/create-maxy-code 0.1.61 → 0.1.63

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

@@ -85,25 +85,41 @@ The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/
 
 **Callers.** `Sidebar.tsx`'s "+ New session" click handler (sends no `initialMessage` — Task 146 made Claude Code's own label canonical, so no UI-side stimulus is injected); the turn-recorder hook (loopback path — see "Turn-recorder" below); future programmatic spawns. Every caller routes through this wrapper. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=<cookie|loopback>` log line followed by `forward-spawn-done`.
 
-## Turn-recorder: a Sidebar-equivalent spawn with three overrides
+## Turn-recorder: a first-class specialist spawn with three body overrides
 
-After every completed operator admin turn, the Stop hook `platform/plugins/admin/hooks/turn-completed-graph-write.sh` dispatches one headless `database-operator` session that writes any new or missing information from the turn into the Neo4j graph. Task 147 — the recorder spawn is byte-for-byte equivalent to a Sidebar "New session" body, with three overrides:
+After every completed operator admin turn, the Stop hook `platform/plugins/admin/hooks/turn-completed-graph-write.sh` dispatches one headless `database-operator` session that writes any new or missing information from the turn into the Neo4j graph. The recorder spawn is structurally a Sidebar "New session" body with three overrides — and the manager treats it as a first-class specialist spawn: the agent file is the prompt, the agent frontmatter is the tool surface, the per-spawn mcp.json is narrowed to the plugins the agent names.
 
+Body overrides relative to a plain Sidebar click:
 - `specialist: 'database-operator'`
 - `model: 'haiku'`
-- `initialMessage: "update the graph with any new or missing information or intent\n\n<last-turn-text>"`
-
-There is no recorder-only carving on the manager side: no preflight, no tool-surface gate, no `originatingSessionId` discriminator, no `MAXY_IS_RECORDER` env stamp, no recorder-only log surfaces. The PTY's own first-use error is the contract for tool absence.
+- `initialMessage: "update the graph with any new or missing information or intent\n\n<conversation-text>"`
 
 **Spawn body.** The hook POSTs `{adminSessionId, channel: 'browser', specialist: 'database-operator', model: 'haiku', initialMessage}` to `POST /api/admin/claude-sessions`. `adminSessionId` is the loopback-bypass key — the wrapper resolves the operator's real `senderId` from `GET <managerBase>/<adminSessionId>/meta` and forwards a Sidebar-shape body to the manager.
 
-**`<last-turn-text>`** is the most recent `assistant` record's text content from the operator JSONL, or — if no assistant record yields text — the most recent `user` record's text. Tool-call blocks, system records, and ephemeral admin-state records are never the candidate. If neither yields text, the hook emits `trigger-skipped reason=last-turn-empty` and no recorder is spawned.
+**`<conversation-text>`** is the operator JSONL walked in transcript order: every `user`/`assistant` record with non-empty text emitted as `"<type>: <text>"`, joined by `\n`. The full exchange is preserved so the recorder can infer operator-asserted facts that span multiple turns (e.g. "hello / what's your business? / Smalleys"). The earlier "last-turn-only" extractor stripped the framing the recorder needed. If no qualifying record exists, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned.
+
+**Manager-side specialist branches.** The recorder is the first specialist subagent that exercises the full specialist flag matrix:
+- The bundled `platform/templates/specialists/agents/database-operator.md` template is symlinked into `$CLAUDE_CONFIG_DIR/agents/database-operator.md` by the installer; without that link `claude --agent database-operator` silently falls back to the admin agent.
+- `--append-system-prompt` is omitted entirely — the agent file IS the prompt; admin IDENTITY / SOUL / aboutOwner do NOT layer on top.
+- `--allowed-tools` is sourced from the agent's frontmatter `tools:` list (11 entries for the recorder), not the admin surface.
+- The per-spawn `mcp.json` is narrowed to only `memory`, `contacts`, `tasks` — the plugins whose tools the agent's frontmatter names.
 
 **End-of-turn auto-archive.** When any session whose specialist is `database-operator` gains an assistant message with `stop_reason: "end_turn"` in its JSONL, the manager posts `/<sid>/stop` against itself, claude exits, the fs-watcher observes the PID-file removal and drops the row from the index. The auto-archive log line is `auto-archive sessionId=<sid> specialist=database-operator reason=end-turn …`.
 
 **Hook recursion gate.** `pty-spawner` stamps `MAXY_SPECIALIST=<specialist>` on every PTY env. The Stop hook short-circuits when `MAXY_SPECIALIST=database-operator` so the recorder's own end-of-turn does not re-fire the hook.
 
-**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> lastTurnBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | last-turn-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
+**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The manager adds `pty-spawn-allowlist specialist=database-operator count=11 sourced-from=agent-frontmatter` and `pty-spawn-start … specialist=database-operator append-system-prompt-bytes=0` before the PTY launches. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | conversation-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
+
+### Recorder lifecycle diagnostic
+
+When the operator reports "the recorder did nothing this turn", run these six greps in order. The first absent line names the phase that failed. `<op>` is the admin operator's session id from the original Stop hook; `<rec>` is the recorder session id returned in phase 2's response and reused across phases 3–6.
+
+1. **Stop hook fired.** `grep '\[turn-recorder\] trigger sessionId=<op>' ~/.<brand>/logs/server.log` — expects one line of shape `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>`. Absent: the Stop hook didn't run; check that `MAXY_SESSION_ROLE=admin` was set on the operator PTY and that `MAXY_SPECIALIST!=database-operator` (recursion gate).
+2. **/spawn accepted.** `grep '\[turn-recorder\] spawn-request sessionId=<op>' ~/.<brand>/logs/server.log` — expects `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The response body of this POST carries `<rec>`. Absent: the hook fired but `/api/admin/claude-sessions` rejected; look for `[turn-recorder] spawn-failed reason=loopback-http http=<code>` on the next line.
+3. **PTY started.** `grep 'pty-spawn-start .* specialist=database-operator' ~/.<brand>/logs/server.log` — expects `pty-spawn-start claudeBin=<…> argv-count=<n> append-system-prompt-bytes=0 … specialist=database-operator prompt-positional=yes prompt-bytes=<n>`. Absent: the wrapper accepted but the manager rejected before exec; check the spawn-failure surfaces (`which-claude-not-found | pty-spawn-failed | pid-file-timeout | host-context-unresolved | identity-unresolved | mcp-config-write-failed`).
+4. **Agent file resolved.** `grep 'pty-spawn-allowlist specialist=database-operator count=11 sourced-from=agent-frontmatter' ~/.<brand>/logs/server.log` — expects exactly one line per recorder spawn. Absent (or `count` not equal to the frontmatter's tool count): the agent file at `$CLAUDE_CONFIG_DIR/agents/database-operator.md` is missing the `tools:` line, or the symlink the installer creates never landed. Re-run the installer.
+5. **Graph write outcome.** `grep '\[mcp:memory\] memory-write .* session=<rec>' ~/.<brand>/logs/server.log` — expects one line ending `result=ok elementId=<id>` or `result=error reason=<slug>` (slug enumerated by the memory MCP write-path observability work). Absent: the recorder loaded but produced no tool calls — model-side decision, not infra. Read the recorder JSONL at `<accountDir>/.claude/projects/<slug>/<rec>.jsonl` to see what the LLM did.
+6. **Auto-archive.** `grep 'auto-archive .* sessionId=<rec> .* specialist=database-operator reason=end-turn' ~/.<brand>/logs/server.log` — expects one line. Absent: the recorder finished but the manager's end-turn watcher didn't fire; the fs-watcher row will get reaped on its TTL but the recorder hung longer than expected. Investigate `pty-spawn-stop` and `pid-file-removed` lines on the same `<rec>`.
 
 ## Session identifiers (Task 135)
 
@@ -114,6 +130,38 @@ The metadata pane surfaces two distinct identifier values. Task 141 collapsed th
 | `sessionId` | Claude's session. Two phases: bridge suffix (`session_xxx`, the URL segment in `claude.ai/code/<session_xxx>`, set when claude prints the `/remote-control` URL) and JSONL basename UUID (claude's intrinsic id on disk, bound when the first turn flushes the JSONL). Both phases coexist on a live row after URL capture; the manager wire emits the bridge form when set, falling back to the JSONL basename in the pre-URL-capture window. The resolver routes either phase to the same row, so callers never need to choose. | `sessionId` (collapsed from the earlier three-field surface (see Task 141) `sessionId` + `claudeSessionId` + `bridgeSessionId`) | `sessionId=` |
 | `accountId` | Account / workspace UUID. For the admin channel, the value the manager carries as `senderId` IS the accountId; for non-admin channels the same wire field carries a phone / email / chat-id (the channel-level sender), so its log key on those paths is still `senderId=`. | `senderId` (channel-agnostic) | `accountId=` in admin-flow emit sites; `senderId=` in channel-bridge sites |
 
+## Memory MCP write-path outcome lines (Task 166)
+
+Every write-path tool in the memory plugin MCP emits one structured line per invocation to `server.log` via the loopback `/api/admin/log-ingest` route. The operator can answer "did this write succeed?" from a single greppable surface — no need to cross-reference the per-process `mcp-memory-stderr-<date>.log`.
+
+Line shapes:
+
+```
+[mcp:memory] <tool-name> account=<id|—> session=<convId|—> labels=<csv|—> name=<value|—> result=ok elementId=<id|—> ms=<n>
+[mcp:memory] <tool-name> account=<id|—> session=<convId|—> labels=<csv|—> name=<value|—> result=error reason=<slug> detail=<≤120 chars> ms=<n>
+```
+
+Enumerated `reason` slugs (failure path): `invalid-input | schema-unknown-label | schema-property-naming | account-isolation | producedby-task-not-found | constraint-violation | conflicting-element-id | invalid-target-node-id | gate-blocked | neo4j-driver-error`. Free-form error text remains in the `detail` field. New slugs are added only by amending the helper's union type; nothing silently falls through to a generic `unknown`.
+
+Wired tools: `memory-write`, `memory-update`, `memory-delete`, `memory-restore`, `memory-empty-trash`, `memory-archive-write`, `memory-ingest`, `memory-ingest-extract`, `memory-ingest-web`, `memory-classify`, `memory-reindex`, `memory-edit-attachment`, `memory-rename-attachment`, `profile-update`, `profile-delete`, `graph-prune-denylist-add`, `graph-prune-denylist-remove`, `conversation-archive-derive-insights`, `conversation-archive-enrich-rejection`, `conversation-memory-expunge`. Read-path tools (`memory-search`, `memory-rank`, etc.) are intentionally out of scope — reads do not change state and their failures already reach the caller.
+
+Diagnostic grep:
+
+```bash
+# Did the most recent memory-write attempt land, and what was it?
+grep '\[mcp:memory\] memory-write .* result=' ~/.${brand}/logs/server.log | tail
+
+# All failed writes across every memory MCP tool, grouped by reason:
+grep '\[mcp:memory\] .* result=error' ~/.${brand}/logs/server.log | awk -F'reason=' '{print $2}' | awk '{print $1}' | sort | uniq -c | sort -rn
+
+# Did the loopback POST itself fail? (Helper falls back to stderr and re-writes
+# the structured line, so the event is never lost — this just flags that the
+# session-manager's /api/admin/log-ingest was unreachable for some window.)
+grep '\[mcp:memory\] log-ingest-failed' ~/.${brand}/logs/mcp-memory-stderr-*.log
+```
+
+The existing `mcp-memory-stderr-<date>.log` capture is unchanged on error paths — the new structured line is additive, not a relocation. Crash-mode debugging continues to read the stderr log; routine "did it land?" questions read `server.log`.
+
 ## Out of scope
 
 - Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.

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

@@ -4,22 +4,31 @@ description: "Email — dedicated email account. Retrieval: email-graph-query fo
 tools:
   - name: email-setup
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-read
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-send
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-reply
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-search
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-graph-query
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-otp-extract
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-status
     publicAllowlist: false
+    adminAllowlist: false
   - name: email-auto-respond-config
     publicAllowlist: false
+    adminAllowlist: false
 always: false
 embed: ["admin"]
 metadata: {"platform":{}}

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

@@ -4,14 +4,19 @@ description: "gov.uk EPC register — by-address and by-UPRN lookup of the most
 tools:
   - name: epc-key-register
     publicAllowlist: false
+    adminAllowlist: false
   - name: epc-key-deregister
     publicAllowlist: false
+    adminAllowlist: false
   - name: epc-key-list
     publicAllowlist: false
+    adminAllowlist: false
   - name: epc-lookup-by-address
     publicAllowlist: false
+    adminAllowlist: false
   - name: epc-lookup-by-uprn
     publicAllowlist: false
+    adminAllowlist: false
 always: false
 metadata: {"platform":{"optional":true,"embed":["admin"]}}
 mcp:

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

@@ -4,58 +4,85 @@ description: "Loop CRM integration — full read/write access to all 8 resource
 tools:
   - name: loop-key-register
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-key-deregister
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-key-list
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-people-search
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-people-detail
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-search
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-detail
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-listed
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-sold
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-viewing
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-callback
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-property-information
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-viewing-search
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-viewing-detail
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-viewing-create
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-viewing-update
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-feedback-get
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-feedback-submit
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-team-info
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-team-availability
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-marketing-match
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-marketing-match-batch
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-marketing-match-request
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-marketing-enquiry
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-auto-responder
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-customer-preferences
     publicAllowlist: false
+    adminAllowlist: false
   - name: loop-supplier
     publicAllowlist: false
+    adminAllowlist: false
 skills:
   - skills/tone-matched-drafter/SKILL.md
   - skills/priority-ranker/SKILL.md

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

@@ -4,62 +4,91 @@ description: "Graph memory plugin. Provides memory-search (with optional `fields
 tools:
   - name: memory-search
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-rank
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-write
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-update
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-reindex
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-ingest
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-ingest-extract
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-ingest-web
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-classify
     publicAllowlist: false
+    adminAllowlist: false
   - name: memory-find-candidates
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-delete
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-restore
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-empty-trash
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-list-attachments
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-read-attachment
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-edit-attachment
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-rename-attachment
     publicAllowlist: false
+    adminAllowlist: true
   - name: memory-archive-write
     publicAllowlist: false
+    adminAllowlist: false
   - name: conversation-archive-derive-insights
     publicAllowlist: false
+    adminAllowlist: false
   - name: conversation-archive-enrich-rejection
     publicAllowlist: false
+    adminAllowlist: false
   - name: conversation-list
     publicAllowlist: false
+    adminAllowlist: true
   - name: conversation-search
     publicAllowlist: false
+    adminAllowlist: true
   - name: profile-read
     publicAllowlist: false
+    adminAllowlist: false
   - name: profile-update
     publicAllowlist: false
+    adminAllowlist: false
   - name: profile-delete
     publicAllowlist: false
+    adminAllowlist: true
   - name: graph-prune-denylist-add
     publicAllowlist: false
+    adminAllowlist: true
   - name: graph-prune-denylist-list
     publicAllowlist: false
+    adminAllowlist: true
   - name: graph-prune-denylist-remove
     publicAllowlist: false
+    adminAllowlist: true
   - name: conversation-memory-expunge
     publicAllowlist: false
+    adminAllowlist: true
 hidden:
   - session-compact
   - session-compact-status
@@ -158,6 +187,14 @@ Before any structured write, load `references/schema-base.md` via `plugin-read`.
 
 **Forbidden properties.** A "Forbidden Properties" table in any schema markdown file declares per-label deny-listed property keys. The validator rejects writes that include a forbidden key for the matching primary label and emits `[schema-validator] outcome=rejected label=<X> property=<Y> reason=forbidden writer=<agentName>`. The first row is `Person | name` — use `givenName` + `familyName` (rendered display name composed at read time). The check fires after the synonym pass, so `firstName → givenName` rewrites still happen first.
 
+**Drift log shape.** On every schema-cache refresh the validator compares `db.labels()` (live) against `schema.cypher` declarations and the schema markdown's documented labels, and emits one summary line per non-empty drift kind:
+
+```
+[schema-validator] drift kind=<kind> count=<n> tokens=<csv up to 10>[+<remainder>]
+```
+
+`<kind>` is one of `declared-not-live`, `live-not-declared`, `markdown-orphan`. Tokens are alphabetically sorted; if more than 10 drift in a kind the line names the first 10 and appends `+<remainder>` (e.g. `count=38 tokens=Applicant,…,Engagement+28`). Empty kinds emit nothing — a clean schema produces no drift lines per refresh. Set `MEMORY_MCP_VERBOSE_DRIFT=1` on the manager unit to keep the historical per-token lines underneath each summary; default off because drift sets of 50+ tokens otherwise bury real signals (write errors, validator rejections) in `mcp-memory-stderr-<date>.log`.
+
 ## Document Ingestion
 
 Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `specialists:database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.

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

@@ -524,7 +524,7 @@ server.tool("conversation-archive-enrich-rejection", "Record or undo a per-row r
         .describe("record = append rejection; undo = remove rejection (called after `wire`)."),
 }, async ({ archiveElementId, chunkElementId, kind, contentHash, mode }) => {
     try {
-        const result = conversationArchiveEnrichRejection({
+        const result = await conversationArchiveEnrichRejection({
             accountId,
             archiveElementId,
             chunkElementId,
@@ -1631,7 +1631,7 @@ if (!readOnly) {
         values: z.array(z.string().min(1)).min(1).describe("Substring values to add. Match is exact substring (case-sensitive) against string-typed properties only."),
     }, async ({ values }) => {
         try {
-            const result = graphPruneDenylistAdd(values);
+            const result = await graphPruneDenylistAdd(values);
             const lines = [
                 `Added ${result.added.length} entries to deny-list (total ${result.totalAfter}).`,
             ];
@@ -1655,7 +1655,7 @@ if (!readOnly) {
         values: z.array(z.string().min(1)).min(1).describe("Substring values to remove (must match exactly as previously added)."),
     }, async ({ values }) => {
         try {
-            const result = graphPruneDenylistRemove(values);
+            const result = await graphPruneDenylistRemove(values);
             const lines = [
                 `Removed ${result.removed.length} entries from deny-list (total ${result.totalAfter}).`,
             ];