@rubytech/create-realagent 1.0.823 → 1.0.824

package/payload/platform/plugins/whatsapp-import/skills/whatsapp-import/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: whatsapp-import
-description: Phase 1 of the WhatsApp `_chat.txt` ingest contract — deterministic, LLM-free. Preview the archive (parsed counts, date range, sender histogram), ask the operator to choose a filter (`all`, `senders=<csv>`, `date-range=<isoFrom>..<isoTo>`), then write Conversation + Messages + NEXT chain + auto-Person participants via the single Bash entry `whatsapp-ingest.sh`. NO observations and NO LLM at this phase — semantic enrichment lives in the `whatsapp-import-enrich` skill (Phase 2). Triggers when the user asks to import a WhatsApp chat, ingest a `_chat.txt` file, or drops the contents of an "Export Chat" folder into chat. Distinct from the live `whatsapp` plugin (Baileys); this is import-from-export only.
+description: Phase 1 of the WhatsApp `_chat.txt` ingest contract — deterministic, LLM-free. Preview the archive (parsed counts, date range, sender histogram), confirm the owner + third-party `:Person`, ask the operator to choose a filter (`all`, `senders=<csv>`, `date-range=<isoFrom>..<isoTo>`), then write Conversation + Messages + NEXT chain via the single Bash entry `whatsapp-ingest.sh`. The writer binds participants to the owner + subject pair: any parsed senderName outside that closed set LOUD-FAILs (Task 887 §A0). NO observations and NO LLM at this phase — semantic enrichment lives in the `whatsapp-import-enrich` skill (Phase 2). Triggers when the user asks to import a WhatsApp chat, ingest a `_chat.txt` file, or drops the contents of an "Export Chat" folder into chat. Distinct from the live `whatsapp` plugin (Baileys); this is import-from-export only.
 ---
 
 # WhatsApp Import — Phase 1 (Load)
 
 Phase 1 of the two-phase WhatsApp ingest contract. Deterministic only: parse → preview → operator-supplied filter → archive-write. NO LLM is invoked at this phase. The chunked Haiku insight pass moved to Phase 2 (`whatsapp-import-enrich` skill) so one ingest cannot blow the operator's context window with `:Observation` enumeration prose.
 
-## Owner confirmation (mandatory first step)
+## Owner + subject confirmation (mandatory first step)
 
-A WhatsApp export belongs to exactly one operator (the person whose phone produced the export). The owner is metadata stamped on the `:Conversation` node — the row-level participants are auto-created by the script and promoted in Phase 2.
+A WhatsApp DM has exactly two participants. The **owner** is the operator who exported the `_chat.txt`; the **subject** is the third party in the conversation. Both must resolve to existing graph nodes (`:AdminUser` or `:Person`) before the script runs — Task 887 §A0 closes the auto-Person leak by binding the writer to that closed pair.
 
-1. List every `:AdminUser` in the graph via `mcp__graph__maxy-graph-read_neo4j_cypher`:
+1. List every `:AdminUser` and the senders surfaced by Step 1 preview via `mcp__graph__maxy-graph-read_neo4j_cypher`:
    `MATCH (u:AdminUser) RETURN elementId(u) AS elementId, u.name AS name, u.userId AS userId, u.accountId AS accountId`
 2. Ask the operator: "Who exported this `_chat.txt`?" — accept either an existing `:AdminUser` elementId or, if the operator names someone not in the graph, surface that as a blocker (auto-creating an unknown owner is refused).
-3. Echo the chosen owner back verbatim. Require explicit yes/no confirmation.
-4. Persist the resolved owner's `elementId` for the script invocation as `--owner-element-id`.
+3. Identify the third party from the preview's sender histogram. Look up the matching `:Person` (by name); if no match, ask the operator to confirm a `:Person` elementId or block until one exists. **Auto-creating the third-party `:Person` is forbidden** — the operator must confirm the canonical node.
+4. Echo both back verbatim and require explicit yes/no confirmation.
+5. Persist the owner's `elementId` as `--owner-element-id` and the subject's as `--subject-person-id`.
 
 ## Step 1 — preview (mandatory before any write)
 
@@ -53,6 +54,7 @@ Single Bash call:
 ```bash
 bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive.zip|dir|_chat.txt> \
   --owner-element-id <id> \
+  --subject-person-id <id> \
   --scope <admin|public> \
   --filter <all|senders=<csv>|date-range=<isoFrom>..<isoTo>>
 ```
@@ -64,9 +66,9 @@ Optional flags:
 
 The script:
 - Unzips the archive if needed; locates `_chat.txt`.
-- Parses the file deterministically (year shape, sender/body grammar, timezone offset).
+- Parses the file deterministically (year shape, sender/body grammar, timezone offset, U+200E/U+200F leading-bidi-strip).
 - Applies the operator-supplied filter to `parseResult.parsedLines` BEFORE archive-write.
-- Auto-creates one `:Person {participantStatus:'auto-created'}` per distinct senderName in the filtered set, scoped to the account, MERGEd on `(accountId, source, name)`.
+- Validates every distinct parsed senderName against the canonical-name candidates of `{owner, subject}` (NFKC-trim-lower normalisation). Any miss LOUD-FAILs with `[whatsapp-ingest] FAIL parser-miss reason="senderName=<verbatim> not in preview histogram (parser failure — re-export or report)"` and exits non-zero. **Never auto-creates a participant** — Task 887 §A0 deleted that fallback path.
 - Writes the Conversation + Messages + edges + NEXT chronology via `memoryArchiveWrite` directly (no MCP envelope between steps).
 
 NO insight pass runs. The `--no-insight` flag of older releases is gone — Phase 1 always means parse + filter + archive-write, nothing else.
@@ -87,7 +89,7 @@ Stdout JSON shape (success — full diagnostic counters per Task 871 success cri
   "messagesAlreadyExisted": 0,
   "nextEdgesProcessed": 1706,
   "nextEdgesCreated": 1706,
-  "participantsAlreadyExisted": 0,
+  "participantsAlreadyExisted": 2,
   "ms": 6800
 }
 ```

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -123,7 +123,7 @@ Per-source archive imports keep their own skill because their CSVs already encod
   - **Phase 1 — preview-then-filtered-write** (`whatsapp-import` skill). Phase 1 is LLM-FREE. Three steps:
     1. **Preview** via `mcp__memory__whatsapp-export-preview` — read-only parse that returns `{conversationSha256, parsed, mediaSkipped, systemSkipped, dateRange:{first,last}, senders:[{name,messageCount}], totalMessages, archiveBytes}`. No Cypher writes.
     2. **Operator chooses a filter.** Surface the preview to the operator and ask: "Filter to apply: `all`, `senders=<csv>`, or `date-range=<isoFrom>..<isoTo>`?". `--filter` is mandatory — the deterministic Bash entry refuses to write without it (`feedback_compress_at_ingest_for_bulk_archives.md`).
-    3. **Archive-write** via `bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin|public> --filter <chosen>`. Parses, applies the filter, writes Conversation + Messages with chronological NEXT chain, auto-creates one `:Person {participantStatus:'auto-created'}` per distinct senderName. ZERO `:Observation` writes — the LLM insight pass moved to Phase 2.
+    3. **Archive-write** via `bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --subject-person-id <id> --scope <admin|public> --filter <chosen>`. Parses, applies the filter, writes Conversation + Messages with chronological NEXT chain. Writer is bound to the `{owner, subject}` pair from the preview histogram — any parsed senderName outside that closed set LOUD-FAILs (Task 887 §A0); the script does NOT auto-create participant `:Person` nodes. ZERO `:Observation` writes — the LLM insight pass moved to Phase 2.
 
     Phase 1 agent-return is COUNTERS ONLY — no inline enumeration of mention/task/preference counts, no multi-paragraph "ask to enrich" prose. Surface as one chat message: the JSON shape `{conversationElementId, conversationId, parsed, written, alreadyExisted, nextEdgesCreated, ms}` plus one sentence: "Preview before any future re-import via `mcp__memory__whatsapp-export-preview`; enrich semantically when ready via the `whatsapp-import-enrich` skill." The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` / `memory-archive-write{archiveType:whatsapp-export}` MCP tools remain blocked at the harness; the Bash script is the only supported archive-write invocation. SKILL: `platform/plugins/whatsapp-import/skills/whatsapp-import/SKILL.md`.
   - **Phase 2 — enrich** (`whatsapp-import-enrich` skill). Operator-triggered ("enrich the X chat"). First runs `mcp__memory__whatsapp-export-insight-pass` against the already-loaded Conversation (chunkSize=50, overlap=5, server-side `confidence>=0.8` gate) to lay down `:Observation {observationStatus:'auto-extracted'}` rows. Then walks the auto-created participants and auto-extracted observations, surfacing evidence per row, and writes operator-confirmed wiring (`apoc.refactor.mergeNodes` for participant promotion/merge, `:MENTIONS` and `:RELATED_TO` edges with `evidenceSnippet`/`evidenceMessageIds`, `:Task` via `mcp__tasks__task-create`, `:Preference` via `memory-write`). Idempotent — re-running surfaces only items still in `auto-created`/`auto-extracted` state. SKILL: `platform/plugins/whatsapp-import/skills/whatsapp-import-enrich/SKILL.md`.

package/payload/server/chunk-JNVZQMTZ.js

@@ -0,0 +1,593 @@
+import {
+  __commonJS,
+  __toESM,
+  getSession
+} from "./chunk-NAP6XMLW.js";
+
+// ../lib/graph-write/dist/audit.js
+var require_audit = __commonJS({
+  "../lib/graph-write/dist/audit.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.auditCypherWrite = auditCypherWrite;
+    exports.formatAuditLine = formatAuditLine;
+    var EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+    var CREATE_OR_MERGE_NODE = /\b(?:CREATE|MERGE)\s*\(\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*[A-Z]/g;
+    var PROVENANCE_TOKEN = /\bcreatedBy(?:Agent|Tool|Session|Source)\b/g;
+    function stripStringLiterals(cypher) {
+      return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+    }
+    function extractEdgeTypes(cleaned) {
+      const out = /* @__PURE__ */ new Set();
+      for (const m of cleaned.matchAll(EDGE_PATTERN)) {
+        for (const t of m[1].split("|")) {
+          const clean = t.trim();
+          if (clean)
+            out.add(clean);
+        }
+      }
+      return out;
+    }
+    function countCreateOrMergeNodes(cleaned) {
+      const matches = cleaned.match(CREATE_OR_MERGE_NODE);
+      return matches ? matches.length : 0;
+    }
+    function countProvenanceStamps(cleaned) {
+      const matches = cleaned.match(PROVENANCE_TOKEN);
+      return matches ? matches.length : 0;
+    }
+    function auditCypherWrite(input) {
+      const warnings = [];
+      const cleaned = stripStringLiterals(input.cypher);
+      const referencedTypes = extractEdgeTypes(cleaned);
+      for (const t of referencedTypes) {
+        if (!input.schema.relationshipTypes.has(t)) {
+          warnings.push({ kind: "unknown-type-warning", type: t });
+        }
+      }
+      if (input.nodesCreated > 0) {
+        const createOrMergeNodes = countCreateOrMergeNodes(cleaned);
+        if (createOrMergeNodes > 0) {
+          const stamps = countProvenanceStamps(cleaned);
+          if (stamps < createOrMergeNodes) {
+            warnings.push({
+              kind: "missing-provenance-warning",
+              created: createOrMergeNodes,
+              stamped: stamps
+            });
+          }
+        }
+      }
+      if (input.orphanIds.length > 0) {
+        warnings.push({ kind: "orphan-warning", orphanIds: input.orphanIds });
+      }
+      return warnings;
+    }
+    function formatAuditLine(line) {
+      const prefixField = `query="${line.cypherPrefix.replace(/"/g, "'")}"`;
+      switch (line.kind) {
+        case "accepted":
+          return `[graph-cypher-write] accepted ${prefixField} nodesCreated=${line.nodesCreated} relsCreated=${line.relsCreated} agentName=${line.agentName} sessionId=${line.sessionId}`;
+        case "orphan-warning":
+          return `[graph-cypher-write] orphan-warning ${prefixField} orphanIds=${line.orphanIds.join(",")}`;
+        case "unknown-type-warning":
+          return `[graph-cypher-write] unknown-type-warning ${prefixField} type=${line.type}`;
+        case "missing-provenance-warning":
+          return `[graph-cypher-write] missing-provenance-warning ${prefixField} created=${line.created} stamped=${line.stamped}`;
+      }
+    }
+  }
+});
+
+// ../lib/graph-write/dist/index.js
+var require_dist = __commonJS({
+  "../lib/graph-write/dist/index.js"(exports) {
+    "use strict";
+    var __createBinding = exports && exports.__createBinding || (Object.create ? (function(o, m, k, k2) {
+      if (k2 === void 0) k2 = k;
+      var desc = Object.getOwnPropertyDescriptor(m, k);
+      if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+        desc = { enumerable: true, get: function() {
+          return m[k];
+        } };
+      }
+      Object.defineProperty(o, k2, desc);
+    }) : (function(o, m, k, k2) {
+      if (k2 === void 0) k2 = k;
+      o[k2] = m[k];
+    }));
+    var __exportStar = exports && exports.__exportStar || function(m, exports2) {
+      for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports2, p)) __createBinding(exports2, m, p);
+    };
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.ACTION_PROVENANCE_LABELS = void 0;
+    exports.stampCreatedBy = stampCreatedBy;
+    exports.writeNodeWithEdges = writeNodeWithEdges2;
+    __exportStar(require_audit(), exports);
+    exports.ACTION_PROVENANCE_LABELS = /* @__PURE__ */ new Set([
+      "Person",
+      "UserProfile",
+      "AdminUser",
+      "Organization",
+      "LocalBusiness",
+      "CloudflareTunnel",
+      "CloudflareHostname"
+    ]);
+    function requiresActionProvenance(labels) {
+      for (const label of labels) {
+        if (exports.ACTION_PROVENANCE_LABELS.has(label))
+          return true;
+      }
+      return false;
+    }
+    function findProducedFromTaskCandidates(relationships) {
+      return relationships.filter((r) => r.type === "PRODUCED" && r.direction === "incoming");
+    }
+    function stampCreatedBy(props, createdBy) {
+      return {
+        ...props,
+        createdByAgent: createdBy.agent ?? "unknown",
+        createdBySession: createdBy.session ?? "unknown",
+        createdByTool: createdBy.tool ?? null,
+        createdBySource: createdBy.source ?? null
+      };
+    }
+    async function writeNodeWithEdges2(params) {
+      const { session, labels, props, relationships, createdBy } = params;
+      const agentLabel = createdBy.agent ?? createdBy.source ?? "unknown";
+      const labelCsv = labels.join(",");
+      const reviewDigestActionTool = typeof props.actionTool === "string" && props.actionTool === "review-digest-compose";
+      if (labels.includes("ReviewAlert") || reviewDigestActionTool) {
+        const actionToolField = reviewDigestActionTool ? "review-digest-compose" : "n/a";
+        process.stderr.write(`[graph-write] reject reason=removed-feature labels=${labelCsv} actionTool=${actionToolField} agent=${agentLabel}
+`);
+        throw new Error("Write doctrine violated: review-detector feature removed (Task 884) \u2014 `:ReviewAlert` and `:Event {actionTool:'review-digest-compose'}` writes are not allowed.");
+      }
+      if (!relationships || relationships.length < 1) {
+        process.stderr.write(`[graph-write] reject reason=zero-relationships labels=${labelCsv} agent=${agentLabel}
+`);
+        throw new Error("Write doctrine violated: a node must be created with at least one relationship. See .docs/neo4j.md (Write doctrine).");
+      }
+      const labelStr = labels.map((l) => `\`${l.replace(/`/g, "")}\``).join(":");
+      const nodeProps = stampCreatedBy(props, createdBy);
+      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 elementId(t) AS id, labels(t) AS labels`, { ids: targetIds });
+        const labelsByTarget = /* @__PURE__ */ new Map();
+        for (const rec of check.records) {
+          labelsByTarget.set(rec.get("id"), rec.get("labels"));
+        }
+        const found = labelsByTarget.size;
+        const uniqueRequested = new Set(targetIds).size;
+        if (found !== uniqueRequested) {
+          process.stderr.write(`[graph-write] reject reason=unresolved-target labels=${labelCsv} agent=${agentLabel} requested=${uniqueRequested} found=${found}
+`);
+          throw new Error(`Write doctrine violated: ${uniqueRequested - found} of ${uniqueRequested} relationship target(s) did not resolve (elementId mismatch). No node created.`);
+        }
+        let producedByTaskId = 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}
+`);
+            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(`CREATE (n:${labelStr} $props) RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`, { props: nodeProps });
+        } catch (err) {
+          const code = err?.code ?? "";
+          if (code === "Neo.ClientError.Schema.ConstraintValidationFailed" && labels.includes("UserProfile")) {
+            const accountIdProp = nodeProps.accountId;
+            const userIdProp = nodeProps.userId;
+            const acctSlice = typeof accountIdProp === "string" ? accountIdProp.slice(0, 8) : "unknown";
+            const userSlice = typeof userIdProp === "string" ? userIdProp.slice(0, 8) : "unknown";
+            process.stderr.write(`[graph-write] reject reason=user-profile-uniqueness-violation accountId=${acctSlice} userId=${userSlice} writer=${agentLabel}
+`);
+          }
+          throw err;
+        }
+        const nodeId = nodeRes.records[0].get("nodeId");
+        const nodeLabels = nodeRes.records[0].get("nodeLabels");
+        let edgesCreated = 0;
+        for (const rel of relationships) {
+          const type = rel.type.replace(/`/g, "");
+          const q = rel.direction === "outgoing" ? `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (a)-[:\`${type}\`]->(b)` : `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (b)-[:\`${type}\`]->(a)`;
+          const r = await tx.run(q, { from: nodeId, to: rel.targetNodeId });
+          const created = r.summary.counters.updates().relationshipsCreated;
+          if (created === 0) {
+            process.stderr.write(`[graph-write] reject reason=unresolved-target-on-create labels=${labelCsv} agent=${agentLabel} relType=${rel.type} targetId=${rel.targetNodeId}
+`);
+            throw new Error(`Write doctrine violated: relationship CREATE to target ${rel.targetNodeId} produced 0 edges (target likely deleted concurrently after pre-check). Transaction rolled back.`);
+          }
+          edgesCreated += created;
+        }
+        if (edgesCreated !== relationships.length) {
+          process.stderr.write(`[graph-write] reject reason=edge-count-mismatch labels=${labelCsv} agent=${agentLabel} requested=${relationships.length} created=${edgesCreated}
+`);
+          throw new Error(`Write doctrine violated: expected ${relationships.length} edges, created ${edgesCreated}. Transaction rolled back.`);
+        }
+        process.stderr.write(`[graph-write] accepted labels=${labelCsv} edges=${edgesCreated} createdByAgent=${createdBy.agent ?? "unknown"} createdByTool=${createdBy.tool ?? createdBy.source ?? "unknown"} producedByTask=${producedByTaskId ?? "none"}
+`);
+        return { nodeId, labels: nodeLabels, edgesCreated };
+      });
+    }
+  }
+});
+
+// app/lib/cloudflare-task-tracker.ts
+import { readFileSync, existsSync } from "fs";
+import { randomUUID } from "crypto";
+var import_dist = __toESM(require_dist(), 1);
+var CREATED_BY_AGENT = "cloudflare-setup-endpoint";
+var TASK_KIND = "cloudflare-tunnel-login";
+async function openCloudflareTask(params) {
+  const { accountId, conversationKey, inputsProvided, inputs, messageId } = params;
+  const taskId = randomUUID();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const session = getSession();
+  try {
+    const conv = await session.run(
+      `MATCH (c:Conversation {sessionKey: $conversationKey, accountId: $accountId}) RETURN elementId(c) AS id LIMIT 1`,
+      { conversationKey, accountId }
+    );
+    if (conv.records.length === 0) {
+      throw new Error(
+        `cloudflare-task-tracker: no Conversation with sessionKey=${conversationKey.slice(-8)} for accountId \u2014 refusing to create an orphan Task`
+      );
+    }
+    const conversationElementId = conv.records[0].get("id");
+    let messageElementId = null;
+    let raisedDuringTag = `raisedDuringConversation=${conversationKey.slice(-8)}`;
+    if (messageId) {
+      const convIdRow = await session.run(
+        `MATCH (c:Conversation {sessionKey: $conversationKey, accountId: $accountId}) RETURN c.conversationId AS conversationId LIMIT 1`,
+        { conversationKey, accountId }
+      );
+      const conversationId = convIdRow.records.length > 0 ? convIdRow.records[0].get("conversationId") : null;
+      if (conversationId) {
+        const msgRow = await session.run(
+          `MATCH (m:Message {messageId: $messageId, accountId: $accountId, conversationId: $conversationId}) RETURN elementId(m) AS id LIMIT 1`,
+          { messageId, accountId, conversationId }
+        );
+        if (msgRow.records.length > 0) {
+          messageElementId = msgRow.records[0].get("id");
+          raisedDuringTag = `raisedDuringMessage=${messageId.slice(0, 8)}`;
+        }
+      }
+    }
+    const props = {
+      taskId,
+      accountId,
+      name: "Cloudflare tunnel login + setup",
+      description: `Deterministic cloudflare setup invoked by /api/admin/cloudflare/setup. inputsProvided=[${inputsProvided.join(", ")}]`,
+      status: "running",
+      priority: "normal",
+      kind: TASK_KIND,
+      inputsProvided,
+      startedAt: now,
+      createdAt: now,
+      updatedAt: now
+    };
+    if (inputs?.adminLabel) props["inputs.adminLabel"] = inputs.adminLabel;
+    if (inputs?.adminDomain) props["inputs.adminDomain"] = inputs.adminDomain;
+    if (inputs?.publicLabel) props["inputs.publicLabel"] = inputs.publicLabel;
+    if (inputs?.publicDomain) props["inputs.publicDomain"] = inputs.publicDomain;
+    if (inputs?.apex) props["inputs.apex"] = inputs.apex;
+    const relationships = [
+      {
+        type: "RAISED_DURING",
+        direction: "outgoing",
+        targetNodeId: messageElementId ?? conversationElementId
+      }
+    ];
+    const result = await (0, import_dist.writeNodeWithEdges)({
+      session,
+      labels: ["Task"],
+      props,
+      relationships,
+      createdBy: {
+        agent: CREATED_BY_AGENT,
+        session: conversationKey,
+        tool: "cloudflare-setup-endpoint"
+      }
+    });
+    process.stderr.write(
+      `[task] action-start kind=${TASK_KIND} taskId=${taskId} ${raisedDuringTag}
+`
+    );
+    return { taskId, taskElementId: result.nodeId };
+  } finally {
+    await session.close();
+  }
+}
+async function appendCloudflareSteps(taskId, accountId, streamLogPath) {
+  if (!existsSync(streamLogPath)) return [];
+  let content;
+  try {
+    content = readFileSync(streamLogPath, "utf-8");
+  } catch {
+    return [];
+  }
+  const steps = [];
+  for (const line of content.split(/\r?\n/)) {
+    const m = line.match(/\bphase_line\s+setup-tunnel\s+step=(\S+)/);
+    if (m) steps.push(m[1]);
+  }
+  if (steps.length === 0) return [];
+  const session = getSession();
+  try {
+    await session.run(
+      `MATCH (t:Task {taskId: $taskId, accountId: $accountId})
+       SET t.steps = coalesce(t.steps, []) + $steps,
+           t.updatedAt = $updatedAt`,
+      { taskId, accountId, steps, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }
+    );
+    for (const step of steps) {
+      process.stderr.write(
+        `[task] action-step kind=${TASK_KIND} taskId=${taskId} step=${step}
+`
+      );
+    }
+    return steps;
+  } finally {
+    await session.close();
+  }
+}
+async function completeCloudflareTask(params) {
+  const { taskId, taskElementId, accountId, conversationKey, tunnelId, tunnelName, hostnames, status, errorMessage } = params;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (status === "failed" && (!errorMessage || errorMessage.trim().length === 0)) {
+    throw new Error(
+      "cloudflare-task-tracker: errorMessage is required when status='failed' (Task 885 process-provenance contract)."
+    );
+  }
+  const session = getSession();
+  try {
+    if (status === "completed" && tunnelId && tunnelName) {
+      const conv = await session.run(
+        `MATCH (c:Conversation {sessionKey: $conversationKey, accountId: $accountId}) RETURN elementId(c) AS id LIMIT 1`,
+        { conversationKey, accountId }
+      );
+      const conversationElementId = conv.records.length > 0 ? conv.records[0].get("id") : null;
+      const tunnelProps = {
+        accountId,
+        tunnelId,
+        tunnelName,
+        createdAt: now,
+        updatedAt: now
+      };
+      const tunnelRels = [
+        { type: "PRODUCED", direction: "incoming", targetNodeId: taskElementId }
+      ];
+      if (conversationElementId) {
+        tunnelRels.push({
+          type: "RAISED_DURING",
+          direction: "outgoing",
+          targetNodeId: conversationElementId
+        });
+      }
+      const tunnelWrite = await (0, import_dist.writeNodeWithEdges)({
+        session,
+        labels: ["CloudflareTunnel"],
+        props: tunnelProps,
+        relationships: tunnelRels,
+        createdBy: {
+          agent: CREATED_BY_AGENT,
+          session: conversationKey,
+          tool: "cloudflare-setup-endpoint"
+        }
+      });
+      for (const h of hostnames ?? []) {
+        const hostRels = [
+          { type: "PRODUCED", direction: "incoming", targetNodeId: taskElementId },
+          {
+            type: "ROUTES_TO",
+            direction: "outgoing",
+            targetNodeId: tunnelWrite.nodeId
+          }
+        ];
+        await (0, import_dist.writeNodeWithEdges)({
+          session,
+          labels: ["CloudflareHostname"],
+          props: {
+            accountId,
+            hostnameValue: h.hostnameValue,
+            tunnelId,
+            isApex: h.isApex,
+            createdAt: now,
+            updatedAt: now
+          },
+          relationships: hostRels,
+          createdBy: {
+            agent: CREATED_BY_AGENT,
+            session: conversationKey,
+            tool: "cloudflare-setup-endpoint"
+          }
+        });
+      }
+    }
+    const setClauses = [
+      "t.status = $status",
+      "t.completedAt = $now",
+      "t.updatedAt = $now"
+    ];
+    const queryParams = { taskId, accountId, status, now };
+    if (status === "failed" && errorMessage) {
+      setClauses.push("t.errorMessage = $errorMessage");
+      queryParams.errorMessage = errorMessage;
+    }
+    if (status === "completed") {
+      if (tunnelId) {
+        setClauses.push("t.tunnelId = $tunnelId");
+        queryParams.tunnelId = tunnelId;
+      }
+      if (tunnelName) {
+        setClauses.push("t.tunnelName = $tunnelName");
+        queryParams.tunnelName = tunnelName;
+      }
+      if (hostnames && hostnames.length > 0) {
+        setClauses.push("t.hostnames = $hostnamesList");
+        queryParams.hostnamesList = hostnames.map((h) => h.hostnameValue);
+      }
+    }
+    const updateRes = await session.run(
+      `MATCH (t:Task {taskId: $taskId, accountId: $accountId})
+       SET ${setClauses.join(", ")}
+       RETURN size(coalesce(t.steps, [])) AS stepsCount, count(t) AS affected`,
+      queryParams
+    );
+    const stepsCount = updateRes.records[0]?.get("stepsCount")?.toNumber?.() ?? 0;
+    const affected = updateRes.records[0]?.get("affected")?.toNumber?.() ?? 0;
+    if (affected !== 1) {
+      throw new Error(
+        `cloudflare-task-tracker: completeCloudflareTask MATCH count=${affected} for taskId=${taskId} \u2014 Task missing or accountId mismatch`
+      );
+    }
+    process.stderr.write(
+      `[task] action-done kind=${TASK_KIND} taskId=${taskId} status=${status} stepsCount=${stepsCount}
+`
+    );
+  } finally {
+    await session.close();
+  }
+}
+function readTunnelState(brandConfigDir) {
+  const statePath = `${process.env.HOME ?? ""}/${brandConfigDir}/cloudflared/tunnel.state`;
+  if (!existsSync(statePath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, "utf-8"));
+    const tunnelId = typeof parsed.tunnelId === "string" ? parsed.tunnelId : null;
+    const tunnelName = typeof parsed.tunnelName === "string" ? parsed.tunnelName : null;
+    const domain = typeof parsed.domain === "string" ? parsed.domain : null;
+    if (!tunnelId || !tunnelName || !domain) return null;
+    return { tunnelId, tunnelName, domain };
+  } catch {
+    return null;
+  }
+}
+var CLOUDFLARE_TASK_DIAGNOSTICS = {
+  scriptExitedNonzero: "script-exited-nonzero",
+  noTunnelStateOnDisk: "no-tunnel-state-on-disk",
+  endpointDiedPreReconcile: "endpoint-died-pre-reconcile"
+};
+var RECONCILE_DELAY_BUDGET_MS = 9e4;
+var RECONCILE_HARD_AGE_MS = 60 * 60 * 1e3;
+async function recoverRunningCloudflareTasks(accountId, brandConfigDir, conversationKeyForState) {
+  const session = getSession();
+  try {
+    const cutoff = new Date(Date.now() - RECONCILE_DELAY_BUDGET_MS).toISOString();
+    const stale = await session.run(
+      `MATCH (t:Task {accountId: $accountId, kind: $kind, status: 'running'})
+       WHERE t.startedAt < $cutoff
+       RETURN t.taskId AS taskId, elementId(t) AS taskElementId, t.startedAt AS startedAt
+       ORDER BY t.startedAt ASC`,
+      { accountId, kind: TASK_KIND, cutoff }
+    );
+    const tunnelState = readTunnelState(brandConfigDir);
+    const tunnelStateFound = tunnelState !== null;
+    const resolved = [];
+    for (const record of stale.records) {
+      const taskId = record.get("taskId");
+      const taskElementId = record.get("taskElementId");
+      const startedAt = record.get("startedAt");
+      const ageMs = Date.now() - new Date(startedAt).getTime();
+      try {
+        if (tunnelStateFound && tunnelState) {
+          const tunnelExistsRow = await session.run(
+            `MATCH (t:Task {taskId: $taskId, accountId: $accountId})-[:PRODUCED]->(tn:CloudflareTunnel {tunnelId: $tunnelId})
+             RETURN count(tn) AS existsCount`,
+            { taskId, accountId, tunnelId: tunnelState.tunnelId }
+          );
+          const existsCountRaw = tunnelExistsRow.records[0]?.get("existsCount");
+          const tunnelAlreadyExists = (typeof existsCountRaw === "number" ? existsCountRaw : existsCountRaw?.toNumber?.() ?? 0) > 0;
+          if (tunnelAlreadyExists) {
+            const now = (/* @__PURE__ */ new Date()).toISOString();
+            const closeRes = await session.run(
+              `MATCH (t:Task {taskId: $taskId, accountId: $accountId})
+               SET t.status = 'completed', t.completedAt = $now, t.updatedAt = $now,
+                   t.tunnelId = $tunnelId, t.tunnelName = $tunnelName
+               RETURN count(t) AS affected`,
+              { taskId, accountId, now, tunnelId: tunnelState.tunnelId, tunnelName: tunnelState.tunnelName }
+            );
+            const aff = closeRes.records[0]?.get("affected");
+            const affN = typeof aff === "number" ? aff : aff?.toNumber?.() ?? 0;
+            if (affN !== 1) {
+              throw new Error(`reconciler close-out MATCH count=${affN} for taskId=${taskId}`);
+            }
+            resolved.push({ taskId, resolution: "completed-existing-tunnel" });
+            process.stderr.write(
+              `[task] action-recover kind=${TASK_KIND} taskId=${taskId} age=${Math.round(ageMs / 1e3)}s tunnel-state-found=true tunnel-already-written=true resolution=completed
+`
+            );
+            continue;
+          }
+          const convRow = await session.run(
+            `MATCH (t:Task {taskId: $taskId, accountId: $accountId})-[:RAISED_DURING]->(target)
+             OPTIONAL MATCH (target)-[:PART_OF]->(c:Conversation)
+             RETURN coalesce(c.sessionKey, target.sessionKey) AS sessionKey LIMIT 1`,
+            { taskId, accountId }
+          );
+          const resolvedConversationKey = convRow.records[0]?.get("sessionKey");
+          await completeCloudflareTask({
+            taskId,
+            taskElementId,
+            accountId,
+            // Empty string when the edge resolution found no Conversation
+            // (rare — would require a malformed Task with no RAISED_DURING).
+            // The live close-out will produce a Tunnel without provenance
+            // edges in that case; better than silently dropping the close-out.
+            conversationKey: resolvedConversationKey ?? conversationKeyForState ?? "",
+            tunnelId: tunnelState.tunnelId,
+            tunnelName: tunnelState.tunnelName,
+            hostnames: void 0,
+            status: "completed"
+          });
+          resolved.push({ taskId, resolution: "completed" });
+          process.stderr.write(
+            `[task] action-recover kind=${TASK_KIND} taskId=${taskId} age=${Math.round(ageMs / 1e3)}s tunnel-state-found=true tunnel-already-written=false resolution=completed
+`
+          );
+        } else {
+          const diagnostic = ageMs > RECONCILE_HARD_AGE_MS ? CLOUDFLARE_TASK_DIAGNOSTICS.noTunnelStateOnDisk : CLOUDFLARE_TASK_DIAGNOSTICS.endpointDiedPreReconcile;
+          await completeCloudflareTask({
+            taskId,
+            taskElementId,
+            accountId,
+            conversationKey: conversationKeyForState ?? "",
+            status: "failed",
+            errorMessage: diagnostic
+          });
+          resolved.push({ taskId, resolution: `failed-${diagnostic}` });
+          process.stderr.write(
+            `[task] action-recover kind=${TASK_KIND} taskId=${taskId} age=${Math.round(ageMs / 1e3)}s tunnel-state-found=false resolution=failed errorMessage=${diagnostic}
+`
+          );
+        }
+      } catch (err) {
+        process.stderr.write(
+          `[task] action-recover kind=${TASK_KIND} taskId=${taskId} resolution=error reason="${err instanceof Error ? err.message : String(err)}"
+`
+        );
+      }
+    }
+    return { scanned: stale.records.length, resolved };
+  } finally {
+    await session.close();
+  }
+}
+
+export {
+  openCloudflareTask,
+  appendCloudflareSteps,
+  completeCloudflareTask,
+  readTunnelState,
+  CLOUDFLARE_TASK_DIAGNOSTICS,
+  recoverRunningCloudflareTasks
+};