@totalreclaw/totalreclaw 3.3.12-rc.9 → 3.3.12

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
@@ -933,14 +791,11 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  * 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`
@@ -954,15 +809,11 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  *      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
  * ------------------
@@ -985,10 +836,10 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  *                    Defaults to `<home>/.openclaw/openclaw.json`.
  */
 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).
+// 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) {
-    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
     // running OpenClaw, or may use a non-standard config location.
@@ -1003,109 +854,44 @@ pluginVersion) {
             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`.
+        // --- Fix #6 (installs self-heal) RETIRED in rc.20 (#402) ---
         //
-        // 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" ---
+        // 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) ---
         //
-        // 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.
+        // 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) ---
         //
-        // 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
-        // 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
-        //
-        //   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.
-        //
-        // 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.
-        //
-        // 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) {
             cfg.plugins.entries = {};
@@ -1148,36 +934,15 @@ pluginVersion) {
                 }
             }
         }
-        // --- Fix #4: plugins.bundledDiscovery = "compat" (3.3.11-rc.4) ---
-        //
-        // 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 #4 (plugins.bundledDiscovery="compat") RETIRED in rc.20 (#402) ---
         //
-        // 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';
         // Write back with 2-space indent to match OpenClaw's own write style.
@@ -1227,81 +992,12 @@ export function checkCredentialsFileMode(credPath, logger) {
     }
     return 'ok';
 }
-/**
- * Load `.pair-pending.json` if it exists and parses. Returns null on
- * missing-file, corrupt JSON, or unknown schema version. Never throws.
- */
-export function loadPairPendingFile(pendingPath) {
-    try {
-        if (!fs.existsSync(pendingPath))
-            return null;
-        const raw = fs.readFileSync(pendingPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (parsed.v !== 1)
-            return null;
-        if (typeof parsed.url !== 'string' || !parsed.url)
-            return null;
-        if (typeof parsed.pin !== 'string' || !parsed.pin)
-            return null;
-        if (typeof parsed.sid !== 'string' || !parsed.sid)
-            return null;
-        if (typeof parsed.expires_at_ms !== 'number')
-            return null;
-        if (typeof parsed.created_at_ms !== 'number')
-            return null;
-        if (parsed.mode !== 'generate'
-            && parsed.mode !== 'import'
-            && parsed.mode !== 'either')
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Write `.pair-pending.json` atomically-ish (single `writeFileSync`). Creates
- * the parent directory if missing. Uses mode `0o600` to match credentials.json
- * even though the contents are NOT secret (URL + PIN are surfaced to chat
- * anyway) — defensive default for the .totalreclaw/ dir.
- *
- * Returns `true` on success, `false` on any I/O error.
- */
-export function writePairPendingFile(pendingPath, payload) {
-    try {
-        const dir = path.dirname(pendingPath);
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(pendingPath, JSON.stringify(payload), { mode: 0o600 });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Delete the pair-pending sentinel. Used by:
- *   - the pair-completion path (after credentials.json is finalized)
- *   - the auto-pair flow when it detects an expired pending session
- *
- * Returns `true` if a file was deleted, `false` otherwise (no file or error).
- */
-export function deletePairPendingFile(pendingPath) {
-    try {
-        if (!fs.existsSync(pendingPath))
-            return false;
-        fs.unlinkSync(pendingPath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Default `.pair-pending.json` path derived from a credentials.json path:
- * the sentinel lives in the same directory under the dot-prefixed name.
- * Callers MAY pass an explicit path (tests, custom layouts) instead.
- */
-export function defaultPairPendingPath(credentialsPath) {
-    return path.join(path.dirname(credentialsPath), '.pair-pending.json');
-}
+// ---------------------------------------------------------------------------
+// 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.