@remits/remits-cli 0.1.81 → 0.1.83

package/index.js

@@ -2810,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);
@@ -3313,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;
       }
 
@@ -3328,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;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.81",
+  "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

@@ -546,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
@@ -618,44 +622,57 @@ Do not assume `--data-mode prod` implies the deployed prod host, or that `--data
 
 ### Tool Execution Lifecycle
 
-`remits-cli tool` supports both synchronous and asynchronous execution.
-
-Use normal synchronous execution for quick investigation tools:
+`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
 ```
 
-Use asynchronous execution for long-running tools, especially Action or Agent runners that can perform OCR,
-AI calls, document writes, or multi-step workflows:
+**There are two independent async mechanisms — do not confuse or stack them:**
 
-```bash
-remits-cli tool --name "mcp_run_action" --async true --input '{"accountId":49,"actionId":200,"executionMode":"async","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
-```
+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.
 
-Async starts return immediately with a stable `callId`, `status:"running"`, `threadGroupingId`,
-`accountId`, `branchName`, `dataMode`, and component provenance when available. The full response is saved to:
+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.
 
-```text
-./.remits-cli/tool-responses/<callId>.json
+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
 ```
 
-Poll or resume an async CLI tool call by call id:
+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
 ```
 
-If you want the CLI process to wait locally while using short polling requests instead of one long HTTP
-request, pass `--wait true`:
+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 "mcp_run_agent" --async true --wait true --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"...","executionMode":"async"}' --data-mode prod
+remits-cli tool --name "some_long_tool_without_its_own_async" --async true --wait true --input '{...}' --data-mode prod
 ```
 
-`--timeout-ms <ms>` controls the HTTP timeout for each individual CLI request. It is useful for slower
-synchronous tools, but for multi-minute Actions/Agents prefer `--async true` so the server-side work is not
-tied to one HTTP connection.
+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
 
@@ -760,11 +777,13 @@ 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, prefer async tool execution and poll by `callId` rather than relying on
-a single request to stay open:
+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" --async true --wait true --input '{"accountId": <ID>, "actionId": <ACTION_ID>, "executionMode": "async", "actionInput": {...}}' --data-mode test
+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
@@ -1045,16 +1064,18 @@ 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 tools, use async mode:
+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" --async true --input '{"accountId":37,"actionName":"Rebuild Invoice","executionMode":"async","actionInput":{"invoiceId":"abc"}}' --data-mode prod
-remits-cli tool status --call-id <callId> --data-mode prod
+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>"}
 ```
 
-Use `--wait true` when you want the CLI to poll until completion and still avoid a single long HTTP request.
-Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is not a replacement for async mode
-on multi-minute workflows.
+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:
 
@@ -1170,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 |
@@ -1179,14 +1200,18 @@ 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
@@ -1198,33 +1223,39 @@ Use direct mode only for quick Actions:
 remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
 ```
 
-Use async mode for long-running direct Action execution:
+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 --async true --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"optional-stable-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+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 the CLI call:
+Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
+`accountId` + `actionRunId`:
 
 ```bash
-remits-cli tool status --call-id <callId> --data-mode prod
+remits-cli tool --name mcp_run_action --input '{"controlAction":"status","accountId":49,"actionRunId":"my-stable-run-id"}' --data-mode prod
 ```
 
-Or poll the tool-level run from another tool/agent context:
+> 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).
 
-```json
-{"command":"status","accountId":49,"actionRunId":"<actionRunId>"}
-```
-
-For job-style Actions (`Action.job == true`), prefer `executionMode:"event"` when you want the durable Event
-lifecycle, Event status, and platform recovery behavior:
+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:
 
-```json
-{"accountId":49,"actionId":200,"executionMode":"event","actionInput":{...}}
+```bash
+remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"event","actionRunId":"my-stable-run-id","actionInput":{}}' --data-mode prod
 ```
 
-Key returned fields: `actionRunId`, `status`, `executionMode`, `threadGroupingId`, `eventId`/`eventStatus`
-for Event mode, `componentSource`, `componentSignature`, `result`, `message`, and `error`.
+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
@@ -1236,26 +1267,24 @@ Use direct mode only for short turns:
 remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Summarize this invoice context","executionMode":"direct"}' --data-mode prod
 ```
 
-Use async mode for autonomous or long Agent turns. Async mode returns both an `agentRunId` and a concrete
-`sessionId` immediately:
+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 --async true --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Audit this invoice","executionMode":"async","context":{"invoiceId":"..."}}' --data-mode prod
+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
 ```
 
-Poll the CLI call:
+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 status --call-id <callId> --data-mode prod
-```
-
-Or poll the tool-level agent run:
-
-```json
-{"command":"status","accountId":49,"agentRunId":"<agentRunId>"}
+remits-cli tool --name mcp_run_agent --input '{"controlAction":"status","accountId":49,"agentRunId":"my-stable-run-id"}' --data-mode prod
 ```
 
-Inspect the AI session while it is running or after it completes:
+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
@@ -1617,8 +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 | Prefer `remits-cli tool --async true` and poll with `remits-cli tool status --call-id <callId>`. Use `--timeout-ms` only for the per-request HTTP timeout. |
-| Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/tool-responses/<callId>.json` for the returned `threadGroupingId`, `actionRunId`, `agentRunId`, or `sessionId`, then poll status or inspect with `mcp_ai_session_search`. |
+| 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`. |