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

package/fs-helpers.ts

@@ -29,6 +29,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { envHomeDir } from './entry.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -132,8 +133,7 @@ export function ensureMemoryHeaderFile(
  *     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.
  *
@@ -544,208 +544,15 @@ export function wipePartialInstall(pluginRootDir: string): boolean {
 }
 
 // ---------------------------------------------------------------------------
-// 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';
-
-/** Schema written to `.loaded.json` — see PLUGIN_LOADED_MANIFEST. */
-export interface PluginLoadManifest {
-  /** Unix epoch milliseconds when register() finished. */
-  loadedAt: number;
-  /** Tool names passed to api.registerTool() during register(). */
-  tools: string[];
-  /** Plugin version string from package.json (or "unknown"). */
-  version: string;
-  /**
-   * 3.3.7-rc.1 (issue #216) — incremented every time register() completes.
-   * Container restart that successfully re-runs register() should bump this.
-   * If a user reports tools missing after-a-restart but bootCount is still N,
-   * the plugin's register() was NOT called on boot (separate root cause
-   * from "register ran but tools didn't bind to active session").
-   */
-  bootCount?: number;
-  /** ISO timestamp of the most recent boot — easier to read than `loadedAt`. */
-  bootAt?: string;
-  /** PID of the gateway process that wrote this manifest. Lets the user
-   * verify the manifest is from the currently-running container vs a
-   * stale-mounted copy. */
-  pid?: number;
-  /**
-   * 3.3.8-rc.1 — true when registerTool() calls are no-op'd due to the
-   * OC 2026.5.2 issue #223 hybrid workaround. Tools in `tools[]` are
-   * exposed via the `tr` CLI binary instead of via the plugin API.
-   */
-  hybridMode?: boolean;
-  /**
-   * 3.3.8-rc.1 — CLI commands that replace the tool registrations
-   * when hybridMode=true. Agent runs these from shell instead of using
-   * tool calls.
-   */
-  hybridCliTools?: string[];
-}
-
-/** Schema written to `.error.json` when register() throws. */
-export interface PluginLoadError {
-  loadedAt: number;
-  error: string;
-  stack?: string;
-  version?: string;
-}
-
-/**
- * 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: string): string {
-  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: string,
-): PluginLoadManifest | null {
-  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) as Partial<PluginLoadManifest>;
-    if (typeof parsed.loadedAt !== 'number' || !Array.isArray(parsed.tools) || typeof parsed.version !== 'string') {
-      return null;
-    }
-    return parsed as PluginLoadManifest;
-  } catch {
-    return null;
-  }
-}
-
-export function writePluginManifest(
-  pluginDir: string,
-  manifest: PluginLoadManifest,
-): boolean {
-  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')) as Partial<PluginLoadManifest>;
-        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: PluginLoadManifest = {
-      ...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: string,
-  error: PluginLoadError,
-): boolean {
-  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
@@ -1130,6 +937,24 @@ export function resolveOnboardingState(
 // ---------------------------------------------------------------------------
 // OpenClaw 2026.5.x config auto-patch (3.3.9-rc.2 — issues #225 + #226)
 // ---------------------------------------------------------------------------
+//
+// Phase 3.4 note (2026-06-22): this is the minimal idempotent slot-ensure
+// that survives the config-patch state-machine retirement. The auto-pair-
+// on-load + .pair-pending.json + SIGUSR1-for-pair dance was retired because
+// pairing is now user-initiated QR. `patchOpenClawConfig` itself was NEVER
+// part of the auto-pair state machine — it applies OpenClaw 2026.5.x
+// compatibility keys (hook access, telegram streaming) and is idempotent
+// (returns `'unchanged'` when all keys are already correct). Its only caller
+// is register() in index.ts; the SIGUSR1 emitted on `'patched'` is the
+// "restart-so-the-new-keys-take-effect-this-boot" signal, NOT a pair signal.
+//
+// Retired in rc.20 (#402): the memory-slot write (formerly Fix #1), the
+// install-record self-heal (formerly Fix #6), and the plugins.allow self-append
+// + bundledDiscovery="compat" pair (formerly Fix #5 + Fix #4). OpenClaw 2026.6.8
+// claims the memory slot natively on `plugins install`/`enable`, manages the
+// allowlist itself, and discards the whole installs map if any entry fails
+// schema validation — so this helper no longer touches `plugins.slots.memory`,
+// `plugins.installs`, `plugins.allow`, or `plugins.bundledDiscovery`.
 
 /**
  * Outcome of `patchOpenClawConfig`.
@@ -1149,14 +974,11 @@ export type OpenClawConfigPatchResult = 'patched' | 'unchanged' | 'skipped' | 'e
  * Auto-patch `~/.openclaw/openclaw.json` with the entries required by
  * OpenClaw 2026.5.x for clean operation (issues #225 + #226 + verbosity):
  *
- *   1. `plugins.slots.memory = "totalreclaw"` (gated on install record)
- *      Claim the memory slot so the plugin loads instead of deferring to
- *      the built-in `memory-core` tenant. As of 3.3.9-rc.4 this fix is
- *      gated on `plugins.installs.totalreclaw.version` being present —
- *      writing the slot without an install record produces a startup
- *      crash loop ("plugins.slots.memory: plugin not found: totalreclaw")
- *      that survives container restarts until `openclaw plugins install`
- *      repopulates the install record.
+ *   NOTE (rc.20, #402): this helper no longer writes `plugins.slots.memory`
+ *   (OpenClaw 2026.6.8 claims the memory slot natively on install/enable) nor
+ *   `plugins.installs` (the former Fix #6 self-heal — its record reader
+ *   discards the whole installs map if any entry fails schema validation).
+ *   Pre-existing values of both are left untouched. The remaining fixes are:
  *
  *   2. `plugins.entries.totalreclaw.hooks.allowConversationAccess = true`
  *      Grant the plugin access to `agent_end` and `before_agent_start`
@@ -1170,15 +992,11 @@ export type OpenClawConfigPatchResult = 'patched' | 'unchanged' | 'skipped' | 'e
  *      this to "off" on first run for a clean UX. Existing explicit values
  *      ("partial", "block", "progress") are preserved.
  *
- *   4. `plugins.bundledDiscovery = "compat"` (only if unset, and only when
- *      `plugins.allow` is populated). When `plugins.allow` is a non-empty
- *      array, OpenClaw 2026.5.x switches the loader into strict-allowlist
- *      mode and silently rejects non-bundled plugins like totalreclaw —
- *      EVEN IF they are listed in the allow array. Setting
- *      `bundledDiscovery: "compat"` restores the looser behavior so allow-
- *      listed non-bundled plugins load. Without this fix, users with
- *      telegram or any model provider configured before TR install (which
- *      populates allow) get a silent plugin-skip on every gateway boot.
+ *   Fix #4 (`plugins.bundledDiscovery="compat"`) and Fix #5 (appending
+ *   "totalreclaw" to `plugins.allow`) were RETIRED together in rc.20 (#402):
+ *   native install manages the allowlist, and TR growing it was the only
+ *   thing that forced strict-allowlist mode (the sole reason the compat
+ *   workaround existed). Pre-existing values of both keys are left untouched.
  *
  * Design constraints
  * ------------------
@@ -1202,8 +1020,11 @@ export type OpenClawConfigPatchResult = 'patched' | 'unchanged' | 'skipped' | 'e
  */
 export function patchOpenClawConfig(
   configPath?: string,
+  // Retained on the signature (register() passes it) but no longer consumed:
+  // the Fix #6 install-record self-heal it fed was retired in rc.20 (#402).
+  pluginVersion?: string,
 ): OpenClawConfigPatchResult {
-  const home = process.env.HOME ?? '/home/node';
+  const home = envHomeDir();
   const target = configPath ?? path.join(home, '.openclaw', 'openclaw.json');
 
   // `'skipped'` when the config file is absent — this host may not be
@@ -1222,51 +1043,46 @@ export function patchOpenClawConfig(
 
     let mutated = false;
 
-    // --- Fix #1: plugins.slots.memory = "totalreclaw" (gated on install) ---
-    //
-    // DEFENSIVE GATE (3.3.9-rc.4 — 2026-05-05): only write the slot when
-    // the plugin is genuinely INSTALLED (`plugins.installs.totalreclaw`
-    // present with a `version`). Writing the slot unconditionally
-    // produced a startup crash loop on Pedro's pop-os QA host on
-    // 2026-05-05 — after a config reset, `plugins.installs.totalreclaw`
-    // was missing but a previously-written `slots.memory = "totalreclaw"`
-    // had survived. OpenClaw's startup validator refuses to start with
+    // --- Fix #6 (installs self-heal) RETIRED in rc.20 (#402) ---
     //
-    //   Gateway failed to start: Error: Invalid config at openclaw.json.
-    //   plugins.slots.memory: plugin not found: totalreclaw
-    //   Run "openclaw doctor --fix" to repair, then retry.
+    // patchOpenClawConfig used to fabricate a `plugins.installs.totalreclaw`
+    // record (version/spec/source:"self-heal"/installedAt) whenever a version
+    // was passed and no record existed. Removed because it was inert at best
+    // and harmful at worst on OpenClaw 2026.6.8:
+    //   (a) the record reader validates the WHOLE installs map against a
+    //       schema where `source` must be a valid PluginInstallSource — the
+    //       fabricated `source:"self-heal"` (and any source-less record) fails
+    //       safeParse, discarding the ENTIRE installs map at load; and
+    //   (b) the native installer never persists install records into
+    //       openclaw.json (it strips them via withoutPluginInstallRecords and
+    //       commits to the SQLite index, which always wins on merge).
+    // So the plugin no longer writes `plugins.installs` at all; a pre-existing
+    // record is left byte-identical. `pluginVersion` is retained on the
+    // signature (register() passes it) but is no longer consumed here.
+    void pluginVersion;
+
+    // --- Fix #5 (plugins.allow self-append) RETIRED in rc.20 (#402) ---
     //
-    // The container restart-loop drained ~13 attempts (12:10-12:23 UTC)
-    // until `openclaw plugins install` was re-run and re-populated
-    // `plugins.installs.totalreclaw`. With this gate, future installs
-    // that wipe `plugins.installs` (config reset, `doctor --fix`,
-    // migration tools) cannot regress into the same boot loop — slot is
-    // only ever written when the install record exists, and the install
-    // record is the install pipeline's authoritative signal that the
-    // plugin is on disk and registered with the gateway.
+    // patchOpenClawConfig used to append "totalreclaw" to a non-empty
+    // `plugins.allow`. Removed as a pair with Fix #4 (below): OpenClaw's native
+    // `persistPluginInstall` already calls `addInstalledPluginToAllowlist`, and
+    // an empty/absent allowlist means allow-all (no write needed). TR
+    // unconditionally growing an allowlist was the very thing that flipped
+    // hosts into strict-allowlist enforcement — which then required the Fix #4
+    // `bundledDiscovery:"compat"` workaround. Dropping both lets native install
+    // own the allowlist; existing hosts keep whatever is already on disk.
+
+    // --- Fix #1 (memory-slot write) RETIRED in rc.20 (#402) ---
     //
-    // The hooks patch (Fix #2) and Telegram streaming patch (Fix #3) are
-    // not gated this way — they write under `plugins.entries` and
-    // `channels` which are inert without an install record, so they can
-    // never trip the validator.
-    const installsRoot = cfg.plugins.installs;
-    const installEntry = typeof installsRoot === 'object' && installsRoot !== null
-      ? installsRoot.totalreclaw
-      : undefined;
-    const pluginIsInstalled = typeof installEntry === 'object'
-      && installEntry !== null
-      && typeof installEntry.version === 'string'
-      && installEntry.version.length > 0;
-
-    if (pluginIsInstalled) {
-      if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
-        cfg.plugins.slots = {};
-      }
-      if (cfg.plugins.slots.memory !== 'totalreclaw') {
-        cfg.plugins.slots.memory = 'totalreclaw';
-        mutated = true;
-      }
-    }
+    // patchOpenClawConfig used to write `plugins.slots.memory = "totalreclaw"`
+    // (install-gated, to dodge a startup crash loop). OpenClaw 2026.6.8 now
+    // claims the memory slot NATIVELY during `plugins install`/`enable` (its
+    // persistPluginInstall "slot selection" phase), so the hand-written write
+    // was redundant on the good path and twice failed in production. The
+    // plugin no longer touches the memory slot — a pre-existing value is left
+    // byte-identical. Fix numbering below is preserved for continuity with the
+    // #225/#226 history. The Fix #6 install-record self-heal was retired
+    // above too (rc.20, #402).
 
     // --- Fix #2: plugins.entries.totalreclaw.hooks.allowConversationAccess = true ---
     if (typeof cfg.plugins.entries !== 'object' || cfg.plugins.entries === null) {
@@ -1311,36 +1127,15 @@ export function patchOpenClawConfig(
       }
     }
 
-    // --- Fix #4: plugins.bundledDiscovery = "compat" (3.3.11-rc.4) ---
+    // --- Fix #4 (plugins.bundledDiscovery="compat") RETIRED in rc.20 (#402) ---
     //
-    // OpenClaw 2026.5.x: when `plugins.allow` is populated (any non-empty
-    // array), the gateway's plugin loader switches into strict-allowlist
-    // mode. In strict mode, NON-BUNDLED plugins like totalreclaw are
-    // silently rejected even when listed in `plugins.allow`, unless
-    // `plugins.bundledDiscovery = "compat"` is explicitly set. Pedro's
-    // 2026-05-07 QA on pop-os surfaced this — the gateway booted with only
-    // the bundled providers (telegram, device-pair) and skipped totalreclaw
-    // despite it being in the allow list. `openclaw doctor --fix` cures it
-    // by setting `bundledDiscovery: "compat"`, but users shouldn't need
-    // to run doctor manually for the plugin to load.
-    //
-    // Fix: when `plugins.allow` is a non-empty array AND
-    // `plugins.bundledDiscovery` is unset, set it to "compat". If the user
-    // explicitly chose "allowlist" (the stricter mode), preserve their
-    // choice — only first-run defaults are touched.
-    //
-    // This bug was missed by the auto-QA harness because the harness ran
-    // on a fresh canonical container with `plugins.allow=null`, hitting
-    // the auto-discover code path. Real users with telegram + a model
-    // provider configured before TR install have a populated allow list,
-    // hitting the strict-mode path. The auto-QA harness in 3.3.11-rc.4
-    // adds a populated-allow scenario to catch future regressions.
-    if (Array.isArray(cfg.plugins.allow) && cfg.plugins.allow.length > 0) {
-      if (cfg.plugins.bundledDiscovery === undefined) {
-        cfg.plugins.bundledDiscovery = 'compat';
-        mutated = true;
-      }
-    }
+    // patchOpenClawConfig used to set `plugins.bundledDiscovery = "compat"`
+    // whenever `plugins.allow` was populated, to keep non-bundled totalreclaw
+    // loadable under strict-allowlist mode. Retired as a pair with Fix #5: the
+    // ONLY reason a host was in strict-allowlist mode was that TR itself grew
+    // the allowlist (Fix #5). With Fix #5 gone, native install manages the
+    // allowlist and this compat workaround is unnecessary. An existing
+    // `bundledDiscovery` value on disk is left untouched.
 
     if (!mutated) return 'unchanged';
 
@@ -1351,3 +1146,82 @@ export function patchOpenClawConfig(
     return 'error';
   }
 }
+
+// ---------------------------------------------------------------------------
+// Credentials file permission check (cred-1 security hardening)
+// ---------------------------------------------------------------------------
+
+/** Subset of the OpenClaw logger used by the permission check. */
+export interface PermissionCheckLogger {
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+/**
+ * Result of `checkCredentialsFileMode`.
+ *
+ * - `'ok'` — file absent (not yet created) or permissions are exactly 0600.
+ * - `'insecure'` — file present with mode broader than 0600; caller must refuse to continue.
+ * - `'warned'` — file is 0600 but lives on a tmpfs / shared-volume path; logged.
+ * - `'stat_error'` — `fs.statSync` failed for an unexpected reason; caller should warn + continue.
+ */
+export type CredentialsPermissionResult = 'ok' | 'insecure' | 'warned' | 'stat_error';
+
+const TMPFS_PREFIXES = ['/tmp/', '/dev/shm/', '/run/', '/var/run/'];
+
+export function checkCredentialsFileMode(
+  credPath: string,
+  logger: PermissionCheckLogger,
+): CredentialsPermissionResult {
+  let stat: fs.Stats;
+  try {
+    stat = fs.statSync(credPath);
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).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/import-adapters/chatgpt-adapter.ts

@@ -59,6 +59,24 @@ 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) {
         errors.push(`Failed to read file: ${e instanceof Error ? e.message : 'Unknown error'}`);

package/import-adapters/claude-adapter.ts

@@ -45,6 +45,24 @@ 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) {
         errors.push(`Failed to read file: ${e instanceof Error ? e.message : 'Unknown error'}`);