@rubytech/create-maxy 1.0.876 → 1.0.877

package/package.json

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

package/payload/platform/neo4j/edge-annotations.json

@@ -81,8 +81,8 @@
       "note": "Flat document-to-chunk (alternative to HAS_SECTION then HAS_CHUNK)."
     },
     "REFERENCES": {
-      "direction": "(Message|KnowledgeDocument)-[:REFERENCES]->(*)",
-      "note": "Soft reference link."
+      "direction": "(Message|KnowledgeDocument|Task)-[:REFERENCES]->(*)",
+      "note": "Soft reference link. Task 892 added `Task` as a source: derived-insight tasks created from a `:Section:Conversation` chunk record their provenance via (:Task)-[:REFERENCES]->(:Section:Conversation) with a `contentHash` merge-key for idempotent re-runs."
     },
     "ABOUT": {
       "direction": "(Review|Message)-[:ABOUT]->(*)",
@@ -102,7 +102,15 @@
     },
     "OBSERVED_IN": {
       "direction": "(*)-[:OBSERVED_IN]->(Conversation)",
-      "note": "Observation provenance."
+      "note": "Observation provenance. Task 892: `:Section:Conversation` chunks (which carry the Conversation label) are valid OBSERVED_IN targets, so (:Preference)-[:OBSERVED_IN]->(:Section:Conversation) pattern-matches this annotation."
+    },
+    "MENTIONS": {
+      "direction": "(Section|Message|KnowledgeDocument)-[:MENTIONS]->(Person|Organization)",
+      "note": "Named entity reference. Task 892 added `Section` (typically Section:Conversation) as a source so chunk-anchored insight derivation can record who a transcript chunk mentions. KnowledgeDocument-source MENTIONS is the document-ingest path; Message-source MENTIONS is reserved for future per-message extraction."
+    },
+    "RELATED_TO": {
+      "direction": "(Person|Organization)-[:RELATED_TO]->(Person|Organization)",
+      "note": "Operator-confirmed relationship between two named entities derived from a transcript chunk (Task 892). Carries `operatorConfirmed: true` plus `relationshipType` naming the specific bond (`broker`, `colleague`, `referrer`, …). Distinct from typed edges like AUTHORED_BY or PARTICIPANT — RELATED_TO is the generic surface for relationships the operator confirmed at enrich time."
     },
     "HAS_IDENTITY": {
       "direction": "(Agent)-[:HAS_IDENTITY]->(KnowledgeDocument)",

package/payload/platform/plugins/admin/hooks/archive-ingest-surface-gate.sh

@@ -1,15 +1,21 @@
 #!/usr/bin/env bash
-# Archive-ingest surface gate (Task 855, updated by Task 891).
+# Archive-ingest surface gate (Task 855, updated by Task 891, Task 892).
 #
 # Five enforcements, one script — phase decided by `hook_event_name` on stdin.
 # Task 855 narrows the database-operator subagent's effective surface during
 # WhatsApp archive ingestion to exactly one Bash entry
 # (`memory/bin/conversation-archive-ingest.sh`) plus read-only neighbours, by
 # blocking the legacy MCP deviation tools mechanically. Task 891 retired the
-# `whatsapp-export-insight-pass` tool entirely (Phase 2 enrichment moved to a
-# separate follow-up task that will operate on :Section:Conversation chunks);
-# the tool name is added to the BLOCK list so any agent that still references
-# it from a stale skill or runbook gets a loud denial instead of MCP-not-found.
+# `whatsapp-export-insight-pass` tool; Task 892 reintroduces Phase 2 as
+# `mcp__memory__conversation-archive-derive-insights` — a read-only tool that
+# walks :Section:Conversation chunks of one named :ConversationArchive in
+# pages and emits per-row proposals. The new tool is NOT in any BLOCK list
+# (the gate is allow-by-default for unrecognised tools) — its writes go
+# through the existing graph-cypher-write surface, gated by the operator per
+# row in the conversation-archive-enrich skill. Stale references to the
+# retired Phase 2 name (`whatsapp-export-insight-pass`) remain in the BLOCK
+# list as a loud-denial breadcrumb for any operator-edited skill that still
+# names them.
 #
 # 1. PreToolUse on the four legacy WhatsApp MCP tools — BLOCK unconditionally.
 #    The single deterministic Bash entry is the only supported path for

package/payload/platform/plugins/admin/skills/onboarding/SKILL.md

@@ -154,7 +154,11 @@ Then call `render-component` with `name: "cloudflare-setup-form"` and data conta
 
 Wait for the user's submission. The `_componentDone` payload contains the `setup-tunnel.sh` output verbatim. Relay that output to the user — quote any `ACTION REQUIRED` block exactly. When the script exits zero, step-7 completion has already been persisted by the script itself — relay the output and stop. Do not call `onboarding-complete-step` with step 7; the script is the authority for step-7 completion, and any call you make after the script's restart dispatch would race the service restart and almost always lose. If the script failed (the endpoint returned `ok: false, field: "script"`), the form surfaced the error and stayed open — relay the output, cite `plugins/cloudflare/references/reset-guide.md` for recovery, and offer to re-render the form after any manual steps. Do not synthesise alternative recovery commands. If the user skipped (step 7 not reached), call `onboarding-complete-step` with step 7 so the next session resumes at step 8.
 
-**Post-restart resume contract.** A successful Cloudflare setup arms a brand-service restart that kills the in-flight admin agent; the operator's "Cloudflare setup completed" message is replayed by the chat client itself after the restart cycle completes (`POST /api/admin/sessions/<cid>/resume` re-binds the session via the surviving `__remote_session` cookie, then the client sends the marker as a normal hidden chat POST). By the time you receive that marker, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in). From your view as the admin agent, the operator just told you "Cloudflare setup completed (actionId: …)" at currentStep=7. Acknowledge, then proceed to step 8 — do NOT re-ask the Cloudflare question, do NOT re-render the cloudflare-setup-form, do NOT call `onboarding-complete-step` with step 7 (already done). The marker turn is your single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced.
+**Post-restart resume contract.** A successful Cloudflare setup arms a brand-service restart that kills the in-flight admin agent. The operator's "Cloudflare setup completed" message is replayed by the chat client after the restart cycle completes. Two pathways converge on the same agent-visible outcome:
+- **Default (Task 982).** The operator's admin sessionKey is a Task-653-style signed token (`v1.…` HMAC) that survives the restart. `validateSession` rehydrates the in-memory session from the token, the chat-route binds the prior `conversationId` via `getMostRecentAdminConversationForUser`, and the SDK's next cold-create passes `resume: <priorAgentSessionId>` — the marker turn lands in the SAME conversation with the SDK's JSONL transcript intact.
+- **Fallback.** If the signed-token rehydrate fails (token tampered, TTL expired, pre-Task-982 legacy sessionKey), the chat client falls through to `POST /api/admin/sessions/<cid>/resume` via the surviving `__remote_session` cookie. Outcome from your view as the admin agent is identical.
+
+By the time you receive the marker, `OnboardingState.currentStep` is already 7 (the script's filesystem flag was consumed by `consumeStep7FlagUI` on the way in). The operator told you "Cloudflare setup completed (actionId: …)" at currentStep=7. Acknowledge, then proceed to step 8 — do NOT re-ask the Cloudflare question, do NOT re-render the cloudflare-setup-form, do NOT call `onboarding-complete-step` with step 7 (already done). The marker turn is your single source of truth that step 7 finished cleanly; the script's flag-consume is the orthogonal proof that the state machine advanced.
 
 ## Step 8 — Anthropic API key
 

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -212,8 +212,16 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # callback forever; subsequent setup-tunnel runs see a stale cert.pem
   # landing asynchronously and race against the new URL-extraction pass.
   CF_PIPELINE_PID=""
+  CHROMIUM_UNIT=""
   cleanup_oauth() {
     [ -n "${CF_PIPELINE_PID}" ] && kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    # Task 982 — stop the transient chromium unit on any early exit between
+    # browser-spawn and the explicit step=browser-close site below. Best-
+    # effort: no phase_line here because the EXIT trap fires on every path
+    # (including the happy one where step=browser-close already ran and
+    # auto-collected the unit). The `|| true` masks the inevitable "Unit
+    # not loaded" return on the happy path.
+    [ -n "${CHROMIUM_UNIT}" ] && systemctl --user stop "${CHROMIUM_UNIT}" 2>/dev/null || true
     rm -f "${URL_FILE}" "${LAST_LINE_FILE}"
   }
   trap cleanup_oauth EXIT
@@ -276,12 +284,19 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # Mechanically open the URL on the Pi VNC chromium (Task 858). Chromium
   # is already running on this brand's ${BRAND_VNC_DISPLAY} with CDP enabled
   # (vnc.sh start_chrome at boot); invoking the resolved binary <url> against
-  # a running instance IPCs the URL into it as a new tab. Fire-and-forget —
-  # the spawn is intentionally NOT tracked in cleanup_oauth's EXIT trap
-  # because it is a sibling open, not a child of cloudflared, and an
-  # orphaned late-arriving tab is harmless. Replaces cloudflared's own
-  # optimistic xdg-open, which does not reliably target the brand's VNC
-  # display in this environment.
+  # a running instance IPCs the URL into it as a new tab. Replaces
+  # cloudflared's own optimistic xdg-open, which does not reliably target
+  # the brand's VNC display in this environment.
+  #
+  # Task 982 — chromium is launched under a transient systemd-user unit so
+  # the full process tree (including any standalone chromium that lands
+  # when no existing instance is running for IPC) lives in its own cgroup.
+  # On cert.pem arrival the unit is stopped, SIGTERMing the whole cgroup
+  # atomically. Pre-Task-982 the spawn was `&` fire-and-forget with no
+  # tracked PID; the resulting orphan chromium on display :101 was the
+  # symptom in maxy-2 2026-05-12T10:06–10:08Z. `step=browser-close
+  # result=ok|orphan` records the teardown outcome at cert.pem mv site
+  # below.
   #
   # Binary path: SETUP_TUNNEL_CHROMIUM_BIN is read at startup from
   # ${MAXY_PLATFORM_ROOT}/config/chromium-binary.path — `/usr/bin/chromium`
@@ -289,9 +304,34 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # where the system chromium is snap-confined (Task 929). Hardcoding
   # `/usr/bin/chromium` here would re-introduce the AppArmor SingletonLock
   # failure on the laptop.
-  DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}" "${SETUP_TUNNEL_CHROMIUM_BIN}" "${AUTH_URL}" >/dev/null 2>&1 &
-  phase_line setup-tunnel step=browser-spawn result=ok \
-    display="${DISPLAY:-${BRAND_VNC_DISPLAY}}" url_extracted=1
+  CHROMIUM_UNIT="maxy-oauth-chromium-${BRAND}-$$.service"
+  CHROMIUM_LAUNCH_DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}"
+  CHROMIUM_SPAWN_ERR="$(mktemp -t maxy-oauth-chromium-err.XXXXXX)"
+  if systemd-run --user \
+      --unit="${CHROMIUM_UNIT}" \
+      --description="Maxy OAuth chromium for ${BRAND}" \
+      --collect \
+      --setenv=DISPLAY="${CHROMIUM_LAUNCH_DISPLAY}" \
+      "${SETUP_TUNNEL_CHROMIUM_BIN}" "${AUTH_URL}" 2>"${CHROMIUM_SPAWN_ERR}"; then
+    rm -f "${CHROMIUM_SPAWN_ERR}"
+    phase_line setup-tunnel step=browser-spawn result=ok \
+      display="${CHROMIUM_LAUNCH_DISPLAY}" url_extracted=1 unit="${CHROMIUM_UNIT}"
+  else
+    SPAWN_RC=$?
+    SPAWN_STDERR="$(tr '\n' ' ' < "${CHROMIUM_SPAWN_ERR}" | head -c 300 || echo unavailable)"
+    rm -f "${CHROMIUM_SPAWN_ERR}"
+    # Loud-fail rather than fire-and-forget fallback: a systemd-run failure
+    # is the same class as the pre-Task-982 orphan (no teardown handle).
+    # Operator should see the bus-not-running / linger-not-enabled cause.
+    phase_line setup-tunnel step=browser-spawn result=error \
+      reason=systemd-run-failed exit="${SPAWN_RC}" stderr="${SPAWN_STDERR}" \
+      unit="${CHROMIUM_UNIT}"
+    echo "ERROR: systemd-run failed to spawn chromium under transient unit (exit=${SPAWN_RC})." >&2
+    echo "       systemd-run stderr: ${SPAWN_STDERR}" >&2
+    echo "       If stderr mentions 'Failed to connect to bus', enable user-scope" >&2
+    echo "       systemd via 'loginctl enable-linger \$(whoami)' and retry." >&2
+    exit 1
+  fi
   phase_line setup-tunnel step=browser-drive mode=operator-click url="${AUTH_URL}"
 
   # Wait for cert.pem to land — cloudflared writes to ~/.cloudflared/cert.pem
@@ -335,6 +375,45 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
   phase_line setup-tunnel step=oauth-login result=ok \
     path="${CFG_DIR}/cert.pem" waited="${LOGIN_WAIT}s"
+
+  # Task 982 — SIGTERM the OAuth chromium cgroup now that cert.pem has
+  # landed. The transient unit was created above at step=browser-spawn; if
+  # chromium IPCs'd to a running brand-VNC instance and exited cleanly, the
+  # unit is already auto-collected and `systemctl stop` returns 0 (no-such-
+  # unit is a benign race, not an orphan). If chromium is still alive (no
+  # pre-existing brand-VNC instance to IPC into), SIGTERM tears the whole
+  # cgroup atomically. `result=ok` covers both clean paths; `result=orphan`
+  # fires only when the stop command itself fails (bus issue, race with
+  # auto-collect that returned non-zero) — operator-visible signal that an
+  # orphan chromium MAY still be alive on the VNC display.
+  CHROMIUM_STOP_ERR="$(mktemp -t maxy-oauth-chromium-stop-err.XXXXXX)"
+  if systemctl --user stop "${CHROMIUM_UNIT}" 2>"${CHROMIUM_STOP_ERR}"; then
+    rm -f "${CHROMIUM_STOP_ERR}"
+    phase_line setup-tunnel step=browser-close result=ok unit="${CHROMIUM_UNIT}"
+  else
+    STOP_RC=$?
+    STOP_STDERR="$(tr '\n' ' ' < "${CHROMIUM_STOP_ERR}" | head -c 300 || echo unavailable)"
+    rm -f "${CHROMIUM_STOP_ERR}"
+    # Distinguish benign "unit already auto-collected" from a true teardown
+    # failure via systemctl's exit-code taxonomy — never via stderr prose
+    # parsing, which breaks on non-English locales (no-stdout-parsing-for-
+    # control-flow doctrine). Exit code 5 is systemd's canonical "Unit not
+    # loaded" return; --collect auto-GCs a terminated unit between the
+    # chromium-side IPC-and-exit and our stop, producing exactly this code.
+    # Any other non-zero exit is a real teardown failure (bus down, permission,
+    # service still alive but stop hung).
+    if [ "${STOP_RC}" -eq 5 ]; then
+      phase_line setup-tunnel step=browser-close result=ok \
+        reason=unit-auto-collected unit="${CHROMIUM_UNIT}"
+    else
+      phase_line setup-tunnel step=browser-close result=orphan \
+        reason=stop-failed exit="${STOP_RC}" stderr="${STOP_STDERR}" \
+        unit="${CHROMIUM_UNIT}"
+      echo "WARNING: failed to stop transient chromium unit ${CHROMIUM_UNIT} (exit=${STOP_RC})." >&2
+      echo "         An orphan chromium may remain on display ${CHROMIUM_LAUNCH_DISPLAY}." >&2
+      echo "         systemctl stderr: ${STOP_STDERR}" >&2
+    fi
+  fi
 fi
 
 # --------------------------------------------------------------------------

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -22,7 +22,7 @@ Any Cloudflare action outside these four surfaces is a discipline violation —
 
 Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, and dispatches the `${BRAND}.service` restart to a transient `systemd-run` unit — all in one invocation. The restart fires a few seconds after the script exits so the script does not kill its own cgroup when invoked via the Bash tool; the chat UI receives a `server_shutdown` SSE frame and reconnects automatically. Post-restart hostname verification is out of scope for the script (connector is not up when the script exits) — verify via the next admin turn or manually with `curl -I https://<hostname>`. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
 
-Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and the instant the URL surfaces, mechanically opens it on the brand's VNC chromium using the install-time-resolved binary (`DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} "${SETUP_TUNNEL_CHROMIUM_BIN}" <url> &` — `SETUP_TUNNEL_CHROMIUM_BIN` is read from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured per Task 929) — emitting `step=browser-spawn result=ok` and `step=browser-drive mode=operator-click`. The operator clicks the zone row + Authorize on the VNC; cloudflared's callback writes `~/.cloudflared/cert.pem`; the wrapper's cert-poll (180 s budget) picks it up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login`, never to layer automation on top.
+Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and the instant the URL surfaces, mechanically opens it on the brand's VNC chromium under a transient `systemd-run --user --unit=maxy-oauth-chromium-${BRAND}-$$.service` so the chromium process tree lives in its own cgroup (Task 982 — pre-Task-982 the spawn was `&` fire-and-forget and orphaned chromium on display `:101` when no pre-existing brand-VNC chromium was available for IPC). The launch uses the install-time-resolved binary (`SETUP_TUNNEL_CHROMIUM_BIN` from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured per Task 929) — emitting `step=browser-spawn result=ok unit=<transient-unit>` and `step=browser-drive mode=operator-click`. The operator clicks the zone row + Authorize on the VNC; cloudflared's callback writes `~/.cloudflared/cert.pem`; the wrapper's cert-poll (180 s budget) picks it up and `mv`s it to the brand-scoped path; the wrapper then `systemctl --user stop`s the transient unit, emitting `step=browser-close result=ok` (or `result=orphan reason=stop-failed` when SIGTERM didn't reach the cgroup — operator-visible signal that an orphan chromium MAY still be alive). There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login`, never to layer automation on top.
 
 ### How inputs reach the script
 

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

@@ -0,0 +1,80 @@
+# Admin Session — restart survival and SDK-resume contract
+
+The admin PIN-gated session-store is the in-memory `Map<sessionKey, Session>` at [`platform/ui/app/lib/claude-agent/session-store.ts`](../../../ui/app/lib/claude-agent/session-store.ts). Every `systemctl --user restart {brand}.service` (notably the one `setup-tunnel.sh` arms 3 s after `step=done` via `systemd-run --on-active=3s`) wipes that Map. This reference documents how an admin session survives the restart without forcing PIN re-entry, and how the SDK conversation chain is preserved across the gap.
+
+## Signed sessionKey
+
+`POST /api/admin/session` mints sessionKeys as HMAC-signed tokens (same primitive as `remote-auth.ts`'s `__remote_session` cookie, generalised to `session-store.ts`):
+
+```
+v1.<base64url(payloadJson)>.<base64url(hmac-sha256(secret, payloadJson))>
+
+payload = { v: "adm", a: <accountId>, u: <userId>, c: <createdAtMs>, n: <16-byte hex nonce> }
+```
+
+The HMAC secret lives at `~/.${brand}/credentials/admin-session-secret` (mode `0o600`, parent dir `0o700`), self-provisioned on first read via the `wx`-create pattern from [`remote-auth.ts::getSecret`](../../../ui/app/lib/remote-auth.ts). The secret is separate from `REMOTE_SESSION_SECRET_FILE` (the `__remote_session` cookie key) — two token surfaces, two security domains, no token-confusion attack across schemas.
+
+**Validation path.** `validateSession(sessionKey, 'admin')`:
+
+1. In-memory `Map.get(sessionKey)` hit → existing behaviour (age check, grant check, return ok).
+2. Map miss AND `agentType === 'admin'` → `tryRehydrateAdminSession(sessionKey)`:
+   - Parse `v1.…` token, verify HMAC against the on-disk secret (timing-safe compare).
+   - Schema-validate the payload (`v === 'adm'`, all required fields present).
+   - TTL check: `Date.now() - payload.c <= 24h`. Expired → return `{kind: 'expired', ageMs}` → caller projects onto the existing `session-expired-age` rejection.
+   - Otherwise, re-register the in-memory entry with `{agentType: 'admin', accountId, userId, wantsPriorConversation: true}` and return `{kind: 'ok', …}`.
+3. Map miss with no valid token → `session-not-registered` (existing legacy `crypto.randomUUID()` sessionKeys land here).
+
+**Observability.** `[session-rehydrate-from-token] sessionKey=… accountId=… userId=… ageMs=…` fires once per successful rehydrate in `server.log`. A tampered token fails HMAC and returns `invalid-token` silently (no log line — would otherwise be a noise/attack-amplifier surface); the request's downstream `[session] middleware-reject status=401 code=session-not-registered` is sufficient.
+
+## SDK-resume contract on PIN-rebind
+
+The Anthropic SDK is stateless against its own JSONL: every cold-create with `resume: <agentSessionId>` reads `${CLAUDE_CONFIG_DIR}/projects/<encoded-cwd>/<agentSessionId>.jsonl` verbatim. The Maxy graph (`Conversation.agentSessionId`) is just the pointer into the JSONL, not a parallel transcript. The PIN-rebind contract preserves this:
+
+1. **Rehydrate** restores `(accountId, userId)` into the in-memory session. `conversationId` and `agentSessionId` are empty.
+2. **Chat-route first POST** (`platform/ui/server/routes/admin/chat.ts`):
+   - `consumeWantsPriorConversation(sessionKey)` returns true → look up prior admin conversation.
+   - `getMostRecentAdminConversationForUser(accountId, userId)` returns `{conversationId, agentSessionId}` for the most recent admin Conversation node carrying a non-null `agentSessionId`.
+   - `setConversationIdForSession(sessionKey, conversationId)` binds the prior `conversationId` so the operator's chat lands in the SAME conversation, not a new one.
+   - `setAgentSessionId(sessionKey, agentSessionId)` seeds the in-memory session's pointer; subsequent `invokeAdminAgent`'s `getAgentSessionId(sessionKey)` returns this value naturally.
+3. **`invokeAdminAgent`** passes `resume: <priorAgentSessionId>` to the SDK options. The SDK opens its on-disk JSONL for that session id and continues from there.
+
+No `<previous-context>` prompt-stuffing. No Neo4j transcript replay. The SDK reads its own JSONL — the only canonical source of multi-block content (`thinking` with signed signatures, `tool_use`/`tool_result` chains, multi-modal blocks) the graph cannot losslessly reconstruct.
+
+## PIN-rebind vs `/sessions/new`
+
+The `wantsPriorConversation` marker is the discriminator between continuity and explicit fresh-start:
+
+| Trigger | Marker set? | Chat-route behaviour |
+|---|---|---|
+| Signed-token rehydrate post-restart (`tryRehydrateAdminSession`) | yes | Resume prior conversation |
+| Explicit PIN re-entry (`POST /api/admin/session`, `createAdminSession`) | yes | Resume prior conversation |
+| Operator clicks "New conversation" (`POST /api/admin/sessions/new`) | NO | Cold-mint new conversation |
+
+Single-shot: the chat-route consumes the marker on the first POST, so subsequent chats in the same session continue with the bound `conversationId` naturally.
+
+## Observability summary
+
+Per chat POST, one `[client-acquire]` line lands in the per-conversation stream log at `{accountDir}/logs/claude-agent-stream-<conversationId>.log`:
+
+```
+[client-acquire] sessionKey=<sk12>… resume=<priorAgentSessionId8|none> reason=<warm|cold|pin-rebind>
+```
+
+- `warm` — pool entry still alive (no restart in between)
+- `cold` — fresh mint (no prior admin conversation, or `/sessions/new`)
+- `pin-rebind` — post-restart resume of prior admin conversation
+
+The pre-existing `[client-cold-create resumedFrom=<id>]` line from `client-pool.ts` fires once per actual SDK subprocess spawn; combined with `[client-acquire]` it gives a complete shape of every acquire-and-spawn event.
+
+Diagnostic grep:
+
+```bash
+grep -E '\[session-rehydrate-from-token\]|\[client-acquire\] reason=pin-rebind' ~/.${brand}/logs/server.log
+grep '\[client-acquire\]' ~/.${brand}/logs/claude-agent-stream-*.log
+```
+
+## Out of scope
+
+- Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.
+- Multi-user PIN identity carry-forward across the same signed token — the token is bound to one `userId`; rotating PINs mints a fresh token.
+- Replacing `systemctl restart` with in-process cloudflared reload — separate task. The restart-survival contract documented here is the operator's safety net while that rewrite is pending.

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

@@ -65,7 +65,7 @@ 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 your brand mark, navigation (Chat, 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. The sidebar's nav rows swap the list view in place — Chat 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). 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 — 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 / 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 / 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 phones (<720px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header. When the sidebar is collapsed to the 56px icon rail, clicking the Artefacts icon expands the rail back open so the artefact list is visible — the row was previously a silent no-op in collapsed state.
+The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, 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. The sidebar's nav rows swap the list view in place — Chat 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). 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 — 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 / 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 / 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 phones (<720px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header — 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. 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 brand mark, nav, recents list, foot — same shape as the desktop sidebar, just on top of the chat instead of beside it). When the sidebar is collapsed to the 56px icon rail, clicking the Artefacts icon expands the rail back open so the artefact list is visible — the row was previously a silent no-op in collapsed state.
 
 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.
 

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

@@ -41,6 +41,7 @@ These are enabled during onboarding and can be added or removed at any time. Som
 | `replicate` | Image generation — three models for photorealistic, design, and fast draft images | Content producer, Research assistant |
 | `linkedin-import` | Import a LinkedIn Basic Data Export — Profile and Connections today, more CSVs as references land | Database operator |
 | `memory/skills/conversation-archive` | Source-agnostic conversation transcript ingest. One skill for WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom transcript, meeting minutes, iMessage, Slack — `--source <enum>` selects the per-source normaliser. Single Bash entry — `bash platform/plugins/memory/bin/conversation-archive-ingest.sh <archive> --source <enum> --owner-element-id <id> --participant-person-ids <csv> --scope <admin\|public>` — runs normalise → operator-confirms owner + every distinct sender → sessionize at gap-hours boundaries (default 12h) → classify each session via Haiku (`memory-classify` with `mode='chat'`) into topic-bounded `:Section:Conversation` chunks → memory-ingest with `parentLabel='ConversationArchive'`, `source=<enum>`. Re-imports are delta-append. Auto-creating participants is forbidden — any sender outside the operator-confirmed closed set LOUD-FAILs with `parser-miss`. Phase 0 ships only `whatsapp`; other normalisers land per-source. Distinct from the live `whatsapp` plugin (Baileys). | Database operator |
+| `memory/skills/conversation-archive-enrich` | Phase 2 for any named `:ConversationArchive` — source-agnostic per-row insight derivation. Operator-triggered (never auto-fires on Phase 1 completion). Walks `:Section:Conversation` chunks in pages via the read-only MCP tool `mcp__memory__conversation-archive-derive-insights`; surfaces high-confidence claims for per-row operator gate (`wire / skip / reject`) over four kinds — `mention`, `task`, `preference`, `observed-relationship`. Idempotent on `(elementId(chunk), kind, contentHash)` — re-runs collapse identical claims. Haiku runs on OAuth (admin-side LLM never the API key); confidence floor is a hedging-avoidance instruction in the system prompt, not a numeric post-filter. | Database operator |
 
 ### Claude Official (marketplace)
 

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

@@ -1,6 +1,6 @@
 ---
 name: memory
-description: "Graph memory plugin. Provides memory-search, memory-rank, memory-write, and memory-update tools for reading from, writing to, and updating the Neo4j knowledge graph. Includes conversational memory — organic preference learning, evidence-backed recall, and transparent 'what do you know about me?' responses. Document ingestion (memory-classify + memory-ingest) supports two modes: `document` (default) for unstructured PDF/web content → KnowledgeDocument + Section, and `chat` for conversation transcripts → ConversationArchive + Section:Conversation chunks. Ships three skills: `conversational-memory`, `document-ingest`, and `conversation-archive` (source-agnostic transcript ingest for WhatsApp, Telegram, Signal, LinkedIn DMs, Zoom, meeting minutes, iMessage, Slack)."
+description: "Graph memory plugin. Provides memory-search, memory-rank, memory-write, and memory-update tools for reading from, writing to, and updating the Neo4j knowledge graph. Includes conversational memory — organic preference learning, evidence-backed recall, and transparent 'what do you know about me?' responses. Document ingestion (memory-classify + memory-ingest) supports two modes: `document` (default) for unstructured PDF/web content → KnowledgeDocument + Section, and `chat` for conversation transcripts → ConversationArchive + Section:Conversation chunks. Conversation-archive Phase 2 (`conversation-archive-derive-insights`) walks chunks of one named archive and emits per-row claim proposals for operator-gated wiring; `conversation-archive-enrich-rejection` records (or undoes) durable per-row rejections so already-triaged claims do not re-surface on re-runs. Ships four skills: `conversational-memory`, `document-ingest`, `conversation-archive` (source-agnostic transcript ingest for WhatsApp, Telegram, Signal, LinkedIn DMs, Zoom, meeting minutes, iMessage, Slack), and `conversation-archive-enrich` (per-row operator-gated insight derivation over a named archive's chunks)."
 tools:
   - memory-search
   - memory-rank
@@ -20,6 +20,8 @@ tools:
   - memory-edit-attachment
   - memory-rename-attachment
   - memory-archive-write
+  - conversation-archive-derive-insights
+  - conversation-archive-enrich-rejection
   - conversation-list
   - conversation-search
   - profile-read
@@ -36,6 +38,7 @@ skills:
   - skills/conversational-memory/SKILL.md
   - skills/document-ingest/SKILL.md
   - skills/conversation-archive/SKILL.md
+  - skills/conversation-archive-enrich/SKILL.md
 always: true
 embed: false
 ---

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

@@ -36,6 +36,8 @@ import { graphPruneDenylistAdd } from "./tools/graph-prune-denylist-add.js";
 import { graphPruneDenylistList } from "./tools/graph-prune-denylist-list.js";
 import { graphPruneDenylistRemove } from "./tools/graph-prune-denylist-remove.js";
 import { conversationMemoryExpunge } from "./tools/conversation-memory-expunge.js";
+import { conversationArchiveDeriveInsights, } from "./tools/conversation-archive-derive-insights.js";
+import { conversationArchiveEnrichRejection } from "./tools/conversation-archive-enrich-rejection.js";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { embed } from "./lib/embeddings.js";
 import { notTrashed } from "../../../../lib/graph-trash/dist/index.js";
@@ -415,6 +417,131 @@ server.tool("memory-rank", "Retrieve entities from the knowledge graph and rank
         };
     }
 });
+// ---------------------------------------------------------------------------
+// Task 892 — conversation-archive Phase 2: chunk-anchored insight derivation.
+// Read-only tool. Walks :Section:Conversation chunks of one named
+// :ConversationArchive in pages and asks Haiku (via OAuth) for the
+// high-confidence claims. Returns operator-facing proposals with the cypher
+// needed to wire them; the conversation-archive-enrich skill drives the
+// per-row operator gate. The tool itself NEVER writes; idempotency lives on
+// the MERGE-key shape (chunkElementId, kind, contentHash) encoded in each
+// proposal's mergeCypher.
+// ---------------------------------------------------------------------------
+server.tool("conversation-archive-derive-insights", "Walk the :Section:Conversation chunks of one named :ConversationArchive and emit high-confidence claim proposals (mention, task, preference, observed-relationship). Read-only: the caller drives a per-row operator gate; this tool never writes. Paginates via chunkOffset + chunkLimit (default 5). Operator-triggered, never automatic.", {
+    archiveElementId: z
+        .string()
+        .describe("elementId of the :ConversationArchive the operator named (required)."),
+    chunkOffset: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Zero-based chunk offset. Default 0. Increase per page."),
+    chunkLimit: z
+        .number()
+        .int()
+        .positive()
+        .max(20)
+        .optional()
+        .describe("Chunks per page (1..20). Default 5 — small pages keep MCP calls under SDK timeout windows."),
+}, async ({ archiveElementId, chunkOffset, chunkLimit }) => {
+    try {
+        const result = await conversationArchiveDeriveInsights({
+            accountId,
+            archiveElementId,
+            chunkOffset,
+            chunkLimit,
+            sessionId: resolveSessionId(),
+        });
+        const proposalLines = result.proposals
+            .map((p, i) => {
+            const disambig = p.disambiguation && p.disambiguation.needsResolution.length > 0
+                ? ` resolve:${p.disambiguation.needsResolution.map((r) => `${r.role}="${r.displayName}"`).join(",")}`
+                : "";
+            return [
+                `Proposal ${i + 1}/${result.proposals.length}:`,
+                `  chunkElementId=${p.chunkElementId}`,
+                `  kind=${p.kind}`,
+                `  contentHash=${p.contentHash}`,
+                `  evidence="${p.evidenceSnippet}"`,
+                `  proposedAction=${p.proposedAction}${disambig}`,
+                `  mergeCypher=${p.mergeCypher.replace(/\n/g, " ")}`,
+                `  mergeParams=${JSON.stringify(p.mergeParams)}`,
+            ].join("\n");
+        })
+            .join("\n\n");
+        const header = `archiveElementId=${result.archiveElementId} title=${JSON.stringify(result.archiveTitle ?? "")} totalChunks=${result.totalChunks} walked=${result.walkedFrom}..${result.walkedTo} proposals=${result.proposals.length} proposalsRemaining=${result.proposalsRemaining} emptyChunks=${result.emptyChunkElementIds.length}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.proposals.length === 0
+                        ? `${header}\n(no high-confidence claims in this page; advance chunkOffset to walk further)`
+                        : `${header}\n\n${proposalLines}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: msg }],
+            isError: true,
+        };
+    }
+});
+process.stderr.write("[memory-mcp] registered tool=conversation-archive-derive-insights\n");
+// ---------------------------------------------------------------------------
+// Task 980 — durable rejection memory for conversation-archive-enrich.
+// Writes to a sidecar JSONL alongside the account's state directory; the
+// filter step in conversation-archive-derive-insights reads the same file.
+// Modes:
+//   record — append rejection line (idempotent on duplicate keys).
+//   undo   — drop matching line via atomic-rename (called after a `wire`
+//            so a later wire of a once-rejected key cleans up its rejection).
+// ---------------------------------------------------------------------------
+server.tool("conversation-archive-enrich-rejection", "Record or undo a per-row rejection from conversation-archive-enrich. Writes a sidecar JSONL keyed on (chunkElementId, kind, contentHash). Call with mode='record' on operator `reject`; call with mode='undo' after a successful `wire` so a later wire of a once-rejected key clears its rejection. Idempotent: duplicate records are no-ops.", {
+    archiveElementId: z
+        .string()
+        .describe("elementId of the :ConversationArchive (carried on each line for diagnostics)."),
+    chunkElementId: z
+        .string()
+        .describe("elementId of the :Section:Conversation chunk the rejection applies to."),
+    kind: z
+        .string()
+        .describe("Proposal kind — one of mention|task|preference|observed-relationship."),
+    contentHash: z
+        .string()
+        .describe("The proposal's contentHash (sha256 over kind + payload)."),
+    mode: z
+        .enum(["record", "undo"])
+        .describe("record = append rejection; undo = remove rejection (called after `wire`)."),
+}, async ({ archiveElementId, chunkElementId, kind, contentHash, mode }) => {
+    try {
+        const result = conversationArchiveEnrichRejection({
+            accountId,
+            archiveElementId,
+            chunkElementId,
+            kind,
+            contentHash,
+            mode,
+            sessionId: resolveSessionId(),
+        });
+        const summary = `mode=${result.mode} beforeCount=${result.beforeCount} afterCount=${result.afterCount} path=${result.path}`;
+        return {
+            content: [{ type: "text", text: summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[conversation-archive-enrich] rejection-tool-fail mode=${mode} chunk=${chunkElementId} reason="${msg}"\n`);
+        return {
+            content: [{ type: "text", text: msg }],
+            isError: true,
+        };
+    }
+});
+process.stderr.write("[memory-mcp] registered tool=conversation-archive-enrich-rejection\n");
 if (!readOnly) {
     server.tool("memory-write", "Create a new node in the knowledge graph with automatic embedding computation. Every node must be created with at least one relationship — call memory-search first to find target elementIds. Writes targeting :Person, :UserProfile, :AdminUser, :Organization, :LocalBusiness, :CloudflareTunnel, or :CloudflareHostname additionally require an inbound :PRODUCED edge from a :Task — pass the active Task's elementId as `producedByTaskId` and the edge will be composed automatically.", {
         labels: z