@rubytech/create-maxy 1.0.805 → 1.0.807

package/package.json

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

package/payload/platform/neo4j/migrations/004-project-admin-agent.ts

@@ -0,0 +1,247 @@
+/**
+ * Migration 004 — Project the admin agent into the graph and clean up
+ * Conversation channel data (Task 864). Numbered 004 because the 003
+ * slot is held by `003-person-name-eradicate.cypher` (boot-time apply).
+ *
+ * Three idempotent passes:
+ *
+ *   1. For every account directory under data/accounts/<accountId>/agents/admin/
+ *      that carries a config.json, call projectAgent(accountId, accountDir,
+ *      'admin'). The projector is the same function migration 002 uses for
+ *      public agents and is content-agnostic — it reads config.json plus any
+ *      IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY files present and MERGEs the
+ *      :Agent node + four owned :KnowledgeDocument projections. Re-running
+ *      this migration produces no duplicate nodes or edges.
+ *
+ *      Migration 002 explicitly SKIPS admin (line 60: `if (entry.name ===
+ *      "admin") continue`); doing the projection here keeps that skip valid
+ *      and isolates admin-specific concerns to one file.
+ *
+ *   2. For every existing :AdminConversation that does NOT yet have a
+ *      :HANDLED_BY edge, MATCH the freshly-projected admin :Agent and MERGE
+ *      the edge. Guarded with `WHERE NOT EXISTS((c)-[:HANDLED_BY]->(:Agent))`
+ *      so re-runs short-circuit per conversation.
+ *
+ *   3. Backfill `c.channel = 'webchat'` for every Conversation node where
+ *      channel IS NULL. Pre-Task-863 conversations were written without the
+ *      property; channel='webchat' is the correct default — only WhatsApp
+ *      and Telegram sessions ever set non-webchat values, and those have
+ *      always come through sessionKeys prefixed `whatsapp:` or `telegram:`
+ *      (see neo4j-store.ts:171). Idempotent: subsequent runs no-op because
+ *      the WHERE clause matches zero rows.
+ *
+ * Run via the platform/ui standalone runtime so it picks up the same
+ * NEO4J_URI / accounts-directory resolution as the server:
+ *
+ *   cd platform/ui && \
+ *     NEO4J_URI=bolt://… NEO4J_PASSWORD=… \
+ *     npx tsx ../neo4j/migrations/004-project-admin-agent.ts
+ *
+ * Output: structured `[admin-agent-graph-backfill]` lines per account + a
+ * final totals line. Non-zero exit code on any per-account agent-projection
+ * failure surfaces to the operator; subsequent accounts are still attempted.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { projectAgent, getSession } from "../../ui/app/lib/neo4j-store";
+import { ACCOUNTS_DIR } from "../../ui/app/lib/claude-agent/account";
+
+interface PerAccountStats {
+  accountId: string;
+  projected: 0 | 1;
+  failed: 0 | 1;
+  handledByCandidates: number;
+  handledByEdges: number;
+  channelBackfilled: number;
+}
+
+async function projectAccountAdmin(
+  accountId: string,
+  accountDir: string,
+): Promise<{ projected: 0 | 1; failed: 0 | 1 }> {
+  const adminDir = resolve(accountDir, "agents", "admin");
+  const configPath = resolve(adminDir, "config.json");
+  if (!existsSync(adminDir) || !existsSync(configPath)) {
+    return { projected: 0, failed: 0 };
+  }
+  try {
+    await projectAgent(accountId, accountDir, "admin");
+    return { projected: 1, failed: 0 };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(
+      `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} project FAILED error="${msg}"`,
+    );
+    return { projected: 0, failed: 1 };
+  }
+}
+
+interface HandledByStats {
+  candidates: number;
+  edges: number;
+}
+
+/**
+ * Backfill HANDLED_BY edges from AdminConversation nodes to the admin Agent
+ * node. Guarded with NOT EXISTS so re-runs of this migration don't redo work
+ * — and so AdminConversations that already gained a HANDLED_BY edge through
+ * the forward path are skipped.
+ *
+ * `candidates` counts AdminConversations that LACK a HANDLED_BY edge; `edges`
+ * counts edges newly created. The admin :Agent must already exist (created
+ * by pass 1); if it doesn't, the OPTIONAL MATCH falls through and zero edges
+ * are written — surfaced through `candidates - edges`.
+ */
+async function backfillAdminHandledBy(
+  accountId: string,
+): Promise<HandledByStats> {
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (c:AdminConversation {accountId: $accountId})
+       WHERE NOT EXISTS((c)-[:HANDLED_BY]->(:Agent))
+       OPTIONAL MATCH (a:Agent {accountId: $accountId, slug: 'admin'})
+       FOREACH (_ IN CASE WHEN a IS NULL THEN [] ELSE [1] END | MERGE (c)-[:HANDLED_BY]->(a))
+       RETURN
+         count(c) AS candidates,
+         sum(CASE WHEN a IS NULL THEN 0 ELSE 1 END) AS edges`,
+      { accountId },
+    );
+    const toNum = (v: unknown): number => {
+      if (typeof v === "number") return v;
+      if (v && typeof (v as { toNumber: () => number }).toNumber === "function") {
+        return (v as { toNumber: () => number }).toNumber();
+      }
+      return 0;
+    };
+    return {
+      candidates: toNum(result.records[0]?.get("candidates")),
+      edges: toNum(result.records[0]?.get("edges")),
+    };
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Backfill `c.channel = 'webchat'` on Conversation nodes that lack the
+ * property. Hits both AdminConversation and PublicConversation — the
+ * predicate is `c.channel IS NULL`, label-agnostic.
+ *
+ * Why default to 'webchat': new writes set channel from sessionKey prefix
+ * (neo4j-store.ts:171). Only `whatsapp:` and `telegram:` prefixes produce
+ * non-webchat values, and those prefixes have always existed. So a NULL
+ * channel can only mean "Conversation written before Task 863 added the
+ * SET clause" — which by definition was a webchat session.
+ *
+ * Idempotent: WHERE clause matches zero rows on re-run.
+ */
+async function backfillChannel(accountId: string): Promise<number> {
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (c:Conversation {accountId: $accountId})
+       WHERE c.channel IS NULL
+       SET c.channel = 'webchat'
+       RETURN count(c) AS backfilled`,
+      { accountId },
+    );
+    const raw = result.records[0]?.get("backfilled");
+    if (typeof raw === "number") return raw;
+    if (raw && typeof (raw as { toNumber: () => number }).toNumber === "function") {
+      return (raw as { toNumber: () => number }).toNumber();
+    }
+    return 0;
+  } finally {
+    await session.close();
+  }
+}
+
+async function main(): Promise<void> {
+  const start = Date.now();
+
+  if (!existsSync(ACCOUNTS_DIR)) {
+    console.error(
+      `[admin-agent-graph-backfill] ACCOUNTS_DIR missing at ${ACCOUNTS_DIR} — nothing to do`,
+    );
+    process.exit(0);
+  }
+
+  const accountEntries = readdirSync(ACCOUNTS_DIR, { withFileTypes: true })
+    .filter((e) => e.isDirectory());
+
+  console.error(
+    `[admin-agent-graph-backfill] start accounts=${accountEntries.length}`,
+  );
+
+  let totalProjected = 0;
+  let totalFailed = 0;
+  let totalHandledByCandidates = 0;
+  let totalHandledByEdges = 0;
+  let totalChannelBackfilled = 0;
+  const perAccount: PerAccountStats[] = [];
+
+  for (const entry of accountEntries) {
+    const accountDir = resolve(ACCOUNTS_DIR, entry.name);
+    const accountId = entry.name;
+    const accountStart = Date.now();
+
+    const { projected, failed } = await projectAccountAdmin(
+      accountId,
+      accountDir,
+    );
+    totalProjected += projected;
+    totalFailed += failed;
+
+    let handledByStats: HandledByStats = { candidates: 0, edges: 0 };
+    let channelBackfilled = 0;
+
+    try {
+      handledByStats = await backfillAdminHandledBy(accountId);
+      totalHandledByCandidates += handledByStats.candidates;
+      totalHandledByEdges += handledByStats.edges;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} handled-by-backfill FAILED error="${msg}"`,
+      );
+    }
+
+    try {
+      channelBackfilled = await backfillChannel(accountId);
+      totalChannelBackfilled += channelBackfilled;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} channel-backfill FAILED error="${msg}"`,
+      );
+    }
+
+    perAccount.push({
+      accountId,
+      projected,
+      failed,
+      handledByCandidates: handledByStats.candidates,
+      handledByEdges: handledByStats.edges,
+      channelBackfilled,
+    });
+    const ms = Date.now() - accountStart;
+    console.error(
+      `[admin-agent-graph-backfill] account=${accountId.slice(0, 8)} projected=${projected} failed=${failed} handled-by-candidates=${handledByStats.candidates} handled-by-edges=${handledByStats.edges} channel-backfilled=${channelBackfilled} ms=${ms}`,
+    );
+  }
+
+  const ms = Date.now() - start;
+  console.error(
+    `[admin-agent-graph-backfill] done totals: projected=${totalProjected} failed=${totalFailed} handled-by-candidates=${totalHandledByCandidates} handled-by-edges=${totalHandledByEdges} channel-backfilled=${totalChannelBackfilled} ms=${ms}`,
+  );
+
+  process.exit(totalFailed > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`[admin-agent-graph-backfill] fatal error="${msg}"`);
+  process.exit(2);
+});

package/payload/platform/neo4j/migrations/004-prune-alien-accounts.ts

@@ -0,0 +1,134 @@
+/**
+ * Migration 004 — Prune alien-account nodes (Task 847).
+ *
+ * Deletes every node whose `accountId` is not present on disk under
+ * `${DATA_ROOT}/accounts/<uuid>/account.json`. Idempotent — silent when
+ * the graph is already clean.
+ *
+ * Why a backstop, not a writer fix: the leaked nodes were written by the
+ * `review-digest-compose` writer, which has since been removed in favour
+ * of a coming gbrain rewrite. With no live writer to fix, this is the
+ * surface that catches future writer drift before the next gbrain ships.
+ *
+ * Hard guard: refuses to run when the on-disk account set is empty
+ * (corrupt-install scenario). Refusing to wipe the graph is louder than
+ * silently wiping it.
+ *
+ * Doctrine in `.docs/neo4j.md` "Account isolation invariant" requires
+ * any writer that stamps `n.accountId` to verify the value against
+ * `${DATA_ROOT}/accounts/<id>/account.json` before write. This migration
+ * is a backstop, not a license.
+ */
+
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Structural alias for the `Driver` instance the runner passes in. We type
+ * structurally rather than importing `Driver` from `neo4j-driver` because
+ * this file lives outside `platform/ui/` — depending on the workspace's
+ * dedupe state, `neo4j-driver` resolves to a different node_modules copy
+ * here than at the runner site, and TS treats two same-shape types from
+ * different paths as nominally distinct. Structural typing sidesteps that.
+ */
+type Neo4jDriverLike = {
+  session(): {
+    run(
+      cypher: string,
+      params?: Record<string, unknown>,
+    ): Promise<{ records: Array<{ get(key: string): unknown }> }>;
+    close(): Promise<void>;
+  };
+};
+
+export async function pruneAlienAccounts(
+  driver: Neo4jDriverLike,
+  platformRoot: string,
+): Promise<void> {
+  const accountsDir = resolve(platformRoot, "..", "data", "accounts");
+  const validIds = enumerateValidAccountIds(accountsDir);
+
+  if (validIds.size === 0) {
+    throw new Error(
+      `refusing to prune: no valid accounts found under ${accountsDir} — corrupt install? not deleting anything to avoid wiping the entire graph.`,
+    );
+  }
+
+  const valid = Array.from(validIds);
+  const session = driver.session();
+  try {
+    // Two-step: first query collects the alien accountIds for the log
+    // line, second query deletes. Two cheap queries beat a single query
+    // that loses either the count or the id list under DELETE semantics.
+    const peek = await session.run(
+      `MATCH (n)
+       WHERE n.accountId IS NOT NULL AND NOT n.accountId IN $valid
+       RETURN DISTINCT n.accountId AS aid`,
+      { valid },
+    );
+    const alienIds: string[] = [];
+    for (const record of peek.records) {
+      const aid: unknown = record.get("aid");
+      if (typeof aid === "string") alienIds.push(aid);
+    }
+
+    if (alienIds.length === 0) return;
+
+    const result = await session.run(
+      `MATCH (n)
+       WHERE n.accountId IS NOT NULL AND NOT n.accountId IN $valid
+       DETACH DELETE n
+       RETURN count(n) AS pruned`,
+      { valid },
+    );
+    const prunedRaw = result.records[0]?.get("pruned");
+    const pruned =
+      typeof prunedRaw === "number"
+        ? prunedRaw
+        : (prunedRaw as { toNumber?: () => number })?.toNumber?.() ?? 0;
+    console.error(
+      `[graph-invariant] alien-accounts pruned=${pruned} accountIds=${alienIds.join(",")}`,
+    );
+  } finally {
+    await session.close();
+  }
+}
+
+/**
+ * Enumerate accountIds with a parseable `account.json`. Directory name IS
+ * the canonical accountId (matches the UUID_RE.test(name) predicate at
+ * `platform/ui/server/routes/admin/files.ts`'s account-name resolver).
+ *
+ * Corruption discipline: a present-but-unparseable account.json is
+ * EXCLUDED from the valid set and emits a skip log line. Better to
+ * over-prune one suspect account than under-prune the leak it might
+ * be hiding.
+ */
+function enumerateValidAccountIds(accountsDir: string): Set<string> {
+  const valid = new Set<string>();
+  let names: string[];
+  try {
+    names = readdirSync(accountsDir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return valid;
+    throw err;
+  }
+  for (const name of names) {
+    if (!UUID_RE.test(name)) continue;
+    const configPath = resolve(accountsDir, name, "account.json");
+    try {
+      JSON.parse(readFileSync(configPath, "utf-8"));
+      valid.add(name);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code ?? "parse-error";
+      if (code === "ENOENT") continue;
+      console.error(
+        `[graph-invariant] account-json-skip uuid=${name} reason=${code}`,
+      );
+    }
+  }
+  return valid;
+}

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

@@ -29,7 +29,7 @@ When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict o
 - **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}`.
-- **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished.
+- **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished. Both invocation surfaces (the form-driven action and the agent-via-Bash path) declare `ACCOUNT_DIR` explicitly because `systemd-run --user` does not inherit parent env — when ACCOUNT_DIR isn't reaching the script you'll see `result=skipped reason=no-account-dir` in the stream log instead of `result=ok`.
 - `systemctl --user restart ${BRAND}.service` — restarts the platform service so the new tunnel spawns via the service's `ExecStartPre=resume-tunnel.sh`.
 - Post-restart verification — `ps -ef | grep '[c]loudflared'` confirms the connector is alive, then `curl -I https://<hostname>` against each subdomain (up to 60 s per host) confirms a non-530 response.
 

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

@@ -70,6 +70,48 @@ border, with their zoom-tier labels intact. The `N msgs` count excludes
 trashed Messages, so the detailed-tier label reflects only live turns in the
 conversation.
 
+## Filtering by channel and message kind
+
+When you select **AdminConversation** or **PublicConversation** in the
+filter popover, two extra rows appear underneath the chip list:
+
+- **Channel** — Web / WhatsApp. Select one to scope the canvas to
+  conversations that came in over that channel only. Selecting both is
+  the same as selecting neither (all channels). After the migration that
+  ships with this release, every conversation carries an explicit
+  channel value — pre-existing conversations are backfilled to "Web"
+  because only the WhatsApp and Telegram intake paths ever set non-Web
+  values.
+- **Message** — User / Assistant / WhatsApp. When you've also pivoted
+  into a conversation neighbourhood (or your search hits messages
+  directly), this row scopes the messages on canvas to the chosen kind.
+  WhatsApp messages persist with their own sublabel so you can isolate
+  the live-channel cohort from the agent-path cohort within the same
+  conversation.
+
+These sub-facets compose with the chip selection. Searching with the
+AdminConversation chip selected now also reaches the body text of every
+admin message — typing a rare word like "ATM" returns every conversation
+that mentions it, not just conversations with that word in the title.
+
+## Sidebar conversations list
+
+The Recents list above the chat sidebar carries a per-row marker:
+WhatsApp conversations show a small WhatsApp glyph next to the
+conversation name. The dropdown above the list filters Recents to a
+specific channel — flipping it to **WhatsApp** hides web-chat
+conversations and vice versa.
+
+## Agents in the graph
+
+Both admin and public agents appear as `:Agent` nodes in the graph. Open
+the **Agents** entry from the sidebar to see them all. Each agent
+carries a `:HANDLED_BY` edge from every conversation it has handled, so
+you can pivot from an agent to the conversations it ran. The admin
+agent's IDENTITY, SOUL, KNOWLEDGE, and KNOWLEDGE-SUMMARY documents
+appear as :KnowledgeDocument nodes connected via `HAS_*` edges, the same
+projection shape used for public agents.
+
 ## Agent-execution telemetry
 
 `ToolCall`, `StepResult`, `WorkflowStep`, and `WorkflowRun` nodes are

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

@@ -140,6 +140,8 @@ WHERE node.accountId = $accountId
 
 Multi-tenancy boundary. Every query is scoped to the requesting account. The `ACCOUNT_ID` environment variable is set at MCP server startup — it is not a tool parameter and cannot be overridden by the agent.
 
+The read filter alone is not sufficient — it correctly *hides* alien-account nodes from every UI but does not prevent them existing. A writer that misresolves `accountId` (literal, undefined, or inferred-from-the-wrong-context) leaks nodes into the graph with no downstream symptom; the read filter then keeps them invisible indefinitely. The write-side doctrine is documented in `.docs/neo4j.md` "Account isolation invariant" — every writer that stamps `n.accountId` must verify the value against `${DATA_ROOT}/accounts/<id>/account.json` before write, and migration `004-prune-alien-accounts.ts` runs at every server boot as a backstop, deleting any node whose accountId is not on disk. Hard guard: refuses to prune when the on-disk account set is empty (corrupt-install scenario), surfaced as `[migration] failed prune-alien-accounts error="refusing to prune: …"`. Boot does not block on the failure.
+
 ---
 
 ## Query Classification
@@ -313,7 +315,7 @@ This tool is read-only and available to both public and admin agents.
 
 ### When conversations are created
 
-`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — {{productName}} only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: a first inbound DM is a committed interaction, so the graph node is created eagerly on message one. See `.docs/web-chat.md` "Deferred conversation persistence (Task 650)" for the full contract.
+`:Conversation` nodes on webchat (admin login, "New conversation" in the burger, a new public visitor) are created lazily. Opening the chat or logging in does not write anything to the graph — {{productName}} only records the conversation once the user sends a second message. This keeps `conversation-search` and the Conversations modal free of one-turn abandoned threads. WhatsApp and Telegram take the opposite posture: every inbound — DM or group, allowed or activation-off, agent-invoked or gated — MERGEs the `:Conversation` and writes a forensic `:Message:WhatsAppMessage` row before any access-control decision (Task 863). The graph is the durable record of every message the device received, not just the ones the agent replied to. See `.docs/web-chat.md` "Deferred conversation persistence (Task 650)" and `.docs/whatsapp.md` "Session continuity" for the full contract.
 
 Each row in the Conversations modal exposes a `View logs` row-action that opens a popover with three links — **Stream**, **Errors**, **SSE** — each of which targets `/api/admin/logs?type={stream|error|sse}&conversationId={full-id}` in a new tab. The row's 8-char id chip is click-to-copy; hover reveals the full `conversationId` as a tooltip. See `.docs/web-chat.md` "In-chat retrieval" for the route contract and `console.debug` observability (Task 686).
 
@@ -464,3 +466,11 @@ grep '[persist] tool-call persisted' server.log | tail -10
 ```
 
 Each log entry includes the tool name and a truncated conversation ID for correlation.
+
+## 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.
+
+The compaction runs against a transient one-shot pool entry separate from the long-lived admin Query (Task 784). Operator-visible side effects:
+- Compaction logs land in `claude-agent-compaction-stream-YYYY-MM-DD.log` alongside the main stream log. Look for `[compaction-start]`, `[compaction-summary-captured]`, `[compaction-failed]`, `[compaction-timeout]`, `[compaction-crashed]`, or `[compaction-spawn-error]` to triage. Subprocess stderr is captured inline as `[subproc-stderr] <line>` — there is no longer a separate `claude-agent-compaction-stderr-…log` file.
+- The one-shot pool entry's lifecycle is greppable as `[client-cold-create] reason=compaction-one-shot …` paired with `[client-evict] reason=compaction-one-shot …`, distinguishable from the regular admin pool's lifecycle tags.

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 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 |
+| `whatsapp-import` | Import a WhatsApp `_chat.txt` export. Two-phase contract: **Phase 1 (load)** is a 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, landing `:Conversation:WhatsAppConversation` + `:Message:WhatsAppMessage` with NEXT chain, auto-created `:Person {participantStatus:'auto-created'}` participants, and `:Observation {observationStatus:'auto-extracted'}` rows for mentions/tasks/preferences/observed-relationships. **Phase 2 (enrich)** is operator-driven: ask "enrich the X chat" / "wire observations from yesterday's import" and the database-operator runs the `whatsapp-import-enrich` skill — walks the auto-created participants and auto-extracted observations row-by-row, writes operator-confirmed wiring (participant promotion/merge via `apoc.refactor.mergeNodes`, `:MENTIONS`/`:RELATED_TO` edges with evidence, `:Task` and `:Preference` nodes). Idempotent — re-running enrichment surfaces only items still in the auto-* states. 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

@@ -1,6 +1,6 @@
 ---
 name: whatsapp-import
-description: "Import a WhatsApp `_chat.txt` export (Conversation + Messages with chronological NEXT chain + analysis-derived insights) into the {{productName}} Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default. Distinct from the live `whatsapp` plugin (Baileys QR pairing + in-memory store)."
+description: "Import a WhatsApp `_chat.txt` export (Conversation + Messages with chronological NEXT chain + analysis-derived insights) into the {{productName}} Neo4j graph as a two-phase contract: Phase 1 (`whatsapp-import` skill) lands raw shape via a deterministic Bash entry; Phase 2 (`whatsapp-import-enrich` skill) is operator-driven semantic resolution over the loaded conversation. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default. Distinct from the live `whatsapp` plugin (Baileys QR pairing + in-memory store)."
 tools: []
 always: false
 embed: false
@@ -12,9 +12,20 @@ metadata: {"platform":{"optional":true,"pluginKey":"whatsapp-import"}}
 
 Ingests a WhatsApp "Export Chat" archive (the `_chat.txt` file plus media attachments) into the {{productName}} Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
 
+## Two-phase contract (Task 855 + Task 859)
+
+The plugin ships two skills that pair as a contract: deterministic load first, then operator-driven semantic enrichment. Splitting them removes the orchestration loop a single bundled phase imposed (Task 804's 7h orchestration), and lets re-imports reuse the load phase without redoing the semantic walk.
+
+| Phase | Skill | What it does | Trigger phrase |
+|-------|-------|--------------|----------------|
+| 1 — load | [`whatsapp-import`](skills/whatsapp-import/SKILL.md) | Parses `_chat.txt`, writes `:Conversation:WhatsAppConversation` + `:Message:WhatsAppMessage` with NEXT chain, auto-creates one `:Person {participantStatus:'auto-created'}` per distinct senderName, lands `:Observation {observationStatus:'auto-extracted'}` rows from the chunked Haiku insight pass. Single Bash entry; no MCP envelope between steps. | Operator drops a `_chat.txt` file or its containing export folder into chat. |
+| 2 — enrich | [`whatsapp-import-enrich`](skills/whatsapp-import-enrich/SKILL.md) | Walks `participantStatus='auto-created'` and `observationStatus='auto-extracted'` rows scoped to a chosen conversation, surfaces evidence per row, writes operator-confirmed wiring: `apoc.refactor.mergeNodes` for participant promotion/merge, `:MENTIONS`/`:RELATED_TO` edges with `evidenceSnippet`, `:Task` via `task-create`, `:Preference` via `memory-write`. Idempotent — re-running surfaces only items still in `auto-created`/`auto-extracted`. | Operator asks to "enrich the X chat", "promote auto-created participants from Y", "wire observations from yesterday's import". |
+
+Phase 2 refuses to run against a Conversation whose `c.lastImportedAt` is null. Phase 1 always precedes Phase 2.
+
 ## 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 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).
+The admin agent delegates to `database-operator` when the operator drops a `_chat.txt` (or its containing folder) into chat (→ Phase 1) or names enrichment of an already-loaded conversation (→ Phase 2). For Phase 1 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). For Phase 2 the specialist runs `whatsapp-import-enrich`'s bulk preview, asks the operator to confirm scope, then walks the rows with operator confirmation gates (Task 859).
 
 ## Accepted export shapes
 
@@ -28,6 +39,8 @@ 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 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.
+- **memory** — Phase 1's underlying write surface, imported in-process by `bin/ingest.mjs` (`memoryArchiveWrite` for bulk Conversation+Messages; direct Cypher `:Observation` writes for the insight pass). Phase 2's enrich skill writes `:Preference` nodes via `mcp__memory__memory-write` and uses `mcp__memory__memory-search` for entity disambiguation. All writes carry `source='whatsapp'` + `createdByAgent='whatsapp-import'` (Phase 1) or `createdByAgent='whatsapp-import-enrich'` (Phase 2) 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 for Phase 1 (Task 855).
+- **tasks** — Phase 2's `:Task` writes go through `mcp__tasks__task-create` with `affects=$conversationElementId`. Database-operator's frontmatter `tools:` includes `mcp__tasks__task-create` for this path.
+- **contacts** — Phase 2's mint-new-Person path (an auto-created participant the operator wants to land as a fresh contact) goes through `mcp__contacts__contact-create`.
+- **database-operator specialist** — owns execution for both phases. 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 (which now names both phases under the WhatsApp entry).
+- **linkedin-import** — sister plugin under the same pattern (LinkedIn Basic Data Export). LinkedIn ingestion is single-phase today (no enrich pass) because CSV rows already encode entity types deterministically — no auto-created participants, no auto-extracted observations to walk. Reading [linkedin-import/PLUGIN.md](../linkedin-import/PLUGIN.md) is the fastest way to understand the load-phase shape this plugin's Phase 1 follows.