@remits/remits-cli 0.1.125 → 0.1.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.125",
+  "version": "0.1.127",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -12,6 +12,7 @@
   "files": [
     "index.js",
     "README.md",
+    "scripts/prepare-index-toc.js",
     "skills/remits-cli/SKILL.md",
     "skills/remits-cli/references"
   ],
@@ -29,8 +30,10 @@
     "automation"
   ],
   "scripts": {
+    "prepare:index-toc": "node scripts/prepare-index-toc.js",
+    "prepack": "node scripts/prepare-index-toc.js",
     "start": "node index.js",
-    "test": "node --test test/*.test.js"
+    "test": "node scripts/prepare-index-toc.js --check && node --test test/*.test.js"
   },
   "dependencies": {
     "@stomp/stompjs": "^7.2.0",

package/scripts/prepare-index-toc.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const indexPath = path.join(__dirname, '..', 'index.js');
+const cliSource = fs.readFileSync(indexPath, 'utf8');
+
+function functionSource(name) {
+  const declaration = new RegExp('(?:async\\s+)?function\\s+' + name + '\\s*\\([^)]*\\)\\s*\\{');
+  const match = declaration.exec(cliSource);
+  assert.notEqual(match, null, name + ' should exist');
+
+  const start = match.index;
+  let depth = 0;
+  for (let i = start + match[0].length - 1; i < cliSource.length; i += 1) {
+    if (cliSource[i] === '{') depth += 1;
+    if (cliSource[i] === '}') {
+      depth -= 1;
+      if (depth === 0) return cliSource.slice(start, i + 1);
+    }
+  }
+  assert.fail(name + ' body should be parseable');
+}
+
+const sandbox = vm.createContext({});
+vm.runInContext(
+  ['headingSlug', 'formatTocEntry', 'resolveTocEntry', 'resolveTableOfContentsLineNumbers']
+    .map(functionSource)
+    .join('\n'),
+  sandbox
+);
+
+const resolveTableOfContentsLineNumbers = vm.runInContext('resolveTableOfContentsLineNumbers', sandbox);
+const prepared = resolveTableOfContentsLineNumbers(cliSource);
+const check = process.argv.includes('--check');
+
+if (check) {
+  if (prepared !== cliSource) {
+    console.error('cli/index.js Table of Contents is stale. Run: npm run prepare:index-toc');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (prepared !== cliSource) {
+  fs.writeFileSync(indexPath, prepared);
+  console.log('Updated cli/index.js Table of Contents line numbers.');
+}

package/skills/remits-cli/SKILL.md

@@ -77,6 +77,11 @@ reference named after it.
   it. Each agent works in its own **clone**, never a same-branch worktree: worktrees share the branch
   ref, so one agent's pull moves `HEAD` under the others, and `components commit` refuses there.
   (`component-resolution.md`)
+- **Land only from trunk or a real variant branch.** A per-agent/feature branch (`components status` says
+  `FEATURE BRANCH … [subscription-fallback]`) is safe to stage and run from — it resolves the same world
+  as its target — but `components commit`/`sync` refuse it. Merge into the branch it resolves and land
+  there; `--create-variant-branch` is only for deliberately creating a new variant branch.
+  (`branch-variants.md`)
 - **On a variant branch, sync with `remits-cli components sync --safe`.** It dry-runs first and refuses
   a plan that would write components this checkout did not change — which is what a branch that is
   behind trunk produces, because it still physically carries old copies of files nobody touched.

package/skills/remits-cli/references/branch-variants.md

@@ -44,13 +44,21 @@ Three facts that everything else follows from:
 
 ### Which world does your working tree resolve? (read this before you run anything)
 
-You will work from **two different checkouts of the same repo**, and they behave differently on both ends
-of the loop. The rule turns entirely on **trunk vs non-trunk**:
+You will work from **different checkouts of the same repo**, and they behave differently on both ends of
+the loop. **You only ever stage the edits you intend to test** — the world beneath them comes from the
+account, not from what you named your git branch:
 
 | Working tree | Staging scope | A run resolves | `components sync`/`commit` writes |
 |---|---|---|---|
 | **trunk** (`main`, or whatever `account-info.json` says) | that branch | trunk + **each account's subscribed** variant branch (production semantics) | the **live component rows** — full reconcile, creates/updates/**deletes** |
-| **any other branch** (`feature_branch`) | that branch | trunk + **`feature_branch`** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+| **a variant branch** (it has committed variants, or an account subscribes to it — e.g. `forked`) | that branch | trunk + **that branch's** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+| **any other branch** (`codex/x`, `feature/y`) | that branch | the **same world as trunk**: trunk + the account's subscribed branch (`forked` for its subscriber) | **refused** (`feature_branch_landing`) — merge into the branch it resolves and land from there |
+
+A branch like that is a **feature branch**, and it is safe to *run* from: stage only the components you edited,
+and runs still resolve every `forked` overlay for the subscriber. Do **not** stage untouched components to
+"restore" something reported missing — check `components status` first. It is never a place to *land* from.
+For parallel agents the preferred shape is still the real branch name plus a workspace; see
+`features/multi-agent-development.md` ("Per-agent git branches: safe to run, never to land").
 
 Do not infer this from the branch name. Ask:
 
@@ -61,12 +69,17 @@ remits-cli components status
 ```
 Working tree: VARIANT BRANCH "feature_branch"  (trunk is "main")
   runs resolve:   trunk + the 'feature_branch' variant overlays
+  variant world:  feature_branch  [branch-has-variants]
   commit writes:  ComponentVariant overlays on 'feature_branch' (never touches trunk rows)
   variants stored on this branch: 3
   subscribing accounts: 101 (Acme Child)
 ```
 
-**The precedence trap that costs the most time:** `variantBranch` **outranks every account's
+From a branch that is not a variant branch the header reads `FEATURE BRANCH` and `runs resolve` names the
+subscribed branch, tagged `[subscription-fallback]`. `test run`, `token` and `tool` responses carry the
+same `variantBranch` / `variantBranchSource` fields, and a verification envelope records that world.
+
+**The precedence trap that costs the most time:** a variant branch's world **outranks every account's
 subscription**. So running a Test suite that asserts *production* semantics from a **variant checkout**
 pins every account in that suite — including fixture accounts subscribed to their own generated branches —
 to your branch, where they have no variants, and they all read trunk. The suite fails in a way that looks
@@ -383,7 +396,9 @@ branch that overlays it.
 
 **`components branches` only lists branches that already have overlays.** A branch you just pushed is
 invisible here until its first sync — that is not an error. Preview it by name (`components sync --dry-run`
-from that checkout).
+from that checkout). Its first real sync (or commit) needs `--create-variant-branch`: until a branch has
+variants or a subscriber the platform treats it as a feature branch and refuses to land it, so creating a
+new variant branch is always a stated decision, never a side effect of a feature branch's name.
 
 **Trunk moving also invalidates a branch.** Variant sparseness compares branch content against *current*
 trunk, so a trunk change can make an overlay obsolete without the branch changing at all. A trunk sync

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

@@ -197,8 +197,8 @@ remits-cli components status [--branch <name>] [--component-type <type>] [--comp
 remits-cli components lanes [--json]                         # every indexed staging lane on the account
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
-remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
-remits-cli components commit [--yes] [--safe] [--allow-shared-branch] [--message|-m "msg"] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); on TRUNK refuses before any git write unless --yes; --safe gates variant sync writes
+remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--create-variant-branch] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components commit [--yes] [--safe] [--allow-shared-branch] [--create-variant-branch] [--message|-m "msg"] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); on TRUNK refuses before any git write unless --yes; --safe gates variant sync writes
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: owner account, overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
@@ -207,6 +207,7 @@ remits-cli components branch <name> --subscribe <accountId> [--parent-account <i
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
 remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
+remits-cli test status --task-id <taskId> [--branch <stagingScope>] [--data-mode test|prod] [--json]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
@@ -268,6 +269,23 @@ remits-cli verify report
 Existing commands also accept `--verify-envelope <id>` to attach to a specific envelope and
 `--no-verify-envelope` to suppress automatic attachment for one command.
 
+Failed `remits-cli test run` output includes compact pivots per failed case: duration, trace id,
+bounded `report(...)` diagnostics, live HTTP signals, and resolved component provenance when the
+platform returns it. Re-read an existing run with `remits-cli test status --task-id <taskId>` before
+rerunning a long suite.
+
+Test-run requirements must name the suite/cases they mean:
+
+```json
+{"id":"api_flow", "packetType":"test_run", "suite":"Statement API Flow", "allCases":true}
+{"id":"one_case", "packetType":"test_run", "suite":"Statement API Flow", "cases":["rejects duplicated fee evidence"]}
+```
+
+`verify start` and `verify manifest` warn when a requirement has a `packetType` but no discriminator.
+The evaluator treats pending async tool packets as pending, not passing; a later `tool status` packet is
+the proof. Tool packets store the response file path, byte size and hash rather than copying the whole
+tool payload into the envelope.
+
 Use `remits-cli verify list` to review open envelopes for the account without SQL. If a newer envelope
 replaces an older one, use `verify supersede`; if a duplicate or abandoned attempt should no longer read
 as live work, use `verify abandon`. Both keep the evidence history.
@@ -341,6 +359,12 @@ For tests specifically:
   (`sharedBranchWorktrees` in `--json`). Worktrees of one branch share its ref, so a stale one would commit
   over landed work. Use one clone per agent; `--allow-shared-branch` overrides after `git status` is clean
   apart from your own changes.
+- `components commit` refuses before any git write, and `components sync` refuses, on a **feature branch** — one
+  `components status` reports as `[subscription-fallback]` (no committed variants, no subscribers). Runs from
+  it resolve the subscribed branch; landing it would write overlays nobody subscribes to and flip every sibling
+  lane on that branch to them (`refusal: "feature_branch_landing"` in `--json`). Merge it into the branch it
+  resolves and land from there. `--create-variant-branch` overrides, for deliberately creating a NEW variant
+  branch (its first sync looks identical). `--dry-run` previews are never refused.
 - `components commit` refuses before any git write, and `components sync --safe` refuses, when this checkout's
   `origin` is not the repository the platform syncs for the resolved account (`branchContext.repository` in
   `components status`). A plain sync warns and reports `repositoryCheck`, including under `--summary`.

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

@@ -57,9 +57,10 @@ source-layer facts the command observed. A staged test packet is proof of the st
 is proof of a source transition; a token packet is proof of the browser token's resolution tuple. Those
 are not interchangeable.
 
-Use `remits-cli verify report` before summarizing the work. It will naturally say when the evidence only
-covered staged source, when committed variant/trunk proof is missing, or when evidence became stale after
-the git head, overlay, or platform sync moved.
+Use `remits-cli verify report` before summarizing the work. It will say when the evidence only covered
+staged source, when committed variant/trunk proof is missing, when the manifest world does not match the
+packet world, or when later packet facts made an earlier proof stale. Packets carry a lane content hash,
+git head, workspace, data lane, and variant-world facts so a re-stage or branch move is visible.
 
 ### Staging cache key format
 
@@ -212,6 +213,9 @@ commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 - `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
 - In lane rows, `currentLane` (also `mine`) marks THIS command's lane; `ownedByCaller` marks every lane
   staged by your CLI user — your other clones' agents included.
+- If your current lane is empty but the same workspace has staged entries on another branch, the CLI
+  prints a warning. That usually means the checkout switched branches after staging; re-stage on this
+  branch or switch back.
 - **A landing clears only the lander's lane.** Every stage records the commit it came from
   (`stageBaseSha`), and `components status` compares that with the last commit the platform synced for the
   branch (`branchContext.lastSyncedSha`) using your local git:

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

@@ -97,6 +97,17 @@ remits-cli verify report
 The report is the final-response source. It separates verified claims, missing evidence, stale packets,
 and the source/account/lane tuple, so do not replace it with a generic "verified" sentence.
 
+For Test requirements, be specific enough for the evaluator to know what a pass means:
+
+```json
+{"id":"api_flow", "packetType":"test_run", "suite":"Statement API Flow", "allCases":true}
+{"id":"duplicate_fee_case", "packetType":"test_run", "suite":"Statement API Flow", "cases":["rejects duplicated fee evidence"]}
+```
+
+A requirement that says only `{"packetType":"test_run"}` is intentionally only a warning-worthy sketch:
+it will not turn a random Test packet into acceptance. Full-suite runs emit suite and passed-case
+categories automatically, so case-level requirements can be satisfied by a real full run.
+
 ## Development Workflow
 
 ### The Golden Rule: Writing Code Is Not Finishing the Job
@@ -327,9 +338,13 @@ This applies to:
 ```bash
 remits-cli test run --test <TEST_ID_OR_NAME>
 remits-cli test run --test "Invoice Tests" --names "specific test case"
+remits-cli test status --task-id <TASK_ID>
 ```
 
-Tests run on the platform against your staged snapshot. They stream results in real-time. If they fail, fix the code, re-stage, and re-run.
+Tests run on the platform against your staged snapshot. They stream results in real-time. If they fail,
+read the printed pivots first: failed cases include timing, trace ids, bounded `report(...)`
+diagnostics, live HTTP signals, and resolved component provenance when available. Fix the code,
+re-stage, and re-run only after those pivots explain the failure.
 
 Important test-runner constraints:
 - `remits-cli test run` now defaults to `test` dataMode unless you explicitly pass `--data-mode prod`.

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

@@ -354,7 +354,7 @@ Inspect individual lifecycle records with line-range or grep.
 | `recordType` | yes | `object`, `object_log`, `event`, or `alert` |
 | `recordId` | yes | Record primary key |
 | `field` | no | `content` (default) or `body` (objects only) |
-| `revisionId` | no | Envers revision ID (not for object_log) |
+| `revisionId` | no | Envers revision ID (not for object_log). Revision history does not retain `content`/`body`; omit it to read the current payload |
 | `lineRange` | no | `{start, end}` (1-based inclusive) |
 | `grep` | no | `{pattern, caseSensitive, contextBefore, contextAfter}` |
 

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

@@ -39,7 +39,8 @@
 | A custom hostname resolves to an unexpected account | Compare `resolution.domainName` with `resolvedDomainName` and the edge `domainName`s. An **edge** host wins over the account's own host and additionally supplies the path travelled (which is what makes that edge's branch variants apply). |
 | Need users of an account, accounts of a user, or account-scoped user fields | Use `mcp_account_user_admin` (`action:'users'`, `action:'user'`, or `action:'user_update'`). Use `mcp_sql_query` on `user` / `user_account` only for raw join-table investigation. Remember user custom fields are stored **per bound account**, so the same person can differ per account. |
 | One account behaves differently from its siblings on the same component | It probably subscribes to a **branch variant**. Check `remits-cli components branches` and `remits-cli components branch <name> --subscribers`, and reproduce with `remits-cli test run --as-account <ID>`. Do NOT "fix" this by adding per-account logic to the origin component. |
-| Edits on a feature branch seem to run against trunk code | You are likely on the **trunk** branch, or passed `--variant-branch none`. Run `remits-cli components status` — it states which world the working tree resolves. |
+| Edits on a feature branch seem to run against trunk code | A branch with no committed variants and no subscribers resolves the account's **subscription** (trunk, if it subscribes to nothing) beneath what you staged — `components status` shows `FEATURE BRANCH … [subscription-fallback]` and names the world. To see a specific branch's overlays, run from that branch's checkout or pass `--variant-branch <name>`. |
+| `components commit`/`sync` refused with `feature_branch_landing` | The branch is a feature branch, not a variant branch. Merge it into the branch the message names and land from that checkout. Do **not** pass `--create-variant-branch` to get past it — that flag deliberately creates a new variant branch nobody subscribes to. |
 | A component vanished for one account after a variant-branch sync | Its file is missing from that branch, so the sync created a **tombstone** that hides it from subscribers. Restore the file on the branch and re-sync. Trunk is unaffected. |
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |