@remits/remits-cli 0.1.165 → 0.1.166

package/README.md

@@ -101,7 +101,8 @@ remits-cli install --skills --overwrite true
 - Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
 - Active verification envelopes are scoped per `baseUrl + accountId + branch + workspace + dataMode`, so a localhost envelope does not silently capture evidence from a production command. Pass `--verify-envelope <id>` for an intentional cross-context attachment.
 - `--base-url` and `--data-mode` are independent. `--base-url` chooses the Remits host (`http://localhost:8080` vs deployed prod), while `--data-mode` chooses the data segment on that host (`test` vs `prod`). Do not assume `--data-mode prod` means the deployed prod host, or that `--data-mode test` means localhost.
-- `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
+- `remits-cli start` scans for `account-info.json` files and updates `~/.remits-cli/account-repos.json` before bringing up the background service. While running, it rescans every five minutes using asynchronous directory reads, then reports the refreshed inventory to the platform. Repos cloned outside the CLI are discovered without a restart or a command run inside them. Both scans use `REMITS_CLI_SCAN_ROOTS` (default: the home directory), the same depth limit and directory exclusions. For immediate discovery, use `remits-cli agent repos --rescan` or **Rescan Account Repos** in the control center.
+- Scans preserve manually selected repository directories and record competing checkouts as ambiguity. `remits-cli agent repos --account-id <id> --forget` suppresses rediscovery until an explicit registration (`--directory <path>`) or a CLI command run from that account repo restores it.
 - Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/front-stage/remits-components-zip-readme.md`).
 - Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
 - On every command, `remits-cli` refreshes the installed remits-cli `SKILL.md` and reference files for `claude`, `codex`, `gemini`, and `antigravity` so local agents stay on the latest packaged instructions.

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- 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
+- L126  Sessions, Account Resolution, And Production Guards
+- L632  Local State, Workspaces, And Verification Evidence
+- L2670  Account Repos, Guide Sync, And Platform Repo
+- L3569  Component Discovery And HTTP Logging
+- L4339  Skill Delivery And TOC Resolution
+- L4654  Auth And Component Staging
+- L5286  Component Summaries, Status, And Sync Gates
+- L7610  Branches, Promotion, Commit, And Test Runs
+- L9873  Tokens, Tools, Verification, And Config
+- L11390  Service Dashboard And WebSocket Listener
+- L13900  Agent And Ticket Workflows
+- L18202  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -75,6 +75,7 @@ const DASHBOARD_HOST = '127.0.0.1';
 const DEFAULT_DASHBOARD_PORT = Number(process.env.REMITS_CLI_DASHBOARD_PORT || 8787);
 const DEFAULT_SCAN_MAX_DEPTH = Number(process.env.REMITS_CLI_SCAN_MAX_DEPTH || 8);
 const SERVICE_MAINTENANCE_INTERVAL_MS = Number(process.env.REMITS_CLI_SERVICE_MAINTENANCE_INTERVAL_MS || 15000);
+const ACCOUNT_REPO_RESCAN_INTERVAL_MS = 5 * 60 * 1000;
 const WEBSOCKET_RECONNECT_DELAY_MS = Number(process.env.REMITS_CLI_WEBSOCKET_RECONNECT_DELAY_MS || 5000);
 const WEBSOCKET_HEARTBEAT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_HEARTBEAT_MS || 10000);
 const WEBSOCKET_CONNECTION_TIMEOUT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_CONNECTION_TIMEOUT_MS || 15000);
@@ -3253,7 +3254,8 @@ function countAccountRepos(index) {
  */
 function mergeAccountRepoEntries(entries, options = {}) {
   const nextIndex = options.existingIndex ? { ...options.existingIndex } : {};
-  const rank = (entry) => (isAccountCheckout(entry.directory) ? 2 : 0) + (entry.source === 'cwd' ? 1 : 0);
+  const sourceRank = (entry) => entry.source === 'manual' ? 2 : (entry.source === 'cwd' ? 1 : 0);
+  const rank = (entry) => (isAccountCheckout(entry.directory) ? 3 : 0) + sourceRank(entry);
 
   for (const entry of entries) {
     if (!entry || !entry.accountId || !entry.directory) {
@@ -3261,8 +3263,15 @@ function mergeAccountRepoEntries(entries, options = {}) {
     }
     const key = String(entry.accountId);
     const current = nextIndex[key];
+    // Forget is an explicit opt-out, not a temporary absence until the next service scan.
+    if (current && current.source === 'forgotten' && entry.source === 'scan') continue;
     if (!current || !current.directory || current.directory === entry.directory) {
-      nextIndex[key] = { ...entry, ambiguousWith: (current && current.ambiguousWith) || [] };
+      nextIndex[key] = {
+        ...entry,
+        source: current && current.directory === entry.directory && sourceRank(current) > sourceRank(entry)
+          ? current.source : entry.source,
+        ambiguousWith: (current && current.ambiguousWith) || []
+      };
       continue;
     }
 
@@ -3305,19 +3314,17 @@ function defaultAccountScanRoots() {
   return [home].filter((dir) => fs.existsSync(dir));
 }
 
-function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+// Share traversal rules between the synchronous command path and asynchronous service scans.
+// The driver supplies directory entries so the service never blocks its WebSocket on readdirSync.
+function* accountRepoScanSteps(dir, depth, matches, visited, platformMatches) {
   const resolvedDir = path.resolve(dir);
   if (visited.has(resolvedDir)) {
     return;
   }
   visited.add(resolvedDir);
 
-  let entries;
-  try {
-    entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
-  } catch (_) {
-    return;
-  }
+  const entries = yield resolvedDir;
+  if (!entries) return;
 
   const names = new Set(entries.map((entry) => entry.name));
   for (const entry of entries) {
@@ -3347,7 +3354,17 @@ function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
     if (entry.name.startsWith('.') && entry.name !== '.config') {
       continue;
     }
-    walkForAccountInfo(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+    yield* accountRepoScanSteps(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+  }
+}
+
+function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+  const steps = accountRepoScanSteps(dir, depth, matches, visited, platformMatches);
+  let step = steps.next();
+  while (!step.done) {
+    let entries = null;
+    try { entries = fs.readdirSync(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+    step = steps.next(entries);
   }
 }
 
@@ -3359,7 +3376,29 @@ function discoverAccountRepos() {
   for (const root of roots) {
     walkForAccountInfo(root, 0, matches, visited, platformMatches);
   }
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches);
+}
 
+async function discoverAccountReposInBackground() {
+  const matches = [];
+  const platformMatches = [];
+  const visited = new Set();
+  const roots = defaultAccountScanRoots();
+  for (const root of roots) {
+    const steps = accountRepoScanSteps(root, 0, matches, visited, platformMatches);
+    let step = steps.next();
+    while (!step.done) {
+      let entries = null;
+      try { entries = await fs.promises.readdir(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+      step = steps.next(entries);
+    }
+  }
+  // Read the latest index only at reconciliation: CLI commands may register a repo during the scan.
+  // Background maintenance discovers existing files; it must never clone or pull repositories.
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches, { background: true });
+}
+
+function reconcileDiscoveredAccountRepos(roots, matches, platformMatches, options = {}) {
   const entries = [];
   for (const file of matches) {
     try {
@@ -3380,7 +3419,7 @@ function discoverAccountRepos() {
     const found = platformMatches.find(looksLikePlatformRepo);
     if (found) {
       setPlatformRepoEntry(found, 'scan');
-    } else {
+    } else if (!options.background) {
       try { ensurePlatformRepoLocal({ allowClone: true }); } catch (_) { /* best-effort */ }
     }
   }
@@ -3395,6 +3434,27 @@ function discoverAccountRepos() {
   };
 }
 
+let accountRepoDiscoveryInFlight = null;
+let lastAccountRepoDiscoveryAttemptAt = 0;
+
+function refreshAccountReposIfDue(now = Date.now()) {
+  if (accountRepoDiscoveryInFlight) return accountRepoDiscoveryInFlight;
+  const lastScanAt = Date.parse(runtimeState.discovery.scannedAt || '') || 0;
+  if (now - Math.max(lastScanAt, lastAccountRepoDiscoveryAttemptAt) < ACCOUNT_REPO_RESCAN_INTERVAL_MS) return;
+  lastAccountRepoDiscoveryAttemptAt = now;
+  accountRepoDiscoveryInFlight = discoverAccountReposInBackground()
+    .then((summary) => {
+      recordDiscoverySummary(summary);
+      // Publish the refreshed inventory on the next maintenance tick, even if presence isn't due yet.
+      for (const managedClient of managedClients) managedClient.lastPresenceAt = 0;
+    })
+    .catch((err) => {
+      appendGlobalActivityLog('listener', 'repos.discovery.failed', { error: describeError(err) }, 'error');
+    })
+    .finally(() => { accountRepoDiscoveryInFlight = null; });
+  return accountRepoDiscoveryInFlight;
+}
+
 function resolvePreferredAccountId(cwd, flags, session) {
   // Explicit --account-id wins over the repo's account-info.json so users can
   // target a child account (e.g. a customer) from a parent-account repo.
@@ -15911,6 +15971,7 @@ async function ticketCommand(flags, subcommand) {
     requiresRepositoryWork: firstDefined(flags['repo-work'], flags['requires-repository-work']),
     tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
     label: flags.label,
+    ...(action === 'artifact' ? ticketArtifactFields(flags) : {}),
     url: flags.url,
     body: flags.body,
     role: flags.role,
@@ -16656,7 +16717,7 @@ function printTicketHelp() {
   console.log('  tag --tags a,b                        Mark it, for a HUMAN reading the queue. When the');
   console.log('      tickets genuinely share a cause, use `relate` instead or as well: the platform reads');
   console.log('      that one, and a tag it cannot read will not stop a cluster being worked N times.');
-  console.log('  artifact --type TYPE --label "..." [--url U | --content "..."]');
+  console.log('  artifact --type TYPE --label "..." (--content "..." | --file PATH | --url U) [--filename F] [--content-type T]');
   console.log('      Attach evidence — a log, a query result, a repro. Better than pasting it into a');
   console.log('      worklog summary, where it is neither typed nor retrievable.');
   console.log('  note --message "..."                  An INTERNAL note. The next worker and a reviewer');
@@ -16701,6 +16762,44 @@ function printTicketHelp() {
  * One helper so the lease, the claim and the registration cannot describe this process three ways —
  * the same reason the platform builds the tuple in exactly one class (AgentRunContext).
  */
+/**
+ * The evidence half of `ticket artifact`. Bytes always travel as `contentBase64`: it is the one form every
+ * deployed platform accepts (JSON cannot carry a byte[], and older platforms ignored a `content` string), so
+ * `--content "text"` and `--file path` behave the same against every host. The help promised `--type` and
+ * `--content` for a long time while neither was sent, and every artifact was refused as `type [null]`; the
+ * refusals here name the missing flag before anything reaches the platform.
+ */
+function ticketArtifactFields(flags = {}, readFile = (p) => fs.readFileSync(p)) {
+  const text = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+  const type = text(flags.type);
+  if (!type) {
+    throw new Error('ticket artifact needs --type (screenshot, pdf, trace, video, log, test_result, link or other).');
+  }
+  if (!text(flags.label)) {
+    throw new Error('ticket artifact needs --label "...".');
+  }
+  const fields = { type, filename: text(flags.filename), contentType: text(flags['content-type'] || flags.contentType) };
+  const filePath = text(flags.file);
+  const content = typeof flags.content === 'string' ? flags.content : undefined;
+  if (filePath) {
+    const bytes = readFile(filePath);
+    fields.contentBase64 = Buffer.from(bytes).toString('base64');
+    fields.filename = fields.filename || path.basename(filePath);
+    if (!fields.contentType) {
+      const ext = path.extname(filePath).toLowerCase();
+      fields.contentType = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.pdf': 'application/pdf',
+        '.json': 'application/json', '.zip': 'application/zip', '.webm': 'video/webm', '.html': 'text/html',
+        '.md': 'text/markdown', '.txt': 'text/plain', '.log': 'text/plain' })[ext];
+    }
+  } else if (content !== undefined) {
+    fields.contentBase64 = Buffer.from(content, 'utf8').toString('base64');
+    fields.contentType = fields.contentType || 'text/plain; charset=utf-8';
+  } else if (!text(flags.url)) {
+    throw new Error('ticket artifact needs something to attach: --content "...", --file PATH or --url URL.');
+  }
+  return fields;
+}
+
 function runContextPayload(flags = {}) {
   const cwd = process.cwd();
   return {
@@ -17504,7 +17603,7 @@ async function agentReposCommand(flags) {
   if (Number.isFinite(accountId) && accountId > 0 && flagEnabled(flags.forget)) {
     const index = readAccountRepoIndex();
     const previous = index[String(accountId)];
-    delete index[String(accountId)];
+    index[String(accountId)] = { accountId, source: 'forgotten', updatedAt: new Date().toISOString() };
     writeAccountRepoIndex(index);
     console.log(previous
       ? 'account ' + accountId + ' removed (was ' + previous.directory + '). Its tickets will now park ' +
@@ -18012,6 +18111,8 @@ async function listenCommand(flags) {
         activeSessionSignature = currentSignature;
       }
 
+      // Do not await the filesystem scan: a slow/unavailable volume must not stall socket upkeep.
+      refreshAccountReposIfDue();
       await runManagedWebsocketWatchdog();
       updateRuntimeServiceState();
     } catch (err) {

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -96,6 +96,13 @@ reference named after it.
   "branch" or "verified"; say what was actually proven: Test pass, browser journey, corpus measurement,
   sync mutation, or ticket lifecycle state. (`component-resolution.md`, `branch-variants.md`,
   `development-loop.md`, `support-tickets.md`)
+- **There are no environments to deploy to, so translate SDLC words before acting.** "Let me try it" means a
+  token link to your staged lane. "Put it in UAT" means a sync to the pre-production component branch, or
+  a link if UAT is a link on this account. "Push to prod" means the promotion loop. "Roll it back" means
+  `git revert` plus a sync, and it does not undo emails or external writes. People who simply sign in never
+  see staged code. Syncing a branch others use, every promotion gate, and a trunk edit on a release-train
+  account each need the person's go for that step. (the account repo's core platform guide → *How A Change Reaches People*,
+  `branch-variants.md`)
 - **Embeddable verification is browser verification.** For page, widget, form, upload, or other
   browser-facing changes, mint a URL with `remits-cli token` and drive it with `playwright-cli`.
   Prefer this over `curl`: `curl` can prove an HTTP response or inspect an action payload, but it does

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

@@ -114,7 +114,7 @@ Agents should use this mental model before guessing.
 
 The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
 
-This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
+This JSON file is automatically maintained by `remits-cli` and tracks known Remits account repositories on this machine. It is updated when a CLI command runs from an account repo directory, at service startup, and by background discovery every five minutes while the service runs. Background scans use the same configured roots, depth limit and exclusions as startup; they report newly discovered repos to the platform without restarting. Use `remits-cli agent repos --rescan` for immediate discovery. The file maps account IDs to their metadata:
 
 ```json
 {
@@ -133,6 +133,8 @@ This JSON file is automatically maintained by `remits-cli` and tracks all known
 - Resolve account names and IDs without making remote API calls
 - Support cross-account workflows where an agent in one repo needs context from another
 
+Manual directory selections survive rescans; competing checkouts are recorded as ambiguity. `agent repos --account-id <id> --forget` stores an opt-out without a directory, so scans do not silently restore it. Explicitly register a directory or run a CLI command from that repo to restore registration.
+
 If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
 
 ## Local State Files

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

@@ -234,7 +234,7 @@ remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [-
 remits-cli ticket deliveries --ticket ID [--channel email]   # what is queued to go out, and what already went
 remits-cli ticket delivered --ticket ID --delivery-id ID | ticket delivery-failed --ticket ID --delivery-id ID --reason "..."
 remits-cli ticket tag --ticket ID --tags a,b           # make a cluster of near-identical tickets visible as one
-remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --content "..."]
+remits-cli ticket artifact --ticket ID --type TYPE --label "..." (--content "..." | --file PATH | --url U)
 remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
 remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
 remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket

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

@@ -808,3 +808,11 @@ Some users want to review every change before staging. Others want you to move f
 - If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
 
 The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.
+
+**Four steps always need the person's go for that step, whatever they said earlier:**
+- syncing a component branch that a pre-production or client account uses;
+- each promotion gate (`features/subscriber-branch-promotions.md` → *The three approval gates*);
+- unsubscribing an account or retiring a branch;
+- editing trunk on an account that runs a release-train branch.
+
+A general "just do it" covers staging and verifying, not these. Each one changes what live accounts run.

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

@@ -32,6 +32,7 @@
   - [Component branches](#component-branches)
   - [`mcp_cache`](#mcp_cache)
   - [`mcp_sql_query`](#mcp_sql_query)
+  - [`mcp_usage`](#mcp_usage)
   - [`mcp_index_search`](#mcp_index_search)
   - [`mcp_get_guide`](#mcp_get_guide)
   - [`mcp_test_fixture`](#mcp_test_fixture)
@@ -931,6 +932,30 @@ SELECT u.id, u.username, u.enabled FROM user u
 Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
 resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
 
+### `mcp_usage`
+Administrator-only usage reports and configuration through the platform's `usageControl` API. The
+System Account owns this global tool; deploy the platform API before staging or syncing its wrapper.
+
+| Parameter | Description |
+|---|---|
+| `operation` | `status` (default), `report`, `gaps`, `savePrice`, `replacePrice`, `endPrice`, `saveBillingMap`, `deleteBillingMap`, `saveManualCharge`, `deleteManualCharge`, `configure`, `runSettle`, `runBilling`, `flushMeter` |
+| `query` | `usage(...)` selectors for reports/gaps: dates, accountId, includeDescendants, lanes, includeSuites, grouping. Omit accountId for platform scope. |
+| `values` | Rate, mapping, charge or settings fields; status lists supported units and allowed settings. `replacePrice` requires the old id and full successor rate. |
+| `apply` | `false` by default: mutations return their normalized plan. `true` applies the authorized change. Configuration is platform-wide, independently of the test/prod data selector. |
+
+Read `status.pricingNotes` first. Rates start at future UTC hour boundaries; overlapping or historical
+changes are refused. Use `replacePrice` for an atomic rate change. Do not price a storage byte counter
+as byte-months or wall time as billed CPU time. `gaps` returns account/provider/model grouping so exact
+missing rate keys are visible. Shared platform overhead is excluded from account hierarchies.
+Provider invoices and estimates remain separate when filters do not match invoice scope.
+
+```bash
+remits-cli tool --name mcp_usage --input '{"operation":"status"}'
+remits-cli tool --name mcp_usage --input '{"operation":"report","query":{"accountId":41,"includeDescendants":true,"from":"2026-10-01"}}'
+```
+
+The full field contract and examples are in `features/usage-and-cost.md` → Configuring usage through MCP.
+
 ### `mcp_index_search`
 Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
 RAG/search-backed component actually retrieves before blaming the component.

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

@@ -62,7 +62,7 @@
 | Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
 | Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
 | Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |
-| Dashboard missing repos | Rebuild `~/.remits-cli/account-repos.json` with `remits-cli start` or the control center rescan action |
+| Dashboard or GitHub menu missing local repos | The running service rediscovers repos every five minutes. Use `remits-cli agent repos --rescan` or the control center rescan action for immediate discovery; allow the next presence update (normally within 30 seconds). Check scan roots if still absent. A forgotten account needs explicit registration with `agent repos --account-id <id> --directory <path>`. |
 | Agent dispatch to wrong directory | Check `~/.remits-cli/account-repos.json` has the correct directory and that you resolved the account type correctly. A `CLIENT` ticket may still belong to a parent `PLATFORM` or `PRODUCT` repo for code changes. |
 
 ### When Something Doesn't Work as Expected