@rubytech/create-maxy 1.0.799 → 1.0.801

package/payload/platform/plugins/cloudflare/scripts/_cdp-authorize.mjs

@@ -1,33 +1,51 @@
 #!/usr/bin/env node
-// Drive the Cloudflare argotunnel Authorize click via CDP WebSocket (Task 588).
+// Drive the Cloudflare argotunnel consent page to a deterministic terminal
+// state via CDP WebSocket. Originally Task 588 (Authorize click from code,
+// collapsing a 180 s human-latency window). Task 855 widens the contract to
+// three states because the dashboard does not always render a button — once
+// the bound account has authorized this device's zones, navigating the same
+// (or a fresh) consent URL renders a Success modal verbatim, and the
+// pre-855 helper conflated "no button visible yet" with "no button will
+// ever appear" and exited error.
 //
-// Why this exists: setup-tunnel.sh navigates the VNC browser to the argotunnel
-// consent URL via `PUT /json/new?<url>`. That opens the page but does not
-// press the Authorize button. Pre-Task 588 the script then polled for
-// cert.pem for up to 180 seconds, waiting for a human click in VNC. This
-// helper does the click from code, collapsing the wait to ~1-3 seconds.
-//
-// Protocol: Chrome DevTools Protocol over WebSocket (https://chromedevtools.github.io/devtools-protocol/).
+// Protocol: Chrome DevTools Protocol over WebSocket
+// (https://chromedevtools.github.io/devtools-protocol/):
 //   1. GET http://127.0.0.1:9222/json/list → find the target with matching id;
 //      extract webSocketDebuggerUrl.
 //   2. Open WS, enable Page + Runtime domains.
 //   3. Wait for Page.loadEventFired (or observe document.readyState==='complete').
-//   4. Poll Runtime.evaluate every 200 ms for up to ~3 s, looking for a
-//      button or input[type=submit] whose trimmed text/value matches
-//      /^(authorize|connect)$/i. When found, click via JS (click() on the
-//      matched node). Exit 0 on success, 1 with structured stderr otherwise.
+//   4. Poll Runtime.evaluate every 200 ms for up to ~3 s, evaluating the
+//      tri-state matcher from _cdp-authorize-matcher.mjs. The matcher
+//      returns one of:
+//        - { kind:'button', descriptor } — Authorize/Connect button found,
+//                                          click() fired in-page; emit
+//                                          reason=clicked, exit 0.
+//        - { kind:'success' }            — Success modal text detected
+//                                          ("Cloudflared has installed a
+//                                          certificate"); cert is bound to
+//                                          the account. Emit reason=
+//                                          cert-already-installed, exit 0.
+//                                          Caller's existing cert-poll picks
+//                                          up the cert (callback is
+//                                          idempotent on this navigation).
+//        - null                          — Neither anchor matched yet; loop.
+//      After BUTTON_POLL_TIMEOUT_MS with no terminal match, emit
+//      reason=authorize-button-not-found, exit 1.
 //
 // Exit codes:
-//   0 - clicked successfully
-//   1 - authorize-button-not-found (the happy-path loud failure)
+//   0 - terminal success (reason=clicked OR reason=cert-already-installed)
+//   1 - authorize-button-not-found (loud failure — button AND modal absent)
 //   2 - cdp-ws-unreachable or node-websocket-unavailable
 //   3 - target-not-found (the target_id isn't in /json/list)
 //   4 - click-evaluate-threw (Runtime.evaluate returned wasThrown=true)
 //   5 - protocol-error (malformed CDP response)
 //
-// Each structured failure prints ONE line to stdout in phase_line-compatible
-// shape so setup-tunnel.sh's tee_subprocess picks it up into the stream log:
+// Stdout contract (read by setup-tunnel.sh's awk-based reason parser):
 //   cdp-authorize result=<ok|error> reason=<…> elapsed_ms=<…> [detail=<…>]
+// Exactly ONE such line per invocation; the wrapper takes the LAST
+// `result=ok` line via awk so future debug-line additions cannot mis-route.
+
+import { MATCH_EXPR } from './_cdp-authorize-matcher.mjs';
 
 const CDP_HOST = '127.0.0.1';
 const CDP_PORT = 9222;
@@ -211,35 +229,16 @@ try {
   die(1, 'page-load-timeout', { detail: err.message, elapsed_ms: Date.now() - started });
 }
 
-// Poll for the Authorize button. The expression finds the first
-// button/input[type=submit] whose trimmed textContent/value matches
-// /^(authorize|connect)$/i, clicks it, and returns a descriptor. Returns
-// null when no match yet.
-const CLICK_EXPR = `
-(() => {
-  const candidates = Array.from(document.querySelectorAll('button, input[type="submit"]'));
-  const match = candidates.find((el) => {
-    const text = (el.textContent ?? el.value ?? '').trim();
-    return /^(authorize|connect)$/i.test(text) && !el.disabled;
-  });
-  if (!match) return null;
-  const descriptor = {
-    tag: match.tagName.toLowerCase(),
-    text: (match.textContent ?? match.value ?? '').trim().slice(0, 40),
-    disabled: Boolean(match.disabled),
-  };
-  match.click();
-  return descriptor;
-})()
-`;
-
-const clickDeadline = Date.now() + BUTTON_POLL_TIMEOUT_MS;
-let clicked = null;
-while (Date.now() < clickDeadline) {
+// Poll the consent page until one of the three terminal states resolves.
+// MATCH_EXPR is built from _cdp-authorize-matcher.mjs's findMatch so the
+// JSDOM unit tests and the live CDP path execute literally identical logic.
+const matchDeadline = Date.now() + BUTTON_POLL_TIMEOUT_MS;
+let matched = null;
+while (Date.now() < matchDeadline) {
   let r;
   try {
     r = await send('Runtime.evaluate', {
-      expression: CLICK_EXPR,
+      expression: MATCH_EXPR,
       returnByValue: true,
       awaitPromise: false,
     });
@@ -253,22 +252,33 @@ while (Date.now() < clickDeadline) {
     });
   }
   const val = r?.result?.value;
-  if (val && typeof val === 'object') {
-    clicked = val;
+  if (val && typeof val === 'object' && (val.kind === 'button' || val.kind === 'success')) {
+    matched = val;
     break;
   }
   await new Promise((res) => setTimeout(res, BUTTON_POLL_INTERVAL_MS));
 }
 
-if (!clicked) {
+if (!matched) {
   die(1, 'authorize-button-not-found', { elapsed_ms: Date.now() - started });
 }
 
-emit('ok', 'clicked', {
-  tag: clicked.tag,
-  text: clicked.text,
-  elapsed_ms: Date.now() - started,
-});
+if (matched.kind === 'button') {
+  const d = matched.descriptor ?? {};
+  emit('ok', 'clicked', {
+    tag: d.tag,
+    text: d.text,
+    elapsed_ms: Date.now() - started,
+  });
+} else {
+  // matched.kind === 'success' — Success modal text is on the page; the
+  // bound account already has a cert. Caller drops into the cert-poll loop;
+  // the in-flight cloudflared subprocess receives the idempotent callback
+  // and writes ~/.cloudflared/cert.pem.
+  emit('ok', 'cert-already-installed', {
+    elapsed_ms: Date.now() - started,
+  });
+}
 
 try { ws.close(); } catch { /* best-effort */ }
 process.exit(0);

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

@@ -60,22 +60,74 @@ CFG_DIR="${HOME}/.${BRAND}/cloudflared"
 mkdir -p "${CFG_DIR}"
 
 # --------------------------------------------------------------------------
-# Step 1: OAuth login (only if cert.pem missing). Corresponds to runbook Step 1.
+# Step 1: OAuth login. Corresponds to runbook Step 1.
 #
-# Control flow, rewritten per Task 556:
+# Step 1 is a state machine over three observable variables — brand-scoped
+# cert path, default cert path, and the helper's outcome (Task 855):
+#
+#   ${CFG_DIR}/cert.pem present                   → Step 1 already done; skip.
+#   ${CFG_DIR}/cert.pem missing                AND
+#     ~/.cloudflared/cert.pem present             → pre-flight: a prior run
+#                                                   reached the OAuth callback
+#                                                   but failed before the mv;
+#                                                   promote and skip the
+#                                                   helper. Idempotent.
+#   both missing                                  → spawn cloudflared, drive
+#                                                   the consent page via CDP,
+#                                                   poll for cert.pem, mv.
+#
+# Control flow when both certs are missing (Task 556 / 588 / 855):
 #   1. CDP precheck on 127.0.0.1:9222 — loud failure if Chromium isn't up.
 #   2. Spawn cloudflared with stdout+stderr teed line-by-line to
 #      $STREAM_LOG_PATH with prefix [script:setup-tunnel:cloudflared]
 #      (Task 605's chat-surface namespace — see _stream-log.sh header).
 #   3. Extract the authorize URL with a tolerant regex as it streams.
 #   4. Drive the VNC Chromium to that URL via CDP `PUT /json/new?<url>`.
-#   5. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
-#   6. Move cert.pem into the brand-scoped path.
+#   5. Run _cdp-authorize.mjs — tri-state matcher returns one of:
+#        reason=clicked                  → button matched + clicked
+#        reason=cert-already-installed   → Success modal detected
+#        reason=authorize-button-not-found → loud failure, exit 1
+#      (a)+(b) drop into the cert-pem poll; (c) bubbles up.
+#   6. Wait for ~/.cloudflared/cert.pem to land with bounded timeout.
+#   7. Move cert.pem into the brand-scoped path.
 #
-# Every branch exits 1 loudly naming the failure — no silent retries,
+# Every failure branch exits 1 loudly naming the cause — no silent retries,
 # no xdg-open race, no cloudflared-internal browser-spawn path.
 # --------------------------------------------------------------------------
 
+# Pre-flight cert-promotion (Task 855). When ${CFG_DIR}/cert.pem is missing
+# but the OAuth-default ~/.cloudflared/cert.pem is present, a prior run
+# reached the cloudflared callback but did not survive to the brand-scoped
+# mv at the end of Step 1. The cert is bound to the account already; the
+# only remediation is the move. Doing it before re-spawning cloudflared is
+# what stops Step 1 from looping forever on a dashboard that has moved past
+# a button-bearing state.
+#
+# The mv exit code is checked: if it fails (EACCES, ENOSPC, weird FS state),
+# loud-fail with reason=cert-promote-failed instead of pretending Step 1
+# succeeded — the next steps would die opaquely on the missing brand cert.
+# stderr is captured into the phase_line so the operator sees the actual
+# failure cause (mv exit-code 1 alone cannot disambiguate EACCES from ENOSPC).
+if [ ! -f "${CFG_DIR}/cert.pem" ] && [ -f "${HOME}/.cloudflared/cert.pem" ]; then
+  MV_ERR="$(mktemp -t maxy-cert-promote-err.XXXXXX)"
+  if mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem" 2>"${MV_ERR}"; then
+    rm -f "${MV_ERR}"
+    phase_line setup-tunnel step=oauth-login result=ok \
+      reason=cert-promoted-from-default-path waited="0s"
+  else
+    MV_RC=$?
+    MV_STDERR="$(tr '\n' ' ' < "${MV_ERR}" 2>/dev/null | head -c 200 || echo unavailable)"
+    rm -f "${MV_ERR}"
+    phase_line setup-tunnel step=oauth-login result=error \
+      reason=cert-promote-failed mv_rc="${MV_RC}" stderr="${MV_STDERR}" \
+      from="${HOME}/.cloudflared/cert.pem" to="${CFG_DIR}/cert.pem"
+    echo "ERROR: failed to promote ~/.cloudflared/cert.pem to ${CFG_DIR}/cert.pem (mv exit=${MV_RC})." >&2
+    echo "       mv stderr: ${MV_STDERR}" >&2
+    echo "       Step 1 cannot proceed without the cert in the brand-scoped path." >&2
+    exit 1
+  fi
+fi
+
 if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   phase_line setup-tunnel step=oauth-login cert_path="${CFG_DIR}/cert.pem" display="${DISPLAY:-:99}"
 
@@ -215,22 +267,61 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     echo "ERROR: _cdp-authorize.mjs helper missing or not executable at ${AUTH_HELPER}" >&2
     exit 1
   fi
-  # tee_subprocess pipes the helper's cdp-authorize result= line into the
-  # stream log under the setup-tunnel:cdp-click tag so the chat UI renders
-  # the click outcome in real time. Exit code drives control flow.
-  if tee_subprocess setup-tunnel:cdp-click -- \
-      node "${AUTH_HELPER}" "${CDP_TARGET_ID}"; then
-    phase_line setup-tunnel step=oauth-login result=authorize-clicked \
-      target_id="${CDP_TARGET_ID}"
+  # tee_subprocess_capture pipes the helper's `cdp-authorize result=…` line
+  # into the stream log under the setup-tunnel:cdp-click tag (live-tailable)
+  # AND through this shell's stdout so the wrapper can capture it for the
+  # tri-state reason discriminator (Task 855). The helper writes exactly
+  # one such line per invocation and exits; the shape is its contract:
+  #   `cdp-authorize result=<ok|error> reason=<token> [k=v …]`.
+  # The wrapper's awk takes the LAST `cdp-authorize result=ok ` line so that
+  # any future emit() additions cannot mis-route the discriminator — the
+  # success line is always the last one before exit.
+  HELPER_OUT="$(mktemp -t maxy-cdp-authorize-out.XXXXXX)"
+  if tee_subprocess_capture setup-tunnel:cdp-click -- \
+      node "${AUTH_HELPER}" "${CDP_TARGET_ID}" \
+      > "${HELPER_OUT}"; then
+    HELPER_REASON="$(awk '/^cdp-authorize result=ok / {m=$0} END {if (m) {match(m, /reason=[a-z0-9-]+/); print substr(m, RSTART+7, RLENGTH-7)}}' "${HELPER_OUT}")"
+    rm -f "${HELPER_OUT}"
+    case "${HELPER_REASON}" in
+      clicked)
+        phase_line setup-tunnel step=browser-drive result=ok \
+          reason=clicked target_id="${CDP_TARGET_ID}"
+        ;;
+      cert-already-installed)
+        # The dashboard rendered the Success modal — the bound account
+        # already has a cert. The OAuth callback URL was exercised by this
+        # navigation, so the in-flight cloudflared subprocess receives the
+        # idempotent callback and writes ~/.cloudflared/cert.pem; the poll
+        # below picks it up.
+        phase_line setup-tunnel step=browser-drive result=ok \
+          reason=cert-already-installed target_id="${CDP_TARGET_ID}"
+        ;;
+      *)
+        # Helper exited 0 but emitted a reason this wrapper does not
+        # recognise — protocol drift between helper and wrapper. Loud-fail
+        # rather than silently fall through to the cert-poll, which would
+        # mask the cause if the cert never lands.
+        kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+        phase_line setup-tunnel step=browser-drive result=error \
+          reason=helper-unknown-success-reason raw="${HELPER_REASON:-empty}"
+        echo "ERROR: CDP helper exited 0 with unrecognised reason: ${HELPER_REASON:-empty}" >&2
+        echo "       Expected reason=clicked or reason=cert-already-installed." >&2
+        echo "       Helper / wrapper protocol drift — investigate stream log." >&2
+        exit 1
+        ;;
+    esac
   else
     CLICK_RC=$?
+    rm -f "${HELPER_OUT}"
     kill "${CF_PIPELINE_PID}" 2>/dev/null || true
-    # Helper exit codes: 1=authorize-button-not-found (loud, expected failure
-    # mode when the VNC browser isn't signed into Cloudflare), 2=cdp-ws-unreachable,
-    # 3=target-not-found, 4=click-evaluate-threw, 5=protocol-error. All are
-    # final — no retry, no silent fallback. Map the exit code 1:1 to a reason
-    # string so the stream-log `reason=<…>` is greppable by exact cause; a
-    # single catch-all reason would defeat the observability contract.
+    # Helper exit codes (mapped 1:1 to reason= so stream-log grep is precise;
+    # a catch-all reason would defeat the observability contract):
+    #   1 = authorize-button-not-found (loud — neither button nor success
+    #       modal matched before BUTTON_POLL_TIMEOUT_MS; the form surfaces
+    #       a verbatim quote of references/dashboard-guide.md "Authorise a
+    #       new tunnel" so the operator can recover without SSH).
+    #   2 = cdp-ws-unreachable, 3 = target-not-found, 4 = click-evaluate-threw,
+    #   5 = protocol-error. All are final — no retry, no silent fallback.
     case "${CLICK_RC}" in
       1) CLICK_REASON=authorize-button-not-found ;;
       2) CLICK_REASON=cdp-ws-unreachable ;;
@@ -242,8 +333,13 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     phase_line setup-tunnel step=browser-drive result=error \
       reason="${CLICK_REASON}" click_rc="${CLICK_RC}"
     echo "ERROR: CDP-driven Authorize click failed (helper exit=${CLICK_RC}, reason=${CLICK_REASON})." >&2
-    echo "       If the VNC browser is not signed into Cloudflare, sign in manually," >&2
-    echo "       close the sign-in tab, and re-run setup — or run ~/reset-tunnel.sh first." >&2
+    if [ "${CLICK_REASON}" = "authorize-button-not-found" ]; then
+      echo "       The dashboard did not present an Authorize button or a Success modal." >&2
+      echo "       The form will surface the dashboard click-path for manual recovery." >&2
+    else
+      echo "       The CDP helper failed before reaching a terminal page state." >&2
+      echo "       Re-run setup — or run ~/reset-tunnel.sh first if state is corrupt." >&2
+    fi
     exit 1
   fi
   fi  # end CDP-available branch (Task 664)
@@ -281,7 +377,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
       echo "ERROR: Timed out after ${LOGIN_WAIT}s waiting for cert.pem to land." >&2
       exit 1
     fi
-    # Heartbeat every 2 s after the click. t=0 is the authorize-clicked
+    # Heartbeat every 2 s after the click. t=0 is the browser-drive
     # phase line above; the first heartbeat fires at t=2. Without this line
     # the tailer sees silence for the full 1-20 s round-trip — the exact
     # state Task 588 forbids.
@@ -294,7 +390,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   done
 
   mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
-  phase_line setup-tunnel step=oauth-login result=cert-received \
+  phase_line setup-tunnel step=oauth-login result=ok \
     path="${CFG_DIR}/cert.pem" waited="${LOGIN_WAIT}s"
 fi
 

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

@@ -22,6 +22,8 @@ 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 (Task 558) — 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 three observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`), the OAuth-default cert path (`~/.cloudflared/cert.pem`), and the consent-page DOM via the CDP helper `_cdp-authorize.mjs` (Task 855). 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 helper polls `dash.cloudflare.com/argotunnel` and resolves to one of three terminal outcomes — `reason=clicked` (button matched and clicked), `reason=cert-already-installed` (Success modal text detected — the bound account already has a cert, callback is idempotent so the in-flight cloudflared subprocess writes the cert anyway), or `reason=authorize-button-not-found` (neither anchor matched; loud failure, exit 1). The first two paths drop into the existing brand-scoped cert poll; the third surfaces a remediation card in the form so the operator can complete the consent click in their own browser without SSH or `~/reset-tunnel.sh`.
+
 ### How inputs reach the script
 
 Inputs arrive through the `cloudflare-setup-form` component, not agent Q&A. The onboarding skill renders the form, the user submits admin/public/apex labels and the admin password in one action, and the `/api/admin/cloudflare/setup` endpoint runs (in this order):
@@ -50,6 +52,8 @@ The agent does not invoke the script directly during onboarding — the endpoint
 
 The endpoint returns `{ ok: false, field: "script", message, output }` and the form surfaces the error inline. Relay the output to the user, name the exit code, and cite `references/reset-guide.md` for the next action. Offer to re-render the form after any manual steps the script's error output named. Do not attempt a second invocation outside the form, a Playwright-driven dashboard inspection, or an alternative `cloudflared` command sequence. The discipline rule below applies.
 
+When the failure reason is `authorize-button-not-found` (Task 855), the form renders a verbatim quote of `references/dashboard-guide.md` § "Authorise a new tunnel (pick the right zone)" alongside a "Try again" button — the operator completes the consent click in their own browser, then re-submits the same form. No agent action is required; relay the form's chat acknowledgement when it arrives. Do not suggest `~/reset-tunnel.sh` for this reason — the cert path is intact and a fresh consent click is the only remediation needed.
+
 ---
 
 ## 2. Manual fallback — `references/manual-setup.md`

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

@@ -40,7 +40,7 @@ These are enabled during onboarding and can be added or removed at any time. Som
 | `waitlist` | Waitlist lifecycle — extract sign-ups from conversations, review | — |
 | `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 |
-| `whatsapp-import` | Import a WhatsApp `_chat.txt` export as a Conversation + chronologically-chained Messages, then extract typed insights (mentions, preferences, commitments, observed relationships) — distinct from the live `whatsapp` plugin which is a Baileys QR-pairing channel | Database operator |
+| `whatsapp-import` | Import a WhatsApp `_chat.txt` export as a Conversation + chronologically-chained Messages plus `:Observation` nodes for typed insights (mentions, tasks, preferences, observed relationships). Single Bash entry — `bash platform/plugins/whatsapp-import/bin/whatsapp-ingest.sh <archive> --owner-element-id <id> --scope <admin\|public>` runs parse → archive-write → Haiku insight in one process. Distinct from the live `whatsapp` plugin which is a Baileys QR-pairing channel. | Database operator |
 
 ### Claude Official (marketplace)
 

package/payload/platform/plugins/whatsapp-import/PLUGIN.md

@@ -14,7 +14,7 @@ Ingests a WhatsApp "Export Chat" archive (the `_chat.txt` file plus media attach
 
 ## When this applies
 
-The admin agent delegates to `database-operator` when the operator drops a `_chat.txt` (or its containing folder) into chat. The specialist runs the skill's archive-owner + participant confirmation flow before any line is written, then ingests the messages via `mcp__memory__memory-archive-write` with `archiveType='whatsapp-export'`.
+The admin agent delegates to `database-operator` when the operator drops a `_chat.txt` (or its containing folder) into chat. The specialist runs the skill's archive-owner confirmation flow before any line is written, then invokes the deterministic Bash entry (`bin/whatsapp-ingest.sh`) once: parse, archive-write (via `memoryArchiveWrite` in-process), and Haiku insight all run in one Node process — no MCP envelope between steps (Task 855).
 
 ## Accepted export shapes
 
@@ -28,6 +28,6 @@ WhatsApp's "Export Chat" emits `[DD/MM/YYYY, HH:MM:SS]` prefixes by default in m
 
 ## Relationship to other plugins
 
-- **memory** — the underlying write surface used by the skill (`memory-archive-write` for bulk Conversation+Messages, `memory-write` / `memory-update` for the second-pass typed observations). The skill is parameterised so all writes carry `source='whatsapp'` + `createdByAgent='whatsapp-import'` for provenance.
+- **memory** — the underlying write surface imported in-process by `bin/ingest.mjs` (`memoryArchiveWrite` for bulk Conversation+Messages; direct Cypher `:Observation` writes for the insight pass). All writes carry `source='whatsapp'` + `createdByAgent='whatsapp-import'` provenance. The legacy `mcp__memory__whatsapp-export-parse` / `whatsapp-export-insight-write` MCP tools and the direct `memory-archive-write` MCP path with `archiveType=whatsapp-export` are blocked at the harness — the Bash entry is the only supported invocation surface (Task 855).
 - **database-operator specialist** — owns execution. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause and [database-operator.md](../../../platform/templates/specialists/agents/database-operator.md) per-source archive list.
 - **linkedin-import** — sister plugin under the same pattern (LinkedIn Basic Data Export). Reading [linkedin-import/PLUGIN.md](../linkedin-import/PLUGIN.md) is the fastest way to understand the shape this plugin follows.