@totalreclaw/totalreclaw 3.3.11-rc.6 → 3.3.12-rc.13

package/dist/entry.js

@@ -0,0 +1,123 @@
+/**
+ * entry — env-reading seam (Task 1.3, OpenClaw native integration plan,
+ * 2026-06-21).
+ *
+ * This file is one of the TWO designated homes for `process.env.*` reads
+ * in the plugin (the other is `config.ts`). Every other source file
+ * receives env-derived values as PARAMETERS via the primitives exported
+ * here — never reading the env directly. The invariant is locked in by
+ * `entry-env.test.ts` and exists so NO plugin file can accidentally trip
+ * OpenClaw's env-harvesting scanner rule (which fires on a per-file AND
+ * of `process.env` + a network trigger word). Keeping every env read in
+ * env-only files (`config.ts` + `entry.ts`) means the AND can never fire
+ * outside these two files, which perform no network I/O.
+ *
+ * Phase 1 scope (this file): expose pure env-reader primitives so the 7
+ * former env-reading modules (`batch-gate`, `consolidation`,
+ * `semantic-dedup`, `download-ux`, `fs-helpers`, `contradiction-sync`,
+ * `claims-helper`) can replace their direct `process.env.*` reads with
+ * imported helpers — keeping their per-call test-toggle semantics intact
+ * (the primitives read env at CALL time, not boot time).
+ *
+ * Phase 2 scope (future): this file becomes the
+ * `definePluginEntry({ register })` home — `register()` will move out of
+ * `index.ts` into here, giving the OpenClaw runtime a single native
+ * entry-point. The env-reader primitives stay; the register logic joins
+ * them.
+ *
+ * Hard contracts (enforced by entry-env.test.ts):
+ *   - This file ONLY reads `process.env.*`. No network. No disk I/O
+ *     beyond what `node:os` already does for the home dir.
+ *   - No outbound-network primitive token in this file's source.
+ */
+import os from 'node:os';
+// ---------------------------------------------------------------------------
+// Primitive env-readers — read at CALL time so tests can toggle env vars
+// between assertions without a module reload. Each helper centralizes one
+// shape (string, number, boolean, home-dir) so call sites stay terse.
+// ---------------------------------------------------------------------------
+/**
+ * Read a string env var. Returns the raw value if set and non-empty,
+ * otherwise the provided fallback. Never throws.
+ */
+export function envString(name, fallback = '') {
+    const v = process.env[name];
+    if (v === undefined || v === null)
+        return fallback;
+    return v;
+}
+/**
+ * Read a string env var and return the trimmed-lowercase form, or the
+ * fallback if unset/empty. Common shape for mode/flag env vars compared
+ * against literal strings like `'true'`, `'off'`, `'shadow'`.
+ */
+export function envStringLower(name, fallback = '') {
+    const v = process.env[name];
+    if (v === undefined || v === null || v === '')
+        return fallback;
+    return v.trim().toLowerCase();
+}
+/**
+ * Read a numeric env var with bounds checking. Returns `fallback` when
+ * the var is unset, empty, non-finite, or outside `[min, max]`.
+ *
+ * `kind` controls integer vs float parsing; defaults to float.
+ */
+export function envNumber(name, fallback, opts = {}) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === null || raw === '')
+        return fallback;
+    const parsed = opts.integer ? parseInt(raw, 10) : parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    if (opts.min !== undefined && parsed < opts.min)
+        return fallback;
+    if (opts.max !== undefined && parsed > opts.max)
+        return fallback;
+    return parsed;
+}
+/**
+ * Read a boolean env var. Returns `true` only when the raw value
+ * case-insensitively equals `truthy`; `false` otherwise (including
+ * unset). Mirrors the common `process.env.X === 'true'` shape.
+ */
+export function envBoolean(name, truthy = 'true') {
+    return process.env[name] === truthy;
+}
+/**
+ * Resolve the user home directory. Centralized so the fallback
+ * (`/home/node`) is consistent across every call site (mirrors
+ * `config.ts`'s own `home` derivation — kept independent so this file
+ * has no dependency on `config.ts`'s internal state).
+ */
+export function envHomeDir() {
+    return process.env.HOME ?? '/home/node';
+}
+/**
+ * Same as `envHomeDir` but prefers `os.homedir()` when `HOME` is unset
+ * — used by modules that historically called `os.homedir()` directly so
+ * behaviour is preserved exactly.
+ */
+export function envHomedir() {
+    const h = process.env.HOME;
+    if (h && h.length > 0)
+        return h;
+    return os.homedir();
+}
+// ---------------------------------------------------------------------------
+// Module-load-time reads — values that are documented as boot-only
+// (intentionally NOT re-read on each call). Imported by modules that need
+// a one-shot snapshot at load time.
+// ---------------------------------------------------------------------------
+/**
+ * Gnosis chain-batching kill-switch. Read ONCE at module load — the env
+ * does not change mid-process and per-call re-parsing is too expensive
+ * for the auto-extraction hot path. Spec #281 §9 Phase 1 (item imp-16).
+ *
+ * `false` (any case) disables batching on every chain; any other value
+ * (including unset) leaves it enabled.
+ */
+const GNOSIS_BATCH_ENABLED_AT_BOOT = envString('TOTALRECLAW_GNOSIS_BATCH_ENABLED').toLowerCase() !== 'false';
+export function isGnosisBatchEnabledAtBoot() {
+    return GNOSIS_BATCH_ENABLED_AT_BOOT;
+}

package/dist/extractor.js

@@ -729,6 +729,140 @@ export async function extractDebrief(rawMessages, storedFactTexts) {
     }
 }
 // ---------------------------------------------------------------------------
+// Crystal-shaped debrief (am-1) — one structured summary per session
+// ---------------------------------------------------------------------------
+const _CRYSTAL_COMMON_FIELDS = `Return a JSON object (no markdown, no code fences):
+{
+  "narrative": "1-2 sentence summary of what happened this session",
+  "key_outcomes": ["outcome or decision 1", "outcome or decision 2"],
+  "open_threads": ["unfinished item 1"],
+  "lessons": ["lesson or gotcha 1"],
+  "importance": 8
+}`;
+export const CRYSTAL_SYSTEM_PROMPT_CHAT = `You are crystallising a finished conversation into one structured session summary.
+
+The following facts were already extracted and stored during this conversation:
+{already_stored_facts}
+
+Write ONE Crystal that captures what turn-by-turn extraction missed. Include:
+- narrative: 1-2 sentences describing the conversation overall
+- key_outcomes: decisions made, problems solved, conclusions reached
+- open_threads: things left unfinished or needing follow-up
+- lessons: patterns, gotchas, or insights worth remembering
+- topics_discussed: the main subjects covered
+- importance: 7-10 (8 default)
+
+Do NOT repeat facts already stored. Return null for trivial or very short conversations.
+
+${_CRYSTAL_COMMON_FIELDS}
+
+Also include "topics_discussed": ["topic 1", "topic 2"] in the object.
+Return null (not an object) for trivial or very short conversations.`;
+export const CRYSTAL_SYSTEM_PROMPT_CODING = `You are crystallising a finished coding session into one structured session summary.
+
+The following facts were already extracted and stored during this conversation:
+{already_stored_facts}
+
+Write ONE Crystal that captures what turn-by-turn extraction missed. Include:
+- narrative: 1-2 sentences describing the session overall
+- key_outcomes: decisions made, bugs fixed, features built
+- open_threads: things left unfinished or needing follow-up
+- lessons: patterns, gotchas, or insights worth remembering
+- files_affected: file paths mentioned or worked on (extract from assistant messages)
+- importance: 7-10 (8 default)
+
+Do NOT repeat facts already stored. Return null for trivial or very short sessions.
+
+${_CRYSTAL_COMMON_FIELDS}
+
+Also include "files_affected": ["/path/to/file.ts", ...] in the object (may be []).
+Return null (not an object) for trivial or very short sessions.`;
+/** Parse an LLM Crystal response into a CrystalMetadata + narrative pair. */
+export function parseCrystalResponse(response, hostType = 'chat') {
+    let cleaned = response.trim();
+    if (cleaned.startsWith('```')) {
+        cleaned = cleaned.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '').trim();
+    }
+    if (cleaned.toLowerCase() === 'null' || cleaned === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null)
+        return null;
+    if (typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const d = parsed;
+    const narrative = typeof d.narrative === 'string' ? d.narrative.trim().slice(0, 512) : '';
+    if (narrative.length < 10)
+        return null;
+    const strList = (key) => {
+        const raw = d[key];
+        if (!Array.isArray(raw))
+            return [];
+        return raw.map((x) => String(x).trim()).filter((x) => x.length > 0).slice(0, 10);
+    };
+    let importance = typeof d.importance === 'number' ? d.importance : 8;
+    importance = Math.max(1, Math.min(10, Math.round(importance)));
+    const metadata = {
+        subtype: 'session_crystal',
+        key_outcomes: strList('key_outcomes'),
+        open_threads: strList('open_threads'),
+        lessons: strList('lessons'),
+    };
+    if (hostType === 'coding') {
+        metadata.files_affected = strList('files_affected');
+    }
+    else {
+        metadata.topics_discussed = strList('topics_discussed');
+    }
+    return { narrative, importance, metadata };
+}
+/**
+ * Extract a Crystal session summary using LLM.
+ *
+ * Returns null if LLM unavailable, session too short, or LLM returns null.
+ */
+export async function extractCrystal(rawMessages, storedFactTexts, hostType = 'coding') {
+    const config = resolveLLMConfig();
+    if (!config)
+        return null;
+    const parsed = rawMessages
+        .map(messageToText)
+        .filter((m) => m !== null);
+    if (parsed.length < 8)
+        return null;
+    const conversationText = truncateMessages(parsed, 12_000);
+    if (conversationText.length < 20)
+        return null;
+    const alreadyStored = storedFactTexts.length > 0
+        ? storedFactTexts.map((t) => `- ${t}`).join('\n')
+        : '(none)';
+    const promptTemplate = hostType === 'coding'
+        ? CRYSTAL_SYSTEM_PROMPT_CODING
+        : CRYSTAL_SYSTEM_PROMPT_CHAT;
+    const systemPrompt = promptTemplate.replace('{already_stored_facts}', alreadyStored);
+    try {
+        const response = await chatCompletion(config, [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: `Crystallise this session:\n\n${conversationText}` },
+        ], {
+            retry: { attempts: 3, baseDelayMs: 1000 },
+            timeoutMs: 30_000,
+        });
+        if (!response)
+            return null;
+        return parseCrystalResponse(response, hostType);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
 // v1 Taxonomy Extraction Pipeline (default as of plugin v3.0.0)
 //
 // Produces facts conforming to Memory Taxonomy v1 (6 types: claim,

package/dist/fs-helpers.js

@@ -28,6 +28,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { envHomeDir } from './entry.js';
 // ---------------------------------------------------------------------------
 // MEMORY.md header ensure
 // ---------------------------------------------------------------------------
@@ -82,8 +83,7 @@ export function ensureMemoryHeaderFile(workspace, header, markerSubstring = 'Tot
  *     covers the OpenClaw plugin sandbox case where the loaded module
  *     lives at `<pluginRoot>/dist/index.js` while `package.json` lives
  *     at `<pluginRoot>/package.json` (3.3.4-rc.1 fix — without this
- *     walk-up, the `.loaded.json` manifest gets `version=unknown` and
- *     all RC-gated logic that depends on the version string fails
+ *     walk-up, version-dependent logic gets `version=unknown` and fails
  *     silently in production OpenClaw deployments).
  *   - Returns the `version` field, or `null` on any I/O / parse error.
  *
@@ -471,157 +471,15 @@ export function wipePartialInstall(pluginRootDir) {
     }
 }
 // ---------------------------------------------------------------------------
-// Plugin load manifest (.loaded.json / .error.json) — 3.3.2-rc.1 #186
+// Plugin load manifest (.loaded.json / .error.json) — RETIRED Phase 3.4
 // ---------------------------------------------------------------------------
-/**
- * Filenames written into the plugin root dir at the end of register() and
- * (on failure) from the surrounding try/catch. The presence of `.loaded.json`
- * is the canonical filesystem signal that the plugin's register() body ran
- * to completion AND the SDK tool/route/hook registries received calls.
- *
- * Acceptance criteria (issue #186):
- *   - `cat ~/.openclaw/extensions/totalreclaw/.loaded.json` shows
- *     `{loadedAt, tools, version}` after every successful gateway start.
- *   - `cat ~/.openclaw/extensions/totalreclaw/.error.json` shows
- *     `{loadedAt, error, stack}` if register() threw.
- *   - Both are overwritten on each register() call so the agent can rely
- *     on the timestamp matching the most recent gateway start.
- *
- * Why these MUST be synchronous writes (same constraint as
- * `registerHttpRoute` per the comment in index.ts around the route
- * registration site): the SDK loader treats register() returning as the
- * signal to freeze the registries. An async `fs.promises.writeFile` would
- * settle one microtask AFTER the loader has moved on, so the manifest
- * could miss tools that registered late OR drop entirely if the gateway
- * exits before the microtask runs. `writeFileSync` is the only safe choice.
- */
-export const PLUGIN_LOADED_MANIFEST = '.loaded.json';
-export const PLUGIN_ERROR_MANIFEST = '.error.json';
-/**
- * Resolve the plugin root dir from the loaded module's directory. The plugin
- * is shipped with `dist/index.js` as the entry, so `import.meta.url` resolves
- * to `<root>/dist/`. We walk up one level to put the manifests next to
- * `package.json`. Defensive: if the caller already passed the root (no
- * trailing `dist`), we still return a sensible path.
- */
-function resolvePluginRootForManifest(pluginDir) {
-    const base = path.basename(pluginDir);
-    return base === 'dist' ? path.resolve(pluginDir, '..') : pluginDir;
-}
-/**
- * Write the success manifest. SYNCHRONOUS — the SDK freezes the plugin
- * registries the moment register() returns; `fs.promises.writeFile` would
- * race that freeze and the manifest could miss late tool registrations or
- * never land at all if the process exits before the microtask runs.
- *
- * Best-effort: returns `true` on success, `false` on any I/O error. Never
- * throws — failing to write the manifest is a diagnostic loss, not a
- * correctness loss, so we don't propagate.
- *
- * The manifest is written at mode 0644 (world-readable). It contains no
- * secrets — only a timestamp, the (publicly known) tool names, and the
- * plugin version. Cleared first so a stale `.error.json` from a previous
- * failed boot doesn't survive a successful boot.
- */
-/**
- * Read the existing `.loaded.json` manifest for diagnostic surfaces
- * (3.3.7-rc.1 — issue #216). Returns `null` if the manifest is
- * missing, unreadable, or malformed. Best-effort: never throws.
- *
- * Scanner note: this helper lives in fs-helpers.ts (where all fs.*
- * operations are consolidated) so the diagnostic slash command in
- * `index.ts` doesn't have to introduce a fresh `readFileSync` call —
- * the OpenClaw scanner whole-file rule disallows fs.read* next to the
- * outbound-request trigger markers that index.ts already has in its
- * on-chain submission code paths.
- */
-export function readPluginLoadedManifest(pluginDir) {
-    try {
-        const root = resolvePluginRootForManifest(pluginDir);
-        const loadedPath = path.join(root, PLUGIN_LOADED_MANIFEST);
-        if (!fs.existsSync(loadedPath))
-            return null;
-        const raw = fs.readFileSync(loadedPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.loadedAt !== 'number' || !Array.isArray(parsed.tools) || typeof parsed.version !== 'string') {
-            return null;
-        }
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-export function writePluginManifest(pluginDir, manifest) {
-    try {
-        const root = resolvePluginRootForManifest(pluginDir);
-        if (!fs.existsSync(root))
-            return false;
-        const loadedPath = path.join(root, PLUGIN_LOADED_MANIFEST);
-        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
-        // Best-effort error-file cleanup — a successful boot supersedes any
-        // prior failure marker. If the unlink fails (e.g. permission), the
-        // .loaded.json timestamp still tells the agent which is current.
-        try {
-            if (fs.existsSync(errorPath))
-                fs.unlinkSync(errorPath);
-        }
-        catch {
-            // Swallow — best-effort.
-        }
-        // 3.3.7-rc.1 (issue #216) — derive bootCount by reading the prior
-        // manifest. Lets the user grep `.loaded.json` after a container
-        // restart to verify register() actually ran. If the prior manifest
-        // is unreadable we start at 1.
-        let priorBootCount = 0;
-        try {
-            if (fs.existsSync(loadedPath)) {
-                const prior = JSON.parse(fs.readFileSync(loadedPath, 'utf-8'));
-                if (typeof prior.bootCount === 'number' && Number.isFinite(prior.bootCount)) {
-                    priorBootCount = prior.bootCount;
-                }
-            }
-        }
-        catch {
-            // Swallow — if the prior manifest is corrupt we just start the counter fresh.
-        }
-        const enriched = {
-            ...manifest,
-            bootCount: priorBootCount + 1,
-            bootAt: new Date(manifest.loadedAt).toISOString(),
-            pid: process.pid,
-        };
-        fs.writeFileSync(loadedPath, JSON.stringify(enriched, null, 2));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Write the error manifest. SYNCHRONOUS for the same reason as
- * `writePluginManifest`. Called from the try/catch surrounding the
- * register() body so the agent has a filesystem signal that the plugin
- * registered AT LEAST attempted to load and failed in a specific way.
- *
- * Does NOT clear `.loaded.json` from a prior successful boot — keeping
- * the older success marker around lets the agent see "last good boot was
- * X, current boot failed at Y" without spelunking logs. The newer
- * `.error.json` timestamp wins as "current state".
- */
-export function writePluginError(pluginDir, error) {
-    try {
-        const root = resolvePluginRootForManifest(pluginDir);
-        if (!fs.existsSync(root))
-            return false;
-        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
-        fs.writeFileSync(errorPath, JSON.stringify(error, null, 2));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+// The 3.3.2-rc.1 `.loaded.json` / `.error.json` manifest machinery (writer
+// + reader + schema) was fully removed in Phase 3.4. Phase 3.1 already
+// dropped the `writePluginManifest` call from register(); 3.4 retires the
+// remaining reader (`readPluginLoadedManifest`) + the error-path writer
+// (`writePluginError`) + the schema types now that no production path
+// references them. The gateway log is the source of truth for register()
+// failures; `/totalreclaw diag` reports pid + in-memory version only.
 /**
  * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
  * (overwrites any existing marker) and best-effort — returns `true` on
@@ -984,8 +842,11 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  * @param configPath  Absolute path to `openclaw.json`.
  *                    Defaults to `<home>/.openclaw/openclaw.json`.
  */
-export function patchOpenClawConfig(configPath) {
-    const home = process.env.HOME ?? '/home/node';
+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 = envHomeDir();
     const target = configPath ?? path.join(home, '.openclaw', 'openclaw.json');
     // `'skipped'` when the config file is absent — this host may not be
     // running OpenClaw, or may use a non-standard config location.
@@ -1000,6 +861,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
@@ -1126,3 +1046,51 @@ export function patchOpenClawConfig(configPath) {
         return 'error';
     }
 }
+const TMPFS_PREFIXES = ['/tmp/', '/dev/shm/', '/run/', '/var/run/'];
+export function checkCredentialsFileMode(credPath, logger) {
+    let stat;
+    try {
+        stat = fs.statSync(credPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return 'ok';
+        logger.warn(`TotalReclaw: could not stat credentials file (${code ?? String(err)}); skipping permission check`);
+        return 'stat_error';
+    }
+    const mode = stat.mode & 0o777;
+    if (mode > 0o600) {
+        const modeStr = '0' + mode.toString(8);
+        logger.error(`TotalReclaw: STARTUP REFUSED — credentials file has insecure permissions (${modeStr}).\n` +
+            `  File: ${credPath}\n` +
+            `  Fix:  chmod 600 "${credPath}"\n` +
+            `  Then restart your OpenClaw gateway.\n` +
+            `  Current mode ${modeStr} allows other OS users to read your recovery phrase.`);
+        return 'insecure';
+    }
+    try {
+        const real = fs.realpathSync(credPath);
+        for (const prefix of TMPFS_PREFIXES) {
+            if (real.startsWith(prefix)) {
+                logger.warn(`TotalReclaw: credentials file is on a volatile/shared path (${real}). ` +
+                    `It may be lost on reboot or be readable by other processes. ` +
+                    `Consider moving it to a persistent private directory and updating TOTALRECLAW_CREDENTIALS_PATH.`);
+                return 'warned';
+            }
+        }
+    }
+    catch {
+        // realpathSync can fail on unusual mounts — not actionable here
+    }
+    return 'ok';
+}
+// ---------------------------------------------------------------------------
+// Pair-pending sentinel — RETIRED Phase 3.4
+// ---------------------------------------------------------------------------
+// The 3.3.13 `~/.totalreclaw/.pair-pending.json` sentinel + its utilities
+// (loadPairPendingFile / writePairPendingFile / deletePairPendingFile /
+// defaultPairPendingPath / PairPendingFile) were removed in Phase 3.4.
+// Pairing is now user-initiated QR (`tr pair` CLI / the pair HTTP route)
+// per the native-integration design — the auto-pair-on-load state machine
+// that wrote + consumed this sentinel is gone.

package/dist/import-adapters/chatgpt-adapter.js

@@ -17,6 +17,20 @@ export class ChatGPTAdapter extends BaseImportAdapter {
         else if (input.file_path) {
             try {
                 const resolvedPath = input.file_path.replace(/^~/, os.homedir());
+                const fileStat = fs.statSync(resolvedPath);
+                const fileSizeMB = fileStat.size / (1024 * 1024);
+                if (fileSizeMB > 500) {
+                    errors.push(`File is too large to import: ${fileSizeMB.toFixed(1)}MB exceeds the 500MB cap. ` +
+                        'Split the file into smaller chunks and import each separately.');
+                    return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+                }
+                const freeMem = os.freemem();
+                if (freeMem < fileStat.size * 2) {
+                    errors.push(`Not enough free memory: ${(freeMem / (1024 * 1024)).toFixed(0)}MB available, ` +
+                        `~${Math.ceil(fileStat.size * 2 / (1024 * 1024))}MB needed (2× file size). ` +
+                        'Close other applications or split the file.');
+                    return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+                }
                 content = fs.readFileSync(resolvedPath, 'utf-8');
             }
             catch (e) {

package/dist/import-adapters/claude-adapter.js

@@ -29,6 +29,20 @@ export class ClaudeAdapter extends BaseImportAdapter {
         else if (input.file_path) {
             try {
                 const resolvedPath = input.file_path.replace(/^~/, os.homedir());
+                const fileStat = fs.statSync(resolvedPath);
+                const fileSizeMB = fileStat.size / (1024 * 1024);
+                if (fileSizeMB > 500) {
+                    errors.push(`File is too large to import: ${fileSizeMB.toFixed(1)}MB exceeds the 500MB cap. ` +
+                        'Split the file into smaller chunks and import each separately.');
+                    return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+                }
+                const freeMem = os.freemem();
+                if (freeMem < fileStat.size * 2) {
+                    errors.push(`Not enough free memory: ${(freeMem / (1024 * 1024)).toFixed(0)}MB available, ` +
+                        `~${Math.ceil(fileStat.size * 2 / (1024 * 1024))}MB needed (2× file size). ` +
+                        'Close other applications or split the file.');
+                    return { facts: [], chunks: [], totalMessages: 0, warnings, errors };
+                }
                 content = fs.readFileSync(resolvedPath, 'utf-8');
             }
             catch (e) {