@remits/remits-cli 0.1.163 → 0.1.165

package/README.md

@@ -139,6 +139,10 @@ remits-cli install --skills --overwrite true
 - The service groups sessions by `baseUrl` so one websocket connection can service multiple authenticated accounts on the same Remits environment.
 - Websocket subscriptions are deduplicated by user topic. If multiple authenticated accounts share the same websocket topic, the listener subscribes once and maps that topic back to all related accounts.
 - The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections.
+- Terminal server authentication/authorization errors suspend WebSocket retries and show
+  `authentication_required`. Reauthenticate to replace the managed client's credentials; the watchdog
+  does not revive rejected credentials. Transient failures use jittered exponential backoff up to
+  60 seconds. Test watchers keep HTTP polling; restart local-AI workers after reauthentication.
 - If the machine sleeps, the network drops, or auth sessions change while the daemon is already running, the service now attempts to reconnect and resubscribe automatically once connectivity returns.
 - Support tickets are the primary unit of dispatched work. A serving agent launches one fresh worker process per routed ticket.
 - Agent sessions register themselves with `remits-cli agent register` or `remits-cli agent serve`; `serve` also starts the local supervisor.

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- L124  Sessions, Account Resolution, And Production Guards
-- L630  Local State, Workspaces, And Verification Evidence
-- L2668  Account Repos, Guide Sync, And Platform Repo
-- L3508  Component Discovery And HTTP Logging
-- L4276  Skill Delivery And TOC Resolution
-- L4591  Auth And Component Staging
-- L5223  Component Summaries, Status, And Sync Gates
-- L7547  Branches, Promotion, Commit, And Test Runs
-- L9791  Tokens, Tools, Verification, And Config
-- L11308  Service Dashboard And WebSocket Listener
-- L13808  Agent And Ticket Workflows
-- L18069  Help, Auto Update, And Command Dispatch
+- L125  Sessions, Account Resolution, And Production Guards
+- L631  Local State, Workspaces, And Verification Evidence
+- L2669  Account Repos, Guide Sync, And Platform Repo
+- L3509  Component Discovery And HTTP Logging
+- L4279  Skill Delivery And TOC Resolution
+- L4594  Auth And Component Staging
+- L5226  Component Summaries, Status, And Sync Gates
+- L7550  Branches, Promotion, Commit, And Test Runs
+- L9813  Tokens, Tools, Verification, And Config
+- L11330  Service Dashboard And WebSocket Listener
+- L13840  Agent And Ticket Workflows
+- L18101  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -32,6 +32,7 @@ const axios = require('axios');
 const openModule = require('open');
 const { Client } = require('@stomp/stompjs');
 const WebSocket = require('ws');
+const { installWebsocketRetry } = require('./lib/websocket-retry');
 const YAML = require('yaml');
 
 Object.assign(global, { WebSocket });
@@ -898,7 +899,7 @@ function localStateWarnings(cwd, flags = {}) {
       .sort((a, b) => Date.parse(b.updatedAt || 0) - Date.parse(a.updatedAt || 0));
     const shown = recent.slice(0, 3).map((a) => a.actor);
     const stale = report.foreignActors.length - recent.length;
-    const setOne = 'Name this one with --actor <name> (or REMITS_AGENT_ID) if another agent shares this checkout.';
+    const setOne = 'Name this one with --local-agent <name> (or REMITS_LOCAL_AGENT_ID) if another agent shares this checkout; REMITS_AGENT_ID also declares agent identity to the platform.';
     const pruneHint = stale
       ? stale + ' spent actor dir(s) (idle, or left behind by finished processes) can be cleared with `remits-cli doctor local-state --prune-actors`.'
       : '';
@@ -3668,7 +3669,9 @@ function collectComponents(cwd) {
         component.html = content;
       } else if (type === 'htmltemplate' && ext === 'json') {
         component.previewData = content;
-      } else if (type === 'tool' && ext === 'json') {
+      } else if ((type === 'tool' || type === 'action') && ext === 'json') {
+        // An Action's .json sidecar is its input schema (manual-run form and x-remits-operations), exactly as
+        // repository sync maps it; staging used to drop it, so a staged declaration silently did not apply.
         component.inputSchema = content;
       } else if (type === 'i18n' && ext === 'json') {
         component.messages = content;
@@ -3849,7 +3852,7 @@ function componentPathInfo(cwd, filePath) {
   else if (type === 'embeddable' && ext === 'js') field = 'javascript';
   else if (type === 'htmltemplate' && ext === 'html') field = 'html';
   else if (type === 'htmltemplate' && ext === 'json') field = 'previewData';
-  else if (type === 'tool' && ext === 'json') field = 'inputSchema';
+  else if ((type === 'tool' || type === 'action') && ext === 'json') field = 'inputSchema';
   else if (type === 'i18n' && ext === 'json') field = 'messages';
   else if (type === 'schema' && ext === 'json') field = 'schema';
 
@@ -9129,10 +9132,18 @@ async function waitForToolStatus(api, cwd, options) {
 
 // One compact progress line for a streamed TestSuite frame: a finished case, or the suite roll-up.
 function testSuiteProgressLine(payload = {}) {
+  if (payload.event === 'case_started') {
+    return '[ws] running ' + (payload.activeCases || []).map((c) =>
+      c.name + (c.traceId ? ' [trace ' + c.traceId + ']' : '')).join(', ');
+  }
   if (payload.total != null || Array.isArray(payload.tests)) {
     const total = payload.total != null ? payload.total : (payload.tests || []).length;
     const passed = payload.passed != null ? payload.passed : (payload.tests || []).filter((t) => t && t.passed).length;
-    return '[ws] ' + (payload.testName || 'suite') + ': ' + passed + '/' + total + ' passed';
+    const active = (payload.activeCases || []).map((c) => c.name + (c.traceId ? ' [trace ' + c.traceId + ']' : ''));
+    const queued = (payload.shards || []).filter((s) => s.status === 'queued').length;
+    return '[ws] ' + (payload.testName || 'suite') + ': ' + passed + '/' + total + ' passed' +
+      (payload.status ? ' (' + payload.status + ')' : '') +
+      (active.length ? '; running: ' + active.join(', ') : '') + (queued ? '; ' + queued + ' workers queued' : '');
   }
   const mark = payload.passed === false ? 'FAIL' : 'pass';
   const detail = payload.outcome && payload.outcome !== 'passed' ? ' [' + payload.outcome + ']' : '';
@@ -9144,7 +9155,16 @@ function watchWebsocket(baseUrl, topicId, taskId, options = {}) {
   const emit = options.stderr ? console.error : console.log;
   const client = new Client({
     brokerURL: webSocketUrl(baseUrl),
-    connectHeaders: { 'X-Auth-Token': options.token || '' },
+    connectHeaders: {
+      'X-Auth-Token': options.token || '',
+      'x-remits-ws-label': 'cli-test',
+      'x-remits-client-kind': 'cli',
+      'x-remits-tab-id': 'cli:' + process.pid + ':test:' + crypto.randomUUID(),
+      'x-remits-origin': 'remits-cli://test',
+      'x-remits-path': 'test/watch',
+      'x-remits-location': normalizeBaseUrl(baseUrl),
+      'x-remits-broker': webSocketUrl(baseUrl)
+    },
     reconnectDelay: 3000,
     heartbeatIncoming: 10000,
     heartbeatOutgoing: 10000,
@@ -9162,7 +9182,7 @@ function watchWebsocket(baseUrl, topicId, taskId, options = {}) {
           if (payload.taskId && followed.length && !followed.includes(payload.taskId)) {
             return;
           }
-          if (payload.tests || payload.name || payload.total != null) {
+          if (payload.tests || payload.name || payload.total != null || payload.event === 'case_started') {
             // Progress, not the payload. This used to print the whole suite result — every case, every
             // stacktrace — as one enormous line immediately before the readable summary said the same thing,
             // which buried the run world, the outcomes and the pivots an agent actually reads. --verbose still
@@ -9176,6 +9196,7 @@ function watchWebsocket(baseUrl, topicId, taskId, options = {}) {
     });
   };
 
+  installWebsocketRetry(client, { onBlocked: code => emit('[ws] Authentication required (' + code + '); HTTP polling continues.') });
   client.activate();
   return () => {
     client.deactivate();
@@ -9334,6 +9355,7 @@ async function testCommand(flags) {
     workspace,
     dataMode,
     dataModeSource,
+    caseConcurrency: flags.parallel !== undefined && runOptions.parallel === 1 ? 1 : undefined,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
     tests: names
@@ -13538,6 +13560,7 @@ function createManagedWebsocketClient(baseUrl, urlSessions) {
     discardWebsocketOnCommFailure: true,
     connectHeaders: {
       'x-remits-ws-label': 'remits-cli',
+      'x-remits-client-kind': 'cli',
       'x-remits-ws-scope': headerScope,
       'x-remits-user-id': headerUserIds.length === 1 ? headerUserIds[0] : '',
       'x-remits-account-id': headerAccountIds.length === 1 ? headerAccountIds[0] : '',
@@ -13643,7 +13666,7 @@ function createManagedWebsocketClient(baseUrl, urlSessions) {
     ensureRuntimeWebsocketEntry(normalizedBaseUrl);
     runtimeState.websocket[normalizedBaseUrl] = {
       ...runtimeState.websocket[normalizedBaseUrl],
-      status: 'disconnected',
+      status: client.remitsAuthBlocked ? 'authentication_required' : 'disconnected',
       disconnectedAt: new Date().toISOString()
     };
     console.log('[listener] Disconnected from', normalizedBaseUrl, '- will reconnect');
@@ -13673,7 +13696,7 @@ function createManagedWebsocketClient(baseUrl, urlSessions) {
     ensureRuntimeWebsocketEntry(normalizedBaseUrl);
     runtimeState.websocket[normalizedBaseUrl] = {
       ...runtimeState.websocket[normalizedBaseUrl],
-      status: 'disconnected',
+      status: client.remitsAuthBlocked ? 'authentication_required' : 'disconnected',
       disconnectedAt: new Date().toISOString(),
       lastError: detail
     };
@@ -13700,6 +13723,12 @@ function createManagedWebsocketClient(baseUrl, urlSessions) {
   };
 
   managedClient.client = client;
+  installWebsocketRetry(client, { onBlocked: code => {
+    runtimeState.websocket[normalizedBaseUrl] = {
+      ...runtimeState.websocket[normalizedBaseUrl], status: 'authentication_required', lastError: code
+    };
+    updateRuntimeServiceState();
+  } });
   return managedClient;
 }
 
@@ -13745,6 +13774,9 @@ async function runManagedWebsocketWatchdog() {
     if (!managedClient || !managedClient.client) {
       continue;
     }
+    // A session-file change replaces the client. The watchdog must not revive rejected credentials
+    // or defeat the normal transport backoff while it is waiting to reconnect.
+    if (managedClient.client.remitsAuthBlocked || managedClient.client.remitsRetryPending) continue;
     const state = ensureRuntimeWebsocketEntry(managedClient.baseUrl);
     const socket = managedClient.client.webSocket;
     const readyState = socket && typeof socket.readyState === 'number' ? socket.readyState : null;

package/lib/local-ai.js

@@ -6,6 +6,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
+const { installWebsocketRetry } = require('./websocket-retry');
 
 const MAX_BYTES = 8 * 1024 * 1024;
 const AGENTS = ['manual', 'codex', 'claude', 'gemini'];
@@ -623,6 +624,9 @@ async function command({ subcommand, flags, context, root, axios, Client, WebSoc
           console.error('Local AI WebSocket unavailable; authenticated polling continues.');
         }
       });
+      installWebsocketRetry(socket, { onBlocked: code => {
+        console.error(`Local AI WebSocket authentication required (${code}); reauthenticate and restart the worker.`);
+      } });
       socket.activate();
     }
     await supervisor.tick();

package/lib/websocket-retry.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// The server sends stable, credential-free codes. A transport close code alone (including 1002)
+// cannot distinguish expired credentials from a transient broker failure.
+const TERMINAL_CODES = new Set(['credentials_missing', 'credentials_rejected', 'credentials_malformed',
+  'session_required', 'topic_denied', 'destination_denied', 'recipient_denied']);
+
+function terminalCode(frame) {
+  const headers = frame?.headers || {};
+  const code = headers['x-remits-error-code'];
+  return TERMINAL_CODES.has(code) ? code : null;
+}
+
+function installWebsocketRetry(client, { onBlocked = () => {}, random = Math.random,
+  setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  const base = Math.max(1, Number(client.reconnectDelay) || 5000);
+  let failures = 0, wait = 0, timer, release;
+  const cancelWait = () => {
+    if (timer) clearTimer(timer);
+    timer = null;
+    if (release) release();
+    release = null;
+    client.remitsRetryPending = false;
+  };
+  const before = client.beforeConnect;
+  client.beforeConnect = async () => {
+    if (client.remitsAuthBlocked) { await client.deactivate(); return; }
+    if (wait > 0) {
+      client.remitsRetryPending = true;
+      await new Promise(resolve => { release = resolve; timer = setTimer(cancelWait, wait); });
+      // A stop/replacement may have resolved the wait; never read or send credentials afterwards.
+      if (!client.active || client.remitsAuthBlocked) return;
+    }
+    client.remitsRetryPending = false;
+    if (before) await before();
+  };
+  const connected = client.onConnect;
+  client.onConnect = frame => {
+    failures = 0; wait = 0; client.remitsRetryPending = false;
+    if (connected) connected(frame);
+  };
+  const closed = client.onWebSocketClose;
+  client.onWebSocketClose = event => {
+    const ceiling = Math.min(60000, base * Math.pow(2, Math.min(++failures, 5)));
+    // STOMP already waits base ms. Add jitter/backoff before its next CONNECT using public APIs.
+    wait = Math.max(0, Math.floor(ceiling / 2 + random() * ceiling / 2) - base);
+    client.remitsRetryPending = !client.remitsAuthBlocked;
+    if (closed) closed(event);
+  };
+  const error = client.onStompError;
+  client.onStompError = frame => {
+    const code = terminalCode(frame);
+    if (code) {
+      client.remitsAuthBlocked = code;
+      cancelWait();
+      // deactivate changes active synchronously, before STOMP schedules the close reconnect.
+      Promise.resolve(client.deactivate({ force: true })).catch(() => {});
+    }
+    if (error) error(frame);
+    if (code) onBlocked(code);
+  };
+  const deactivate = client.deactivate.bind(client);
+  client.deactivate = options => { cancelWait(); return deactivate(options); };
+  return client;
+}
+
+module.exports = { installWebsocketRetry, terminalCode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.163",
+  "version": "0.1.165",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -13,6 +13,7 @@
     "index.js",
     "lib/sync-operation.js",
     "lib/local-ai.js",
+    "lib/websocket-retry.js",
     "README.md",
     "scripts/prepare-index-toc.js",
     "skills/remits-cli/SKILL.md",

package/skills/remits-cli/SKILL.md

@@ -181,10 +181,15 @@ reference named after it.
   from `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (or the legacy flat fallback
   if `doctor local-state` says the response is there) before reporting the work as done.
   (`tool-reference.md`)
-- **Workspace and local actor are different.** `workspace` is the server-side staging lane namespace;
-  `local actor` is the repo-local filesystem namespace for session logs, tool responses, and verification
-  mirrors. Use `REMITS_AGENT_ID=<name>` or `--local-agent <name>` when agents share a checkout, and run
-  `remits-cli doctor local-state` when inheriting one. (`cli-state.md`, `component-resolution.md`)
+- **Workspace, local actor and agent identity are three different things.** `workspace` is the
+  server-side staging lane. The **local actor** is only the repo-local folder for session logs, tool
+  responses and verification mirrors: name it with `--local-agent <name>` or `REMITS_LOCAL_AGENT_ID` when
+  agents share a checkout, and run `remits-cli doctor local-state` when inheriting one. **Agent identity**
+  (`--agent-id` / `REMITS_AGENT_ID`) is what the PLATFORM sees: it is sent on every call, it makes the
+  call an `agent` to the account's policy rules, and it decides ticket ownership. `REMITS_AGENT_ID` also
+  names the local folder when no local actor is set, which is why setting it "just for the folder" changes
+  how the platform treats you. If you are an AI agent, setting it is correct: say who you are, and let the
+  account's agent rules apply to you. (`cli-state.md`, `agent-sessions.md`)
 - **Writing the code is not finishing the job.** A change is complete when it is verified — a Test
   component (preferred, because it becomes regression protection) or a browser flow through
   `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
@@ -232,6 +237,11 @@ reference named after it.
 - **Reading and investigating are parallel-safe; editing one account's repository is exclusive**, via a
   lease. A refusal is not an error — carry on read-only and hand off with `ticket progress --next-step`.
   Never wait or poll for a lease. (`support-tickets.md`)
+- **`Refused by this account's '<rule>' rule` is a POLICY decision, not a missing capability.** The
+  sentence says who the call presented as (`[This call presents as agent (agentId=…)]`). Find the rule in
+  the account's `OPERATIONS.md` `remits-policy` block, report its id, its `when`/`forbid`, and why your call
+  matched, then ask a person. Never generalize it ("syncs are impossible here"), and never drop your agent
+  identity to get past it. (`support-tickets.md`)
 - **A brief's `## Rules you will be held to` section is ENFORCED, not requested.** The platform refuses
   the verb and the message says what to do instead — act on that sentence rather than retrying or
   looking for another door. A `[require]` rule needs a person; hand off. (`support-tickets.md`)

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

@@ -76,13 +76,19 @@ Think about remits-cli as two cooperating layers:
      - where a large tool response was written
      - which tool schemas were most recently cached here
 
-Per-repo state has two independent namespaces:
+Per-repo state has two independent namespaces, and one identity sits beside them:
 
 - **Workspace** (`--workspace`, `REMITS_WORKSPACE`, `.remits-cli/workspace`) chooses the server-side
   Redis staging lane. It changes what staged entries a run resolves.
-- **Local actor** (`--local-agent`, `REMITS_AGENT_ID`, generated fallback) chooses the local filesystem
-  namespace under `.remits-cli/actors/<local-agent>/`. It changes where session logs, tool responses,
-  verification mirrors, and diagnostics are written.
+- **Local actor** (`--local-agent` / `--actor`, then `REMITS_AGENT_ID`, then `REMITS_LOCAL_AGENT_ID`, then a
+  generated fallback) chooses the local filesystem namespace under `.remits-cli/actors/<local-agent>/`. It
+  changes where session logs, tool responses, verification mirrors, and diagnostics are written. To name
+  only the folder, use `--local-agent` or `REMITS_LOCAL_AGENT_ID`.
+- **Agent identity** (`--agent-id`, then `REMITS_AGENT_ID`) is not local state. The CLI sends it to the
+  platform on every call (`X-Remits-Agent-Id` and the payload `agentId`), so the call is an `agent` to the
+  account's `remits-policy` rules, owns the tickets it claims, and is attributed to that agent. Without it
+  the call is the signed-in person. `REMITS_AGENT_ID` therefore does two jobs, folder and identity; an AI
+  agent should set it deliberately, as identity.
 
 Run `remits-cli doctor local-state` to print the active actor, state directory, workspace source,
 foreign actors, git-tracked `.remits-cli` files, legacy flat state, and large/suspicious logs.

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

@@ -284,10 +284,12 @@ remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restor
 `test run` starts a server-side task immediately. By default the CLI process polls until the task is
 terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
 return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
-and those cases execute sequentially in declaration order. To overlap independent slow cases, launch
-separate `remits-cli test run --names "<case>" --wait false` commands from the same staged lane and keep the
-printed task ids; complete each proof with `test status --task-id <id>`. Avoid parallel runs for cases that
-share mutable fixtures, suite-level side effects, or undeclared live AI/provider calls.
+and those cases execute sequentially by default. Test metadata `caseConcurrency` (1–16, default 1)
+enables native server workers. Explicit `--parallel N` overrides it; `--parallel 1` forces serial.
+Parent/group IDs work with `test status` and corpus commands; case results retain child task and trace IDs.
+Scheduled batches additionally accept `suiteConcurrency` (1–16, default 1) and overlap only suites marked
+`parallelSafe: true`; other suites run as exclusive barriers. Avoid concurrency for shared mutable
+fixtures or order-dependent setup. See the Test component guide's Configuring Parallel Execution section.
 
 ### Reading a failing run
 

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

@@ -430,8 +430,9 @@ id + content hash, platform sync vs local HEAD. If it is not the world you meant
 about a different world.
 
 The platform launch is asynchronous. By default `remits-cli test run` waits for its task to finish, and any
-cases selected by `--names "a|b"` execute sequentially inside that suite task. If several slow cases are
-independent, use `--parallel N`. It splits the selected cases across N shards that run side by side, and the run
+cases selected by `--names "a|b"` execute sequentially by default. A Test sidecar can set
+`caseConcurrency: 2` for native server workers, including scheduled runs. Explicit `--parallel N`
+overrides that setting (`--parallel 1` forces serial). It splits the selected cases across N shards that run side by side, and the run
 keeps ONE id (`grp-…`) for `test status` and every corpus command. An instance runs only a few suites at once
 (two by default), so shards beyond that wait for a slot. Ask for 2–4. Starting separate
 `test run --names "<case>" --wait false` commands also works for one-off proofs, but every such run is a separate