@remits/remits-cli 0.1.80 → 0.1.83

package/index.js

@@ -413,6 +413,18 @@ function writeToolResponseFile(cwd, callId, responsePayload) {
   return file;
 }
 
+function readToolResponseFile(cwd, callId) {
+  if (!callId) return null;
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolResponsesDir, callId + '.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
 function normalizeName(name) {
   return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
 }
@@ -1191,9 +1203,14 @@ function collectComponents(cwd) {
   return components;
 }
 
-function buildAxios(baseUrl, token) {
+function parsePositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+function buildAxios(baseUrl, token, timeoutMs = 60000) {
   const headers = token ? { Authorization: 'Bearer ' + token } : {};
-  return axios.create({ baseURL: baseUrl, timeout: 60000, headers });
+  return axios.create({ baseURL: baseUrl, timeout: parsePositiveInt(timeoutMs, 60000), headers });
 }
 
 function describeError(err) {
@@ -1934,6 +1951,37 @@ async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dat
   }
 }
 
+async function waitForToolStatus(api, cwd, options) {
+  const started = Date.now();
+  let pollDelayMs = parsePositiveInt(options.pollIntervalMs, 1000);
+  const maxPollDelayMs = parsePositiveInt(options.maxPollIntervalMs, 5000);
+  const deadline = options.waitTimeoutMs ? (started + parsePositiveInt(options.waitTimeoutMs, 0)) : null;
+
+  while (true) {
+    const statusResponse = await loggedPost(api, cwd, '/cli/tool', {
+      token: options.token,
+      command: 'status',
+      accountId: options.accountId,
+      accountIdExplicit: options.accountIdExplicit,
+      branchName: options.branchName,
+      dataMode: options.dataMode,
+      callId: options.callId
+    }, { toolResponseFile: true, toolCallId: options.callId });
+
+    const status = statusResponse.data;
+    if (status.status === 'completed' || status.status === 'failed') {
+      return { data: status, responseFile: statusResponse.responseFile };
+    }
+
+    if (deadline && Date.now() >= deadline) {
+      throw new Error('Timed out waiting for async tool call ' + options.callId + ' after ' + (Date.now() - started) + 'ms');
+    }
+
+    await new Promise((r) => setTimeout(r, pollDelayMs));
+    pollDelayMs = Math.min(maxPollDelayMs, pollDelayMs + 500);
+  }
+}
+
 function watchWebsocket(baseUrl, topicId, taskId) {
   const client = new Client({
     brokerURL: webSocketUrl(baseUrl),
@@ -2130,8 +2178,10 @@ async function toolCommand(flags) {
   const sessionContext = resolveSessionContext(cwd, flags);
   const { session, accountId } = sessionContext;
 
+  const subcommand = flags._ && flags._[1];
+  const statusMode = subcommand === 'status' || flagEnabled(flags.status);
   const toolName = flags.name || flags.tool;
-  if (!toolName) {
+  if (!toolName && !statusMode) {
     throw new Error('Missing --name <toolName>');
   }
 
@@ -2144,8 +2194,48 @@ async function toolCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
-  const callId = crypto.randomUUID();
-  const api = buildAxios(baseUrl, session.token);
+  const timeoutMs = parsePositiveInt(flags['timeout-ms'] || flags.timeoutMs, 60000);
+  const callId = String(flags['call-id'] || flags.callId || crypto.randomUUID());
+  const asyncMode = flagEnabled(flags.async) || flagEnabled(input.async);
+  const waitForAsync = flagEnabled(flags.wait);
+  const pollIntervalMs = parsePositiveInt(flags['poll-interval-ms'] || flags.pollIntervalMs, 1000);
+  const waitTimeoutMs = flags['wait-timeout-ms'] || flags.waitTimeoutMs;
+  const api = buildAxios(baseUrl, session.token, timeoutMs);
+
+  if (statusMode) {
+    const requestedCallId = String(flags['call-id'] || flags.callId || '');
+    if (!requestedCallId) {
+      throw new Error('Missing --call-id <callId>');
+    }
+
+    const stored = readToolResponseFile(cwd, requestedCallId);
+    const statusAccountId = flags['account-id'] || (stored && stored.accountId) || accountId;
+    const statusResponse = await loggedPost(api, cwd, '/cli/tool', {
+      token: session.token,
+      command: 'status',
+      accountId: statusAccountId,
+      accountIdExplicit: accountIdExplicit || Boolean(stored && stored.accountId),
+      branchName: flags.branch || (stored && stored.branchName) || branchName,
+      dataMode: flags['data-mode'] || (stored && stored.dataMode) || dataMode,
+      callId: requestedCallId
+    }, { toolResponseFile: true, toolCallId: requestedCallId });
+
+    const data = statusResponse.data;
+    if (!data.success) {
+      throw new Error(data.message || 'Tool status lookup failed');
+    }
+
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    console.log('Tool call status:', data.status);
+    console.log('Call ID:', requestedCallId);
+    console.log('Data mode:', data.dataMode || dataMode);
+    if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
+    console.log('Session log:', sessionJsonlFile(cwd));
+    console.log('Tool response file:', statusResponse.responseFile);
+    if (data.status === 'failed') process.exitCode = 1;
+    return;
+  }
 
   const response = await loggedPost(api, cwd, '/cli/tool', {
     token: session.token,
@@ -2155,7 +2245,8 @@ async function toolCommand(flags) {
     dataMode,
     name: String(toolName),
     input,
-    callId
+    callId,
+    async: asyncMode
   }, { toolResponseFile: true, toolCallId: callId });
 
   const data = response.data;
@@ -2165,9 +2256,11 @@ async function toolCommand(flags) {
 
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
-  console.log('Tool call succeeded.');
+  console.log(asyncMode ? 'Tool call started.' : 'Tool call succeeded.');
   console.log('Call ID:', callId);
-  console.log('Data mode:', dataMode);
+  console.log('Data mode:', data.dataMode || dataMode);
+  if (data.status) console.log('Status:', data.status);
+  if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
   // Make the resolved component version explicit so callers never assume staged vs DB.
   if (data.componentSource) {
     const sig = data.componentSignature ? ` (${data.componentSignature})` : '';
@@ -2175,6 +2268,25 @@ async function toolCommand(flags) {
   }
   console.log('Session log:', sessionJsonlFile(cwd));
   console.log('Tool response file:', response.responseFile);
+
+  if (asyncMode && waitForAsync) {
+    const finalStatus = await waitForToolStatus(api, cwd, {
+      token: session.token,
+      accountId: data.accountId || accountId,
+      accountIdExplicit: true,
+      branchName: data.branchName || branchName,
+      dataMode: data.dataMode || dataMode,
+      callId,
+      pollIntervalMs,
+      waitTimeoutMs
+    });
+
+    console.log('Final status:', finalStatus.data.status);
+    console.log('Tool response file:', finalStatus.responseFile);
+    if (finalStatus.data.status !== 'completed') {
+      process.exitCode = 1;
+    }
+  }
 }
 
 async function dataModeCommand(flags, subcommand) {
@@ -2698,36 +2810,78 @@ function truncateText(value, maxChars = 20000) {
   return text.slice(0, maxChars) + '\n...[truncated ' + (text.length - maxChars) + ' chars]';
 }
 
+const DASHBOARD_FILE_PREVIEW_BYTES = 512 * 1024;
+
 function readJsonFilePretty(file) {
   if (!fs.existsSync(file)) {
     return null;
   }
+  const stat = fileStat(file);
+  if (stat && stat.size > DASHBOARD_FILE_PREVIEW_BYTES) {
+    const tail = tailTextFile(file, 80);
+    return tail === null
+      ? null
+      : '...[large file; showing tail only]\n' + tail;
+  }
   try {
-    return JSON.stringify(JSON.parse(fs.readFileSync(file, 'utf8')), null, 2);
+    return truncateText(JSON.stringify(JSON.parse(fs.readFileSync(file, 'utf8')), null, 2));
   } catch (_) {
     return truncateText(fs.readFileSync(file, 'utf8'));
   }
 }
 
-function tailTextFile(file, maxLines = 80) {
+function readTextTail(file, maxBytes = 512 * 1024) {
   if (!fs.existsSync(file)) {
+    return { text: null, truncated: false };
+  }
+  let fd = null;
+  try {
+    const stat = fs.statSync(file);
+    const bytesToRead = Math.min(stat.size, maxBytes);
+    const start = Math.max(0, stat.size - bytesToRead);
+    const buffer = Buffer.allocUnsafe(bytesToRead);
+    fd = fs.openSync(file, 'r');
+    const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, start);
+    return {
+      text: buffer.subarray(0, bytesRead).toString('utf8'),
+      truncated: start > 0
+    };
+  } catch (_) {
+    return { text: null, truncated: false };
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch (_) {}
+    }
+  }
+}
+
+function tailTextFile(file, maxLines = 80) {
+  const tail = readTextTail(file);
+  if (tail.text === null) {
     return null;
   }
-  const text = fs.readFileSync(file, 'utf8');
-  const lines = text.split('\n');
-  return truncateText(lines.slice(-maxLines).join('\n'));
+  const lines = tail.text.split('\n');
+  const selected = lines.slice(-maxLines);
+  if (tail.truncated && selected.length) {
+    selected.unshift('...[earlier log content omitted]');
+  }
+  return truncateText(selected.join('\n'));
 }
 
 function readJsonLinesFile(file, maxEntries = 80) {
-  if (!file || !fs.existsSync(file)) {
+  if (!file) {
     return [];
   }
   try {
-    const lines = fs.readFileSync(file, 'utf8')
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean)
-      .slice(-maxEntries);
+    const tail = readTextTail(file, 1024 * 1024);
+    if (tail.text === null) {
+      return [];
+    }
+    let lines = tail.text.split('\n');
+    if (tail.truncated && lines.length) {
+      lines = lines.slice(1);
+    }
+    lines = lines.map((line) => line.trim()).filter(Boolean).slice(-maxEntries);
     return lines.map((line) => {
       try {
         return JSON.parse(line);
@@ -3201,12 +3355,32 @@ async function reconnectManagedWebsockets() {
 
 function startDashboardServer(preferredPort) {
   return new Promise((resolve, reject) => {
+    const sendDashboardError = (res, err, wantsJson = true) => {
+      const message = describeError(err);
+      appendGlobalActivityLog('dashboard', 'request.failed', { error: message }, 'error');
+      if (res.headersSent) {
+        res.end('');
+        return;
+      }
+      res.statusCode = 500;
+      if (wantsJson) {
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ success: false, message }));
+      } else {
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        res.end('Dashboard error: ' + message);
+      }
+    };
     const server = http.createServer(async (req, res) => {
       const requestUrl = new URL(req.url, 'http://' + DASHBOARD_HOST + ':' + (runtimeState.service.dashboardPort || preferredPort));
       if (req.method === 'GET' && requestUrl.pathname === '/api/state') {
-        res.statusCode = 200;
-        res.setHeader('Content-Type', 'application/json');
-        res.end(JSON.stringify(collectDashboardSnapshot(), null, 2));
+        try {
+          res.statusCode = 200;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify(collectDashboardSnapshot(), null, 2));
+        } catch (err) {
+          sendDashboardError(res, err, true);
+        }
         return;
       }
 
@@ -3216,51 +3390,59 @@ function startDashboardServer(preferredPort) {
           body += chunk.toString();
         });
         req.on('end', async () => {
-          const params = new URLSearchParams(body);
-          const action = params.get('action');
-          let actionResult = null;
-          runtimeState.lastAction = {
-            action,
-            at: new Date().toISOString()
-          };
-          if (action === 'export-issues') {
-            const bundlePath = exportIssueBundle(collectDashboardSnapshot());
-            actionResult = { bundlePath };
-            runtimeState.lastAction.bundlePath = bundlePath;
-          } else if (action === 'rescan-repos') {
-            recordDiscoverySummary(discoverAccountRepos());
-          } else if (action === 'open-tmux') {
-            openTmuxSessionForUser();
-          } else if (action === 'start-tmux') {
-            ensureTmuxSession(os.homedir());
-          } else if (action === 'stop-tmux') {
-            killTmuxSession();
-          } else if (action === 'reconnect-websockets') {
-            await reconnectManagedWebsockets();
-          }
           const wantsJson = String(req.headers.accept || '').includes('application/json');
-          if (wantsJson) {
-            res.statusCode = 200;
-            res.setHeader('Content-Type', 'application/json');
-            res.end(JSON.stringify({
-              success: true,
+          try {
+            const params = new URLSearchParams(body);
+            const action = params.get('action');
+            let actionResult = null;
+            runtimeState.lastAction = {
               action,
-              result: actionResult,
-              state: collectDashboardSnapshot()
-            }));
-            return;
+              at: new Date().toISOString()
+            };
+            if (action === 'export-issues') {
+              const bundlePath = exportIssueBundle(collectDashboardSnapshot());
+              actionResult = { bundlePath };
+              runtimeState.lastAction.bundlePath = bundlePath;
+            } else if (action === 'rescan-repos') {
+              recordDiscoverySummary(discoverAccountRepos());
+            } else if (action === 'open-tmux') {
+              openTmuxSessionForUser();
+            } else if (action === 'start-tmux') {
+              ensureTmuxSession(os.homedir());
+            } else if (action === 'stop-tmux') {
+              killTmuxSession();
+            } else if (action === 'reconnect-websockets') {
+              await reconnectManagedWebsockets();
+            }
+            if (wantsJson) {
+              res.statusCode = 200;
+              res.setHeader('Content-Type', 'application/json');
+              res.end(JSON.stringify({
+                success: true,
+                action,
+                result: actionResult,
+                state: collectDashboardSnapshot()
+              }));
+              return;
+            }
+            res.statusCode = 302;
+            res.setHeader('Location', '/');
+            res.end('');
+          } catch (err) {
+            sendDashboardError(res, err, wantsJson);
           }
-          res.statusCode = 302;
-          res.setHeader('Location', '/');
-          res.end('');
         });
         return;
       }
 
       if (req.method === 'GET' && requestUrl.pathname === '/') {
-        res.statusCode = 200;
-        res.setHeader('Content-Type', 'text/html; charset=utf-8');
-        res.end(renderDashboardHtml(collectDashboardSnapshot()));
+        try {
+          res.statusCode = 200;
+          res.setHeader('Content-Type', 'text/html; charset=utf-8');
+          res.end(renderDashboardHtml(collectDashboardSnapshot()));
+        } catch (err) {
+          sendDashboardError(res, err, false);
+        }
         return;
       }
 
@@ -4550,7 +4732,8 @@ async function main() {
     console.log('  remits-cli data-mode [set test|prod]');
     console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
     console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
-    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod]');
+    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--timeout-ms 60000] [--async true --wait true]');
+    console.log('  remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
     console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
     console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.80",
+  "version": "0.1.83",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -5,6 +5,85 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 
 # remits-cli
 
+## Table of Contents
+
+- Line 89: Account Targeting Model
+- Line 112: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
+- Line 118: How the platform reconciles the repo into the database (the mechanism you must understand)
+- Line 144: The surfaces and their intended behavior
+- Line 166: Intended workflows
+- Line 185: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
+- Line 195: If something looks wrong — stop, don't paper over
+- Line 219: Required Local Index Reads
+- Line 253: Big Picture: How remits-cli State Is Organized
+- Line 283: Support Ticket Mental Model
+- Line 319: Efficiency Rules
+- Line 331: Account Repository Index
+- Line 356: Two Workflows
+- Line 363: Test Mode vs Prod Mode
+- Line 395: Platform Mental Model: Front Stage vs Back Stage
+- Line 402: Documents vs Records
+- Line 412: HTTP Audits
+- Line 466: Record `content` / Context Mental Model
+- Line 486: Provenance Fields
+- Line 504: Why Persisted Context Looks Different From Runtime Context
+- Line 525: Investigation Rule for Record Context
+- Line 540: AI Request Response Records
+- Line 547: AI Session Groupings
+- Line 562: Correlation Keys
+- Line 568: Node Reference Table
+- Line 578: Repository vs External Context
+- Line 585: Getting Started
+- Line 587: Authentication
+- Line 600: Host vs Data Mode
+- Line 619: Tool Execution Lifecycle
+- Line 660: Data Mode
+- Line 670: Development Workflow
+- Line 672: The Golden Rule: Writing Code Is Not Finishing the Job
+- Line 684: The Development Fast Loop
+- Line 843: User Confirmation Preferences
+- Line 853: Component Resolution: Staging Cache vs DB (which "version" actually runs)
+- Line 859: The two source layers + the compile cache
+- Line 870: Staging cache key format
+- Line 883: How the platform picks staged vs DB (the compile signature)
+- Line 900: When staged overrides apply
+- Line 924: Diagnosing which version is in play
+- Line 945: Stage / commit / clear with the MCP tools
+- Line 969: Stale after sync / commit (the in-memory compile cache)
+- Line 979: Production Support Workflow
+- Line 987: Investigation Strategy
+- Line 1017: Presenting Findings
+- Line 1025: Verifying a Production Issue Fix
+- Line 1038: Tool Reference
+- Line 1040: Execute a Tool
+- Line 1067: `mcp_account_view`
+- Line 1074: `mcp_firestore_search`
+- Line 1112: `mcp_object_activity`
+- Line 1121: `mcp_record_listing`
+- Line 1146: `mcp_record_view`
+- Line 1159: `mcp_ai_session_search`
+- Line 1191: `mcp_run_action`
+- Line 1229: `mcp_run_agent`
+- Line 1267: `mcp_system_logs`
+- Line 1290: `mcp_component_view`
+- Line 1308: `mcp_component_grep`
+- Line 1321: `mcp_support_ticket`
+- Line 1370: `mcp_run_test`
+- Line 1379: `mcp_component_edit`
+- Line 1394: `mcp_component_create`
+- Line 1408: `mcp_component_commit`
+- Line 1416: `mcp_cache`
+- Line 1428: Multi-Session Support
+- Line 1448: Persistent Service, Control Center, and Agent Dispatch
+- Line 1457: Starting the Service
+- Line 1483: Control Center
+- Line 1498: Agent Dispatch
+- Line 1519: Configuring the Preferred Agent
+- Line 1530: Local State Files
+- Line 1578: Command Reference
+- Line 1605: Troubleshooting
+- Line 1632: When Something Doesn't Work as Expected
+
 `remits-cli` is the brainstem for both **development** and **production support**. You might run it inside an account repository (where `account-info.json` and `/components` already exist) or from outside any repo when a user needs help on another account. Your users are business professionals — they think in terms of what they can see in a browser.
 
 ## Account Targeting Model
@@ -467,10 +546,14 @@ The goal of an investigation is not only to find a suspicious record. It is to e
 
 ### AI Session Groupings
 
-- For front-stage investigation and tuning work, use `mcp_ai_session_search` to search persisted AI session groupings and export grouping detail in human-readable form.
+- For front-stage investigation and tuning work, use `mcp_ai_session_search` to search persisted AI session groupings and audit grouping detail. A grouping spans every related session that shares one grouping ID — the agent turns plus its guardrail and internal `ai()` calls.
 - This tool mirrors the admin AI Groupings UI:
-  - search filters: `search`, `sessionId`, `groupingId`, `user`, `account`, `agent`, `scope`
-  - detail/export sections: `full`, `conversation_messages`, `system`, `response`, `tools`
+  - search filters: `search`, `sessionId`, `groupingId`, `user`, `account`, `agent`, `scope`, `status`
+  - detail parts: `index`, `stats`, `transcript`, `tool_calls`, plus the record sections `full`, `conversation_messages`, `system`, `response`, `tools`
+- Audit a grouping with a **map → open** workflow, not a whole-detail dump (which re-sends the same cumulative prompt on every record and burns tokens):
+  1. `action:"detail"` + `summaryOnly:true` (or `parts:["index"]`) → the MAP, no payloads: a per-request record list (id, callType, agent, model, tokens, raw `finishReason`, `toolCallsRequested`, `responsePreview`) + a timeline of interleaved tool-call ids. Same rows the admin grouping detail shows.
+  2. Then open only what you need: `recordIds:[<id>]` + `parts:["conversation_messages"|"system"|"response"|"tools"|"full"]` for one record; `parts:["transcript"]` for the deduplicated end-to-end conversation (each message once, in order); `parts:["tool_calls"]` (then `toolCallIds:[<id>]`) for the exact input/result a tool produced.
+- **Tool-result lens — do not conflate the two:** `parts:["tool_calls"]`/`toolCallIds` returns what a tool **PRODUCED** (the exact `ai_tool_call` result). That is **not** necessarily what the model saw next turn — front-stage control keys (`_offload`/`_offloadSynopsis`, `_hideResult`, `_message`, `_supersedes`/`_evict*`, `_stop`, …) can offload, hide, summarize, or collapse the re-provided value. To see what the AI **CONSUMED**, read the tool_result inside `conversation_messages`/`transcript`. (`resultChars` in the tool_calls index flags the large results most likely to have been transformed.)
 - Use it when you need to understand:
   - what prompts, system instructions, tools, and responses were actually sent for a session
   - how an Agent behaved across one grouping, including prompt-tuning and tool-usage opportunities
@@ -537,6 +620,60 @@ remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-
 
 Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
 
+### Tool Execution Lifecycle
+
+`remits-cli tool` supports both synchronous and asynchronous execution. Use normal synchronous execution
+for quick investigation tools:
+
+```bash
+remits-cli tool --name "mcp_account_view" --input '{"accountId": 37}' --data-mode prod
+```
+
+**There are two independent async mechanisms — do not confuse or stack them:**
+
+1. **The tool's own async mode** (`mcp_run_action` / `mcp_run_agent`, via `executionMode:"async"` in the
+   tool input). The tool spawns the long work server-side and **returns immediately in the same HTTP
+   response** with its own run identifiers — `actionRunId` (or `agentRunId`) and, for agents, a stable
+   `sessionId`. You poll it with the tool's **own** status protocol (`controlAction:"status"`). This is the
+   preferred path for long Actions/Agents, because the run ids come back on the very first call.
+
+2. **The CLI transport async** (`--async true`). This wraps *any* tool call in a background server task and
+   returns a CLI-level `callId` immediately, which you poll with `remits-cli tool status --call-id`. Use it
+   for long tools that do **not** have their own async mode. Its start response carries `callId`,
+   `status:"running"`, `threadGroupingId`, `accountId`, `branchName`, and `dataMode` — but **not** any
+   tool-specific ids, because the tool has not run yet; those arrive inside the `result` of the polled
+   completed status.
+
+For `mcp_run_action` / `mcp_run_agent`, prefer mechanism (1) alone — it already makes the call non-blocking
+**and** returns the run ids up front. Pass your own `actionRunId`/`agentRunId` so you can poll it
+deterministically:
+
+```bash
+remits-cli tool --name "mcp_run_action" --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Every tool response is saved to `./.remits-cli/tool-responses/<callId>.json`.
+
+Poll a CLI-transport async call (mechanism 2) by call id:
+
+```bash
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+Pass `--wait true` to have the CLI process poll locally until the transport call completes (short polling
+requests instead of one long HTTP connection):
+
+```bash
+remits-cli tool --name "some_long_tool_without_its_own_async" --async true --wait true --input '{...}' --data-mode prod
+```
+
+Stacking both (`--async true` **and** `executionMode:"async"`) works but is redundant: the tool's
+`actionRunId`/`agentRunId`/`sessionId` then appear only in the polled completed `result`, not in the CLI
+start response — which is why the start response looks "incomplete." Pick one mechanism.
+
+`--timeout-ms <ms>` controls the per-request HTTP timeout. Prefer async execution over a large timeout for
+multi-minute work so the server task is not tied to one HTTP connection.
+
 ### Data Mode
 
 Controls whether you work with test data or production data. **Default is `test`.**
@@ -640,6 +777,15 @@ For changes to Readers, Actions, or Rules that process data rather than display
 remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "collection": "<collection>", "limit": 5, "sort": [{"field": "_lastModifiedAt", "direction": "DESC"}]}'
 ```
 
+For long-running backend verification, use the Action runner's own async mode (`executionMode:"async"`) and
+poll by `actionRunId` rather than holding a single request open (see "Tool Execution Lifecycle" for why not
+to also stack the CLI `--async` flag):
+
+```bash
+remits-cli tool --name "mcp_run_action" --input '{"accountId": <ID>, "actionId": <ACTION_ID>, "executionMode": "async", "actionInput": {...}}' --data-mode test
+# then poll:  {"controlAction":"status","accountId": <ID>, "actionRunId":"<actionRunId>"}
+```
+
 #### Step 5: Iterate If Needed
 
 If verification reveals issues, repeat the loop: **edit → stage → run**. Every iteration must include a fresh `remits-cli components stage` after your edits and before the next test run. Never run a test immediately after editing without staging first — the platform will execute the previous version, not your latest changes.
@@ -918,6 +1064,19 @@ remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collec
 
 Response saved to `./.remits-cli/tool-responses/<callId>.json`. Read the file to see results.
 
+For long-running Action/Agent runners, use the tool's own async mode (`executionMode:"async"`), which returns
+the `actionRunId`/`agentRunId` (and, for agents, `sessionId`) immediately:
+
+```bash
+remits-cli tool --name "mcp_run_action" --input '{"accountId":37,"actionName":"Rebuild Invoice","executionMode":"async","actionInput":{"invoiceId":"abc"}}' --data-mode prod
+# poll by run id:  {"controlAction":"status","accountId":37,"actionRunId":"<actionRunId>"}
+```
+
+For long tools that lack their own async mode, use the CLI transport async (`--async true`), optionally with
+`--wait true` to poll locally, and `remits-cli tool status --call-id <callId>`. Do not stack both mechanisms
+(see "Tool Execution Lifecycle"). Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is
+not a replacement for async mode on multi-minute workflows.
+
 **Account-id precedence for tool calls.** When the CLI and the tool input both carry an account id, the server resolves them in this order:
 
 1. Explicit `--account-id <ID>` flag — always wins. Use this when you want to be certain the tool runs against a specific account (and the user's session covers it).
@@ -1032,7 +1191,7 @@ Front-stage references:
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `action` | no | `search` (default) or `detail` |
+| `action` | no | `search` (default), `detail`, or session control `pause`/`unpause`/`interrupt` |
 | `search` | no | Broad text match against session IDs and grouping IDs |
 | `sessionId` | no | Session ID filter in search mode, or grouping/session key in detail mode |
 | `groupingId` | no | Grouping ID filter in search mode, or grouping key in detail mode |
@@ -1041,14 +1200,98 @@ Front-stage references:
 | `account` | no | Account filter |
 | `agent` | no | Agent filter |
 | `scope` | no | `all`, `agents`, or `internal` |
+| `status` | no | Search mode: filter by live runtime status, comma-separated (e.g. `paused,interrupted`) |
+| `scanLimit` | no | Search mode: window scanned when `status` is set. Default `100`, max `500` |
 | `page` | no | 1-based page number. Default: `1` |
 | `pageSize` | no | Results per page. Default: `25`, max: `100` |
-| `recordIds` | no | Optional request/response record IDs to export from the selected grouping |
-| `parts` | no | Export sections: `full`, `conversation_messages`, `system`, `response`, `tools` |
+| `summaryOnly` | no | Detail mode: return the MAP (record index + stats + timeline) with no payloads. Same as `parts:["index"]` |
+| `parts` | no | Detail parts: `index`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
 | `sections` | no | Alias for `parts` |
+| `recordIds` | no | Detail mode: open only these request/response record IDs |
+| `toolCallIds` | no | Detail mode: return the FULL exact input/result from `ai_tool_call` for these tool-call ids (what the tool PRODUCED — see the lens caveat) |
 | `consolidateContext` | no | When `true`, collapses repeated XML-like prompt context into a consolidated section |
 
-Use `action: "search"` first, then `action: "detail"` with the returned `groupingKey` when you want the human-readable export for investigation or tuning.
+Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
+
+### `mcp_run_action`
+Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
+staged-vs-DB provenance in the result.
+
+Use direct mode only for quick Actions:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Use the tool's own async mode for long-running Action execution — it returns immediately with an
+`actionRunId`. Pass your **own** `actionRunId` so you can poll deterministically without first parsing it out
+of the start response. Do **not** also pass the CLI `--async` flag; that only buries these ids behind the
+transport layer:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
+`accountId` + `actionRunId`:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"controlAction":"status","accountId":49,"actionRunId":"my-stable-run-id"}' --data-mode prod
+```
+
+> This poll is a normal `remits-cli tool --name mcp_run_action` call — **not** `remits-cli tool status`,
+> which polls the CLI-transport `--async` `callId` (a different mechanism). Use `controlAction:"status"`
+> (rather than `command:"status"`) inside the input so it is never conflated with the transport-level status.
+> If you started the run with a different `userId`, include that same `userId` in the poll (the run's status
+> is keyed by account + user + `actionRunId`; it otherwise defaults to the current user).
+
+For job-style Actions only (`Action.job == true`), prefer `executionMode:"event"` when you want the durable
+Event lifecycle, Event status, and platform recovery behavior. Event mode is inherently async; poll it the
+same way (`controlAction:"status"` + `actionRunId`) — the status resolves the backing Event's terminal state:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"event","actionRunId":"my-stable-run-id","actionInput":{}}' --data-mode prod
+```
+
+Returned fields on the async/event start: `actionRunId`, `status:"running"`, `executionMode`,
+`threadGroupingId`, `componentSource`, `componentSignature`, and (event mode) `eventId`/`eventStatus`. The
+`status` poll adds `result` on completion, or `message`/`error` on failure.
+
+### `mcp_run_agent`
+Run one real Agent turn on a target account. The Agent hooks and tools execute for real against the requested
+`dataMode`; pass `dataMode:"test"` for safer tuning.
+
+Use direct mode only for short turns:
+
+```bash
+remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Summarize this invoice context","executionMode":"direct"}' --data-mode prod
+```
+
+Use the tool's own async mode for autonomous or long Agent turns. It returns immediately with both an
+`agentRunId` and a single, stable `sessionId` — the **same** id the running session uses, so you can inspect
+it right away. Pass your own `agentRunId` for deterministic polling. Do **not** also pass the CLI `--async`
+flag (that only delays these ids into a polled result):
+
+```bash
+remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Audit this invoice","executionMode":"async","agentRunId":"my-stable-run-id","context":{"invoiceId":"..."}}' --data-mode prod
+```
+
+Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
+`accountId` + `agentRunId` (this is a normal `mcp_run_agent` call, **not** `remits-cli tool status`):
+
+```bash
+remits-cli tool --name mcp_run_agent --input '{"controlAction":"status","accountId":49,"agentRunId":"my-stable-run-id"}' --data-mode prod
+```
+
+Inspect the live/persisted AI session at any time using the `sessionId` returned by the start call (it is the
+run's real, canonical session id):
+
+```bash
+remits-cli tool --name mcp_ai_session_search --input '{"action":"detail","sessionId":"<sessionId>","summaryOnly":true}' --data-mode prod
+```
+
+Key returned fields: `agentRunId`, `sessionId`, `status`, `threadGroupingId`, runtime pause/interruption
+hints, `lastAssistantMessage`, `toolCallCount`, `result`, `message`, and `error`.
 
 ### `mcp_system_logs`
 Query Cloud Run service logs.
@@ -1380,7 +1623,8 @@ remits-cli components commit [--message "msg"] [--data-mode test|prod]
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod]
 remits-cli tools [--branch <name>] [--data-mode test|prod]
-remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod]
+remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--timeout-ms 60000] [--async true --wait true]
+remits-cli tool status --call-id <callId> [--data-mode test|prod]
 ```
 
 For tests specifically:
@@ -1402,6 +1646,8 @@ For tests specifically:
 | 500 / `Internal Server Error` from Remits | Stop normal task work. Capture the exact command, error, and response artifact, then escalate to a Remits system admin. Do not invent a workaround. |
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
 | Tool response missing | Check `./.remits-cli/tool-responses/` |
+| Long-running tool times out | For `mcp_run_action`/`mcp_run_agent`, use the tool's own `executionMode:"async"` and poll with a `controlAction:"status"` call (see "Tool Execution Lifecycle"). For other long tools without their own async, use `remits-cli tool --async true` and poll `remits-cli tool status --call-id <callId>`. `--timeout-ms` only adjusts the per-request HTTP timeout; it is not a substitute for async. |
+| Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/tool-responses/<callId>.json` for the returned `actionRunId`/`agentRunId`/`sessionId`/`threadGroupingId`. Re-poll the run with a `controlAction:"status"` call carrying that `actionRunId`/`agentRunId`, or inspect the agent session via `mcp_ai_session_search` with the `sessionId`. |
 | Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB. `commit` to make it durable. See "Component Resolution". |
 | New source shown by `mcp_component_view` but old behavior persists after sync/commit | The compile cache (`CLOSURE_CACHE`) is keyed by `version:<N>:<sourceHash12>`, so a source change on the same version now invalidates it automatically — a run right after sync/commit picks up the new source. If old behavior still persists, confirm the run actually hit the synced instance and that no staged override is still shadowing DB (`remits-cli components status`). |
 | Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, the `mcp_component_edit` tool on that instance is on an old/cached version. Inspect with `mcp_cache`. |