create-walle 0.9.22 → 0.9.24

package/template/wall-e/mcp-server.js

@@ -6,6 +6,7 @@ const brain = require('./brain');
 const { createSessionIngestService } = require('./memory/session-ingest-service');
 const ctmSessionContext = require('./memory/ctm-session-context');
 const ctmContextClient = require('./memory/ctm-context-client');
+const ctmOperationalContext = require('./memory/ctm-operational-context');
 const { collectIngestRecords } = require('./sources/base');
 const { ensureBuiltinSourceAdapters } = require('./sources/builtin');
 const sourceRegistry = require('./sources/registry');
@@ -192,6 +193,8 @@ const TOOL_OUTPUT_SCHEMAS = {
   },
   walle_memory_status: ANY_OBJECT_SCHEMA,
   walle_live_capabilities: ANY_OBJECT_SCHEMA,
+  walle_ctm_context: ANY_OBJECT_SCHEMA,
+  walle_ctm_remote_access_status: ANY_OBJECT_SCHEMA,
   walle_search_sessions: ANY_OBJECT_SCHEMA,
   walle_get_session: ANY_OBJECT_SCHEMA,
   walle_context_pack: ANY_OBJECT_SCHEMA,
@@ -243,6 +246,8 @@ const TOOL_ANNOTATIONS = {
   brain_stats: READ_ONLY_TOOL_ANNOTATION,
   walle_memory_status: READ_ONLY_TOOL_ANNOTATION,
   walle_live_capabilities: READ_ONLY_TOOL_ANNOTATION,
+  walle_ctm_context: READ_ONLY_TOOL_ANNOTATION,
+  walle_ctm_remote_access_status: READ_ONLY_TOOL_ANNOTATION,
   walle_list_sources: READ_ONLY_TOOL_ANNOTATION,
   walle_source_ingest: ADDITIVE_WRITE_TOOL_ANNOTATION,
   walle_search_sessions: READ_ONLY_TOOL_ANNOTATION,
@@ -280,6 +285,7 @@ const MCP_TOOLS = [
         limit: { type: 'number', description: 'Max memories/session snippets/entities per source (default 5, max 20)' },
         include_memories: { type: 'boolean', description: 'Include Wall-E memory search results (default true when route needs Wall-E)' },
         include_sessions: { type: 'boolean', description: 'Include CTM coding-session context (default true for session routes)' },
+        include_ctm_operational: { type: 'boolean', description: 'Include CTM operational context such as current phone URLs and Dev Tunnel status (default true for CTM operational routes)' },
         include_entities: { type: 'boolean', description: 'Include knowledge-graph entity matches (default true for people/work routes)' },
         entity_name: { type: 'string', description: 'Optional explicit entity/person/project/tool name to look up' },
         force_memory: { type: 'boolean', description: 'Search Wall-E memory even when routing says live/public/direct' },
@@ -501,6 +507,33 @@ const MCP_TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'walle_ctm_context',
+    description: 'Resolve CTM operational and session-memory context for CTM primary, mobile phone URLs, Dev Tunnel, /m/, and related CTM session-memory questions. Use this instead of generic memory for CTM remote-access answers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The CTM/mobile/session-memory question to resolve' },
+        context: { type: 'string', description: 'Optional nearby conversation context' },
+        limit: { type: 'number', description: 'Max CTM session-memory snippets to include (default 5, max 10)' },
+        force: { type: 'boolean', description: 'Force CTM operational lookup even if the query classifier is unsure' },
+        timeout_ms: { type: 'number', description: 'Timeout for CTM API calls (default 6000)' },
+        cooldown_ms: { type: 'number', description: 'Cooldown for CTM API retry suppression (default 0 for this exact lookup)' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'walle_ctm_remote_access_status',
+    description: 'Read current CTM setup/network status and summarize active phone access URLs, including Microsoft Dev Tunnel and Tailscale. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        timeout_ms: { type: 'number', description: 'Timeout for the CTM setup/network API call (default 6000)' },
+        cooldown_ms: { type: 'number', description: 'Cooldown for CTM API retry suppression (default 0)' },
+      },
+    },
+  },
   {
     name: 'walle_list_sources',
     description: 'List source adapters Wall-E can ingest, including Claude Code, Codex, Gemini, and Wall-E JSONL sessions.',
@@ -627,7 +660,10 @@ const MCP_TOOLS = [
     description: 'Run a dry integrity scan for brain memory, knowledge, entity, and index consistency.',
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        limit: { type: 'number', description: 'Max issue rows to return in the sample (default 50, max 500)' },
+        include_all: { type: 'boolean', description: 'Return all issue rows instead of a bounded sample' },
+      },
     },
   },
   {
@@ -702,24 +738,47 @@ async function executeTool(name, args) {
         until: args.until,
       };
       const hasFilters = Object.values(filters).some(Boolean);
-      let results = brain.searchMemories({ query: args.query, limit, ...filters });
-      // Hybrid: merge with vector results if embeddings available
-      if (!hasFilters && _embeddings && _embeddings.isAvailable()) {
-        try {
-          const queryEmb = await _embeddings.computeEmbedding(args.query);
-          if (queryEmb) {
-            const vectorResults = _embeddings.searchSimilarMemories(queryEmb, limit);
-            if (vectorResults.length > 0) {
-              results = _embeddings.reciprocalRankFusion(results, vectorResults, limit);
-            }
+      // Person-aware recall: if the query references a person, expand the search to
+      // their aliases / email / @handle so messages that reference them indirectly
+      // still match (full-name-only search misses email/handle mentions).
+      let personTerms;
+      let resolvedPerson = '';
+      try {
+        const inferred = inferEntityName(args.query);
+        if (inferred) {
+          const ident = brain.resolvePersonIdentities(inferred);
+          if (ident && Array.isArray(ident.terms) && ident.terms.length > 1) {
+            personTerms = ident.terms;
+            resolvedPerson = ident.canonical;
           }
-        } catch {}
-      }
-      return {
-        results: results.map(formatMemoryResult),
+        }
+      } catch {}
+      const memorySearch = await searchWallEMemories({
+        query: args.query,
+        limit,
+        filters,
+        hybrid: !hasFilters,
+        terms: personTerms,
+      });
+      const out = {
+        results: memorySearch.results.map(formatMemoryResult),
         filters_applied: Object.fromEntries(Object.entries(filters).filter(([, value]) => Boolean(value))),
-        vector_search_used: Boolean(!hasFilters && _embeddings && _embeddings.isAvailable()),
+        vector_search_used: memorySearch.vector_search_used,
+        source: memorySearch.source,
+        warnings: memorySearch.source.ok ? [] : [memorySearch.source],
       };
+      if (resolvedPerson) out.resolved_person = resolvedPerson;
+      // Empty stored memory is NOT a dead end — steer the caller to escalate to
+      // live sources / the full chat pipeline rather than declining.
+      if (memorySearch.source.ok && memorySearch.results.length === 0) {
+        out.hint = 'No stored memory matched. The brain may not have ingested this yet — this does NOT mean no history exists.';
+        out.next_steps = [
+          'Call ask_walle with the original request — it can search LIVE Slack / Gmail / Calendar and compose the reply.',
+          ...(inferEntityName(args.query) ? ["Call list_people / entity_search to resolve the person's email or @handle, then search those."] : []),
+          'If this is a write/compose request, draft it with [placeholders] for any unknowns instead of declining.',
+        ];
+      }
+      return out;
     }
     case 'remember': {
       const result = brain.insertKnowledge({
@@ -821,7 +880,7 @@ async function executeTool(name, args) {
       let entityCount = 0, embeddingCount = 0;
       try { entityCount = brain.listEntities({ limit: 1 }).length > 0 ? brain.getDb().prepare('SELECT COUNT(*) as c FROM entities').get().c : 0; } catch {}
       try { embeddingCount = brain.getDb().prepare("SELECT COUNT(*) as c FROM embedding_map").get().c; } catch {}
-      return { ...stats, entity_count: entityCount, embedding_count: embeddingCount };
+      return { ...stats, entity_count: entityCount, embedding_count: embeddingCount, storage_risk: brain.getStorageRisk?.() || null };
     }
     case 'walle_memory_status': {
       ensureBuiltinSourceAdapters();
@@ -830,6 +889,7 @@ async function executeTool(name, args) {
       return {
         ok: true,
         stats,
+        storage_risk: brain.getStorageRisk?.() || null,
         ctm_db: await getCtmDbStatus(),
         resources: {
           static: MCP_RESOURCES.map((resource) => resource.uri),
@@ -844,6 +904,22 @@ async function executeTool(name, args) {
     case 'walle_live_capabilities': {
       return getLiveCapabilities();
     }
+    case 'walle_ctm_context': {
+      return ctmOperationalContext.lookupCtmOperationalContext(args);
+    }
+    case 'walle_ctm_remote_access_status': {
+      const status = await ctmContextClient.getRemoteAccessStatus({}, {
+        timeoutMs: args.timeout_ms || 6000,
+        cooldownMs: args.cooldown_ms || 0,
+      });
+      return {
+        ok: !status.reason,
+        source: status.source || 'ctm-api',
+        reason: status.reason || '',
+        api_transport: status.api_transport || null,
+        remote_access: status.reason ? null : ctmOperationalContext.summarizeRemoteAccess(status),
+      };
+    }
     case 'walle_list_sources': {
       ensureBuiltinSourceAdapters();
       return {
@@ -877,16 +953,21 @@ async function executeTool(name, args) {
       const ctmResults = args.prefer_db === false
         ? { ok: false, results: [], skipped: true, reason: 'prefer_db_false' }
         : await safeCtmSearchSessions({ query: args.query, limit });
-      const memoryResults = args.include_memory === false
-        ? []
-        : brain.searchMemories({ query: args.query, limit: limit * 4 })
-          .filter(isSessionMemory)
-          .slice(0, limit * 2)
-          .map((memory, index) => ({
-            ...formatSessionMemory(memory),
-            source_layer: 'wall-e-memory',
-            rank: 10000 + index,
-          }));
+      const memorySearch = args.include_memory === false
+        ? {
+          results: [],
+          source: { searched: false, ok: true, source: 'wall-e-memory', count: 0, reason: '' },
+          vector_search_used: false,
+        }
+        : await searchWallEMemories({ query: args.query, limit: limit * 4, hybrid: false });
+      const memoryResults = memorySearch.results
+        .filter(isSessionMemory)
+        .slice(0, limit * 2)
+        .map((memory, index) => ({
+          ...formatSessionMemory(memory),
+          source_layer: 'wall-e-memory',
+          rank: 10000 + index,
+        }));
       const ctmSourceLayer = ctmResults.source === 'ctm-api' ? 'ctm-api' : 'ctm-db';
       const dbResults = (ctmResults.results || []).map((result, index) => ({
         ...result,
@@ -915,6 +996,10 @@ async function executeTool(name, args) {
           },
           wall_e_memory: {
             searched: args.include_memory !== false,
+            ok: Boolean(memorySearch.source.ok),
+            source: memorySearch.source.source,
+            reason: memorySearch.source.reason || '',
+            error: memorySearch.source.error || '',
             count: memoryResults.length,
           },
         },
@@ -997,7 +1082,10 @@ async function executeTool(name, args) {
     }
     case 'walle_repair_status': {
       const repair = require('./utils/repair');
-      return repair.scanIntegrity();
+      return compactRepairScan(repair.scanIntegrity(), {
+        limit: args.limit,
+        include_all: args.include_all,
+      });
     }
     case 'walle_rebuild_ctm_message_index': {
       requireWriteConfirmation('walle_rebuild_ctm_message_index', args);
@@ -1038,6 +1126,19 @@ function routeWallEQuery(query, opts = {}) {
   const selfProfile = add('self_profile', [/\b(my|me)\b.*\b(writing style|communication style|tone|personality|leadership style|work style)\b/, /\banaly[sz]e my\b/, /\bwhat.*\bpatterns\b.*\bme\b/, /\bam i too\b/]);
   const liveAction = add('live_action', [/\bsend\b/, /\bpost\b/, /\bcreate\b/, /\bschedule\b/, /\bopen\b/, /\bdelete\b/, /\bupdate\b/, /\bunread\b/, /\binbox\b/, /\btoday'?s calendar\b/, /\btomorrow'?s calendar\b/]);
   const publicCurrent = add('public_current', [/\bweb\b/, /\bpublic\b/, /\bnews\b/, /\blatest\b/, /\bcurrent\b/, /\bprice\b/, /\bstock\b/, /\bweather\b/, /\bdocs?\b/, /\bofficial\b/]);
+  const ctmOperational = ctmOperationalContext.classifyCtmOperationalQuery(query, { context: opts.context });
+  if (ctmOperational.required) {
+    matched.push({ name: 'ctm_operational_context', hits: ctmOperational.matched });
+    return {
+      route: 'ctm_operational_context',
+      should_use_walle: true,
+      primary_tools: ['walle_ctm_context', 'walle_ctm_remote_access_status', 'walle_search_sessions'],
+      secondary_tools: ['walle_lookup_context', 'search_memories'],
+      avoid_until_memory_miss: ['web_search', 'web_fetch'],
+      reason: ctmOperational.reason,
+      matched,
+    };
+  }
 
   if (selfProfile) {
     return {
@@ -1118,7 +1219,9 @@ async function lookupWallEContext(args = {}) {
   const isProfileLookup = route.matched?.some(match => match.name === 'self_profile');
   const includeMemories = args.include_memories === true || (args.include_memories !== false && shouldUseWallE);
   const includeSessions = args.include_sessions === true
-    || (args.include_sessions !== false && (route.route === 'walle_session_context' || isProfileLookup));
+    || (args.include_sessions !== false && (route.route === 'walle_session_context' || route.route === 'ctm_operational_context' || isProfileLookup));
+  const includeCtmOperational = args.include_ctm_operational === true
+    || (args.include_ctm_operational !== false && route.route === 'ctm_operational_context');
   const includeEntities = args.include_entities === true
     || (args.include_entities !== false && (route.route === 'walle_private_memory' || args.force_memory));
   const inferredEntityName = String(args.entity_name || inferEntityName(query) || '').trim();
@@ -1130,13 +1233,34 @@ async function lookupWallEContext(args = {}) {
     session_results: [],
     entity_results: [],
     context_pack: null,
+    ctm_operational_context: null,
     sources: {
       memories: { searched: false, count: 0 },
       ctm_sessions: { searched: false, count: 0 },
+      ctm_operational: { searched: false, count: 0 },
       entities: { searched: false, count: 0 },
     },
   };
 
+  if (includeCtmOperational) {
+    const operational = await ctmOperationalContext.lookupCtmOperationalContext({
+      query,
+      context: args.context,
+      limit,
+      force: true,
+    });
+    result.ctm_operational_context = operational;
+    result.sources.ctm_operational = {
+      searched: true,
+      ok: Boolean(operational.ok),
+      required: Boolean(operational.required),
+      reason: operational.ok ? '' : 'ctm_operational_context_unavailable',
+      remote_access: operational.sources?.remote_access || null,
+      ctm_sessions: operational.sources?.ctm_sessions || null,
+      count: (operational.session_results || []).length,
+    };
+  }
+
   if (includeSessions) {
     const sessionQuery = isProfileLookup ? 'thorough review fix issues commit high-agency' : query;
     const sessionSearch = await safeCtmSearchSessions({
@@ -1169,21 +1293,37 @@ async function lookupWallEContext(args = {}) {
       since: args.since,
       until: args.until,
     };
-    result.memory_results = brain.searchMemories({ query: memoryQuery, limit, ...filters }).map(formatMemoryResult);
+    const memorySearch = await searchWallEMemories({
+      query: memoryQuery,
+      limit,
+      filters,
+      hybrid: !Object.values(filters).some(Boolean),
+    });
+    result.memory_results = memorySearch.results.map(formatMemoryResult);
     result.sources.memories = {
       searched: true,
       query: memoryQuery,
       filters_applied: Object.fromEntries(Object.entries(filters).filter(([, value]) => Boolean(value))),
+      ok: Boolean(memorySearch.source.ok),
+      source: memorySearch.source.source,
+      reason: memorySearch.source.reason || '',
+      error: memorySearch.source.error || '',
+      vector_search_used: memorySearch.vector_search_used,
       count: result.memory_results.length,
     };
   }
 
   if (includeEntities) {
     if (inferredEntityName) {
-      result.entity_results = searchEntitiesForContext(inferredEntityName, limit);
+      const entitySearch = safeSearchEntitiesForContext(inferredEntityName, limit);
+      result.entity_results = entitySearch.results;
       result.sources.entities = {
         searched: true,
         query: inferredEntityName,
+        ok: Boolean(entitySearch.ok),
+        source: entitySearch.source,
+        reason: entitySearch.reason || '',
+        error: entitySearch.error || '',
         count: result.entity_results.length,
       };
     } else {
@@ -1220,6 +1360,98 @@ function compactSnippet(text, max = 260) {
   return cleaned.length > max ? cleaned.slice(0, Math.max(0, max - 1)).trimEnd() + '...' : cleaned;
 }
 
+function classifySourceError(err, fallbackReason = 'source_read_failed') {
+  const code = String(err?.code || '');
+  const message = String(err?.message || err || '');
+  const text = `${code} ${message}`.toLowerCase();
+  let reason = fallbackReason;
+  if (/sqlite_(corrupt|notadb)|database disk image is malformed|malformed database|database schema is corrupt/.test(text)) {
+    reason = 'sqlite_structural_corruption';
+  } else if (/sqlite_(busy|locked)|database is locked|database table is locked/.test(text)) {
+    reason = 'sqlite_locked';
+  } else if (/sqlite_cantopen|unable to open database file/.test(text)) {
+    reason = 'sqlite_unavailable';
+  } else if (/database not initialized/.test(text)) {
+    reason = 'sqlite_not_initialized';
+  }
+  return {
+    ok: false,
+    reason,
+    error: message,
+    code: code || undefined,
+  };
+}
+
+function sourceStatus(source, patch = {}) {
+  return {
+    searched: true,
+    ok: true,
+    source,
+    reason: '',
+    error: '',
+    count: 0,
+    ...patch,
+  };
+}
+
+function safeBrainSearchMemories(args = {}) {
+  try {
+    const results = brain.searchMemories(args);
+    return {
+      results,
+      source: sourceStatus('wall-e-memory', {
+        ok: true,
+        count: results.length,
+      }),
+    };
+  } catch (err) {
+    const failure = classifySourceError(err, 'wall_e_memory_search_failed');
+    return {
+      results: [],
+      source: sourceStatus('wall-e-memory', {
+        ...failure,
+        count: 0,
+      }),
+    };
+  }
+}
+
+async function searchWallEMemories({ query, limit, filters = {}, hybrid = true, terms } = {}) {
+  const base = safeBrainSearchMemories({ query, limit, terms, ...filters });
+  let results = base.results;
+  let vectorSearchUsed = false;
+  const vectorStatus = { attempted: false, ok: true, reason: '', error: '' };
+
+  if (base.source.ok && hybrid && _embeddings && _embeddings.isAvailable()) {
+    vectorStatus.attempted = true;
+    try {
+      const queryEmb = await _embeddings.computeEmbedding(query);
+      if (queryEmb) {
+        const vectorResults = _embeddings.searchSimilarMemories(queryEmb, limit);
+        if (vectorResults.length > 0) {
+          results = _embeddings.reciprocalRankFusion(results, vectorResults, limit);
+          vectorSearchUsed = true;
+        }
+      }
+    } catch (err) {
+      const failure = classifySourceError(err, 'wall_e_vector_search_failed');
+      vectorStatus.ok = false;
+      vectorStatus.reason = failure.reason;
+      vectorStatus.error = failure.error;
+    }
+  }
+
+  return {
+    results,
+    vector_search_used: vectorSearchUsed,
+    source: sourceStatus('wall-e-memory', {
+      ...base.source,
+      count: results.length,
+      vector: vectorStatus,
+    }),
+  };
+}
+
 function evidenceFromMemory(memory, aspect) {
   return {
     kind: 'memory',
@@ -1265,17 +1497,20 @@ function profileAspectEvidence(aspect, limit) {
 
   for (const query of PROFILE_ASPECT_QUERIES[aspect] || []) {
     if (rows.length >= limit) break;
-    for (const memory of brain.searchMemories({ query, limit: Math.max(limit, 4) })) {
+    const memorySearch = safeBrainSearchMemories({ query, limit: Math.max(limit, 4) });
+    for (const memory of memorySearch.results) {
       addMemory(memory);
       if (rows.length >= limit) break;
     }
   }
 
   if (aspect === 'preferences') {
-    for (const row of brain.findKnowledge({ category: 'preference', status: 'active', limit, orderBy: 'confidence DESC' })) {
-      addKnowledge(row);
-      if (rows.length >= limit) break;
-    }
+    try {
+      for (const row of brain.findKnowledge({ category: 'preference', status: 'active', limit, orderBy: 'confidence DESC' })) {
+        addKnowledge(row);
+        if (rows.length >= limit) break;
+      }
+    } catch {}
   }
 
   return rows.slice(0, limit);
@@ -1476,6 +1711,7 @@ function buildPostflightCheck(args = {}) {
 
 function inferEntityName(query) {
   const text = String(query || '').trim();
+  // End-anchored question patterns (case-insensitive): the whole tail is the name.
   for (const pattern of [
     /\bdo you know\s+(.+?)[?.!]?$/i,
     /\bwho is\s+(.+?)[?.!]?$/i,
@@ -1487,6 +1723,19 @@ function inferEntityName(query) {
       return match[1].replace(/^["']|["']$/g, '').trim();
     }
   }
+  // Mid-sentence references to a proper-noun name (1-3 capitalized words), e.g.
+  // "search history about Eric Gu", "write Eric Gu's anniversary note",
+  // "a note for Eric Gu". Case-sensitive so it keys on the capitalized name.
+  const NAME = "([A-Z][\\w.-]*(?:\\s+[A-Z][\\w.-]*){0,2})";
+  for (const pattern of [
+    new RegExp("\\b(?:note|message|email|card|memo)\\s+(?:to|for|about)\\s+" + NAME),
+    new RegExp("\\babout\\s+" + NAME),
+    new RegExp("\\bfor\\s+" + NAME + "(?:'s)?\\b"),
+    new RegExp(NAME + "'s\\b"),
+  ]) {
+    const match = text.match(pattern);
+    if (match?.[1]) return match[1].trim();
+  }
   return '';
 }
 
@@ -1512,6 +1761,39 @@ function searchEntitiesForContext(name, limit) {
   }));
 }
 
+function safeSearchEntitiesForContext(name, limit) {
+  try {
+    const results = searchEntitiesForContext(name, limit);
+    return {
+      ok: true,
+      source: 'wall-e-entities',
+      results,
+      count: results.length,
+    };
+  } catch (err) {
+    const failure = classifySourceError(err, 'wall_e_entity_search_failed');
+    return {
+      ...failure,
+      source: 'wall-e-entities',
+      results: [],
+      count: 0,
+    };
+  }
+}
+
+function compactRepairScan(scan = {}, { limit = 50, include_all = false } = {}) {
+  const issues = Array.isArray(scan.issues) ? scan.issues : [];
+  const cap = include_all ? issues.length : clampLimit(limit, 50, 500);
+  const sample = issues.slice(0, cap);
+  return {
+    ...scan,
+    issues: sample,
+    issues_sample: sample,
+    issues_truncated: sample.length < issues.length,
+    total_issues: issues.length,
+  };
+}
+
 function clampLimit(value, fallback, max) {
   const n = Number(value || fallback);
   if (!Number.isFinite(n)) return fallback;

package/template/wall-e/memory/ctm-context-client.js

@@ -2,7 +2,7 @@
 
 const ctmSessionContext = require('./ctm-session-context');
 
-const DEFAULT_TIMEOUT_MS = 700;
+const DEFAULT_TIMEOUT_MS = 2500;
 const DEFAULT_COOLDOWN_MS = 15000;
 
 let apiFailureUntil = 0;
@@ -11,16 +11,18 @@ let lastApiFailure = null;
 function resolveApiBaseUrl(env = process.env) {
   const explicit = env.CTM_SESSION_MEMORY_API_BASE_URL || env.CTM_API_BASE_URL || env.CTM_BASE_URL;
   if (explicit) return explicit.replace(/\/+$/, '');
-  if (env.WALLE_CTM_API === '1' && (env.CTM_PORT || env.DEV_CTM_PORT)) {
-    return `http://127.0.0.1:${env.CTM_PORT || env.DEV_CTM_PORT}`;
-  }
-  return '';
+  if (env.WALLE_CTM_API === '0') return '';
+  return `http://127.0.0.1:${env.CTM_PORT || env.DEV_CTM_PORT || '3456'}`;
 }
 
 function apiDisabled(env = process.env) {
   return env.WALLE_CTM_API_DISABLED === '1' || env.CTM_SESSION_MEMORY_API === '0';
 }
 
+function directFallbackAllowed(env = process.env, options = {}) {
+  return options.allowDirectFallback === true || env.WALLE_CTM_DIRECT_READ_FALLBACK === '1';
+}
+
 async function getHealth(options = {}) {
   return apiFirst({
     path: '/api/ctm/session-memory/health',
@@ -61,6 +63,24 @@ async function getSessionContext(args = {}, options = {}) {
   });
 }
 
+async function getRemoteAccessStatus(args = {}, options = {}) {
+  return apiFirst({
+    path: '/api/setup/network',
+    fallback: () => ({
+      ok: false,
+      source: 'ctm-api',
+      authority: 'ctm',
+      reason: 'ctm_api_required',
+      remote_access: null,
+    }),
+    options: {
+      ...options,
+      preferApi: args.prefer_api !== false && options.preferApi !== false,
+      timeoutMs: options.timeoutMs ?? 6000,
+    },
+  });
+}
+
 async function buildContextPack(args = {}, options = {}) {
   return apiFirst({
     path: '/api/ctm/session-memory/context-pack',
@@ -112,21 +132,38 @@ async function backfillMessageIndex(args = {}, options = {}) {
 async function apiFirst({ path, method = 'GET', body, fallback, options = {} }) {
   const env = options.env || process.env;
   const preferApi = options.preferApi !== false;
-  const fallbackResult = () => annotateFallback(fallback(), {
-    attempted: false,
-    skipped: true,
-    reason: apiDisabled(env) ? 'api_disabled' : 'api_base_url_missing',
-  });
+  const fallbackResult = (apiTransport) => {
+    if (directFallbackAllowed(env, options)) return annotateFallback(fallback(), apiTransport);
+    return {
+      ok: false,
+      source: 'ctm-api',
+      authority: 'ctm',
+      reason: 'ctm_api_required',
+      api_transport: apiTransport,
+    };
+  };
 
-  if (!preferApi || apiDisabled(env)) return fallbackResult();
+  if (!preferApi || apiDisabled(env)) {
+    return fallbackResult({
+      attempted: false,
+      skipped: true,
+      reason: apiDisabled(env) ? 'api_disabled' : 'api_not_preferred',
+    });
+  }
 
   const baseUrl = resolveApiBaseUrl(env);
-  if (!baseUrl) return fallbackResult();
+  if (!baseUrl) {
+    return fallbackResult({
+      attempted: false,
+      skipped: true,
+      reason: 'api_base_url_missing',
+    });
+  }
 
   const now = Date.now();
   const cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
   if (cooldownMs > 0 && apiFailureUntil > now) {
-    return annotateFallback(fallback(), {
+    return fallbackResult({
       attempted: false,
       skipped: true,
       reason: 'api_cooldown',
@@ -154,7 +191,7 @@ async function apiFirst({ path, method = 'GET', body, fallback, options = {} })
   } catch (err) {
     lastApiFailure = err.message;
     apiFailureUntil = Date.now() + cooldownMs;
-    return annotateFallback(fallback(), {
+    return fallbackResult({
       attempted: true,
       ok: false,
       base_url: baseUrl,
@@ -224,6 +261,7 @@ module.exports = {
   getHealth,
   searchSessions,
   getSessionContext,
+  getRemoteAccessStatus,
   buildContextPack,
   backfillMessageIndex,
   resetApiState,