@totalreclaw/totalreclaw 3.3.12-rc.2 → 3.3.12-rc.6

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.12-rc.5] — 2026-05-09
+
+Final RC for the 3.3.12 stable promote. Behavioral fix: Pedro's Pop-OS Telegram QA (zai/glm-5-turbo) on rc.4 found the agent storing user statements in `MEMORY.md` / `USER.md` via `write` tool calls instead of calling `totalreclaw_remember`. 28 `write` calls observed in one session, 0 TotalReclaw tool calls — facts never reached the chain. Root cause: SKILL.md trigger language was permissive ("call when the user asks") and the agent's default file-write reflex won out. rc.5 makes the memory-storage rule the TOP RULE of SKILL.md with an explicit prohibition on `write`/`edit` against `MEMORY.md`/`USER.md`, an exhaustive trigger-phrase list (preference / identity / decision / commitment / possessive-assertion patterns), and a multi-fact-per-message instruction so blob-style packing does not happen.
+
+### Changed
+
+- **SKILL.md TOP RULE rewrite — aggressive triggers, no MEMORY.md fallback.** Memory storage section moved to the very top of SKILL.md (before architecture, vocabulary, install flow). Adds: (1) absolute prohibition on `write`/`edit` against `MEMORY.md` / `USER.md` / `~/.claude/memory/*.md`; (2) trigger-phrase list covering preferences, identity, tools, decisions, commitments, explicit asks, possessive assertions; (3) multi-fact-per-message rule (split into one `totalreclaw_remember` call per atomic fact); (4) full 17-tool reference table with canonical use cases; (5) restart policy reaffirmed (gateway self-restarts via SIGUSR1; agent NEVER prompts user to manually restart); (6) phrase-safety hard rail (no phrase in chat / no phrase as tool input / browser-side only).
+- **Public quickstart guide audit** (`docs/guides/openclaw-setup-quickstart.md`) — already prose-style + clean from rc.6 revert. No edits required.
+- **Long-form setup guide cleanup** (`docs/guides/openclaw-setup.md`) — F-flip default URL corrected (`api.totalreclaw.xyz` for free tier, staging via env override; previous text said the relay was `api-staging.*`); line 1 wording aligned with SKILL.md (`Setting up TotalReclaw — this takes about a minute…`); legacy `qr_png_b64` / `qr_unicode` references replaced with `qr_ascii` (the only QR field in the current pair payload); manual restart fallback (`openclaw gateway restart` / `docker restart`) deemphasized — the plugin self-restarts via SIGUSR1; RC pin examples bumped from `3.3.11-rc.5` to `3.3.12-rc.5`.
+- **Version sync** — package.json, skill.json, SKILL.md frontmatter, tr-cli.ts PLUGIN_VERSION all aligned to 3.3.12-rc.5 via `sync-version.mjs`. `check-version-drift` green.
+
+### Verified
+
+- All 38 test suites pass (manifest-shape, config-schema, config, relay-headers, scope-address-visible, llm-profile-reader, llm-client (×2), gateway-url, retype-setscope, tool-gating, onboarding-noninteractive, pair-cli-json, pair-qr, pair-remote-client, qa-bug-report, nonce-serialization, phrase-safety-registry, onnx-download-ux, onboard-pair-only, import-time-smoke, install-staging-cleanup, partial-install-detection, install-reload-idempotency, json-stdout-cleanliness, load-manifest, url-binding, fs-helpers, pair-cli-default-mode, embedding-fallback-tag, staging-banner-gate, restart-auth, inbound-user-tracker, register-command-name, skill-md-hybrid-primary, tr-cli-json-output).
+- `check-scanner` green (0 flags).
+- `check-version-drift` green (3 sites + tr-cli.ts all = 3.3.12-rc.5).
+- E2E on clean OpenClaw 2026.5.7 container — agent given `"Hi, I'm Pedro. I live in Porto. I prefer PostgreSQL over MySQL."` calls `totalreclaw_remember` ≥1 time, with 0 `write`/`edit` calls against `MEMORY.md` / `USER.md`. (See PR description for the captured `toolSummary` JSON.)
+
+### Out of scope (unchanged from rc.4)
+
+- Plugin install lifecycle on OpenClaw 2026.5.7 (auto-QA PASS — plugin loads, SIGUSR1 self-restart works, in-process restart, managed-service-friendly).
+- `tr` CLI on-chain memory ops (rc.4 fix verified).
+- Pair flow (browser-side phrase, no leakage).
+- Trajectory poller (auto-extraction backup).
+- F flip (RC + stable both default to prod URL; staging via env override).
+
 ## [3.3.12-rc.2] — 2026-05-08
 
 Hot-fix on rc.1's F flip. Pair flow regression: rc.1 set `pairRelayUrl`'s default to `wss://api.totalreclaw.xyz` (production) independently of `serverUrl`. RC users who set `TOTALRECLAW_SERVER_URL=https://api-staging.totalreclaw.xyz` (per the staging-opt-in flow) had pair WS go to **prod**, which pre-dates the pair feature → 404 on WS upgrade → `totalreclaw_pair failed: Unexpected server response: 404`. End-to-end blocker: pair never completed → no credentials → no memories.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.12-rc.2
+description: "End-to-end encrypted, decentralized memory for OpenClaw. Set up an account once, then call totalreclaw_remember / totalreclaw_recall (or the tr CLI under hybrid-primary) instead of writing to MEMORY.md / USER.md / local files. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any remember / recall request, AND any user statement that contains a preference / fact / decision / commitment about themselves."
+version: 3.3.12-rc.6
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -24,26 +24,61 @@ metadata:
 
 # TotalReclaw — OpenClaw
 
-> **Agent-executable quickstart (5 KB, copy-paste-runnable)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md>
+> **Agent-executable quickstart**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md>
 >
-> **Human-readable setup guide (full rationale, troubleshooting)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
->
-> If the user pastes either URL: prefer the quickstart for execution. Fetch the full guide only if the user asks for context or troubleshooting beyond what the quickstart covers. This SKILL.md mirrors the quickstart's hard rules so you can act even if the URL is unreachable.
+> **Human-readable setup guide**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+
+## TOP RULE — MEMORY STORAGE (read this before anything else)
+
+**When the user states ANYTHING about themselves, their preferences, decisions, plans, identity, work, location, or facts they want retained, you MUST call `totalreclaw_remember` (NOT `write`, NOT `edit`, NOT MEMORY.md/USER.md).** Under hybrid-primary mode (OpenClaw 2026.5.x), if `totalreclaw_remember` is not bound as a tool, fall back to the `tr` CLI: `node "$TR_CLI" remember --json "<fact>"`. Either path lands the fact encrypted, on-chain. Both are valid.
+
+### ABSOLUTE PROHIBITION
+
+**NEVER use the `write` or `edit` tools to store user statements in `MEMORY.md`, `USER.md`, `~/.claude/memory/*.md`, `~/.openclaw/memory/*.md`, or any other file.** Those files are for AGENT PERSONA and CODEBASE INSTRUCTIONS — read-only operational config the agent loads at startup. Storing user data there is a SKILL VIOLATION. User memories live encrypted on-chain via TotalReclaw, not in flat files.
+
+- ✅ DO call `totalreclaw_remember` (or `tr remember --json` under hybrid-primary).
+- ❌ DO NOT `Write` to `MEMORY.md`.
+- ❌ DO NOT `Edit` `USER.md` to append a user fact.
+- ❌ DO NOT echo "saving this to MEMORY.md…" — that file is not yours to write to.
+
+### Trigger phrases — call `totalreclaw_remember` on detection
+
+Do not wait for an explicit "remember this". These are first-class triggers — every one of them MUST result in a `totalreclaw_remember` call (parallel with your normal reply):
+
+- **Preferences**: "I prefer X", "I like X", "I love X", "I hate X", "my favorite X is Y", "I'd rather X", "X over Y"
+- **Identity**: "I'm a X", "I am X", "my name is X", "I'm based in X", "I live in X", "I work at X", "I work on X", "I have X"
+- **Tools / setup**: "I use X", "I'm running X", "my X is Y", "I've configured X to Y"
+- **Decisions / plans**: "I decided to X", "I'm going to X", "I'm planning X", "we agreed X", "we settled on X", "let's call this X", "from now on X"
+- **Commitments**: "I'll X by Y", "remind me to X", "I need to X by Y", "don't forget X"
+- **Explicit asks**: "remember that X", "save X", "note that X", "store X", "make a note of X"
+- **Possessive assertions**: "my [anything] is [value]" (preference assertion pattern)
+- **Any 1st-person factual claim worth retaining** about identity, work, location, tools, preferences, ongoing projects, contacts, schedule.
+
+If a single user message contains MULTIPLE such facts (e.g. "I'm Pedro. I live in Porto. I prefer PostgreSQL over MySQL."), call `totalreclaw_remember` MULTIPLE TIMES — once per atomic fact. Don't blob multiple unrelated facts into a single memory.
+
+### When to call `totalreclaw_recall`
 
-## CRITICAL: How TotalReclaw actually stores memories (read before anything else)
+**ALWAYS call `totalreclaw_recall` first when the user asks about themselves, their preferences, or anything from past conversations.** Trigger phrases:
+
+- "what's my X?", "do I X?", "where do I X?", "when did I X?", "have I told you X?"
+- "what do you remember about me?", "what do you know about my X?"
+- "remind me about X", "what did we decide about X?"
+- "do you remember when X?"
+
+Recall first, then answer from the returned facts. If 0 results come back, say so plainly — do not guess from session history.
+
+## CRITICAL: How TotalReclaw actually stores memories
 
 **TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server.** Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
 
-Forbidden vocabulary — these claims are WRONG (some imply local-only storage; some imply a single-company server):
-- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only). Memories require an account; they're encrypted and submitted on-chain.
-- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody). The relay forwards ciphertext; storage is decentralized on-chain.
+Forbidden vocabulary — these claims are WRONG:
+- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only).
+- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody).
 - "without an account" — wrong (an account is required to derive the encryption key).
 
-If you need to describe how it works, the canonical line is: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
+Canonical line: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
 
-## User-facing vocabulary (substitute internal jargon for plain words)
-
-Internal terms that the user does NOT know — translate when you must speak:
+## User-facing vocabulary
 
 | Internal term | Say to the user |
 |---|---|
@@ -55,33 +90,39 @@ Internal terms that the user does NOT know — translate when you must speak:
 | credentials.json / mnemonic file | "your recovery phrase" |
 | `tr pair --json` / `setsid -f` / shell exec | (don't mention; just do the work silently) |
 
-The word "pair" is internal jargon — never use it in user-visible prose. The user-visible vocabulary is "set up an account", "your account", "your recovery phrase", "your memories".
+The word "pair" is internal jargon — never use it in user-visible prose. Use "set up an account", "your account", "your recovery phrase", "your memories".
 
-## Top-level rule (read this before anything else)
+## Install / setup top-level rule
 
-**Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do. Errors are the only allowed deviation, and only as a single tight line.** The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**. Anything more is a SKILL violation. Telegram and similar transports edit the bot's messages live as your tool calls progress — every interim "Let me check…" / "Plugin loaded. Let me verify…" line shows up to the user as awkward edit churn, even if you "delete" it. The fix is to never emit it in the first place.
+**Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do.** Errors are the only allowed deviation, and only as a single tight line. The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**.
 
 ### ⚡ MANDATORY ACK BEFORE FIRST TOOL CALL
 
-**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon. The ack tells them work is happening.
+**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon.
 
-The ack is unconditional. It fires the moment you decide to install / set up TotalReclaw — even before you've resolved `TR_CLI`, even before you've checked whether the plugin is already installed, even before the first `openclaw plugins install` shell call. Send line 1, THEN start the work.
+The ack is unconditional. Send line 1, THEN start the work.
 
 Forbidden order (silent-then-narrate): ❌ run `openclaw plugins install` → wait 60s → emit line 1.
 Required order (ack-then-work): ✅ emit line 1 → run `openclaw plugins install` silently → emit line 2 when `tr status` returns.
 
-## ⛔ FORBIDDEN ACTIONS (4 hard rules from 2026-05-05 QA)
+## ⛔ FORBIDDEN ACTIONS
 
-These specific actions break the pair flow. Everything else is governed by the "emit only the numbered user-visible lines" rule above.
+These specific actions break the install / pair flow:
 
-1. **Do NOT restart the gateway.** No `/totalreclaw-restart`, no `kill -USR1`, no `docker restart`, no `openclaw gateway restart`. The plugin self-patches and signals its own restart needs. You restarting it kills the in-flight `setsid -f` pair subprocess → 502 on browser respond.
+1. **Do NOT restart the gateway.** No `kill -USR1`, no `docker restart`, no `openclaw gateway restart`. The plugin self-patches and signals its own restart needs (SIGUSR1 in-process, automatic). You restarting it kills the in-flight `setsid -f` pair subprocess → 502 on browser respond. If for some specific reason a restart IS required, issue the literal slash command `/totalreclaw-restart` — nothing else. **NEVER prompt the user to manually restart anything**; the plugin handles its own restart.
 
-2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote `plugins.slots.memory`, `plugins.entries.totalreclaw.hooks.allowConversationAccess`, `channels.telegram.streaming.mode`. Any further write triggers a deferred SIGUSR1 reload that kills pair. No `openclaw config set …`, no `jq …>openclaw.json`, no `sed -i openclaw.json`.
+2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote the required keys. Any further write triggers a deferred SIGUSR1 reload that kills pair. No `openclaw config set …`, no `jq …>openclaw.json`, no `sed -i openclaw.json`.
 
-3. **Do NOT save QR PNGs.** `tr pair --json` returns `qr_ascii` — emit that inline in a triple-backticked code block. No `/tmp/totalreclaw-pair-qr.png` (OpenClaw media-policy blocks it: `LocalMediaAccessError`). No PNG decode. No `qr_png_b64` (legacy field, no longer exists in payload).
+3. **Do NOT save QR PNGs.** `tr pair --json` returns `qr_ascii` — emit that inline in a triple-backticked code block. No `/tmp/totalreclaw-pair-qr.png` (OpenClaw media-policy blocks it: `LocalMediaAccessError`). No PNG decode.
 
 4. **`tr pair --json` MUST run via `setsid -f`** (exact form below). Foreground invocation is killed when your shell-tool exec returns → 502.
 
+5. **Do NOT pass `--allow-dangerous` to any TotalReclaw command.** The plugin is sandboxed by design.
+
+6. **Do NOT manually edit `~/.totalreclaw/credentials.json`.** Round-trip via `tr pair --json` (re-generate) instead.
+
+7. **Do NOT install the legacy from-source path alongside the published plugin.** The two paths overlap and will double-write facts.
+
 ## Hybrid-primary architecture (3.3.9-rc.1)
 
 OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. **3.3.9-rc.1 makes the `tr` CLI the PRIMARY path for all memory operations.** Native tools (`totalreclaw_*`) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use `tr` from your shell tool for everything.
@@ -96,7 +137,7 @@ TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cl
 ```
 Then invoke as `node "$TR_CLI" <cmd> [--json]`.
 
-**Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223.
+**Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223. If `totalreclaw_remember` IS bound, use it (preferred). If not, use `tr remember --json` from the shell. EITHER way, the user fact MUST land in TotalReclaw — never in `MEMORY.md`/`USER.md`.
 
 ## User-visible line set (THIS IS ALL YOU SAY)
 
@@ -111,78 +152,61 @@ Speak only these lines, in order. Substitute the bracketed placeholders with the
 4. (done + free-tier confirmation)
    > ✓ You're set up on the TotalReclaw free tier — 500 memories/month, unlimited reads. https://totalreclaw.xyz/pricing. Ask me to remember anything.
 
-If existing credentials are detected (step "Check for existing credentials" below), emit ONLY this line and stop:
+If existing credentials are detected, emit ONLY this line and stop:
    > ✓ TotalReclaw is already set up.
 
 ### Hard silence rules between numbered lines
 
-Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden (verbatim examples from Pedro's 2026-05-06 QA):
+Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden:
 
-- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`. Emit line 2 when it returns.
-- ❌ "Now let me check if you already have credentials:" → silent. Just run `test -s ~/.totalreclaw/credentials.json`.
-- ❌ "Need to pair. Let me kick that off:" → silent. Just run the `setsid -f` block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.
-- ❌ "Standing by." → silent. Acknowledgements between lines are noise.
+- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`.
+- ❌ "Now let me check if you already have credentials:" → silent.
+- ❌ "Need to pair. Let me kick that off:" → silent.
+- ❌ "Standing by." → silent.
 - ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
-- ❌ **Skipping line 1 entirely and going straight to shell tool calls.** Line 1 ack must precede the first tool call. Silent install = user thinks the prompt didn't register.
-
-The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between. Line 1 fires immediately. Lines 2–4 fire as work completes. No prose between.
-
-## How does TotalReclaw work? (canonical answer for user questions)
-
-When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" / similar — answer with this content. Do NOT say "stored on a relay server", "stored on TotalReclaw's server", or any phrasing that implies single-company custody. The actual architecture:
-
-> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay server only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories. Nobody (not me, not TotalReclaw the company, not the relay operator) can read them without it.
-
-If the user asks shorter questions, reply with the relevant slice:
-
-- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
-- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device. Only your recovery phrase can decrypt them."
-- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
+- ❌ **Skipping line 1 entirely and going straight to shell tool calls.**
 
 ## Setup flow (hybrid-primary)
 
-1. **Install plugin first, skill second (silent — emit user-visible line 1 once at the start, then no prose until line 2).** Run via your shell tool, in this exact order:
+1. **Install plugin first, skill second.** Run via your shell tool, in this exact order:
    ```
    openclaw plugins install @totalreclaw/totalreclaw
    openclaw skills install totalreclaw
    ```
-   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. **Plugin BEFORE skill is deliberate** (3.3.4-rc.1 — issue from Pedro's QA on rc.3): the skill install triggers a config-driven SIGUSR1 gateway reload that can race a concurrent plugin install.
+   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. Plugin BEFORE skill is deliberate.
 
-   If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+   If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim: *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
 
 2. **Verify CLI works — emit user-visible line 2 when successful.** Resolve `TR_CLI` and run:
    ```bash
    TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
    node "$TR_CLI" status --json
    ```
-   Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2 with the version substituted. **Do NOT wait for tool binding. Do NOT issue `/totalreclaw-restart`. Do NOT check whether `totalreclaw_pair` is in your toolset.** The CLI works independently of tool binding. If `tr status` exits non-zero or the file doesn't exist, wait 5s and retry once — it may still be installing.
+   Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2.
 
-3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, emit *"✓ TotalReclaw is already set up."* and stop.
+3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists, emit *"✓ TotalReclaw is already set up."* and stop.
 
-4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run pair in DETACHED mode. CRITICAL: a foreground `node tr-cli pair` is killed when the gateway fires its post-install SIGUSR1 reload (3.3.10 finding from Pedro's 2026-05-05 QA — relay logs `gateway_disconnected` 502 on `/respond`). Use `setsid -f` so the pair process is in its own session and survives any subsequent gateway SIGUSR1 reload. The handshake URL+PIN is written to a tmp file the moment the WS opens (~100-500ms typical):
+4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** Use `setsid -f` so the pair process survives gateway SIGUSR1 reloads. The handshake URL+PIN is written to a tmp file the moment the WS opens:
    ```bash
    PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
    setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
    sleep 2
    cat "$PAIR_OUT"
    ```
-   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. If the cat output is empty after 2s, sleep 2 more seconds and try again (relay handshake can take up to 4s on a cold network). If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
+   Parse the JSON `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. This is UNCONDITIONAL — do NOT ask "Would you like to set up an account?". The URL + PIN itself is the consent moment.
 
-5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the `setsid -f node "$TR_CLI" pair --json` block and resend line 3 once. If present, emit user-visible line 4 and stop.
+5. **Verify and confirm.** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the pair block and resend line 3 once. If present, emit user-visible line 4 and stop.
 
-## `tr` CLI reference (hybrid-primary commands)
+## `tr` CLI reference
 
-Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
+Always use `--json` flag when running from shell for machine-parseable output.
 
 ```bash
-# (Resolve TR_CLI once at the top of your session)
-TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-
-# Status check (parse JSON to confirm install + onboarding state)
+# Status
 node "$TR_CLI" status --json
-# Returns: {"version":"3.3.11-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
+# Returns: {"version":"3.3.12-rc.5","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
 
-# Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
+# Pair (always via setsid -f)
 PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
 setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
 # Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
@@ -196,102 +220,101 @@ node "$TR_CLI" recall --json "where does the user work" --limit 5
 # Returns: {"results":[{"text":"...","score":0.8},...]}
 ```
 
-**Note on tool names**: `totalreclaw_remember`, `totalreclaw_recall`, etc. may or may not appear in your toolset depending on OpenClaw version. Under hybrid-primary, you use the `tr` CLI instead. If native tools ARE available (older OpenClaw or future OC fix), they work too — but always prefer `tr` for reliability.
-
-## Rendering the QR on your transport (3.3.10-rc.4 — corrected)
-
-`tr pair --json` returns a `qr_ascii` field — Unicode block-char QR (43 lines × ~43 cols). That is the ONLY QR field in the payload. The legacy `qr_png_b64` and `qr_unicode` field names referenced by older skill docs no longer exist.
+## Tool reference (all 17 plugin tools)
 
-The simplest path that works on every transport (Telegram, Slack, web, terminal SSH): emit `qr_ascii` INLINE inside a triple-backtick code block right above user-visible line 3. Block-char QR renders correctly in monospace fonts on every modern transport — the user scans from their phone. The pair PAGE itself renders a real PNG QR alongside, so users on a desktop browser see both.
+The plugin exposes these tools via OpenClaw's plugin runtime. Under hybrid-primary mode, prefer the `tr` CLI for `pair` / `remember` / `recall` / `status`; the rest below are typically only available as native tools.
 
-Format the line-3 message as:
+| Tool | Use case |
+|---|---|
+| `totalreclaw_pair` | Set up the user's account (browser-side phrase generation/import) |
+| `totalreclaw_remember` | **Store a fact / preference / decision (encrypted, on-chain). PRIMARY tool for user statements.** |
+| `totalreclaw_recall` | Semantic search across the user's memories |
+| `totalreclaw_forget` | Delete a memory by id (tombstone on-chain) |
+| `totalreclaw_pin` | Mark a memory as never-supersedable |
+| `totalreclaw_unpin` | Remove pin status |
+| `totalreclaw_retype` | Change a memory's type (claim/preference/directive/etc.) |
+| `totalreclaw_set_scope` | Change a memory's scope (work / personal / health / family / creative / finance / misc) |
+| `totalreclaw_export` | Export all memories (json / markdown) |
+| `totalreclaw_import_from` | Import from another tool (Mem0, MCP-Memory, ChatGPT, Claude, Gemini) |
+| `totalreclaw_import_batch` | Bulk import with chunking + extraction |
+| `totalreclaw_consolidate` | Merge near-duplicates after a fresh import |
+| `totalreclaw_status` | Check onboarding state, version, billing tier, quota |
+| `totalreclaw_upgrade` | Open the Stripe upgrade flow (free → paid tier) |
+| `totalreclaw_migrate` | Move testnet memories to mainnet (Pro tier) |
+| `totalreclaw_onboarding_start` | (Internal — used by setup flow) |
+| `totalreclaw_report_qa_bug` | (RC only) Surface a QA bug into the agent log |
+
+All tools accept JSON input and return structured JSON.
+
+## Auto-extraction (background, no agent action required)
+
+The plugin runs a trajectory poller every 60 seconds that scans `~/.openclaw/agents/<agent>/sessions/*.trajectory.jsonl` for new conversation turns and runs LLM-driven extraction. Extracted facts go through importance filtering and dedup before landing on-chain.
+
+**Auto-extraction is a SAFETY NET, not a substitute for explicit `totalreclaw_remember` calls.** Explicit calls are higher-fidelity (the agent decides the importance, type, and scope). Auto-extraction catches things the agent missed.
 
-```
-<qr_ascii contents — 43 lines of ▄▀█▄▀█ block chars>
-```
+## Phrase safety (HARD — never break)
 
-Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
+The 12-word recovery phrase is the master key. Hard rules:
 
-Do NOT decode `qr_png_b64` (does not exist), do NOT save a PNG to `/tmp/totalreclaw-pair-qr.png` (`LocalMediaAccessError` blocks delivery), do NOT re-render the QR through any other library. The `qr_ascii` field is the single source of truth.
+- **NEVER echo, generate, log, or ask the user to paste a recovery phrase in chat.** The browser at the pair URL handles phrase generation and import. The phrase NEVER enters the agent's LLM context.
+- **NEVER include a recovery phrase as input to ANY tool call** — not `totalreclaw_pair` (its only inputs are `mode` + optional config), not `totalreclaw_remember`, not `Bash`, not `Write`, not `Edit`. Anything that surfaces the phrase to the agent's context is a security incident.
+- **NEVER invoke any phrase-touching CLI via your shell tool.** `openclaw totalreclaw onboard` (bare interactive form) and `totalreclaw setup` print phrase material to stdout, which enters LLM context. The ONLY agent-facilitated account-setup paths are: (1) `tr pair --json` (preferred); (2) the `totalreclaw_pair` tool; (3) `openclaw totalreclaw pair generate --url-pin-only` or `openclaw totalreclaw onboard --pair-only` (single-line URL+PIN JSON, zero phrase material — both account-setup payloads are x25519-only, not BIP-39).
+- **NEVER display the recovery phrase back to the user in chat** even if the browser leaks it to you somehow.
+- **If the user pastes a phrase anyway**: tell them the phrase is now compromised, re-run `tr pair --json` for a fresh wallet.
 
-The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-band confirmation — deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside the user-facing reply. The PIN must NOT end up in any other tool call, log file, or memory store.
+## Browser flow context
 
-## Browser flow context (know it, narrate only on user question)
+After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard:
 
-After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard before the relay forwards the encrypted phrase to the plugin. You don't narrate this proactively (silence rules). But you MUST know it so you can answer questions and recover from issues:
+1. **Step 1 — Enter PIN.** 6 digits matching what you sent.
+2. **Step 2 — Recovery phrase.** Two tabs: **Set up** (generates fresh BIP-39 phrase locally) or **Log in** (paste existing phrase to restore). User checks "I've written this down" and clicks Set up.
+3. **Step 3 — You're all set.** Browser already POSTed the encrypted phrase. Plugin writes `~/.totalreclaw/credentials.json`.
 
-1. **Step 1 of 3 — Enter your PIN.** Six PIN cells. The user types or pastes the 6-digit PIN you sent in line 3. "Continue" is disabled until all 6 digits match. There's a 10-minute countdown displayed in the corner.
-2. **Step 2 of 3 — Your recovery phrase.** Two tabs: **Set up** (default — generates a fresh 12-word BIP-39 phrase locally in the browser) and **Log in** (paste an existing phrase to restore on a new device). User must check **"I've written this down and stored it somewhere safe"** then click **Set up TotalReclaw**.
-3. **Step 3 of 3 — You're all set.** Confirmation screen with a "Close this page" link. The browser already POSTed the encrypted phrase by this point — the relay forwards to your gateway, the plugin decrypts, writes `~/.totalreclaw/credentials.json`, and your `awaitPhraseUpload` resolves.
+Common user-side issues during pair:
 
-Common user-side issues during pair (recover gracefully — emit ONE tight line, don't pre-narrate):
+- **"The page won't load"** → confirm URL host. Default for both stable and RC is `api.totalreclaw.xyz`. Staging via `TOTALRECLAW_SERVER_URL=https://api-staging.totalreclaw.xyz`.
+- **"PIN expired"** → re-run pair block, resend line 3.
+- **"Invalid phrase"** during Log in → user pasted a non-BIP-39-valid phrase. Tell them to re-paste or switch to Set up tab.
+- **502 on Set up** → the gateway WS dropped. Pair subprocess is alive (`setsid -f`). Wait 30s; re-run pair if still 502.
+- **"Where do I write down the phrase?"** → paper, password manager, encrypted note. NOT in this chat.
 
-- **"The page won't load"** → confirm the URL host is `api.totalreclaw.xyz` (the default for both stable and RC post-3.3.12-rc.1). If a `TOTALRECLAW_SERVER_URL` env override was set, the host might be `api-staging.totalreclaw.xyz` (staging, opt-in) or a self-hosted relay. Wrong stub host → generate a fresh URL.
-- **"PIN says expired"** or countdown ran out → re-run the pair block (Step 4 above) and emit line 3 again with the fresh URL+PIN. The previous session is dead.
-- **"It says invalid phrase"** during Log in → the user pasted a phrase that isn't BIP-39 valid (typo or wrong source). Tell them to double-check and re-paste; or switch to **Set up** tab to generate a fresh one (loses existing memories).
-- **"I clicked Set up TotalReclaw but nothing happened"** / **502** → the gateway WS dropped before respond. The pair subprocess is alive (you used `setsid -f`). Wait 30s; if the user still sees the 502, re-run Step 4 (the deferred reload should have completed by then).
-- **"Where do I write down the phrase?"** → tell them: anywhere safe and durable — paper, password manager, encrypted note. NOT in this chat. NOT in a screenshot to cloud-synced photos. The phrase IS the account; losing it means losing all memories.
+## Forbidden vocabulary in agent prose
 
-## Phrase safety (HARD — never break)
+Unless the user explicitly asks how the install works, these patterns must not appear:
 
-NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard` (bare interactive form), `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated account-setup paths are (in order of preference): (1) `tr pair --json`; (2) the `totalreclaw_pair` account-setup tool; (3) if both are missing — shell out to EITHER `openclaw totalreclaw pair generate --url-pin-only` (single-line JSON `{v,url,pin,expires_at_ms}`) OR `openclaw totalreclaw onboard --pair-only` (single-line JSON `{v,pair_url,pin,expires_at_ms}`). Both have zero phrase material on stdout (account-setup crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, re-run `tr pair --json` for a fresh wallet.
-
-## Usage (post-setup)
-
-- Stable user facts / preferences / identity / "remember X":
-  ```bash
-  node "$TR_CLI" remember --json "<fact>"
-  ```
-- First-person factual query ("do I / what's my / where do I…"):
-  ```bash
-  node "$TR_CLI" recall --json "<query>" --limit 5
-  ```
-  Recall FIRST, then answer from returned facts. If 0 results, say so.
-- For forget / pin / unpin / retype / set_scope — use native tools if available, or ask user to run `openclaw totalreclaw` subcommand.
-- "status" → `tr status --json` (parse version + onboarded + next_step).
-- "upgrade" → `totalreclaw_upgrade` native tool (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
-- "import / export / consolidate" → `totalreclaw_import_from` · `totalreclaw_export` · `totalreclaw_consolidate` native tools.
-
-**Forbidden vocabulary** (these are anti-patterns that violate the silence rule):
 - "Let me check that…"
 - "Plugin loaded. Let me verify…"
 - "I'll now…"
 - "Quick fix…"
 - "However, I don't see…"
 - "I need to use…"
-- "Should I /totalreclaw-restart" / "Do you have a public URL" / "Want me to restart" / "Let me check if the tool is bound" / "I need permission to restart"
+- "Should I /totalreclaw-restart" / "Want me to restart" / "Let me check if the tool is bound" / "Do you have a public URL"
 - "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
 - "local" / "local-only" / "stored locally" / "on disk" / "without an account" / "local memory" / "local storage"
 
 ## Diagnostics
 
-- `tr` CLI not found → plugin not installed or install still in progress. Wait 5s, retry. If still missing, retry `openclaw plugins install @totalreclaw/totalreclaw@rc` once.
-- `totalreclaw_*` tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use `tr` CLI instead. Do not restart, do not issue `/totalreclaw-restart`, do not issue `/new`.
-- If `/totalreclaw-restart` is needed for another reason, issue the literal slash command `/totalreclaw-restart` — nothing else. Do not narrate.
-- User says done but `credentials.json` missing → PIN expired or entered wrong phrase; re-run `tr pair --json` and resend line 3 once.
+- `tr` CLI not found → plugin not installed or install still in progress. Wait 5s, retry.
+- `totalreclaw_*` tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use `tr` CLI instead.
+- User says done but `credentials.json` missing → PIN expired; re-run `tr pair --json` and resend line 3.
 - `onboarding required` → credentials missing; redo from the account-setup step.
-- `quota exceeded` → `tr status --json` or `totalreclaw_status`, then offer `totalreclaw_upgrade`.
-- `No LLM available for auto-extraction` at startup → provider key unreachable; check `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or plugin config `extraction.llm`.
-
-## Required post-install config (OpenClaw 2026.5.2+)
-
-Add to `~/.openclaw/openclaw.json` after installing:
-```json
-{
-  "plugins": {
-    "allow": ["totalreclaw"],
-    "entries": {
-      "totalreclaw": {
-        "hooks": { "allowConversationAccess": true }
-      }
-    }
-  }
-}
-```
+- `quota exceeded` → `tr status --json`, then offer `totalreclaw_upgrade`.
+- `No LLM available for auto-extraction` → check `~/.openclaw/agents/<agent>/agent/auth-profiles.json`.
+
+## How does TotalReclaw work? (canonical answer for user questions)
+
+When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" — answer:
+
+> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories.
+
+Shorter slices:
+- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
+- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device."
+- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
 
-`plugins.allow` suppresses the "plugins.allow is empty" warning. `hooks.allowConversationAccess` unlocks typed hooks (`agent_end`, etc.) for auto-extraction.
+## Tool surface summary
 
-## Tool surface
+Hybrid-primary: `tr remember` · `tr recall` · `tr pair` · `tr status` (primary path under OpenClaw 2026.5.x).
+Native fallback (when bound): `totalreclaw_pair` · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` · `_report_qa_bug` (RC only).
 
-Hybrid-primary: `tr remember` · `tr recall` · `tr pair` · `tr status` (primary path for all agent ops)
-Native fallback (when available): `totalreclaw_pair` · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` · `_report_qa_bug` (RC only)
+**Default behavior summary**: the agent's job is to call `totalreclaw_remember` aggressively on user statements that match the trigger-phrase list, and `totalreclaw_recall` when the user asks about themselves. Local files (`MEMORY.md`, `USER.md`, etc.) are NOT for user memory — they are agent-persona configuration only.

package/dist/fs-helpers.js

@@ -984,7 +984,10 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  * @param configPath  Absolute path to `openclaw.json`.
  *                    Defaults to `<home>/.openclaw/openclaw.json`.
  */
-export function patchOpenClawConfig(configPath) {
+export function patchOpenClawConfig(configPath, 
+// 3.3.12-rc.3 — plugin version (used by Fix #6 to self-heal a stripped
+// `plugins.installs.totalreclaw` record so Fix #1 (slot) can fire).
+pluginVersion) {
     const home = process.env.HOME ?? '/home/node';
     const target = configPath ?? path.join(home, '.openclaw', 'openclaw.json');
     // `'skipped'` when the config file is absent — this host may not be
@@ -1000,6 +1003,65 @@ export function patchOpenClawConfig(configPath) {
             cfg.plugins = {};
         }
         let mutated = false;
+        // --- Fix #6 (3.3.12-rc.3): self-heal `plugins.installs.totalreclaw` ---
+        //
+        // OpenClaw 2026.5.6 has a config-rewrite-after-restart behaviour
+        // observed on Pedro's pop-os QA host (2026-05-08): `openclaw plugins
+        // install` writes the install record, gateway restart fires, but
+        // after the restart something STRIPS `plugins.installs.totalreclaw` (and
+        // sometimes `plugins.allow`, `plugins.entries.totalreclaw`,
+        // `plugins.slots.memory`) from openclaw.json. The plugin's binary
+        // remains in `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/`,
+        // but `openclaw plugins list` shows it as `disabled` because no
+        // install record + no allow entry.
+        //
+        // Defensive self-heal: when this register() runs (which means the
+        // plugin IS physically loaded by the gateway), if the install record
+        // is missing or has no version, write a minimal record. This unlocks
+        // Fix #1 (slot) and avoids the user-visible "plugin disabled"
+        // condition without requiring `openclaw plugins install --force`.
+        //
+        // Phrase-safety: writes only metadata (version, spec, source,
+        // installedAt). No mnemonic / userId / SA leakage.
+        if (pluginVersion) {
+            if (typeof cfg.plugins.installs !== 'object' || cfg.plugins.installs === null) {
+                cfg.plugins.installs = {};
+            }
+            const existing = cfg.plugins.installs.totalreclaw;
+            const existingVersion = (typeof existing === 'object' && existing !== null && typeof existing.version === 'string')
+                ? existing.version
+                : null;
+            if (!existingVersion) {
+                cfg.plugins.installs.totalreclaw = {
+                    ...(typeof existing === 'object' && existing !== null ? existing : {}),
+                    version: pluginVersion,
+                    spec: '@totalreclaw/totalreclaw',
+                    source: 'self-heal',
+                    installedAt: new Date().toISOString(),
+                };
+                mutated = true;
+            }
+        }
+        // --- Fix #5 (3.3.12-rc.3): plugins.allow includes "totalreclaw" ---
+        //
+        // OpenClaw 2026.5.x: when `plugins.allow` is a non-empty array, the
+        // gateway switches into strict-allowlist mode. Plugins NOT in the
+        // allow list are silently rejected at load time — even bundled ones
+        // are gated. Pedro's pop-os 2026-05-08 QA had `plugins.allow` =
+        // ['device-pair', 'google', 'telegram', 'zai'] AFTER `openclaw
+        // plugins install @totalreclaw/totalreclaw@rc` ran. The install
+        // command did NOT add 'totalreclaw' to the allow list. Plugin
+        // shipped as `disabled`. Setup never proceeded.
+        //
+        // Defensive: when allow is a non-empty array and 'totalreclaw' is
+        // not in it, append. Don't touch null/undefined allow (means
+        // auto-discover mode — plugin is reachable without explicit allow).
+        if (Array.isArray(cfg.plugins.allow) && cfg.plugins.allow.length > 0) {
+            if (!cfg.plugins.allow.includes('totalreclaw')) {
+                cfg.plugins.allow.push('totalreclaw');
+                mutated = true;
+            }
+        }
         // --- Fix #1: plugins.slots.memory = "totalreclaw" (gated on install) ---
         //
         // DEFENSIVE GATE (3.3.9-rc.4 — 2026-05-05): only write the slot when