@remits/remits-cli 0.1.139 → 0.1.141

package/package.json

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

package/skills/remits-cli/references/component-integrity.md

@@ -71,6 +71,9 @@ local working tree** — and:
 > want it versioned in git, addressable by a stable id, or discoverable by another agent, it is not
 > auxiliary. Symptom to recognize: *"I added `new_Foo.groovy`, synced, and it neither appeared on the account
 > nor got renamed."* Check the sidecar's `auxiliary` flag first.
+>
+> For durable Test suites that should be part of the promotion confirmation set, keep `auxiliary: false` and
+> add `regression: true`. The admin Test runner can select only those suites without hand-picking every case.
 
 **The single most important consequence:** the id in a component's **filename is load-bearing**. If a file's id
 no longer matches its DB row (a renumber or move across ids), the next sync will **create a duplicate at the

package/skills/remits-cli/references/development-loop.md

@@ -556,13 +556,20 @@ remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "coll
 
 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 `command-reference.md` → *Tool Execution Lifecycle* for why not
-to also stack the CLI `--async` flag):
+to also stack the CLI `--async` flag). For job-style Actions where you need durable Event lifecycle,
+recovery, or interruption, use `executionMode:"event"` instead and poll the same way:
 
 ```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>"}
 ```
 
+Read the returned world and lifecycle fields before deciding what happened. `dataMode` is the data lane
+the run actually used; `componentSource` / `componentBranch` / `stagingLane` say which source world ran.
+For event mode, `awaiting_delivery` means the Event exists but has not been claimed yet, not that the
+Action failed. If that state persists, use `mcp_event_diagnostics` on the returned `eventId` instead of
+guessing that the queue, Action source, or data lane is wrong.
+
 #### 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.

package/skills/remits-cli/references/tool-reference.md

@@ -485,9 +485,23 @@ same way (`controlAction:"status"` + `actionRunId`) — the status resolves the
 remits-cli tool --account-id 21 --as-account 49 --target-account 49 --name mcp_run_action --input '{"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.
+Event-mode start means "the Event was created and dispatched", not "the Action has finished". Returned
+fields on the async/event start: `actionRunId`, `status:"running"`, `executionMode`, `threadGroupingId`,
+`componentSource`, `componentSignature`, and (event mode) `eventId`/`eventStatus` plus `dispatchMode` when
+available. The `status` poll adds `result` on async completion, or `message`/`error` on failure.
+
+Event-mode status values to read deliberately:
+
+| `status` | Meaning | What to do |
+|---|---|---|
+| `awaiting_delivery` | The backing Event exists but has not been claimed by a worker yet (`eventStatus` is usually `PENDING`/`QUEUED`, `eventStartTime` is null) | Wait briefly, then inspect `eventDelivery` / `eventNode`; use `mcp_event_diagnostics` if it stays there |
+| `running` | The Event was claimed and is processing | Wait or inspect logs/traces by `threadGroupingId` |
+| `completed` | The backing Event reached `SUCCESS` | Read the Action's persisted outputs / activity trail |
+| `failed` | The backing Event reached `FAILURE`, `CANCELED`, or `INTERRUPTED` | Read `eventStatus`, `errorMessage`, alerts, and `mcp_event_diagnostics` |
+
+If an old run is stuck at `QUEUED` and never reports `awaiting_delivery` or fresh delivery fields, start a
+new event-mode run after confirming the System Account tools are synced. Do not keep polling a run that was
+created by an older tool version whose dispatch path already missed delivery.
 
 Every response (describe, direct, async start, and failures) also states the world the run resolved:
 `executionAccountId`, `componentOwnerAccountId`, `componentSource` (`staged` / `variant` / `db`),
@@ -501,7 +515,7 @@ closest existing names; check that the lane named there is the one you staged in
 
 > **In event mode the EVENT is the source of truth, not the promise.** `status` is driven by the Event's
 > own state; the value the dispatch call returned is reported separately as `dispatchResult` and is **not**
-> the Action's result. Read `eventStatus` for the outcome.
+> the Action's result. Read `eventStatus`, `eventStartTime`, and `eventDelivery` for the lifecycle outcome.
 
 #### Stopping a run — `controlAction:'interrupt'`
 

package/skills/remits-cli/references/troubleshooting.md

@@ -28,6 +28,8 @@
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/shared/tools/tools.json` with latest schemas. |
 | Tool response missing | Run `remits-cli doctor local-state`, then check `./.remits-cli/actors/<local-agent>/tool-responses/` and any legacy flat `./.remits-cli/tool-responses/` fallback it reports. |
 | 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 `command-reference.md` → *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. |
+| `mcp_run_action` event-mode status is `awaiting_delivery` | The backing Event row exists but no worker has claimed it yet. This is a lifecycle state, not an Action failure and not proof of the wrong data lane. Poll once or twice; if it persists, run `mcp_event_diagnostics` with the returned `eventId` and inspect `eventDelivery`, `eventStartTime`, `eventNode`, and queue/action-node health. |
+| An old `mcp_run_action` event-mode run is stuck `QUEUED` | Do not keep trying to recover the stale run in place. Confirm the System Account tools are synced, start a fresh run with a stable `actionRunId`, and poll that. Interrupt/cancel the stale Event if it would confuse later investigation. |
 | `components sync` timed out, or you are unsure whether overlays advanced | Treat the result as **unknown**, not failed. Run `remits-cli components sync doctor` and `remits-cli components promotion --branch <branch> --no-fail`. Do not put `components sync` in a polling loop and do not use shell detach tricks; observation may poll, writes may not. |
 | Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` for the returned `actionRunId`/`agentRunId`/`sessionId`/`threadGroupingId` (or the legacy flat fallback if `doctor local-state` reports it there). 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 (trunk, or the account's subscribed variant). `commit` to make it durable. See `component-resolution.md`. |