@rubytech/create-realagent 1.0.818 → 1.0.820

package/payload/platform/lib/graph-write/src/index.ts

@@ -13,14 +13,24 @@ export * from "./audit.js";
  * maps, and flat props are queryable — `MATCH (n) WHERE n.createdBySession
  * = $id RETURN n` is the forensic entry point).
  *
+ * Process provenance doctrine (Task 885): writes targeting any label in
+ * `ACTION_PROVENANCE_LABELS` (Person, UserProfile, AdminUser, Organization,
+ * LocalBusiness, CloudflareTunnel, CloudflareHostname) must include exactly
+ * one inbound `:PRODUCED` edge whose source is a `:Task` node. This makes
+ * every durable LLM-tool-driven entity creation traversable from the Task
+ * node that produced it, and forward from Task→Conversation via
+ * `:RAISED_DURING`. Bootstrap writes (`createdBy.agent === 'system'`) are
+ * exempt — installer / migration / lazy-create paths run as system writers.
+ *
  * Rejection paths (every one emits a stderr log the admin server pipes to
  * server.log, so orphan pressure is visible per-write not just in the
  * hourly [graph-health] signal):
- *   - zero relationships      → `[graph-write] reject reason=zero-relationships`
- *   - unresolved target id    → `[graph-write] reject reason=unresolved-target`
- *   - removed-feature write   → `[graph-write] reject reason=removed-feature`
- *     (Task 884 — `:ReviewAlert` and `:Event {actionTool:"review-digest-compose"}`
- *     are deleted features; the gate catches doctrine-compliant writers
+ *   - zero relationships          → `[graph-write] reject reason=zero-relationships`
+ *   - unresolved target id        → `[graph-write] reject reason=unresolved-target`
+ *   - missing action provenance   → `[graph-write] reject reason=missing-action-provenance`
+ *   - removed-feature write       → `[graph-write] reject reason=removed-feature`
+ *     (`:ReviewAlert` and `:Event {actionTool:"review-digest-compose"}` are
+ *     deleted features; the gate catches doctrine-compliant writers
  *     re-introducing them. The vitest tombstone grep is the primary fence
  *     for raw `session.run("MERGE …")` callers that bypass this primitive.)
  *
@@ -31,6 +41,43 @@ export * from "./audit.js";
  * this field for access control — it is forensic, not a security boundary.
  */
 
+/**
+ * Labels that require an inbound `:PRODUCED` edge from a `:Task` (Task 885).
+ * Bootstrap writes with `createdBy.agent === 'system'` are exempt — that
+ * carve-out covers PIN-setup `writeAdminUserAndPerson`, schema migrations,
+ * and the lazy `loadUserProfile` MERGE path that bypasses this primitive
+ * entirely (raw Cypher in `platform/ui/app/lib/neo4j-store.ts`).
+ *
+ * The set is intentionally not exhaustive — labels added here become a
+ * blocking gate for every LLM-tool write of that label. Add a label only
+ * after every legitimate writer of it can either (a) carry a Task-PRODUCED
+ * edge, or (b) declare itself as `agent: 'system'`.
+ */
+export const ACTION_PROVENANCE_LABELS: ReadonlySet<string> = new Set([
+  "Person",
+  "UserProfile",
+  "AdminUser",
+  "Organization",
+  "LocalBusiness",
+  "CloudflareTunnel",
+  "CloudflareHostname",
+]);
+
+function requiresActionProvenance(labels: readonly string[]): boolean {
+  for (const label of labels) {
+    if (ACTION_PROVENANCE_LABELS.has(label)) return true;
+  }
+  return false;
+}
+
+function findProducedFromTaskCandidates(
+  relationships: readonly GraphRelationship[],
+): GraphRelationship[] {
+  return relationships.filter(
+    (r) => r.type === "PRODUCED" && r.direction === "incoming",
+  );
+}
+
 import type { Session } from "neo4j-driver";
 
 export interface GraphRelationship {
@@ -128,10 +175,16 @@ export async function writeNodeWithEdges(
   return await session.executeWrite(async (tx) => {
     const targetIds = relationships.map((r) => r.targetNodeId);
     const check = await tx.run(
-      `UNWIND $ids AS id MATCH (t) WHERE elementId(t) = id RETURN count(DISTINCT t) AS found`,
-      { ids: targetIds }
+      `UNWIND $ids AS id MATCH (t) WHERE elementId(t) = id RETURN elementId(t) AS id, labels(t) AS labels`,
+      { ids: targetIds },
     );
-    const found = check.records[0].get("found").toNumber();
+
+    const labelsByTarget = new Map<string, string[]>();
+    for (const rec of check.records) {
+      labelsByTarget.set(rec.get("id") as string, rec.get("labels") as string[]);
+    }
+
+    const found = labelsByTarget.size;
     const uniqueRequested = new Set(targetIds).size;
     if (found !== uniqueRequested) {
       process.stderr.write(
@@ -142,6 +195,34 @@ export async function writeNodeWithEdges(
       );
     }
 
+    // Process provenance gate (Task 885). Labels in
+    // ACTION_PROVENANCE_LABELS require a `:Task` source on at least one
+    // inbound :PRODUCED edge so every durable LLM-tool entity write is
+    // traversable from the Task that produced it. Bootstrap writes
+    // (createdBy.agent === 'system') are exempt — installer + migration
+    // paths predate any Task. The check runs INSIDE the transaction so
+    // the labels-by-target map is consistent with target resolution.
+    let producedByTaskId: string | null = null;
+    if (
+      requiresActionProvenance(labels) &&
+      (createdBy.agent ?? "") !== "system"
+    ) {
+      const candidates = findProducedFromTaskCandidates(relationships);
+      const taskCandidates = candidates.filter((r) => {
+        const lbls = labelsByTarget.get(r.targetNodeId);
+        return Array.isArray(lbls) && lbls.includes("Task");
+      });
+      if (taskCandidates.length === 0) {
+        process.stderr.write(
+          `[graph-write] reject reason=missing-action-provenance labels=${labelCsv} agent=${agentLabel}\n`
+        );
+        throw new Error(
+          `Process provenance doctrine violated: write to ${labelCsv} requires an inbound :PRODUCED edge from a :Task (createdBy.agent='${agentLabel}'). See .docs/neo4j.md (Process provenance doctrine).`
+        );
+      }
+      producedByTaskId = taskCandidates[0].targetNodeId;
+    }
+
     let nodeRes;
     try {
       nodeRes = await tx.run(
@@ -212,7 +293,7 @@ export async function writeNodeWithEdges(
     }
 
     process.stderr.write(
-      `[graph-write] accepted labels=${labelCsv} edges=${edgesCreated} createdByAgent=${createdBy.agent ?? "unknown"} createdByTool=${createdBy.tool ?? createdBy.source ?? "unknown"}\n`
+      `[graph-write] accepted labels=${labelCsv} edges=${edgesCreated} createdByAgent=${createdBy.agent ?? "unknown"} createdByTool=${createdBy.tool ?? createdBy.source ?? "unknown"} producedByTask=${producedByTaskId ?? "none"}\n`
     );
 
     return { nodeId, labels: nodeLabels, edgesCreated };

package/payload/platform/neo4j/schema.cypher

@@ -1018,3 +1018,27 @@ FOR (n:Section) ON (n.createdBySession);
 
 CREATE INDEX task_created_by_session IF NOT EXISTS
 FOR (n:Task) ON (n.createdBySession);
+
+// ----------------------------------------------------------
+// CloudflareTunnel / CloudflareHostname (Task 885) — graph audit of
+// the tunnel-login deterministic flow. Written by the
+// /api/admin/cloudflare/setup endpoint after setup-tunnel.sh exits 0,
+// linked via (Task {kind:'cloudflare-tunnel-login'})-[:PRODUCED]->.
+// CloudflareHostname carries the routed FQDN; CloudflareTunnel
+// carries the connector identity. Source of truth remains the on-disk
+// cert.pem + tunnel.state + config.yml — these nodes are the graph
+// projection so operators can MATCH from a Conversation to "which
+// cloudflare resources did this onboarding produce?"
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT cloudflare_tunnel_id_unique IF NOT EXISTS
+FOR (t:CloudflareTunnel) REQUIRE t.tunnelId IS UNIQUE;
+
+CREATE INDEX cloudflare_tunnel_account IF NOT EXISTS
+FOR (t:CloudflareTunnel) ON (t.accountId);
+
+CREATE CONSTRAINT cloudflare_hostname_unique IF NOT EXISTS
+FOR (h:CloudflareHostname) REQUIRE (h.accountId, h.hostnameValue) IS UNIQUE;
+
+CREATE INDEX cloudflare_hostname_account IF NOT EXISTS
+FOR (h:CloudflareHostname) ON (h.accountId);

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

@@ -201,21 +201,38 @@ Pin the operator's persona and bootstrap the graph nodes that satisfy the graph-
 
 **Wait for the user's submission.** If the user picks "Other" or types free text instead of selecting, ask them which of the two personas best describes them and re-render the select. Do not proceed without one of the two documented modes — the agent must not improvise a third path. If the user pivots off-topic mid-flow, answer their question briefly and re-render the select; step 9 stays incomplete until they pick a mode.
 
-**Call `onboarding-step9-mode` with the chosen mode before any graph write or skill invocation.** The tool emits the diagnostic log line and returns the deterministic next-action prose. Branch on the mode:
+**Call `onboarding-step9-mode` with the chosen mode before any graph write or skill invocation.** The tool emits the diagnostic log line and returns the deterministic next-action prose.
+
+**Open the action record with `task-create` (Task 885 process-provenance doctrine).** Before any graph write or skill invocation, call:
+
+```
+task-create
+  name: "Establish operator owner — onboarding step 9"
+  description: "<one-line summary of the chosen mode and what entities will be produced>"
+  status: "running"
+  kind: "onboarding-establish-owner"
+  inputsProvided: ["mode"]
+```
+
+The returned `taskId` is the action-provenance handle for this step — every subsequent `memory-write` for an action-provenance-gated label (`Person`, `UserProfile`, `AdminUser`, `Organization`, `LocalBusiness`) MUST pass it as `producedByTaskId` so the inbound `:PRODUCED` edge from the Task is composed into the write. The Task is auto-linked to the current `AdminConversation` via `RAISED_DURING` (this is what makes `MATCH (c:AdminConversation)<-[:RAISED_DURING]-(t:Task)-[:PRODUCED]->(entity)` traversable from the conversation that initiated onboarding).
+
+Then branch on the mode.
 
 ### `business-owner`
 
-Invoke the `business-profile` skill. Follow its first-run path: create the `AdminUser` node, create the `LocalBusiness` node, collect identity + address + whichever additional domains (hours, services, FAQs, brand assets) the user provides. When `business-profile` reports that both nodes exist in the graph, call `onboarding-complete-step` with step 9. Do not mark step 9 complete before both nodes exist — the gate's precondition must be real, not just recorded.
+Invoke the `business-profile` skill, passing the `taskId` so the skill can thread it as `producedByTaskId` into every `memory-write` it issues. The skill follows its first-run path: create the `AdminUser` node, create the `LocalBusiness` node, create the `Organization` node, collect identity + address + whichever additional domains (hours, services, FAQs, brand assets) the user provides. When `business-profile` reports that the required nodes exist in the graph, call `task-update(appendStep:"business-profile-complete")` then write the `HAS_PROFILE` edge from the personal-profile `Person` to the operator's `UserProfile` via `memory-update` (one `memory-search` to resolve both elementIds; the `UserProfile` already exists from step 6 onwards via the lazy-create in `loadUserProfile`). Then call `task-complete(taskId)` and `onboarding-complete-step` with step 9. Do not mark step 9 complete before the required nodes + the HAS_PROFILE edge exist — the gate's precondition must be real, not just recorded.
 
 ### `personal`
 
-Personal mode does not register a `LocalBusiness`. The `AdminUser` and personal-profile `Person` nodes were written deterministically at PIN setup time (Task 830 — `writeAdminUserAndPerson`), so this step only enriches the existing Person with an email:
+Personal mode does not register a `LocalBusiness`. The `AdminUser` and personal-profile `Person` nodes were written deterministically at PIN setup time (Task 830 — `writeAdminUserAndPerson`, run as `createdBy.agent === 'system'` and therefore exempt from the action-provenance gate), so this step only enriches the existing Person with operator-identity fields and links it to the `UserProfile`:
 
-1. **Ask the user for their email** in one short conversational message — {{productName}} needs an email or phone number on the personal-profile node for downstream features (notifications, contact-method matching).
-2. **Locate the personal-profile `Person`.** Call `memory-search` with the user's name from `admin-identity` plus `role: "admin-personal"` to find the existing node bound to the `AdminUser` via `OWNS`.
-3. **Attach the email.** Call `memory-update` on that Person with `properties: { email }`. Do NOT create a new Person — the set-pin path already created and bound it.
-4. **Mark step 9 complete.** Call `onboarding-complete-step` with step 9.
+1. **Ask the user for their email AND phone number** in one short conversational message — {{productName}} stores both on the personal-profile Person for downstream features (notifications, contact-method matching, identity-coverage signal that the agent uses to detect missing identity in future turns). The user may decline either; record what they provide. (Operator-identity fix: the system-prompt's "Identity coverage" block surfaces missing identity fields on every turn, so a partial answer becomes a follow-up prompt rather than a silent gap.)
+2. **Attach the identity to Person.** Call `profile-update` with `personFields: { email: "<value>", telephone: "<value>" }` (omit either key the user declined). The tool resolves the personal-profile Person via `(au:AdminUser {userId:$you})-[:OWNS]->(p:Person)` server-side and writes the canonical `email`/`telephone` fields. Use canonical `telephone` — `phone` is the schema synonym, not the canonical name; `profile-update` rejects `phone` rather than silently rewriting it. The tool throws if the OWNS edge is missing rather than silently no-oping (the PIN-setup path is the only place that edge is created — a missing edge means PIN setup never ran or was rolled back).
+3. **Append the step.** Call `task-update(appendStep:"identity-attached")`.
+4. **Link the personal-profile `Person` to the `UserProfile`.** Call `memory-search` to resolve the `UserProfile` elementId for the operator (the lazy `loadUserProfile` write created it on the first admin session). Then call `memory-update` on the Person to add the `HAS_PROFILE` edge to the UserProfile. (`HAS_PROFILE` from `:Person` is a sibling pattern to the existing `AdminUser→HAS_PROFILE→UserProfile`; both are valid sources for the same edge type. See [schema-base.md Relationship Patterns](../../../memory/references/schema-base.md).)
+5. **Close the action record.** Call `task-update(appendStep:"profile-linked")` then `task-complete(taskId)`.
+6. **Mark step 9 complete.** Call `onboarding-complete-step` with step 9.
 
 After step 9 completes in personal mode, tell the user that {{productName}} is configured for personal use — their employer (if any) is not registered here. If they later become the operator for a business of their own, they can ask {{productName}} to set up a business profile, which invokes the `business-profile` skill directly.
 
-If the user declines to bootstrap during step 9 in any mode, leave step 9 incomplete. The next session will resume here, and any attempt to write user-domain data will surface `Write blocked (no-admin-user)` or `Write blocked (no-local-business)` via the gate, pulling the agent back into this step.
+If the user declines to bootstrap during step 9 in any mode, leave step 9 incomplete AND call `task-update(taskId, status:"failed", errorMessage:"<one-line reason>")` so the action record reflects the abandonment instead of dangling in `running` forever. The next session will resume here with a fresh `task-create` (the prior failed Task stays in the graph as the audit record). Any attempt to write user-domain data will surface `Write blocked (no-admin-user)` or `Write blocked (no-local-business)` via the gate, pulling the agent back into this step.

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

@@ -30,7 +30,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is dr
 
 | Script | Purpose |
 |---|---|
-| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel create, DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (earlier platform fixes — wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the Pi VNC chromium (`DISPLAY=${DISPLAY:-:99} /usr/bin/chromium <url> &`), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel from `/api/admin/cloudflare/tunnels`) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the Pi VNC chromium (`DISPLAY=${DISPLAY:-:99} /usr/bin/chromium <url> &`), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
 | [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. No polling blocks — every long-wait is bounded by `cloudflared`'s network round-trip, so no heartbeat contract applies. |
 
 ### Skills

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

@@ -274,32 +274,82 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
 fi
 
 # --------------------------------------------------------------------------
-# Step 2+3: Create tunnel if absent; otherwise reuse. Capture UUID.
-# Emit phase_line step=tunnel-resolve with action=reused|created so the
-# stream log tailer shows which tunnel identity Steps 4+5 are writing
-# against (Task 559 — Bug B: previously a bare `echo` that only surfaced
-# in the Bash tool_result after subprocess exit).
+# Step 2+3: Resolve the tunnel identity from operator input (Task 886 §B).
+#
+# Pre-Task-886 the script derived TUNNEL_NAME locally as "${BRAND}-$(hostname
+# -s)" and reused-or-created. That breaks the same doctrine as pre-Task-589
+# zone selection: the local hostname has no authority over which tunnel the
+# operator's logged-in Cloudflare account holds. A renamed device produced a
+# new tunnel; existing CNAMEs continued to point at the old one; the chat
+# said "Done. tunnel=maxy-maxytest" while the operator's `maxytest` hostname
+# kept resolving via a stale orphan.
+#
+# New contract: the form (rendered via /api/admin/cloudflare/tunnels list) is
+# the source of truth. The endpoint passes exactly one of:
+#   TUNNEL_ID   — operator selected an existing tunnel from the list
+#   TUNNEL_NAME — operator typed a name to create a new tunnel
+# The endpoint validates the exactly-one constraint; the script enforces it
+# again here as defence in depth. Setting both, or neither, is a misuse.
 # --------------------------------------------------------------------------
 
-TUNNEL_NAME="${BRAND}-$(hostname -s)"
-TUNNEL_ID="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json 2>/dev/null \
-  | jq -r --arg N "${TUNNEL_NAME}" '.[]? | select(.name == $N) | .id' | head -1)"
-TUNNEL_ACTION="reused"
-if [ -z "${TUNNEL_ID}" ] || [ "${TUNNEL_ID}" = "null" ]; then
+if [ -n "${TUNNEL_ID:-}" ] && [ -n "${TUNNEL_NAME:-}" ]; then
+  phase_line setup-tunnel step=tunnel-resolve result=error reason=both-set
+  echo "ERROR: TUNNEL_ID and TUNNEL_NAME are mutually exclusive — pass exactly one." >&2
+  exit 1
+fi
+if [ -z "${TUNNEL_ID:-}" ] && [ -z "${TUNNEL_NAME:-}" ]; then
+  phase_line setup-tunnel step=tunnel-resolve result=error reason=neither-set
+  echo "ERROR: TUNNEL_ID (selected) or TUNNEL_NAME (explicit-create) is required." >&2
+  echo "       The form derives one of these from operator input via" >&2
+  echo "       /api/admin/cloudflare/tunnels — re-run the form, do not" >&2
+  echo "       invoke this script directly without one of the env vars." >&2
+  exit 1
+fi
+
+if [ -n "${TUNNEL_ID:-}" ]; then
+  # Operator-selected branch. Resolve the name back from `tunnel list` for
+  # the log line + tunnel.state file. A missing row here means the operator
+  # selected a tunnel that has since been deleted from another surface
+  # (rare but possible) — fail loudly so the operator sees the cause
+  # rather than getting a silent fallback to "create new".
+  TUNNEL_NAME="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json 2>/dev/null \
+    | jq -r --arg I "${TUNNEL_ID}" '.[]? | select(.id == $I) | .name' | head -1)"
+  if [ -z "${TUNNEL_NAME}" ] || [ "${TUNNEL_NAME}" = "null" ]; then
+    phase_line setup-tunnel step=tunnel-resolve result=error \
+      reason=selected-tunnel-not-found tunnel_id="${TUNNEL_ID}"
+    echo "ERROR: TUNNEL_ID ${TUNNEL_ID} is not on the logged-in Cloudflare account." >&2
+    echo "       It may have been deleted from the dashboard since the form loaded." >&2
+    echo "       Re-render the form to refresh the tunnel list." >&2
+    exit 1
+  fi
+  TUNNEL_SOURCE="operator-selected"
+else
+  # Operator-create branch. Refuse to silently reuse an existing tunnel of
+  # the same name — that recreates the pre-Task-886 silent-collision bug.
+  # The operator should have picked it from the list.
+  EXISTING_ID="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json 2>/dev/null \
+    | jq -r --arg N "${TUNNEL_NAME}" '.[]? | select(.name == $N) | .id' | head -1)"
+  if [ -n "${EXISTING_ID}" ] && [ "${EXISTING_ID}" != "null" ]; then
+    phase_line setup-tunnel step=tunnel-resolve result=error \
+      reason=name-already-exists tunnel_name="${TUNNEL_NAME}" tunnel_id="${EXISTING_ID}"
+    echo "ERROR: a tunnel named ${TUNNEL_NAME} already exists (id=${EXISTING_ID})." >&2
+    echo "       Re-render the form and select it from the list, or pick a different name." >&2
+    exit 1
+  fi
   cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel create "${TUNNEL_NAME}"
   TUNNEL_ID="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json \
     | jq -r --arg N "${TUNNEL_NAME}" '.[]? | select(.name == $N) | .id' | head -1)"
-  TUNNEL_ACTION="created"
-fi
-if [ -z "${TUNNEL_ID}" ] || [ "${TUNNEL_ID}" = "null" ]; then
-  phase_line setup-tunnel step=tunnel-resolve result=error \
-    reason=uuid-missing tunnel_name="${TUNNEL_NAME}"
-  echo "ERROR: failed to create or find tunnel ${TUNNEL_NAME}" >&2
-  exit 1
+  if [ -z "${TUNNEL_ID}" ] || [ "${TUNNEL_ID}" = "null" ]; then
+    phase_line setup-tunnel step=tunnel-resolve result=error \
+      reason=create-then-uuid-missing tunnel_name="${TUNNEL_NAME}"
+    echo "ERROR: created tunnel ${TUNNEL_NAME} but its UUID is missing from tunnel list." >&2
+    exit 1
+  fi
+  TUNNEL_SOURCE="operator-created"
 fi
-phase_line setup-tunnel step=tunnel-resolve tunnel_name="${TUNNEL_NAME}" \
-  tunnel_id="${TUNNEL_ID}" action="${TUNNEL_ACTION}"
-echo "tunnel: ${TUNNEL_NAME} (${TUNNEL_ID})"
+phase_line setup-tunnel step=tunnel-resolve source="${TUNNEL_SOURCE}" \
+  tunnel_id="${TUNNEL_ID}" tunnel_name="${TUNNEL_NAME}"
+echo "tunnel: ${TUNNEL_NAME} (${TUNNEL_ID}) [${TUNNEL_SOURCE}]"
 
 # --------------------------------------------------------------------------
 # Step 3b: Zone pre-flight. Before routing DNS, verify every non-apex

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

@@ -25,7 +25,7 @@ Ask the agent to set up Cloudflare. The agent first confirms the domain is alrea
 When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict order — `setRemotePassword`, launches a `cloudflare-setup` action (earlier platform fixes: `systemd-run --user` transient unit wrapping `setup-tunnel.sh <brand> <port> <hostname...>`), and registers a post-exit handler to write alias-domains for every non-`public.*` public or apex hostname (so e.g. `chat.yourdomain.com` is classified as public by `isPublicHost`). The script runs end-to-end:
 
 - `cloudflared tunnel login` — OAuth browser sign-in. The VNC browser opens the Cloudflare authorize page; pick the account that owns your domain, click Authorize. `cert.pem` lands.
-- Tunnel creation under the naming convention `{brand}-{hostname}` (e.g. `maxy-neo`). Stream log emits `step=tunnel-resolve action=reused|created` once the UUID is known so the admin agent can see which tunnel the later steps will write against.
+- Tunnel resolution from operator-supplied identity (operator-selected-tunnel fix). The form populates a tunnel-select dropdown from `GET /api/admin/cloudflare/tunnels` (which calls `cloudflared tunnel list --output json` on your logged-in account). You either pick an existing tunnel from the list or type a name to create a new one. The form posts EXACTLY ONE of `{tunnelId, tunnelName}`; the script enforces the same constraint as defence in depth. Pre-fix the script derived `${BRAND}-$(hostname -s)` locally; that broke the operator-state-is-authoritative doctrine and silently created orphan tunnels whenever the device hostname changed. Stream log emits `step=tunnel-resolve source=operator-selected|operator-created tunnel_id=… tunnel_name=…` once the UUID is known.
 - **Zone pre-flight** — for every non-apex hostname the script queries `1.1.1.1` for the registrable parent's NS records and refuses the whole run if they don't point at Cloudflare. Stream log: `step=zone-preflight result=ok|error zones_on_account=… missing_parent_for=…`. Catches "domain not on Cloudflare"; does not catch "domain on a different Cloudflare account than `cert.pem` is bound to" — that case surfaces later via `tunnel-status`.
 - `cloudflared tunnel route dns` for each subdomain hostname. Apex hostnames cannot be routed this way — the script prints an **ACTION REQUIRED** block naming the exact dashboard record to add or edit. Stream log emits `step=route-dns hostname=… tunnel_id=…` before the call and `step=route-dns hostname=… result=ok|apex-skip|error` after; on error the bounded cloudflared stderr (≤400 chars) rides in the same phase line. **The script does not parse cloudflared's stdout** — exit code is the sole decision signal, so all three legitimate cloudflared output shapes (new record, overwrite, idempotent "already configured") are treated as success.
 - `config.yml` and `tunnel.state` written under `${CFG_DIR}`.

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

@@ -31,6 +31,26 @@ readable when you zoom out to see a large subgraph.
 Tier transitions are debounced so spinning the scroll wheel does not cause
 label flicker; labels only rewrite once zoom settles on a new tier.
 
+## Cluster-expand on Conversation/Message clicks (cluster-integrity fix)
+
+Clicking a Conversation node OR any Message node pulls the WHOLE
+conversation cluster onto the canvas: the Conversation node itself plus
+every Message belonging to it (via `PART_OF`), capped at 200 messages
+for layout reasons. The arrow chain along the conversation (the `NEXT`
+edges) renders for free because the inter-node relationship pass picks
+up edges where both endpoints are in the visible window.
+
+Pre-fix, clicking a middle Message expanded only its prev+next
+neighbours; the head, tail, and Conversation node dropped off, visually
+disintegrating the conversation. The new behaviour keeps the cluster
+intact across click navigation. `PART_OF` edges are now rendered between
+visible Conversation/Message pairs (previously suppressed because they
+"added no information when the Conversation node wasn't on canvas" — an
+assumption that broke the moment the cluster-expand put it there).
+
+The breadcrumb above the canvas tracks each pivot — every entry except
+the last is clickable to pop the view-stack back to that point.
+
 ## Tooltips and side panel
 
 Hovering a node still shows the full 5-line tooltip (display name, labels,

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

@@ -467,6 +467,22 @@ grep '[persist] tool-call persisted' server.log | tail -10
 
 Each log entry includes the tool name and a truncated conversation ID for correlation.
 
+## Process provenance — durable actions emit Tasks
+
+Every durable action — onboarding, cloudflare tunnel-login, brand publish, future deterministic flows — emits a `:Task {kind:"<flow>"}` node carrying the action's lifecycle and a `:PRODUCED` edge to every entity the action created. This makes the graph traversable from the originating Conversation to every entity created during it via `(c)<-[:RAISED_DURING]-(t:Task)-[:PRODUCED]->(e)` — answering "what did this turn produce" in one Cypher hop.
+
+The doctrine is enforced at the storage primitive: writes to `:Person`, `:UserProfile`, `:AdminUser`, `:Organization`, `:LocalBusiness`, `:CloudflareTunnel`, or `:CloudflareHostname` MUST include exactly one inbound `:PRODUCED` edge whose source is a `:Task`. Bootstrap writes (PIN-setup, schema migrations, lazy `loadUserProfile`) are exempt via `createdBy.agent === 'system'`.
+
+Two surfaces emit the lifecycle: agent-driven actions call `task-create`/`task-update`/`task-complete` over MCP (`task-create` accepts `kind`, `inputsProvided` — names only, never values — and `raisedDuringConversationKey` to resolve the `RAISED_DURING` edge). Shell-driven actions wrap their script invocation in [platform/ui/app/lib/cloudflare-task-tracker.ts](../../../ui/app/lib/cloudflare-task-tracker.ts) (cloudflare is the first; installer / brand-publish / OAuth-login deferred). Both surfaces emit the same `[task] action-start|step|done` log lines so operators can grep one channel uniformly.
+
+`memory-write` accepts an optional `producedByTaskId` parameter. When set, an inbound `:PRODUCED` edge from that Task is composed into the write's relationships before the gate runs — the typical agent-side pattern is to call `task-create` at the start of a flow, capture `taskId`, and pass it as `producedByTaskId` on every subsequent `memory-write` for an action-provenance-gated label. The gate verifies Task and write share the same `accountId`; mismatch is rejected loud.
+
+Operator audit cyphers:
+- "What entities did this conversation's actions produce?" — `MATCH (c:AdminConversation {conversationId:$id})<-[:RAISED_DURING]-(t:Task)-[:PRODUCED]->(e) RETURN labels(e), e.name, t.kind, t.status`
+- "What cloudflare resources did this onboarding produce?" — `MATCH (t:Task {kind:'cloudflare-tunnel-login', status:'completed'})-[:PRODUCED]->(r) RETURN t.taskId, r.tunnelId, r.hostnameValue ORDER BY t.completedAt DESC`
+
+See `.docs/neo4j.md § Process provenance doctrine` for the full enforcement contract, observability surface, and out-of-scope deferrals.
+
 ## Context compaction
 
 When an admin turn crosses 75% of the model's context window, {{productName}} runs a silent compaction turn that asks the agent to call the `session-compact` MCP tool with a structured briefing (what you asked for, what was done, decisions made, work-in-progress, things you've shared about yourself). The briefing is written to Neo4j; the next admin turn injects it back into the system prompt, so continuity survives across the compaction boundary without re-sending the full transcript.

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

@@ -20,6 +20,8 @@ metadata: {"platform":{}}
 
 Manages the agent's own dedicated email account — IMAP for reading, SMTP for sending. Admin agent only.
 
+**Identity boundary (operator-identity fix).** This plugin manages the AGENT's email channel: an `:EmailAccount` node with IMAP/SMTP credentials, polling state, and the agent's `agentAddress`. It is NOT the operator-identity store. The operator's own email lives on the OWNS-bound `:Person` (`Person.email`) and is captured via `profile-update` with `personFields`. Confusing the two surfaces (writing the operator's personal email to `EmailAccount.agentAddress`, or vice versa) breaks routing AND identity coverage. See [.docs/agents.md § Coverage-driven elicitation bias] for the operator-identity contract.
+
 ## Capabilities
 
 - **Setup:** `email-setup` — collect credentials via rendered `form`, connect IMAP/SMTP. Supports alias addresses (`agentAddress`).

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

@@ -59,6 +59,12 @@ Ranking is ephemeral and contextual — nothing is written back to the graph. Wh
 
 Use `expandHops: 0` for listing and inventory queries (returns node properties only — compact output). Use `expandHops: 1` (default) for deep context queries where related nodes add value. Queries that combine a high `limit` with `expandHops: 1` on node types that have many relationships (e.g. KnowledgeDocument with HAS_SECTION) are most likely to trigger trimming.
 
+## Process provenance — `producedByTaskId`
+
+`memory-write` accepts an optional `producedByTaskId` parameter. When set, an inbound `:PRODUCED` edge from that `:Task` node is composed into the write's `relationships` array before the storage gate runs. The gate verifies the Task and the new node share the same `accountId`; mismatch is rejected loud.
+
+Writes targeting `:Person`, `:UserProfile`, `:AdminUser`, `:Organization`, `:LocalBusiness`, `:CloudflareTunnel`, or `:CloudflareHostname` REQUIRE this thread (or `createdBy.agent === 'system'` for bootstrap paths). The typical pattern: call `task-create` at the start of a flow with `kind` and `raisedDuringConversationKey`; capture the returned `taskId`; pass it as `producedByTaskId` on every subsequent `memory-write` for an action-provenance-gated label. See `.docs/neo4j.md § Process provenance doctrine`.
+
 ## Graph Hygiene
 
 Graph hygiene is **agent-directed, case by case** — no autonomous rule engine, no cron. The Neo4j graph degrades into a landfill if pollution from prior agent errors (wrong-account hostnames, fabricated identifiers, raw monologue dumps) is allowed to compound. Cleanup happens when the admin agent observes a match against the operator-curated deny-list (or the user directly asks) and applies discretion using `memory-update`, `memory-delete`, or `conversation-memory-expunge`.

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

@@ -415,7 +415,7 @@ server.tool("memory-rank", "Retrieve entities from the knowledge graph and rank
     }
 });
 if (!readOnly) {
-    server.tool("memory-write", "Create a new node in the knowledge graph with automatic embedding computation. Write doctrine (Task 673): every node must be created with at least one relationship. Call memory-search first to find target elementIds.", {
+    server.tool("memory-write", "Create a new node in the knowledge graph with automatic embedding computation. Write doctrine (Task 673): every node must be created with at least one relationship. Call memory-search first to find target elementIds. Process-provenance (Task 885): writes targeting :Person, :UserProfile, :AdminUser, :Organization, :LocalBusiness, :CloudflareTunnel, or :CloudflareHostname 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
             .array(z.string())
             .describe("Node labels (e.g. ['Person'], ['Question'], ['DefinedTerm'])"),
@@ -433,7 +433,11 @@ if (!readOnly) {
         }))
             .min(1)
             .describe("Relationships to create with existing nodes. At least one is required — a node without an adjacency is noise, not knowledge."),
-    }, async ({ labels, properties, scope, relationships }) => {
+        producedByTaskId: z
+            .string()
+            .optional()
+            .describe("Active Task elementId (Task 885). When set, an inbound :PRODUCED edge from this Task is composed into relationships before the write — required for action-provenance-gated labels (Person, UserProfile, AdminUser, Organization, LocalBusiness, CloudflareTunnel, CloudflareHostname). Task must share the same accountId; mismatch is rejected."),
+    }, async ({ labels, properties, scope, relationships, producedByTaskId }) => {
         try {
             const result = await memoryWrite({
                 labels,
@@ -447,6 +451,7 @@ if (!readOnly) {
                     tool: "memory-write",
                 },
                 validator,
+                producedByTaskId,
             });
             return {
                 content: [
@@ -1582,7 +1587,7 @@ if (!readOnly) {
             await dbSession.close();
         }
     });
-    server.tool("profile-update", "Create, update, or reinforce a user preference, and set top-level UserProfile fields (timezone, locale, givenName, role, expertise) via the profileFields parameter. Supports modes: reinforce (re-observed, boost confidence), update (value changed), contradict (value contradicts prior), merge (combine overlapping preferences).", {
+    server.tool("profile-update", "Create, update, or reinforce a user preference; set top-level UserProfile fields (timezone, locale, givenName, role, expertise) via profileFields; AND set operator-identity fields (email, telephone) on the operator's personal-profile Person via personFields (Task 886 §D — Person is the canonical operator-identity store; UserProfile carries preferences and behavioural state only). Supports modes: reinforce (re-observed, boost confidence), update (value changed), contradict (value contradicts prior), merge (combine overlapping preferences).", {
         category: z.enum(["communication", "scheduling", "decision", "workflow", "content", "interaction"])
             .describe("Preference category"),
         key: z.string().describe("Preference identifier (e.g. 'response_length', 'meeting_time')"),
@@ -1595,9 +1600,14 @@ if (!readOnly) {
             .describe("Conversation ID for evidence linking"),
         profileFields: z.record(z.string(), z.unknown()).optional()
             .describe("Top-level UserProfile fields to update (e.g. timezone, locale, role)"),
+        personFields: z.object({
+            email: z.string().optional(),
+            telephone: z.string().optional(),
+        }).optional()
+            .describe("Operator-identity fields written to the OWNS-bound Person (Task 886 §D). Use canonical `telephone` (NOT `phone` — that is the schema synonym, not the canonical name). Tool throws if the AdminUser-OWNS-Person edge is missing rather than silently no-op."),
         mergeSourceIds: z.array(z.string()).optional()
             .describe("For mode 'merge': preferenceIds of sources to combine into this preference"),
-    }, async ({ category, key, value, source, mode, conversationId, profileFields, mergeSourceIds }) => {
+    }, async ({ category, key, value, source, mode, conversationId, profileFields, personFields, mergeSourceIds }) => {
         try {
             if (!userId) {
                 return { content: [{ type: "text", text: "profile-update requires an authenticated admin session with userId" }], isError: true };
@@ -1612,6 +1622,7 @@ if (!readOnly) {
                 mode,
                 conversationId,
                 profileFields: profileFields,
+                personFields,
                 mergeSourceIds,
             });
             return {