@totalreclaw/totalreclaw 3.3.8-rc.1 → 3.3.9-rc.1

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.9-rc.1] — 2026-05-02
+
+Pedro's QA on 3.3.8-rc.1 (Telegram → canonical OpenClaw 2026.5.2) revealed five issues that all stem from the same architectural problem — TotalReclaw's tools registered via `api.registerTool()` are blocked by OpenClaw 2026.5.2's tool-policy strip race (issue #223, filed upstream). Each release we ship adds a fix for one gate, hits another. 3.3.9-rc.1 pivots to hybrid-primary: the `tr` CLI is now the PRIMARY path. Native tools are kept for back-compat only.
+
+### Five issues from Pedro's 3.3.8-rc.1 QA — root causes and fixes:
+
+1. **Agent hallucinated "without an account, memories are local only"** — FALSE. TR is relay-based, no local storage. Fix: SKILL.md now has a "CRITICAL: Relay-based architecture" section at the top with an explicit forbidden-vocabulary denylist (`local`, `local-only`, `stored locally`, `on disk`, `without an account`, `local memory`, `local storage`). Both `skill/plugin/SKILL.md` and `skill/SKILL.md` updated.
+
+2. **Agent did not autonomously emit account-setup URL+PIN after install** — asked user instead. Fix: SKILL.md now makes step 4 (running `tr pair --json`) UNCONDITIONAL — no "Want me to set up an account?" gate. The URL+PIN is the consent moment.
+
+3. **Pair tool reply did NOT include the URL** ("open in your browser, enter PIN" with no link). Fix: `tr pair --json` output documented in SKILL.md with explicit JSON shape `{"url":"...","pin":"...","expires_at":"..."}`. Agent is instructed to parse and emit URL verbatim.
+
+4. **`totalreclaw_pair` not bound after install, `/totalreclaw-restart` did not restore binding** — root cause is issue #223 (tool-policy strip race). Fix: SKILL.md drops the "wait for tool-bind / /totalreclaw-restart / /new" cycle from the user-facing path. `tr status --json` replaces the tool-binding check. Agent no longer depends on `totalreclaw_*` binding.
+
+5. **Pair-page POST `/respond` returned 502 then 400** — separate relay bug, out of scope for this RC.
+
+### Changed — SKILL.md (both `skill/plugin/SKILL.md` and `skill/SKILL.md`):
+
+- Added "CRITICAL: Relay-based architecture" section at top with positive assertion and forbidden-vocabulary denylist.
+- Rewritten setup flow: Step 1 install → Step 2 verify CLI (`tr status --json`) → Step 3 credentials check → Step 4 emit URL+PIN via `tr pair --json` (unconditional) → Step 5 confirm.
+- Dropped the entire "wait for tool-bind, restart with /totalreclaw-restart, fall back to /new" cycle.
+- Added "tr CLI reference" section documenting `--json` flag shapes for all commands.
+- Autonomous account setup: removed consent gate, agent runs `tr pair --json` immediately.
+- User-visible line set updated: line 2 now confirms "hybrid mode"; line 3 emitted immediately from `tr pair --json` output.
+
+### Changed — `tr-cli.ts` → CLI JSON-first output:
+
+- `tr status --json` → `{"version":"3.3.9-rc.1","onboarded":bool,"next_step":"pair|none","tool_count":N,"hybrid_mode":bool}`
+- `tr pair --json` → `{"url":"...","pin":"...","expires_at":"..."}` (delegated to pair-cli-relay.ts, already JSON-capable)
+- `tr remember --json '<fact>'` → `{"ok":true,"id":"...","claim_count":0}`
+- `tr recall --json '<query>' --limit 5` → `{"results":[{"text":"...","score":0.8}]}`
+- Plain text mode kept for direct user CLI use; `--json` flag required for agent shell calls.
+- Updated plugin version reference to `3.3.9-rc.1` in pair delegation.
+
+### New tests:
+
+- `skill-md-hybrid-primary.test.ts` — asserts SKILL.md contains hybrid-primary instructions, forbidden-vocabulary denylist, relay-based architecture assertion, and autonomous pair call.
+- `tr-cli-json-output.test.ts` — asserts each `tr <cmd> --json` code path returns parseable JSON with expected keys (via static source analysis).
+
+### Not changed:
+
+- Hooks (`before_agent_start`, `agent_end`, `message_received`, `before_reset`) — not affected by issue #223, unchanged.
+- HTTP routes (4 QR-pairing routes) — unchanged.
+- `/totalreclaw-restart` slash command — kept for environments where users want a manual reload.
+- `api.registerTool()` calls — kept for back-compat (older OpenClaw versions where tools work).
+- Relay code — 502/400 pair page bugs are out of scope.
+- Hermes Python code — separate runtime.
+
 ## [3.3.7-rc.3] — 2026-05-04
 
 Root cause of tool-binding gap on OpenClaw 2026.5.2: the plugin manifest (`openclaw.plugin.json`) was missing the `contracts.tools` declaration that OpenClaw 2026.5.2 now requires before any non-bundled plugin may register agent tools. Without it, every `api.registerTool()` call is silently rejected — `openclaw plugins doctor` shows 17× "plugin must declare contracts.tools before registering agent tools". The gateway loads the plugin module (ESM import succeeds, `plugins.allow` check passes) but no tools bind to any session, so `totalreclaw_pair` / `totalreclaw_remember` / etc. are invisible to the agent and auto-QA step 1 fails.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.8-rc.1
+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.9-rc.1
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -26,9 +26,33 @@ metadata:
 
 > The canonical install flow lives at <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>. If a user pastes that URL in chat, fetch it and follow its agent-instructions section. This SKILL.md mirrors the same steps so you can act even if the URL is unreachable.
 
+## CRITICAL: Relay-based architecture (read before anything else)
+
+**TotalReclaw is RELAY-BASED. All memories require a paired account on the staging or production relay (depending on RC vs stable). There is NO local-only mode. NEVER claim memories are stored locally without an account.**
+
+Forbidden vocabulary — these claims are FALSE and MUST NEVER appear in your responses:
+- "local"
+- "local-only"
+- "stored locally"
+- "on disk"
+- "without an account"
+- "local memory"
+- "local storage"
+- any phrasing suggesting memories can be stored without pairing a relay account
+
+If you find yourself about to say any of these, STOP. The correct statement is: "TotalReclaw requires a paired relay account to store memories — run `tr pair` to set one up."
+
 ## Top-level rule (read this before anything else)
 
-**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 **5–6 short lines TOTAL** (lines 1, 2, 5, 6 always; lines 3 and 4 only if the corresponding condition fires). 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**. 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.
+
+## 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.
+
+**The `tr` binary is installed at:** `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
+**Always invoke via:** `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd> [--json]`
+**Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223.
 
 ## User-visible line set (THIS IS ALL YOU SAY)
 
@@ -36,70 +60,70 @@ Speak only these lines, in order. Substitute the bracketed placeholders with the
 
 1. (start of install)
    > Installing TotalReclaw…
-2. (after install + auto-reload + `totalreclaw_pair` is bound)
-   > ✓ Installed (totalreclaw &lt;version&gt;)
-3. (optional — only if auto-reload didn't fire and you need to issue `/totalreclaw-restart`)
-   > Restarting OpenClaw to load the plugin…
-4. (optional — only if you successfully disabled the built-in memory tool to prevent dual-write)
-   > Disabled built-in memory tool.
-5. (account-setup URL + PIN, immediately after `totalreclaw_pair` returns)
+2. (after install + CLI verify — `tr status` works)
+   > ✓ Installed (totalreclaw &lt;version&gt;, hybrid mode)
+3. (account-setup URL + PIN, IMMEDIATELY after `tr pair --json` returns — no consent gate)
    > Open &lt;url&gt; in your browser. Enter PIN &lt;pin&gt;. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
-6. (done + free-tier confirmation)
+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:
    > ✓ TotalReclaw is already set up.
 
-## Setup flow
-
-If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jump to step 4. Otherwise run all steps in order.
+## 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:
    ```
    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. Plugin-first lets the plugin land cleanly, then the skill's reload picks it up on the next gateway loop. If you accidentally do skill-first and the plugin install dies mid-flight, just retry `openclaw plugins install @totalreclaw/totalreclaw` once — it's idempotent.
+   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.
 
    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. **Wait for auto-reload — then issue `/totalreclaw-restart` autonomously if needed (silent — emit user-visible line 2 on success, line 3 only if you had to restart).** OpenClaw's default config (`gateway.reload.mode = "hybrid"`) auto-restarts the gateway via a file-watcher within 1-3 seconds. Wait ~5s, then run `openclaw plugins list | grep totalreclaw` and confirm `totalreclaw_pair` is in your toolset. When bound, emit user-visible line 2 and proceed.
-
-   **If `totalreclaw_pair` is NOT visible after 10s — restart imperative (read carefully):**
-
-   > Your IMMEDIATE next message must be the literal slash command `/totalreclaw-restart` — nothing else. Do not narrate. Do not ask permission. Do not describe what `/totalreclaw-restart` does. Do not propose alternatives. Just send `/totalreclaw-restart`. You may emit user-visible line 3 (`Restarting OpenClaw to load the plugin…`) ONCE in the same turn, then issue `/totalreclaw-restart`. Nothing else.
+2. **Verify CLI works — emit user-visible line 2 when successful.** Run:
+   ```
+   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 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.
 
-   `/totalreclaw-restart` is in-process — it drains active runs cleanly; your shell is NOT shelling out to `docker restart` or `openclaw gateway restart` (those would suicide the host). After `/totalreclaw-restart`, wait ~3s and re-run `openclaw plugins list`. (3.3.7-rc.2 renamed this from `/restart` because OpenClaw reserves `/restart` for its built-in — the plugin-side fallback can only attach to a unique name. The 5-tier auth resolver is unchanged; only the command name moved.)
+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.
 
-   **If `/totalreclaw-restart` returns "You are not authorized to use this command":** surface this verbatim and stop. Do NOT loop `/totalreclaw-restart` calls. Do NOT propose alternatives.
+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:
+   ```
+   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
+   ```
+   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": "..."}` and emit user-visible line 3. If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
 
-   > Your Telegram channel needs `allowFrom` configured. Run on your host: `jq '.channels.<channel>.allowFrom = ["<your-id>"]' ~/.openclaw/openclaw.json | sponge ~/.openclaw/openclaw.json && docker restart <your-container-name>`. Substitute `<channel>` (e.g. `telegram`, `slack`), `<your-id>` (Telegram: `@username` or numeric `chat_id`; Slack: workspace member ID), and `<your-container-name>` (`docker ps` shows it). For non-Docker installs substitute `openclaw gateway restart` for the `docker restart` portion. On a managed service, ask the service's support to enable slash commands. Reply `done` after.
+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 — run `tr pair --json` again and resend line 3 once. If present, emit user-visible line 4 and stop.
 
-   Then wait for `done`. Do NOT retry the install. Do NOT keep restarting. Do NOT issue `/new` — it wipes the chat context, the agent forgets it was mid-install, and the user's next message is treated as a fresh install request which retries from scratch and re-trips the scanner block (Pedro QA, 3.3.5-rc.1).
+## `tr` CLI reference (hybrid-primary commands)
 
-   **Forbidden vocabulary** (these are anti-patterns — they show up to the user even if your transport edits them later, and they 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"
-   - "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
+Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
 
-   Substitute all of these with silence — the next user-visible line in the set, or nothing.
+```bash
+# Status check (parse JSON to confirm install + onboarding state)
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json
+# Returns: {"version":"3.3.9-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
 
-3. **Verify `totalreclaw_pair` is bound.** If still missing after `/totalreclaw-restart` (or after the user fixed allowFrom and said `done`), tell them the restart didn't take effect and ask them to retry. Do not loop the install.
+# Pair / account setup
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
+# Returns: {"url":"https://...","pin":"123456","expires_at":"2026-05-05T..."}
 
-4. **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.
+# Remember a fact
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "I work at Graph Foundation"
+# Returns: {"ok":true,"id":"...","claim_count":N}
 
-5. **Set up the user's TotalReclaw account (emit user-visible line 5 once, after `totalreclaw_pair` returns).** Call `totalreclaw_pair` silently (the account-setup tool — name kept for backward compatibility). It returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR" below). Then emit user-visible line 5 with `<url>` and `<pin>` substituted. Do not pre-narrate ("I'll walk you through…", "Setting up your account now…") — line 5 itself is the only thing the user needs to see. The URL + PIN itself is the real consent moment: surfacing them verbatim is what gives the user the chance to opt out by simply not opening the page.
+# Recall memories
+node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall --json "where does the user work" --limit 5
+# Returns: {"results":[{"text":"...","score":0.8},...]}
+```
 
-6. **Verify and confirm (silent until line 6).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — call `totalreclaw_pair` again silently and resend line 5 once. If present, emit user-visible line 6 and stop.
+**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 (rc.5+)
 
-When you receive the `totalreclaw_pair` payload, render the QR based on your chat transport:
+When you receive the `totalreclaw_pair` payload (from tool OR `tr pair --json`), render the QR based on your chat transport:
 
 - **Transport supports image attachments** (Telegram, Slack, web chat, any transport with file/image upload): decode `qr_png_b64` from base64 to bytes, save to a tempfile with a `.png` suffix, and attach the tempfile as an image. Also show the URL + PIN as text so users who prefer clicking can still do so.
 - **Terminal-only transport** (OpenClaw native CLI chat, bare SSH shell): emit `qr_unicode` inline in your reply. It renders as block characters in most terminal fonts; the user scans from their phone.
@@ -109,44 +133,52 @@ The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-
 
 ## Phrase safety (HARD — never break)
 
-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) the `totalreclaw_pair` account-setup tool; (2) if the tool is missing from your tool list — a known gap for some container-based agents, issue #87 — 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}`, issue #95 — same account-setup flow, `pair_url` key naming). 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, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
+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" → `totalreclaw_remember` (don't ask permission).
-- First-person factual query ("do I / what's my / where do I …") → `totalreclaw_recall` FIRST, then answer from returned facts. If 0 results, say so.
-- "forget / pin / unpin / retype / move to <scope>" X → `totalreclaw_recall` first for `factId`, then `totalreclaw_forget` / `_pin` / `_unpin` / `_retype` / `_set_scope`.
-- "status" → `totalreclaw_status`. "upgrade" → `totalreclaw_upgrade` (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
-- "import / export / consolidate" → `totalreclaw_import_from` (`dry_run=true` first; `_import_batch` for >50 chunks) · `totalreclaw_export` · `totalreclaw_consolidate` (`dry_run` first).
+- Stable user facts / preferences / identity / "remember X":
+  ```
+  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "<fact>"
+  ```
+- First-person factual query ("do I / what's my / where do I…"):
+  ```
+  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 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"
+- "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
+- "local" / "local-only" / "stored locally" / "on disk" / "without an account" / "local memory" / "local storage"
 
-## OpenClaw 2026.5.2 hybrid mode (issue #223 workaround — plugin 3.3.8-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. Plugin 3.3.8-rc.1 ships a hybrid workaround:
-
-- **Hooks still fire**: `before_agent_start`, `agent_end`, `message_received`, `before_reset` use a separate code path not affected by issue #223. Auto-extraction, digest injection, preloading, and billing checks all work normally.
-- **Tools replaced by `tr` CLI**: instead of `totalreclaw_remember`, `totalreclaw_recall`, etc., use the `tr` binary installed with the plugin. The agent runs it via shell tool.
-
-**Agent usage under hybrid mode** (check `tr status` output for `hybrid-mode: yes`):
-
-```
-# remember a fact
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember "I work at Graph Foundation"
-# → outputs {"ok":true,"id":"...","text":"..."}
-
-# recall facts
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall "where does the user work"
-# → outputs {"ok":true,"count":1,"query":"...","memories":[...]}
+## Diagnostics
 
-# status check
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status
-```
+- `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.
+- `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`.
 
-Note: the `tr` bin name conflicts with the system `tr` utility; always invoke via full path `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd>` or the gateway host's equivalent path.
+## Required post-install config (OpenClaw 2026.5.2+)
 
-**Required post-install config** (add to `~/.openclaw/openclaw.json`):
+Add to `~/.openclaw/openclaw.json` after installing:
 ```json
 {
   "plugins": {
+    "allow": ["totalreclaw"],
     "entries": {
       "totalreclaw": {
         "hooks": { "allowConversationAccess": true }
@@ -156,16 +188,9 @@ Note: the `tr` bin name conflicts with the system `tr` utility; always invoke vi
 }
 ```
 
-This unlocks typed hooks (`agent_end`, etc.) for non-bundled plugins. Without it, auto-extraction still works (extraction runs in `message_received`) but the `agent_end` hook that writes the digest is silently blocked.
-
-## Diagnostics
-
-- `totalreclaw_*` tools not visible → plugin not installed or auto-reload didn't fire. Verify via `openclaw plugins list | grep totalreclaw` (or, on a managed service that doesn't expose the CLI, ask the user to confirm via their service's plugins UI). If `totalreclaw` is listed but tools are still absent, the gateway probably hasn't completed its auto-restart yet (give it 5-10s) OR `gateway.reload.mode = off` is set — instruct manual restart as fallback: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host), or the managed service's restart control. If the plugin is listed and the gateway has been restarted but tools are still missing (container-agent gap, issue #87 / OC 2026.5.2 issue #223), switch to hybrid mode: use `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd>` for remember/recall/pair/status. If your shell doesn't reach the gateway host (managed service), tell the user to install/enable the plugin via their service's plugins UI and restart the gateway via the service's restart control. Do NOT suggest the bare `openclaw totalreclaw onboard` (leaks phrase on stdout — deprecated in rc.18, removed next RC).
-- User says done but `credentials.json` missing → PIN expired or entered wrong phrase; call `totalreclaw_pair` again.
-- `onboarding required` → credentials missing; redo from the account-setup step.
-- `quota exceeded` → `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`.
+`plugins.allow` suppresses the "plugins.allow is empty" warning. `hooks.allowConversationAccess` unlocks typed hooks (`agent_end`, etc.) for auto-extraction.
 
 ## Tool surface
 
-`totalreclaw_pair` (ONLY account-setup path) · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` (pointer to local-terminal wizard, for users explicitly rejecting the browser flow) · `_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)

package/dist/tr-cli.js

@@ -1,24 +1,28 @@
 #!/usr/bin/env node
 /**
- * tr — TotalReclaw hybrid CLI (3.3.8-rc.1 workaround for OpenClaw 2026.5.2 issue #223)
+ * tr — TotalReclaw hybrid CLI (3.3.9-rc.1 primary architecture)
  *
- * OpenClaw 2026.5.2 has a tool-policy-pipeline bug that strips non-bundled plugin tools
- * before they reach the agent toolset. This CLI bypasses the broken tool-registration
- * path entirely. The agent runs `tr <cmd>` from shell; the plugin keeps its hooks
- * (before_agent_start, agent_end, message_received) via the unbroken hook code path.
+ * OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin
+ * tools before they reach the agent toolset. In 3.3.9-rc.1, this CLI is the PRIMARY path for
+ * all agent memory operations (not a fallback). The agent runs `tr <cmd> --json` from shell;
+ * hooks (before_agent_start, agent_end, message_received, before_reset) continue via the
+ * unbroken hook code path.
  *
  * Phrase-safety: this CLI reads credentials.json (mnemonic at rest) but NEVER
  * prints the mnemonic to stdout, stderr, or any log. Phrase only enters via QR-pair
  * browser tier (pair-cli.ts / pair-cli-relay.ts — unchanged).
  *
  * Commands:
- *   tr status               — print onboarding + credentials state
- *   tr pair [--json]        — start a relay pairing session, print URL+PIN+QR
- *   tr remember <text>      — store a memory in the encrypted vault
- *   tr recall <query>       — search the encrypted vault, print results as JSON
+ *   tr status [--json]          — print onboarding + credentials state
+ *   tr pair [--json]            — start a relay pairing session, print URL+PIN+QR
+ *   tr remember [--json] <text> — store a memory in the encrypted vault
+ *   tr recall [--json] [--limit N] <query> — search the encrypted vault
+ *
+ * --json flag: all agent-facing CLI calls MUST use --json for clean machine-parseable output.
+ *              Plain text mode is for direct user CLI use only.
  *
  * Install: wired via package.json `bin.tr` → dist/tr-cli.js
- * Usage from container: `docker exec tr-openclaw tr status`
+ * Usage from container: `docker exec tr-openclaw node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json`
  */
 import path from 'node:path';
 import os from 'node:os';
@@ -34,6 +38,7 @@ import { createApiClient } from './api-client.js';
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 const SERVER_URL = CONFIG.serverUrl;
 const STATE_PATH = CONFIG.onboardingStatePath;
+const PLUGIN_VERSION = '3.3.9-rc.1';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);
@@ -41,16 +46,32 @@ function die(msg, code = 1) {
 function log(msg) {
     process.stdout.write(msg + '\n');
 }
+/** Parse --flag from args array, returning the cleaned args without the flag. */
+function popFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return [false, args];
+    return [true, [...args.slice(0, idx), ...args.slice(idx + 1)]];
+}
+/** Parse --limit N from args, returning [limit, cleanedArgs]. Default: defaultLimit. */
+function popLimitFlag(args, defaultLimit) {
+    const idx = args.indexOf('--limit');
+    if (idx === -1 || idx + 1 >= args.length)
+        return [defaultLimit, args];
+    const n = parseInt(args[idx + 1], 10);
+    const limit = isNaN(n) || n < 1 ? defaultLimit : n;
+    return [limit, [...args.slice(0, idx), ...args.slice(idx + 2)]];
+}
 async function buildContext() {
     const creds = loadCredentialsJson(CREDENTIALS_PATH);
     if (!creds) {
-        die('TotalReclaw is not set up. Run: openclaw totalreclaw onboard\n(or: tr pair)');
+        die('TotalReclaw is not set up. Run: node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json');
     }
     const mnemonic = (typeof creds.mnemonic === 'string' && creds.mnemonic.trim()) ||
         (typeof creds.recovery_phrase === 'string' && creds.recovery_phrase.trim()) ||
         '';
     if (!mnemonic) {
-        die('No recovery phrase in credentials.json. Run: openclaw totalreclaw onboard');
+        die('No recovery phrase in credentials.json. Run: tr pair --json');
     }
     // Parse existing salt/userId from credentials.json
     let existingSalt;
@@ -101,40 +122,59 @@ async function buildContext() {
 // ---------------------------------------------------------------------------
 // Command: status
 // ---------------------------------------------------------------------------
-async function cmdStatus() {
-    // Print onboarding + credentials state (never prints mnemonic — same as
-    // the `openclaw totalreclaw status` subcommand surface).
-    printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
-    // Additional: loaded.json check to confirm plugin hooks are active.
-    // Reads manifest written by register() in index.ts.
-    // Probe both install paths: extensions/ (local tgz installs) and npm/ (registry installs).
+async function cmdStatus(jsonMode) {
+    // Probe plugin manifest for version/hybridMode/toolCount.
+    let pluginVersion;
+    let bootCount;
+    let hybridMode = true; // default true in 3.3.9-rc.1 (hybrid-primary)
+    let toolCount;
+    let loadedAgeSec;
     try {
         const fs = await import('node:fs');
         const candidatePaths = [
-            // extensions-path (local tgz / --force install) — .loaded.json sits at root, not dist/
             path.join(os.homedir(), '.openclaw', 'extensions', 'totalreclaw', '.loaded.json'),
-            // npm-path (registry install) — .loaded.json inside dist/
             path.join(os.homedir(), '.openclaw', 'npm', 'node_modules', '@totalreclaw', 'totalreclaw', 'dist', '.loaded.json'),
         ];
         const resolvedPath = candidatePaths.find((p) => fs.existsSync(p));
         if (resolvedPath) {
             const raw = fs.readFileSync(resolvedPath, 'utf-8');
             const manifest = JSON.parse(raw);
+            pluginVersion = manifest.version ?? PLUGIN_VERSION;
+            bootCount = manifest.bootCount;
+            hybridMode = manifest.hybridMode !== false; // default true
+            toolCount = manifest.tools?.length;
             const ageMs = Date.now() - (manifest.loadedAt ?? 0);
-            const ageSec = Math.round(ageMs / 1000);
-            process.stdout.write(`\n  plugin:      loaded (version=${manifest.version ?? '?'} bootCount=${manifest.bootCount ?? '?'} loaded=${ageSec}s ago)\n` +
-                `  hybrid-mode: ${manifest.hybridMode ? 'yes (use tr <cmd>)' : 'no'}\n` +
-                `  hooks:       before_agent_start, agent_end, message_received, before_reset\n` +
-                `  note:        tools from .loaded.json are STRIPPED by OC 2026.5.2 issue #223;\n` +
-                `               use \`tr <cmd>\` from shell instead\n`);
-        }
-        else {
-            process.stdout.write('\n  plugin:      .loaded.json not found — plugin may not be loaded\n');
+            loadedAgeSec = Math.round(ageMs / 1000);
         }
     }
     catch {
         // Best-effort
     }
+    // Check onboarding state
+    const creds = loadCredentialsJson(CREDENTIALS_PATH);
+    const onboarded = !!creds;
+    if (jsonMode) {
+        // JSON-first output for agent parsing
+        const out = {
+            version: pluginVersion ?? PLUGIN_VERSION,
+            onboarded,
+            next_step: onboarded ? 'none' : 'pair',
+            tool_count: toolCount ?? 17,
+            hybrid_mode: hybridMode,
+        };
+        if (bootCount !== undefined)
+            out.boot_count = bootCount;
+        if (loadedAgeSec !== undefined)
+            out.loaded_age_sec = loadedAgeSec;
+        log(JSON.stringify(out));
+    }
+    else {
+        // Human-readable plain text for direct user CLI use
+        printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
+        process.stdout.write(`\n  plugin:      ${pluginVersion ? `loaded (version=${pluginVersion}` + (bootCount !== undefined ? ` bootCount=${bootCount}` : '') + (loadedAgeSec !== undefined ? ` loaded=${loadedAgeSec}s ago` : '') + ')' : 'not found in .loaded.json'}\n` +
+            `  hybrid-mode: ${hybridMode ? 'yes (primary — use tr <cmd> --json)' : 'no'}\n` +
+            `  hooks:       before_agent_start, agent_end, message_received, before_reset\n`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Command: pair
@@ -156,7 +196,7 @@ async function cmdPair(args) {
             warn: (m) => process.stderr.write(`[warn] ${m}\n`),
             error: (m) => process.stderr.write(`[error] ${m}\n`),
         },
-        pluginVersion: '3.3.8-rc.1',
+        pluginVersion: PLUGIN_VERSION,
         deriveScopeAddress: undefined,
         renderQr: defaultRenderQr,
         io,
@@ -172,10 +212,11 @@ async function cmdPair(args) {
 // ---------------------------------------------------------------------------
 // Command: remember
 // ---------------------------------------------------------------------------
-async function cmdRemember(args) {
+async function cmdRemember(rawArgs) {
+    const [jsonMode, args] = popFlag(rawArgs, '--json');
     const text = args.join(' ').trim();
     if (!text) {
-        die('Usage: tr remember <text>');
+        die('Usage: tr remember [--json] <text>');
     }
     const ctx = await buildContext();
     // Build a minimal MemoryTaxonomy v1 claim blob (same format as storeExtractedFacts)
@@ -211,7 +252,14 @@ async function cmdRemember(args) {
     };
     try {
         await ctx.apiClient.store(ctx.userId, [payload], ctx.authKeyHex);
-        log(JSON.stringify({ ok: true, id: factId, text }));
+        if (jsonMode) {
+            // JSON-first output for agent parsing
+            // claim_count requires an extra relay call to tally stored claims; not worth the latency — use 0
+            log(JSON.stringify({ ok: true, id: factId, claim_count: 0 }));
+        }
+        else {
+            log(`ok — stored memory (id=${factId})`);
+        }
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -221,31 +269,36 @@ async function cmdRemember(args) {
 // ---------------------------------------------------------------------------
 // Command: recall
 // ---------------------------------------------------------------------------
-async function cmdRecall(args) {
-    const query = args.join(' ').trim();
+async function cmdRecall(rawArgs) {
+    const [jsonMode, argsAfterJson] = popFlag(rawArgs, '--json');
+    const [limit, argsAfterLimit] = popLimitFlag(argsAfterJson, 5);
+    const query = argsAfterLimit.join(' ').trim();
     if (!query) {
-        die('Usage: tr recall <query>');
+        die('Usage: tr recall [--json] [--limit N] <query>');
     }
     const ctx = await buildContext();
     // Generate word trapdoors for blind search
     const trapdoors = generateBlindIndices(query);
     if (trapdoors.length === 0) {
-        log(JSON.stringify({ ok: true, count: 0, memories: [] }));
+        if (jsonMode) {
+            log(JSON.stringify({ results: [] }));
+        }
+        else {
+            log('No results (0 searchable terms in query).');
+        }
         return;
     }
     try {
-        const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, 12, ctx.authKeyHex);
-        const memories = [];
+        const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, Math.min(limit * 2, 20), ctx.authKeyHex);
+        const results = [];
         for (const c of candidates) {
             try {
                 const raw = decrypt(c.encrypted_blob, ctx.encryptionKey);
                 const parsed = JSON.parse(raw);
                 if (parsed.text) {
-                    memories.push({
-                        id: c.fact_id,
+                    results.push({
                         text: parsed.text,
                         score: c.decay_score,
-                        timestamp: new Date(c.timestamp).toISOString(),
                     });
                 }
             }
@@ -253,9 +306,19 @@ async function cmdRecall(args) {
                 // Skip undecryptable
             }
         }
-        // Simple relevance sort by decay_score (descending)
-        memories.sort((a, b) => b.score - a.score);
-        log(JSON.stringify({ ok: true, count: memories.length, query, memories }));
+        // Sort by score descending, then trim to limit
+        results.sort((a, b) => b.score - a.score);
+        const trimmed = results.slice(0, limit);
+        if (jsonMode) {
+            // JSON-first output for agent parsing — canonical format per spec
+            log(JSON.stringify({ results: trimmed }));
+        }
+        else {
+            log(`Found ${trimmed.length} result(s) for: ${query}`);
+            for (const r of trimmed) {
+                log(`  [score=${r.score.toFixed(2)}] ${r.text}`);
+            }
+        }
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -269,9 +332,11 @@ async function main() {
     const args = process.argv.slice(2);
     const cmd = args[0];
     switch (cmd) {
-        case 'status':
-            await cmdStatus();
+        case 'status': {
+            const [jsonMode] = popFlag(args.slice(1), '--json');
+            await cmdStatus(jsonMode);
             break;
+        }
         case 'pair':
             await cmdPair(args.slice(1));
             break;
@@ -284,15 +349,23 @@ async function main() {
         case undefined:
         case '--help':
         case '-h':
-            process.stdout.write('TotalReclaw hybrid CLI (OpenClaw 2026.5.2 issue #223 workaround)\n\n' +
+            process.stdout.write(`TotalReclaw hybrid CLI v${PLUGIN_VERSION} (primary mode — OpenClaw 2026.5.2+)\n\n` +
                 'Usage:\n' +
-                '  tr status              — onboarding + plugin load state\n' +
-                '  tr pair [--json]       — start a relay pairing session\n' +
-                '  tr remember <text>     — store a memory\n' +
-                '  tr recall <query>      — search memories (outputs JSON)\n\n' +
+                '  tr status [--json]                       — onboarding + plugin load state\n' +
+                '  tr pair [--json]                         — start a relay pairing session\n' +
+                '  tr remember [--json] <text>              — store a memory\n' +
+                '  tr recall [--json] [--limit N] <query>   — search memories (default limit: 5)\n\n' +
+                'Flags:\n' +
+                '  --json    Output machine-parseable JSON (required for agent shell calls)\n' +
+                '  --limit N Limit recall results (default: 5)\n\n' +
+                'JSON output shapes:\n' +
+                '  status:   {"version":"...","onboarded":bool,"next_step":"pair|none","tool_count":N,"hybrid_mode":bool}\n' +
+                '  pair:     {"url":"...","pin":"123456","expires_at":"..."}\n' +
+                '  remember: {"ok":true,"id":"...","claim_count":N}\n' +
+                '  recall:   {"results":[{"text":"...","score":0.8}]}\n\n' +
                 'Environment:\n' +
-                '  TOTALRECLAW_SERVER_URL — relay URL (default: api-staging.totalreclaw.xyz)\n' +
-                '  TOTALRECLAW_CREDENTIALS_PATH — override credentials.json path\n');
+                '  TOTALRECLAW_SERVER_URL           — relay URL (default: api-staging.totalreclaw.xyz)\n' +
+                '  TOTALRECLAW_CREDENTIALS_PATH     — override credentials.json path\n');
             break;
         default:
             die(`Unknown command: ${cmd}. Run \`tr --help\` for usage.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.8-rc.1",
+  "version": "3.3.9-rc.1",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -67,7 +67,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx load-manifest.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx load-manifest.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-hybrid-primary.test.ts && npx tsx tr-cli-json-output.test.ts",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "check-version-drift": "node ../scripts/check-version-drift.mjs",

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.8-rc.1",
+  "version": "3.3.9-rc.1",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/tr-cli.ts

@@ -1,24 +1,28 @@
 #!/usr/bin/env node
 /**
- * tr — TotalReclaw hybrid CLI (3.3.8-rc.1 workaround for OpenClaw 2026.5.2 issue #223)
+ * tr — TotalReclaw hybrid CLI (3.3.9-rc.1 primary architecture)
  *
- * OpenClaw 2026.5.2 has a tool-policy-pipeline bug that strips non-bundled plugin tools
- * before they reach the agent toolset. This CLI bypasses the broken tool-registration
- * path entirely. The agent runs `tr <cmd>` from shell; the plugin keeps its hooks
- * (before_agent_start, agent_end, message_received) via the unbroken hook code path.
+ * OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin
+ * tools before they reach the agent toolset. In 3.3.9-rc.1, this CLI is the PRIMARY path for
+ * all agent memory operations (not a fallback). The agent runs `tr <cmd> --json` from shell;
+ * hooks (before_agent_start, agent_end, message_received, before_reset) continue via the
+ * unbroken hook code path.
  *
  * Phrase-safety: this CLI reads credentials.json (mnemonic at rest) but NEVER
  * prints the mnemonic to stdout, stderr, or any log. Phrase only enters via QR-pair
  * browser tier (pair-cli.ts / pair-cli-relay.ts — unchanged).
  *
  * Commands:
- *   tr status               — print onboarding + credentials state
- *   tr pair [--json]        — start a relay pairing session, print URL+PIN+QR
- *   tr remember <text>      — store a memory in the encrypted vault
- *   tr recall <query>       — search the encrypted vault, print results as JSON
+ *   tr status [--json]          — print onboarding + credentials state
+ *   tr pair [--json]            — start a relay pairing session, print URL+PIN+QR
+ *   tr remember [--json] <text> — store a memory in the encrypted vault
+ *   tr recall [--json] [--limit N] <query> — search the encrypted vault
+ *
+ * --json flag: all agent-facing CLI calls MUST use --json for clean machine-parseable output.
+ *              Plain text mode is for direct user CLI use only.
  *
  * Install: wired via package.json `bin.tr` → dist/tr-cli.js
- * Usage from container: `docker exec tr-openclaw tr status`
+ * Usage from container: `docker exec tr-openclaw node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json`
  */
 
 import path from 'node:path';
@@ -45,6 +49,7 @@ import { createApiClient } from './api-client.js';
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 const SERVER_URL = CONFIG.serverUrl;
 const STATE_PATH = CONFIG.onboardingStatePath;
+const PLUGIN_VERSION = '3.3.9-rc.1';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);
@@ -55,6 +60,22 @@ function log(msg: string): void {
   process.stdout.write(msg + '\n');
 }
 
+/** Parse --flag from args array, returning the cleaned args without the flag. */
+function popFlag(args: string[], flag: string): [boolean, string[]] {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return [false, args];
+  return [true, [...args.slice(0, idx), ...args.slice(idx + 1)]];
+}
+
+/** Parse --limit N from args, returning [limit, cleanedArgs]. Default: defaultLimit. */
+function popLimitFlag(args: string[], defaultLimit: number): [number, string[]] {
+  const idx = args.indexOf('--limit');
+  if (idx === -1 || idx + 1 >= args.length) return [defaultLimit, args];
+  const n = parseInt(args[idx + 1], 10);
+  const limit = isNaN(n) || n < 1 ? defaultLimit : n;
+  return [limit, [...args.slice(0, idx), ...args.slice(idx + 2)]];
+}
+
 // ---------------------------------------------------------------------------
 // Core init — minimal version of index.ts initialize()
 // ---------------------------------------------------------------------------
@@ -70,7 +91,7 @@ interface CliContext {
 async function buildContext(): Promise<CliContext> {
   const creds = loadCredentialsJson(CREDENTIALS_PATH);
   if (!creds) {
-    die('TotalReclaw is not set up. Run: openclaw totalreclaw onboard\n(or: tr pair)');
+    die('TotalReclaw is not set up. Run: node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json');
   }
 
   const mnemonic =
@@ -79,7 +100,7 @@ async function buildContext(): Promise<CliContext> {
     '';
 
   if (!mnemonic) {
-    die('No recovery phrase in credentials.json. Run: openclaw totalreclaw onboard');
+    die('No recovery phrase in credentials.json. Run: tr pair --json');
   }
 
   // Parse existing salt/userId from credentials.json
@@ -134,20 +155,18 @@ async function buildContext(): Promise<CliContext> {
 // Command: status
 // ---------------------------------------------------------------------------
 
-async function cmdStatus(): Promise<void> {
-  // Print onboarding + credentials state (never prints mnemonic — same as
-  // the `openclaw totalreclaw status` subcommand surface).
-  printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
+async function cmdStatus(jsonMode: boolean): Promise<void> {
+  // Probe plugin manifest for version/hybridMode/toolCount.
+  let pluginVersion: string | undefined;
+  let bootCount: number | undefined;
+  let hybridMode = true; // default true in 3.3.9-rc.1 (hybrid-primary)
+  let toolCount: number | undefined;
+  let loadedAgeSec: number | undefined;
 
-  // Additional: loaded.json check to confirm plugin hooks are active.
-  // Reads manifest written by register() in index.ts.
-  // Probe both install paths: extensions/ (local tgz installs) and npm/ (registry installs).
   try {
     const fs = await import('node:fs');
     const candidatePaths = [
-      // extensions-path (local tgz / --force install) — .loaded.json sits at root, not dist/
       path.join(os.homedir(), '.openclaw', 'extensions', 'totalreclaw', '.loaded.json'),
-      // npm-path (registry install) — .loaded.json inside dist/
       path.join(os.homedir(), '.openclaw', 'npm', 'node_modules', '@totalreclaw', 'totalreclaw', 'dist', '.loaded.json'),
     ];
     const resolvedPath = candidatePaths.find((p) => fs.existsSync(p));
@@ -160,21 +179,42 @@ async function cmdStatus(): Promise<void> {
         hybridMode?: boolean;
         tools?: string[];
       };
+      pluginVersion = manifest.version ?? PLUGIN_VERSION;
+      bootCount = manifest.bootCount;
+      hybridMode = manifest.hybridMode !== false; // default true
+      toolCount = manifest.tools?.length;
       const ageMs = Date.now() - (manifest.loadedAt ?? 0);
-      const ageSec = Math.round(ageMs / 1000);
-      process.stdout.write(
-        `\n  plugin:      loaded (version=${manifest.version ?? '?'} bootCount=${manifest.bootCount ?? '?'} loaded=${ageSec}s ago)\n` +
-        `  hybrid-mode: ${manifest.hybridMode ? 'yes (use tr <cmd>)' : 'no'}\n` +
-        `  hooks:       before_agent_start, agent_end, message_received, before_reset\n` +
-        `  note:        tools from .loaded.json are STRIPPED by OC 2026.5.2 issue #223;\n` +
-        `               use \`tr <cmd>\` from shell instead\n`,
-      );
-    } else {
-      process.stdout.write('\n  plugin:      .loaded.json not found — plugin may not be loaded\n');
+      loadedAgeSec = Math.round(ageMs / 1000);
     }
   } catch {
     // Best-effort
   }
+
+  // Check onboarding state
+  const creds = loadCredentialsJson(CREDENTIALS_PATH);
+  const onboarded = !!creds;
+
+  if (jsonMode) {
+    // JSON-first output for agent parsing
+    const out: Record<string, unknown> = {
+      version: pluginVersion ?? PLUGIN_VERSION,
+      onboarded,
+      next_step: onboarded ? 'none' : 'pair',
+      tool_count: toolCount ?? 17,
+      hybrid_mode: hybridMode,
+    };
+    if (bootCount !== undefined) out.boot_count = bootCount;
+    if (loadedAgeSec !== undefined) out.loaded_age_sec = loadedAgeSec;
+    log(JSON.stringify(out));
+  } else {
+    // Human-readable plain text for direct user CLI use
+    printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
+    process.stdout.write(
+      `\n  plugin:      ${pluginVersion ? `loaded (version=${pluginVersion}` + (bootCount !== undefined ? ` bootCount=${bootCount}` : '') + (loadedAgeSec !== undefined ? ` loaded=${loadedAgeSec}s ago` : '') + ')' : 'not found in .loaded.json'}\n` +
+      `  hybrid-mode: ${hybridMode ? 'yes (primary — use tr <cmd> --json)' : 'no'}\n` +
+      `  hooks:       before_agent_start, agent_end, message_received, before_reset\n`,
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -200,7 +240,7 @@ async function cmdPair(args: string[]): Promise<void> {
       warn: (m: string) => process.stderr.write(`[warn] ${m}\n`),
       error: (m: string) => process.stderr.write(`[error] ${m}\n`),
     },
-    pluginVersion: '3.3.8-rc.1',
+    pluginVersion: PLUGIN_VERSION,
     deriveScopeAddress: undefined,
     renderQr: defaultRenderQr,
     io,
@@ -219,10 +259,11 @@ async function cmdPair(args: string[]): Promise<void> {
 // Command: remember
 // ---------------------------------------------------------------------------
 
-async function cmdRemember(args: string[]): Promise<void> {
+async function cmdRemember(rawArgs: string[]): Promise<void> {
+  const [jsonMode, args] = popFlag(rawArgs, '--json');
   const text = args.join(' ').trim();
   if (!text) {
-    die('Usage: tr remember <text>');
+    die('Usage: tr remember [--json] <text>');
   }
 
   const ctx = await buildContext();
@@ -263,7 +304,13 @@ async function cmdRemember(args: string[]): Promise<void> {
 
   try {
     await ctx.apiClient.store(ctx.userId, [payload], ctx.authKeyHex);
-    log(JSON.stringify({ ok: true, id: factId, text }));
+    if (jsonMode) {
+      // JSON-first output for agent parsing
+      // claim_count requires an extra relay call to tally stored claims; not worth the latency — use 0
+      log(JSON.stringify({ ok: true, id: factId, claim_count: 0 }));
+    } else {
+      log(`ok — stored memory (id=${factId})`);
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     die(`remember failed: ${msg}`);
@@ -274,10 +321,12 @@ async function cmdRemember(args: string[]): Promise<void> {
 // Command: recall
 // ---------------------------------------------------------------------------
 
-async function cmdRecall(args: string[]): Promise<void> {
-  const query = args.join(' ').trim();
+async function cmdRecall(rawArgs: string[]): Promise<void> {
+  const [jsonMode, argsAfterJson] = popFlag(rawArgs, '--json');
+  const [limit, argsAfterLimit] = popLimitFlag(argsAfterJson, 5);
+  const query = argsAfterLimit.join(' ').trim();
   if (!query) {
-    die('Usage: tr recall <query>');
+    die('Usage: tr recall [--json] [--limit N] <query>');
   }
 
   const ctx = await buildContext();
@@ -286,25 +335,27 @@ async function cmdRecall(args: string[]): Promise<void> {
   const trapdoors = generateBlindIndices(query);
 
   if (trapdoors.length === 0) {
-    log(JSON.stringify({ ok: true, count: 0, memories: [] }));
+    if (jsonMode) {
+      log(JSON.stringify({ results: [] }));
+    } else {
+      log('No results (0 searchable terms in query).');
+    }
     return;
   }
 
   try {
-    const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, 12, ctx.authKeyHex);
+    const candidates = await ctx.apiClient.search(ctx.userId, trapdoors, Math.min(limit * 2, 20), ctx.authKeyHex);
 
-    const memories: Array<{ id: string; text: string; score: number; timestamp: string }> = [];
+    const results: Array<{ text: string; score: number }> = [];
 
     for (const c of candidates) {
       try {
         const raw = decrypt(c.encrypted_blob, ctx.encryptionKey);
         const parsed = JSON.parse(raw) as { text?: string };
         if (parsed.text) {
-          memories.push({
-            id: c.fact_id,
+          results.push({
             text: parsed.text,
             score: c.decay_score,
-            timestamp: new Date(c.timestamp).toISOString(),
           });
         }
       } catch {
@@ -312,10 +363,19 @@ async function cmdRecall(args: string[]): Promise<void> {
       }
     }
 
-    // Simple relevance sort by decay_score (descending)
-    memories.sort((a, b) => b.score - a.score);
+    // Sort by score descending, then trim to limit
+    results.sort((a, b) => b.score - a.score);
+    const trimmed = results.slice(0, limit);
 
-    log(JSON.stringify({ ok: true, count: memories.length, query, memories }));
+    if (jsonMode) {
+      // JSON-first output for agent parsing — canonical format per spec
+      log(JSON.stringify({ results: trimmed }));
+    } else {
+      log(`Found ${trimmed.length} result(s) for: ${query}`);
+      for (const r of trimmed) {
+        log(`  [score=${r.score.toFixed(2)}] ${r.text}`);
+      }
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     die(`recall failed: ${msg}`);
@@ -331,9 +391,11 @@ async function main(): Promise<void> {
   const cmd = args[0];
 
   switch (cmd) {
-    case 'status':
-      await cmdStatus();
+    case 'status': {
+      const [jsonMode] = popFlag(args.slice(1), '--json');
+      await cmdStatus(jsonMode);
       break;
+    }
 
     case 'pair':
       await cmdPair(args.slice(1));
@@ -351,15 +413,23 @@ async function main(): Promise<void> {
     case '--help':
     case '-h':
       process.stdout.write(
-        'TotalReclaw hybrid CLI (OpenClaw 2026.5.2 issue #223 workaround)\n\n' +
+        `TotalReclaw hybrid CLI v${PLUGIN_VERSION} (primary mode — OpenClaw 2026.5.2+)\n\n` +
         'Usage:\n' +
-        '  tr status              — onboarding + plugin load state\n' +
-        '  tr pair [--json]       — start a relay pairing session\n' +
-        '  tr remember <text>     — store a memory\n' +
-        '  tr recall <query>      — search memories (outputs JSON)\n\n' +
+        '  tr status [--json]                       — onboarding + plugin load state\n' +
+        '  tr pair [--json]                         — start a relay pairing session\n' +
+        '  tr remember [--json] <text>              — store a memory\n' +
+        '  tr recall [--json] [--limit N] <query>   — search memories (default limit: 5)\n\n' +
+        'Flags:\n' +
+        '  --json    Output machine-parseable JSON (required for agent shell calls)\n' +
+        '  --limit N Limit recall results (default: 5)\n\n' +
+        'JSON output shapes:\n' +
+        '  status:   {"version":"...","onboarded":bool,"next_step":"pair|none","tool_count":N,"hybrid_mode":bool}\n' +
+        '  pair:     {"url":"...","pin":"123456","expires_at":"..."}\n' +
+        '  remember: {"ok":true,"id":"...","claim_count":N}\n' +
+        '  recall:   {"results":[{"text":"...","score":0.8}]}\n\n' +
         'Environment:\n' +
-        '  TOTALRECLAW_SERVER_URL — relay URL (default: api-staging.totalreclaw.xyz)\n' +
-        '  TOTALRECLAW_CREDENTIALS_PATH — override credentials.json path\n',
+        '  TOTALRECLAW_SERVER_URL           — relay URL (default: api-staging.totalreclaw.xyz)\n' +
+        '  TOTALRECLAW_CREDENTIALS_PATH     — override credentials.json path\n',
       );
       break;