dexbot 1.4.19 → 1.4.21

package/claw/modules/claw_launcher.ts

@@ -56,6 +56,40 @@ function getSpawn(): any {
     return _spawn;
 }
 
+/**
+ * Spawn a detached background child and wait for the spawn itself to succeed.
+ * Spawn failures (missing script, ENOENT, EACCES) are reported asynchronously
+ * via the child's 'error' event; waiting one macrotask lets those surface as a
+ * thrown error instead of callers receiving a false { started: true } result.
+ * A permanent 'error' handler remains attached so late errors are logged
+ * rather than crashing the host with an unhandled 'error' event.
+ */
+function spawnDetached(scriptPath: string, args: string[], cwd: string): Promise<any> {
+    const child = getSpawn()('node', [scriptPath, ...args], {
+        detached: true,
+        stdio: 'ignore',
+        cwd
+    });
+
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        child.on('error', (err: any) => {
+            if (!settled) {
+                settled = true;
+                reject(new Error(`Failed to spawn ${scriptPath}: ${getErrorMessage(err)}`));
+                return;
+            }
+            console.error(`[LAUNCHER] Child process error (${scriptPath}): ${getErrorMessage(err)}`);
+        });
+        setImmediate(() => {
+            if (!settled) {
+                settled = true;
+                resolve(child);
+            }
+        });
+    });
+}
+
 let _pm2: any;
 function getPM2Module(): any {
     if (_pm2 === undefined) {
@@ -88,16 +122,7 @@ async function launcherStart(botName: string | null, options: Record<string, any
     args.push(botName);
   }
 
-  const child = getSpawn()('node', [dexbotPath, ...args], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: ROOT
-  });
-
-  child.on('error', (err: any) => {
-    console.error(`[LAUNCHER] Failed to spawn ${dexbotPath}: ${getErrorMessage(err)}`);
-  });
-
+  const child = await spawnDetached(dexbotPath, args, ROOT);
   child.unref();
 
   return {
@@ -124,16 +149,7 @@ async function launcherDrystart(botName: string | null, options: Record<string,
     args.push(botName);
   }
 
-  const child = getSpawn()('node', [dexbotPath, ...args], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: ROOT
-  });
-
-  child.on('error', (err: any) => {
-    console.error(`[LAUNCHER] Failed to spawn ${dexbotPath}: ${getErrorMessage(err)}`);
-  });
-
+  const child = await spawnDetached(dexbotPath, args, ROOT);
   child.unref();
 
   return {
@@ -158,10 +174,10 @@ async function launcherReset(botName: string | null, options: Record<string, any
   const { config } = loadSettingsFile(PROFILES_BOTS_FILE);
   const entries = normalizeBotEntries(resolveRawBotEntries(config));
 
-  const targets = botName ? entries.filter((b: any) => b.name === botName) : entries.filter((b: any) => b.active);
+  const targets = botName ? entries.filter((b: any) => b.name === botName) : entries.filter((b: any) => b.active !== false);
 
   if (botName && targets.length === 0) {
-    throw new Error(`Bot '${botName}' not found in profiles/bots.json`);
+    throw new Error(`Bot '${botName}' not found in ${PROFILES_BOTS_FILE}`);
   }
 
   const triggered: Array<Record<string, any>> = [];
@@ -221,7 +237,7 @@ async function launcherDisable(botName: string | null, options: Record<string, a
 
   const match = entries.find((b: any) => b.name === botName);
   if (!match) {
-    throw new Error(`Bot '${botName}' not found in profiles/bots.json`);
+    throw new Error(`Bot '${botName}' not found in ${PROFILES_BOTS_FILE}`);
   }
 
   if (match.active === false) {
@@ -252,10 +268,10 @@ async function launcherPm2Start(botName: string | null, options: Record<string,
   const { config } = loadSettingsFile(PROFILES_BOTS_FILE);
   const entries = normalizeBotEntries(resolveRawBotEntries(config));
 
-  const targets = botName ? entries.filter((b: any) => b.name === botName) : entries.filter((b: any) => b.active);
+  const targets = botName ? entries.filter((b: any) => b.name === botName) : entries.filter((b: any) => b.active !== false);
 
   if (botName && targets.length === 0) {
-    throw new Error(`Bot '${botName}' not found or not active in profiles/bots.json`);
+    throw new Error(`Bot '${botName}' not found or not active in ${PROFILES_BOTS_FILE}`);
   }
 
   // Then check if daemon is ready
@@ -292,7 +308,7 @@ async function launcherPm2Start(botName: string | null, options: Record<string,
  * @param {Object} [options={}] - Options
  * @returns {Promise<Object>} { stopped: true, target }
  */
-async function launcherPm2Stop(target: string, options: Record<string, any> = {}) {
+async function launcherPm2Stop(target: string, _options: Record<string, any> = {}) {
   await getPM2Module().stopPM2Processes(target || 'all');
   return {
     stopped: true,
@@ -306,7 +322,7 @@ async function launcherPm2Stop(target: string, options: Record<string, any> = {}
  * @param {Object} [options={}] - Options
  * @returns {Promise<Object>} { deleted: true, target }
  */
-async function launcherPm2Delete(target: string, options: Record<string, any> = {}) {
+async function launcherPm2Delete(target: string, _options: Record<string, any> = {}) {
   await getPM2Module().deletePM2Processes(target || 'all');
   return {
     deleted: true,
@@ -320,7 +336,7 @@ async function launcherPm2Delete(target: string, options: Record<string, any> =
  * @param {Object} [options={}] - Options
  * @returns {Promise<Object>} { restarted: true, target }
  */
-async function launcherPm2Restart(target: string, options: Record<string, any> = {}) {
+async function launcherPm2Restart(target: string, _options: Record<string, any> = {}) {
   await getPM2Module().restartPM2Processes(target || 'all');
   return {
     restarted: true,
@@ -422,16 +438,7 @@ async function launcherClawOnly(options: Record<string, any> = {}) {
   const ROOT = normalizeRoot(options);
   const pm2ScriptPath = resolveRuntimeScript(ROOT, 'pm2.js');
 
-  const child = getSpawn()('node', [pm2ScriptPath, 'claw-only'], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: ROOT
-  });
-
-  child.on('error', (err: any) => {
-    console.error(`[LAUNCHER] Failed to spawn ${pm2ScriptPath}: ${getErrorMessage(err)}`);
-  });
-
+  const child = await spawnDetached(pm2ScriptPath, ['claw-only'], ROOT);
   child.unref();
 
   return {
@@ -459,16 +466,7 @@ async function launcherUnlockStart(botName: string | null, options: Record<strin
     args.push(botName);
   }
 
-  const child = getSpawn()('node', [unlockPath, ...args], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: ROOT
-  });
-
-  child.on('error', (err: any) => {
-    console.error(`[LAUNCHER] Failed to spawn ${unlockPath}: ${getErrorMessage(err)}`);
-  });
-
+  const child = await spawnDetached(unlockPath, args, ROOT);
   child.unref();
 
   return {
@@ -481,5 +479,5 @@ async function launcherUnlockStart(botName: string | null, options: Record<strin
   };
 }
 
-export { launcherRun, launcherStart, launcherDrystart, launcherReset, launcherDisable, launcherPm2Start, launcherPm2Stop, launcherPm2Delete, launcherPm2Restart }
+export { launcherRun, launcherDrystart, launcherReset, launcherDisable, launcherPm2Start, launcherPm2Stop, launcherPm2Delete, launcherPm2Restart }
 

package/claw/modules/claw_skill_md.ts

@@ -11,14 +11,15 @@ function normalizeClawRepoRoot(repoRoot: string) {
   return normalizeRepoRoot(repoRoot);
 }
 
-// Generated docs must reference scripts that actually exist. Prefer the built
-// .js (dist layout); fall back to the .ts source run through tsx.
+// Generated docs must reference scripts that actually exist. Claw tooling
+// lives in claw/scripts/ (shipped as source); prefer a compiled sibling when
+// present, otherwise fall back to the .ts source run through tsx.
 function resolveScriptInvocation(repoRoot: string, name: string) {
-  const jsPath = path.join(repoRoot, 'scripts', `${name}.js`);
+  const jsPath = path.join(repoRoot, 'claw', 'scripts', `${name}.js`);
   if (storage.exists(jsPath)) {
     return { command: 'node', script: jsPath };
   }
-  return { command: 'npx tsx', script: path.join(repoRoot, 'scripts', `${name}.ts`) };
+  return { command: 'npx tsx', script: path.join(repoRoot, 'claw', 'scripts', `${name}.ts`) };
 }
 
 function buildBridgeInvocation(repoRoot: string, profileRoot: string, command: string, extraArgs: any[] = []) {
@@ -208,7 +209,7 @@ function buildRuntimeSetup(runtime: any, repoRoot: string, profileRoot: string)
         'Start the memU MCP server:',
         '',
         '```bash',
-        `tsx ${path.join(repoRoot, 'scripts', 'memu_mcp_server.ts').replace(/\\/g, '/')} --memu-dir ${PATHS.CLAW.MEMU_DIR.replace(/\\/g, '/')}`,
+        `tsx ${path.join(repoRoot, 'claw', 'scripts', 'memu_mcp_server.ts').replace(/\\/g, '/')} --memu-dir ${PATHS.CLAW.MEMU_DIR.replace(/\\/g, '/')}`,
         '```',
         '',
         'Or use the npm script:',
@@ -236,20 +237,17 @@ function buildRuntimeSetup(runtime: any, repoRoot: string, profileRoot: string)
 }
 
 function buildRuntimeWorkflow(runtime: any) {
-  if (runtime.runtime === 'hermes') {
-    return [
-      '- Start with `claw_manifest`, `claw_runtime`, `claw_profile_context`, `claw_market_snapshot`, `claw_account_snapshot`, or `claw_open_orders`.',
-      '- For MPA and short workflows, use `claw_build_open_short_plan`, `claw_build_take_profit_plan`, or `claw_build_close_short_plan` before executing trades.',
-      '- Use `claw_honest_context`, `claw_honest_pair`, and `claw_honest_price` when the task involves HONEST assets or discovery.',
-      '- The shared Claw MCP server registers raw tool ids such as `claw_manifest`; if Hermes shows a namespaced label in its UI, follow the label shown there.'
-    ].join('\n');
-  }
-
-  return [
+  const baseLines = [
     '- Start with `claw_manifest`, `claw_runtime`, `claw_profile_context`, `claw_market_snapshot`, `claw_account_snapshot`, or `claw_open_orders`.',
     '- For MPA and short workflows, use `claw_build_open_short_plan`, `claw_build_take_profit_plan`, or `claw_build_close_short_plan` before executing trades.',
     '- Use `claw_honest_context`, `claw_honest_pair`, and `claw_honest_price` when the task involves HONEST assets or discovery.'
-  ].join('\n');
+  ];
+
+  if (runtime.runtime === 'hermes') {
+    baseLines.push('- The shared Claw MCP server registers raw tool ids such as `claw_manifest`; if Hermes shows a namespaced label in its UI, follow the label shown there.');
+  }
+
+  return baseLines.join('\n');
 }
 
 function buildRuntimeSkillToml(runtime: any, repoRoot: string, profileRoot: string) {

package/claw/modules/credit_runtime_adapter.ts

@@ -24,7 +24,7 @@ function createCreditRuntimeAdapter(infra: any, options: Record<string, any> = {
         assetA: botEntry.assetA,
         assetB: botEntry.assetB,
       },
-      _log: (msg: string, level?: string) => {
+      _log: (msg: string) => {
         const logger = infra.runtime?.logger || console;
         if (typeof logger.info === 'function') logger.info(`[credit-runtime] ${msg}`);
         else logger.log(`[credit-runtime] ${msg}`);
@@ -100,10 +100,7 @@ function createCreditRuntimeAdapter(infra: any, options: Record<string, any> = {
       const rt = await _getRuntime(botRef);
       if (!rt) {
         try {
-          const bundle = await infra.profiles.loadBundle();
-          const bot = bundle.bots.find(
-            (b: Record<string, any>) => b.botKey === botRef || b.name === botRef,
-          );
+          const bot = await _resolveBotEntry(botRef);
           if (!bot) return { error: `bot not found: ${botRef}` };
           if (!bot.debtPolicy) return { error: `bot ${botRef} has no debtPolicy configured` };
           return { error: `unable to initialize credit runtime for ${botRef}` };
@@ -142,19 +139,6 @@ function createCreditRuntimeAdapter(infra: any, options: Record<string, any> = {
       _ensureSigningKey(rt, privateKey);
       return rt.processPendingReborrows();
     },
-
-    listRuntimes(): any[] {
-      return Array.from(_runtimes.entries())
-        .filter(([_, rt]) => rt.isEnabled())
-        .map(([key, rt]) => ({
-          botKey: key,
-          enabled: rt.isEnabled(),
-        }));
-    },
-
-    getRuntime(botRef: string): any | null {
-      return _runtimes.get(botRef) || null;
-    },
   };
 }
 

package/claw/modules/decision_loop.ts

@@ -186,6 +186,10 @@ function buildSummary(assessments: Array<Record<string, any>>) {
 function resetAnalyzers() {
   analyzers.clear();
   analyzerConfigs.clear();
+  // Premiums belong to the analyzer generation that produced them; keeping
+  // them across a reset would let the reuse path report a stale value from
+  // discarded config.
+  marketPremiums.clear();
 }
 
 export { evaluate, getOrCreateAnalyzer, resetAnalyzers }

package/claw/modules/dexbot_bridge.ts

@@ -78,5 +78,5 @@ function loadDexbotOrderSystemUtils() {
   return requireDexbot2Module('modules/order/utils/system');
 }
 
-export { getDexbot2Root, loadDexbotOrderConstants, loadDexbotOrderSubsystem, loadDexbotOrderSystemUtils, loadDexbotOrderUtils, requireDexbot2Module, resolveDexbot2Path }
+export { getDexbot2Root, loadDexbotOrderConstants, loadDexbotOrderSubsystem, loadDexbotOrderSystemUtils, loadDexbotOrderUtils, requireDexbot2Module }
 

package/claw/modules/dexbot_profiles.ts

@@ -12,7 +12,7 @@ import { clone } from './utils.js';
 import { createBotKey, sanitizeKey } from '../../modules/account_orders.js';
 const storage = getStorage();
 
-import type { BotSettings, ProfileOptions, Logger, ClawProfileBundle } from './types.js';
+import type { BotSettings, ProfileOptions, ClawProfileBundle } from './types.js';
 import { getErrorMessage } from '../../modules/utils/errors.js';
 
 const DEFAULT_MANIFEST_FILE = 'config.json';
@@ -661,7 +661,7 @@ async function normalizeBotEntries(rawEntries: Record<string, any>[], options: P
     if (logger) {
       validateBotEntry(entry, index, logger);
     }
-    const normalized = { active: entry.active === undefined ? true : !!entry.active, ...entry };
+    const normalized = { ...entry, active: entry.active === undefined ? true : !!entry.active };
     results.push({ ...normalized, botIndex: index, botKey: createBotKey(normalized, index) });
   }
   return results;
@@ -706,7 +706,9 @@ function resolveProfilesDir(profileRoot: any) {
     candidates.push(path.join(envRoot, 'profiles'));
   }
 
-  if (Config.CWD) candidates.push(path.resolve(Config.CWD, 'profiles'));
+  // No bare CWD/profiles candidate here: an existing home config is
+  // authoritative (matching modules/paths.ts), and legacy cwd profiles are
+  // handled by the central resolver's migration logic below.
 
   for (const candidate of candidates) {
     if (isFileLike(candidate)) {
@@ -1006,8 +1008,8 @@ async function loadDexbotProfileBundle(profileRoot: string | null, options: Part
  * The adapter wraps bundle loading, settings validation, and atomic writes behind
  * per-file locks so concurrent updates do not clobber each other.
  *
- * @returns {Object} Adapter with loadBundle, listBots, findBot, getBotBundle,
- *   getBotSettings, previewBotSettingsUpdate, applyBotSettingsPatch, getProfilesDir
+ * @returns {Object} Adapter with loadBundle, getBotSettings,
+ *   previewBotSettingsUpdate, applyBotSettingsPatch, updateBotSettings, getClawProfileContext
  */
 function createDexbotProfileAdapter(profileRoot: string | null, options: Partial<ProfileOptions> = {}) {
   let cachedBundle: any = null;
@@ -1023,16 +1025,6 @@ function createDexbotProfileAdapter(profileRoot: string | null, options: Partial
     return resolveProfilesDir(profileRoot || options.profileRoot);
   }
 
-  async function listBots({ activeOnly = false, forceReload = false } = {}) {
-    const bundle = await loadBundle(forceReload);
-    return activeOnly ? bundle.activeBots : bundle.bots;
-  }
-
-  async function findBot(identifier: any, forceReload = false) {
-    const bundle = await loadBundle(forceReload);
-    return bundle.bots.find((bot: any) => matchBotIdentifier(bot, identifier)) || null;
-  }
-
   async function getBotBundle(identifier: any, forceReload = false) {
     const bundle = await loadBundle(forceReload);
     const bot = bundle.bots.find((entry: any) => matchBotIdentifier(entry, identifier)) || null;
@@ -1270,20 +1262,14 @@ function createDexbotProfileAdapter(profileRoot: string | null, options: Partial
   }
 
   return {
-    buildClawProfileContext: (bundle: any, contextOptions = {}) => buildClawProfileContext(bundle, contextOptions),
     applyBotSettingsPatch,
-    findBot,
-    getBotBundle,
     getBotSettings,
     getClawProfileContext,
-    getProfilesDir,
-    listBots,
     loadBundle,
     previewBotSettingsUpdate,
-    resolveProfilesDir: () => resolveProfilesDir(profileRoot || options.profileRoot),
     updateBotSettings
   };
 }
 
-export { buildBotSettingsView, createBotKey, createDexbotProfileAdapter, buildClawProfileContext, describeBotSettingMutability, loadDexbotProfileBundle, matchBotIdentifier, normalizeBotSettings, normalizeBotEntries, readTriggerFile, resolveProfilesDir, resolveRawBotEntries, sanitizeKey, validateBotEntry, validateBotSettingsPatch, validateBotSettingsState, writeJsonFileAtomic }
+export { createBotKey, createDexbotProfileAdapter, matchBotIdentifier, normalizeBotEntries, resolveProfilesDir, resolveRawBotEntries, validateBotEntry, writeJsonFileAtomic }
 

package/claw/modules/honest_ecosystem.ts

@@ -88,7 +88,11 @@ async function fetchLivePoolReserves(poolId: string = HARDCODED_POOL_ID) {
     };
     _poolReservesCache = { poolId, ts: Date.now(), value: result };
     return result;
-  } catch {
+  } catch (err: any) {
+    // Never cache failures, but surface them: silently serving the hardcoded
+    // fallback snapshot hides a degraded node and produces confidently-wrong
+    // bridge prices with no telemetry trail.
+    console.warn(`[honest-ecosystem] live pool reserves fetch failed for ${poolId}, using hardcoded fallback: ${err?.message || err}`);
     return null;
   }
 }
@@ -217,10 +221,15 @@ async function resolveHonestPairContext(assetA: any, assetB: any, options: Recor
   };
 }
 
-async function loadHonestAssets({ prefix = DEFAULT_PREFIX, batchSize = 100, maxPages = 100, startSymbol = DEFAULT_PREFIX }: Record<string, any> = {}) {
-  const all = [];
+/**
+ * Paginate list_assets with the shared dedup/boundary rules used across the
+ * HONEST tooling. `onPage` receives each de-duplicated page and accumulates
+ * whatever it needs; returning `false` stops pagination early (e.g. crossing
+ * a prefix boundary).
+ */
+async function paginateListAssets({ batchSize = 100, maxPages = 100, startSymbol = '' }: Record<string, any> = {}, onPage: (pageItems: any[], batch: any[]) => boolean | void) {
   let lowerBound = startSymbol;
-  let previousLastSymbol = null;
+  let previousLastSymbol: string | null = null;
 
   for (let page = 0; page < maxPages; page += 1) {
     const batch = await listAssets(lowerBound, batchSize);
@@ -237,17 +246,24 @@ async function loadHonestAssets({ prefix = DEFAULT_PREFIX, batchSize = 100, maxP
       break;
     }
 
-    const matching = pageItems.filter((asset) => isHonestAsset(asset) && asset.symbol.startsWith(prefix));
-    all.push(...matching);
+    const keepGoing = await onPage(pageItems, batch);
 
     previousLastSymbol = pageItems[pageItems.length - 1].symbol;
     lowerBound = previousLastSymbol;
 
-    if (batch.length < batchSize) {
+    if (keepGoing === false || batch.length < batchSize) {
       break;
     }
   }
+}
 
+async function loadHonestAssets({ prefix = DEFAULT_PREFIX, batchSize = 100, maxPages = 100, startSymbol = DEFAULT_PREFIX }: Record<string, any> = {}) {
+  const all: any[] = [];
+
+  await paginateListAssets({ batchSize, maxPages, startSymbol }, (pageItems) => {
+    const matching = pageItems.filter((asset) => isHonestAsset(asset) && asset.symbol.startsWith(prefix));
+    all.push(...matching);
+  });
   const mpas = [];
   for (const asset of all) {
     if (!isMpa(asset)) {
@@ -357,5 +373,5 @@ function createHonestEcosystemAdapter(options: Record<string, any> = {}) {
   };
 }
 
-export { CORE_SYMBOL, DEFAULT_PREFIX, REFERENCE_SYMBOL, buildHonestEcosystemContext, createHonestEcosystemAdapter, getHardcodedHonestMoneyBridge, loadHonestAssets, isHardcodedHonestMoneyBtsPair, resolveHardcodedHonestMoneyPrice, resolveHonestPairContext, resolveHonestPairPrice }
+export { buildHonestEcosystemContext, createHonestEcosystemAdapter, getHardcodedHonestMoneyBridge, getHonestMoneyBridge, isMpa, loadHonestAssets, paginateListAssets, resolveHardcodedHonestMoneyPrice, resolveHonestPairContext, resolveHonestPairPrice }
 

package/claw/modules/launcher_paths.ts

@@ -44,8 +44,10 @@ function normalizeRoot(options: Record<string, any> = {}) {
       if (parent === candidate) break;
       candidate = parent;
     }
-    // Fall back to one level up (original behavior)
-    return path.dirname(resolved);
+    // No code root found above the profile dir (e.g. a home config like
+    // ~/.config/dexbot2/profiles). Spawn from the code location actually
+    // running this launcher instead of guessing an unrelated ancestor.
+    return DEFAULT_ROOT;
   }
   return DEFAULT_ROOT;
 }

package/claw/modules/liquidity_pools.ts

@@ -1,7 +1,7 @@
 
 
 import * as client from './bitshares_client.js';
-import { getDexbot2Root, loadDexbotOrderSystemUtils, requireDexbot2Module } from './dexbot_bridge.js';
+import { loadDexbotOrderSystemUtils, requireDexbot2Module } from './dexbot_bridge.js';
 function getDexbotSystem() {
   return loadDexbotOrderSystemUtils();
 }
@@ -13,9 +13,16 @@ function derivePoolPrice(assetA: any, assetB: any, poolRef?: string | null | Rec
     try {
       const { withPoolRef: wrapWithPoolRef } = requireDexbot2Module('modules/order/utils/withPoolRef') as any;
       const override = wrapWithPoolRef(client.BitShares, resolvedPoolRef);
-      if (override) return override.derivePoolPrice(assetA, assetB);
+      // The caller pinned a specific pool: honoring the pin or failing is
+      // correct, silently deriving from a different auto-selected pool is not.
+      if (!override) {
+        console.warn(`[liquidity-pools] derivePoolPrice could not pin pool ${resolvedPoolRef}`);
+        return null;
+      }
+      return override.derivePoolPrice(assetA, assetB);
     } catch (e: any) {
       console.warn(`[liquidity-pools] derivePoolPrice with poolRef failed: ${e?.message || e}`);
+      return null;
     }
   }
   return system.derivePoolPrice(client.BitShares, assetA, assetB);
@@ -47,5 +54,5 @@ function createDexbotPoolHelper() {
   };
 }
 
-export { derivePoolPrice, derivePrice, createDexbotPoolHelper, getDexbot2Root, requireDexbot2Module }
+export { derivePoolPrice, derivePrice, createDexbotPoolHelper }
 

package/claw/modules/mcp_utils.ts

@@ -43,6 +43,106 @@ export function failure(id: any, code: any, message: any, data = undefined) {
   });
 }
 
+/**
+ * Build an Error that createJsonRpcToolsHandler maps to a JSON-RPC error
+ * response with the given code instead of the isError:true result convention.
+ * Use -32602 for caller-input problems (invalid params, unknown tool).
+ */
+export function jsonRpcError(code: number, message: string): Error & { statusCode: number } {
+  const err = new Error(message) as Error & { statusCode: number };
+  err.statusCode = code;
+  return err;
+}
+
+/**
+ * Shared JSON-RPC request shell for the claw/memu stdio servers: initialize
+ * handshake (echoing the client's protocolVersion), notifications/initialized,
+ * ping, tools/list (internal failures map to -32603), tools/call delegation,
+ * and method-not-found. `callTool(params, defaults)` returns the result value
+ * for a successful call; thrown Errors carrying a numeric `statusCode`
+ * become JSON-RPC errors, everything else becomes an isError:true result.
+ */
+export function createJsonRpcToolsHandler(options: {
+  serverName: string;
+  serverVersion?: string;
+  listTools: () => any[] | Promise<any[]>;
+  callTool: (params: any, defaults: any) => Promise<any>;
+}) {
+  const { serverName, listTools, callTool } = options;
+  const serverVersion = options.serverVersion || '0.1.0';
+
+  return async function handleRequest(message: any, defaults: any) {
+    const { id, method, params } = message;
+
+    switch (method) {
+      case 'initialize':
+        return success(id, {
+          // Echo the client's requested protocol version when provided, so a
+          // JSONL-speaking client can negotiate its own version.
+          protocolVersion: params?.protocolVersion || '2024-11-05',
+          capabilities: {
+            tools: {
+              listChanged: false
+            }
+          },
+          serverInfo: {
+            name: serverName,
+            version: serverVersion
+          }
+        });
+
+      case 'notifications/initialized':
+        return;
+
+      case 'ping':
+        return success(id, {});
+
+      case 'tools/list':
+        try {
+          return success(id, {
+            tools: await listTools()
+          });
+        } catch (error: any) {
+          // Catalog load failure is a server-side problem, not bad input.
+          return failure(id, -32603, `Failed to load tool catalog: ${error && error.message ? error.message : String(error)}`);
+        }
+
+      case 'tools/call': {
+        try {
+          const result = await callTool(params, defaults);
+          return success(id, {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(result, null, 2)
+              }
+            ],
+            structuredContent: result
+          });
+        } catch (error: any) {
+          if (error && typeof error.statusCode === 'number') {
+            return failure(id, error.statusCode, error.message);
+          }
+          return success(id, {
+            content: [
+              {
+                type: 'text',
+                text: error && error.stack ? error.stack : String(error)
+              }
+            ],
+            isError: true
+          });
+        }
+      }
+
+      default:
+        if (id !== undefined) {
+          return failure(id, -32601, `Method not found: ${method}`);
+        }
+    }
+  };
+}
+
 export function createMessageParser(onMessage: any, onDrain?: () => void) {
   if (!hasProcess()) {
     throw new Error('MCP stdio transport not available in this environment');
@@ -128,6 +228,7 @@ export async function runMcpServer(parseArgs: (argv: string[]) => Record<string,
     }
   });
   let lastQueue = Promise.resolve();
+  let finishInput: () => void = () => {};
 
   runtime.stdin!.on('data', (chunk) => {
     lastQueue = parser.push(chunk);
@@ -138,10 +239,18 @@ export async function runMcpServer(parseArgs: (argv: string[]) => Record<string,
       runtime.stdin!.pause();
     }
   });
+  // Without an 'error' listener an EPIPE/EIO on stdin emits an unhandled
+  // 'error' event and crashes the MCP server mid-session. Treat it as EOF.
+  runtime.stdin!.on('error', (err: any) => {
+    runtime.stderr.write(`[mcp] stdin error: ${err && err.stack ? err.stack : String(err)}\n`);
+    // The 'end' event never fires after a stream error; unblock the wait.
+    finishInput();
+  });
   runtime.stdin!.resume();
 
   await new Promise<void>((resolve) => {
     runtime.stdin!.on('end', () => resolve());
+    finishInput = resolve;
   });
   await lastQueue;
 }