@remits/remits-cli 0.1.125 → 0.1.126

package/README.md

@@ -64,6 +64,9 @@ remits-cli install --skills --overwrite true
 
 ## How It Works
 
+- `cli/index.js` opens with a line-numbered code Table of Contents. Section entries are generated from
+  the `##` section marker comments in the file. Run `npm run prepare:index-toc` after moving sections;
+  `npm test` checks that the prepared line numbers still point at the real headings.
 - `components stage` has three modes, and the difference decides what a run in the lane resolves:
   - **default (full snapshot)** — uploads the whole repository manifest and reconciles the lane to it, so stale aliases from prior stages are removed. Correct as a complete snapshot and as a "what is stale here?" reset; a poor progress signal, because the lane then holds every component in the repo.
   - **`--workset`** — uploads only the components git reports changed and reconciles the lane to exactly those. The normal iteration mode. `--changed-only --replace-lane` is the explicit spelling.
@@ -89,7 +92,7 @@ remits-cli install --skills --overwrite true
 - `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
 - 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.
-- During account-repo discovery, `remits-cli` also overwrites the installed remits-cli `SKILL.md` for `claude`, `codex`, and `gemini` so local agents stay on the latest packaged instructions.
+- On every command, `remits-cli` refreshes the installed remits-cli `SKILL.md` and reference files for `claude`, `codex`, and `gemini` so local agents stay on the latest packaged instructions.
 - The platform repo's `docs/front-stage/` tree remains the single source of truth; the platform serves it from the classpath, so published CLI versions never carry guide content.
 - Authenticated users also get the **core Remits platform repo** locally. After guide sync (and on `auth` / discovery), `remits-cli` first reuses any existing local copy it already knows about, can detect directly (`REMITS_PLATFORM_DIR`, the running CLI source in dev, `~/remits`), or can discover under the configured scan roots; only if none is found does it clone `git@github.com:tmillhouse/remits.git` (default `~/remits`, override with `REMITS_PLATFORM_DIR`; cloning only runs in an interactive terminal). On each authenticated run it also fast-forwards the repo (`git pull --ff-only`, once per process) so back-stage analysis runs against current code — skipped automatically if the working tree is dirty, so local work is never clobbered. The repo is tracked in `~/.remits-cli/account-repos.json` under the reserved `platform` entry so agents can analyze back-stage seams and open a fix PR when a front-stage failure turns out to be platform brittleness.
 - Branch defaults to the current local git branch.
@@ -106,7 +109,7 @@ remits-cli install --skills --overwrite true
 - `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.
 - On `test run`, `--branch <name>` is only the Redis staging namespace. Pair an unused value with `--variant-branch none` when existing staged entries on the real git branch would shadow committed trunk/variant rows. Do not apply that shortcut to `components sync` or `components commit`, where `--branch` names the GitHub branch to reconcile.
 
-## Service, Dashboard, WebSocket, and Tmux Lifecycle
+## Service, Dashboard, and WebSocket Lifecycle
 
 - The primary lifecycle commands are `remits-cli start`, `remits-cli stop`, and `remits-cli status`.
 - `remits-cli listen`, `remits-cli listen stop`, and `remits-cli listen status` still work as compatibility aliases.
@@ -116,16 +119,14 @@ remits-cli install --skills --overwrite true
 - `remits-cli status` reports whether the background service is alive, prints the dashboard URL when available, and prints the resolved session tuple: Account ID, User ID, current git branch, and active data mode.
 - `remits-cli whoami` prints only the resolved session tuple. Use `--base-url`, `--account-id`, and `--data-mode` to prove the exact host/account/lane before running a tool or test.
 - Both print **two** data modes. "Data mode" governs `tool` / `tools` / `token` and falls back to the stored session lane; "Data mode (test run)" governs `test run`, which ignores the session and defaults to `test` unless `--data-mode prod` is passed. The test-run line also reports its source, such as `cliDefault` or `explicitFlag`.
-- `remits-cli stop` stops the background service, kills the shared tmux session, and clears pane tracking state.
+- `remits-cli stop` stops the background service.
 - The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
-- The dashboard shows websocket connection health, topic subscriptions, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.
-- If websocket connections are disconnected or the tmux session is missing, the dashboard exposes actions to reconnect websockets or recreate the tmux session.
+- The dashboard shows websocket connection health, topic subscriptions, registered agents, live and recent worker runs, the discovered account repo index, global state files, and per-repo remits-cli files.
+- If websocket connections are disconnected, the dashboard exposes an action to reconnect them.
 - 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 and recreates the shared tmux session if it disappears.
+- The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections.
 - 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.
-- Incoming websocket messages of type `remits-cli` are dispatched into dedicated tmux windows so the selected agent can continue working interactively with a full terminal view.
-- The listener creates a shared tmux session named `remits-listener`.
 - 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.
 - Tickets are delivered by durable routing on the ticket record, then the agent asks for routed work with `remits-cli agent work`.
@@ -179,12 +180,14 @@ There are two separate state areas:
   PID for the background remits-cli service process.
 - `~/.remits-cli/service-state.json`
   Dashboard URL, repo scan summary, and websocket state snapshot for the running service.
-- `~/.remits-cli/dispatch-panes.json`
-  Persistent map of support ticket routing key to the active tmux pane id for that ticket's dedicated window. `ticketId` is preferred, with legacy `taskId` fallback.
 - `~/.remits-cli/account-repos.json`
   Index of known account repositories on this machine, rebuilt by `remits-cli start` via account-info discovery and also refreshed when commands run inside an account repo.
-- `~/.remits-cli/tmux-activity.log`
-  Human-readable global activity log for listener and tmux lifecycle events.
+- `~/.remits-cli/agents.json`
+  Agent sessions registered from this machine, including the process each one is anchored to.
+- `~/.remits-cli/workers.json`
+  Active and recent ticket worker state for serving agents.
+- `~/.remits-cli/activity.log`
+  Human-readable global activity log for service lifecycle, websocket events, agent registration, and ticket routing.
 
 ## Control Center
 
@@ -192,21 +195,20 @@ There are two separate state areas:
 - Open that page in a browser to inspect the full local remits-cli integration state without manually opening JSON files.
 - The page refreshes automatically and includes the latest global state files plus per-repo `account-info.json`, local tools snapshot, and current session log tail for every indexed account repo. Large account configuration fields live in `account-configurations.json` and should be opened only when needed.
 
-## Tmux Activity Log
+## Activity Log
 
-- `~/.remits-cli/tmux-activity.log` is the quickest way to understand what the listener is doing.
-- It records timestamped lifecycle events such as listener start/stop, websocket connect/disconnect, topic subscription, dispatch receipt, pane creation, follow-up delivery, pane replacement, and dispatch failures.
-- Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as `accountId`, `ticketId`, any legacy `taskId`, available keys, and prompt length.
+- `~/.remits-cli/activity.log` is the quickest way to understand what the service, websocket clients, and local agents are doing.
+- It records timestamped lifecycle events such as service start/stop, websocket connect/disconnect, topic subscription, agent registration/heartbeat, ticket routing, worker launch, and worker completion.
+- Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as `accountId`, `ticketId`, available keys, and prompt length.
 - Typical inspection commands:
 
 ```bash
-tail -f ~/.remits-cli/tmux-activity.log
-tail -n 200 ~/.remits-cli/tmux-activity.log
+tail -f ~/.remits-cli/activity.log
+tail -n 200 ~/.remits-cli/activity.log
 ```
 
 ## Operational Notes
 
-- `tmux` must be installed for agent dispatch to work. Without it, websocket dispatch is received but agent panes cannot be created.
 - In sandboxed local agent environments, `remits-cli` network calls may fail with `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar errors even when dispatch worked correctly. That means the command needs escalated permissions or must be run outside the sandbox.
 - If the platform returns a 500 or other unexpected server-side failure, stop normal task execution and escalate to a Remits system admin. Agents should not invent workarounds for platform faults.
 - Recommended durable update flow for agents: `components stage --workset` for testing, then `git add/commit/push`, then `remits-cli components sync --safe`, then `git pull --ff-only` to confirm platform-generated files like `account-info.json`. To verify the COMMITTED variant rather than your staging, run `components clear --all` first — staged entries still win for CLI-scoped runs.

package/index.js

@@ -1,5 +1,27 @@
 #!/usr/bin/env node
 
+/*
+## Table of Contents
+
+- L22  Runtime Bootstrap And Shared State
+- L116  Sessions, Account Resolution, And Production Guards
+- L595  Local State, Workspaces, And Verification Evidence
+- L1234  Account Repos, Guide Sync, And Platform Repo
+- L1892  Component Discovery And HTTP Logging
+- L2382  Skill Delivery And TOC Resolution
+- L2692  Auth And Component Staging
+- L3280  Component Summaries, Status, And Sync Gates
+- L4991  Branches, Promotion, Commit, And Test Runs
+- L5988  Tokens, Tools, Verification, And Config
+- L6889  Service Dashboard And WebSocket Listener
+- L8984  Agent And Ticket Workflows
+- L12042  Help, Auto Update, And Command Dispatch
+*/
+
+/*
+## Runtime Bootstrap And Shared State
+*/
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -90,6 +112,10 @@ const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved', 'names'
 // a flag, never a value, and these aliases map it to its long name. Values like `-5` or `-abc` are untouched.
 const SHORT_FLAG_ALIASES = { m: 'message', h: 'help' };
 
+/*
+## Sessions, Account Resolution, And Production Guards
+*/
+
 function isFlagToken(token) {
   return typeof token === 'string' && (token.startsWith('--') || /^-[a-zA-Z]$/.test(token));
 }
@@ -565,6 +591,10 @@ function resolveDataMode(flags, session) {
   return DEFAULT_DATA_MODE;
 }
 
+/*
+## Local State, Workspaces, And Verification Evidence
+*/
+
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
@@ -1083,7 +1113,11 @@ function buildCommandWorld(response, fallback = {}) {
     branchName: response && response.branchName || fallback.branchName,
     workspace: response && response.workspace !== undefined ? response.workspace : fallback.workspace,
     stagingLane: response && response.stagingLane || source.stagingLane || fallback.stagingLane,
-    componentBranch: resolution.componentBranch || response && response.variantBranch || fallback.componentBranch,
+    // `variantWorld.componentBranch` is the platform's answer for the run (the variant branch, else the
+    // subscription); a bare `variantBranch` is null whenever the subscription decided.
+    componentBranch: resolution.componentBranch ||
+      response && ((response.variantWorld && response.variantWorld.componentBranch) || response.variantBranch) ||
+      fallback.componentBranch,
     variantId: resolution.variantId || fallback.variantId,
     sourceLayer: fallback.sourceLayer || (source.testComponentSource === 'staged' ? 'staged' : undefined)
   };
@@ -1196,6 +1230,10 @@ function loadAccountInfo(cwd) {
   }
 }
 
+/*
+## Account Repos, Guide Sync, And Platform Repo
+*/
+
 function readAccountRepoIndex() {
   if (!fs.existsSync(ACCOUNT_REPO_INDEX_FILE)) {
     return {};
@@ -1850,6 +1888,10 @@ function resolveSessionContext(cwd, flags) {
   };
 }
 
+/*
+## Component Discovery And HTTP Logging
+*/
+
 /**
  * Record the FILE identity of a component (type + filename id, or type + filename stem) on an object without
  * sending it anywhere. Non-enumerable, so JSON payloads and the content hash never see it.
@@ -2336,6 +2378,10 @@ async function loggedGet(api, cwd, endpoint, params = {}) {
   }
 }
 
+/*
+## Skill Delivery And TOC Resolution
+*/
+
 // ---------------------------------------------------------------------------
 // Skill delivery
 //
@@ -2465,6 +2511,14 @@ function resolveTocEntry(line, byAnchor, byTitle) {
     return formatTocEntry(legacyEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
   }
 
+  // Prepared form. This makes generated TOCs idempotent: a later package/build pass can re-derive the
+  // current line numbers from the emitted heading text instead of preserving stale numbers.
+  const preparedEntry = /^(\s*)[-*]\s+L\d+\s\s(.+?)\s*$/.exec(line);
+  if (preparedEntry) {
+    const title = preparedEntry[2];
+    return formatTocEntry(preparedEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
+  }
+
   return null;
 }
 
@@ -2634,6 +2688,10 @@ async function installSkillsCommand(flags) {
   }
 }
 
+/*
+## Auth And Component Staging
+*/
+
 async function authCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -3218,6 +3276,10 @@ async function stageOrRefuse(api, cwd, payload) {
   }
 }
 
+/*
+## Component Summaries, Status, And Sync Gates
+*/
+
 /** What the account's rules said about this stage or commit — including "they could not be read". */
 function printComponentPolicy(response) {
   const policy = response && response.policy;
@@ -3499,9 +3561,7 @@ function printLanesSummary(response, flags) {
 }
 
 function printStagingLaneRow(lane) {
-  const world = lane.onTrunk === true ? 'trunk'
-              : lane.onTrunk === false ? 'variant'
-              : 'unknown-world';
+  const world = laneWorldLabel(lane);
   const ws = lane.workspace ? ' [ws:' + lane.workspace + ']' : ' [shared]';
   const workset = lane.worksetKnown && lane.worksetCountAsOf != null
     ? ' workset ' + lane.worksetCountAsOf
@@ -3598,10 +3658,7 @@ function printAccountLanes(response) {
   console.log('');
   console.log('Other staging lanes on this ACCOUNT (as of the last stage/clear in each):');
   lanes.forEach((lane) => {
-    // null onTrunk means the owner could not be resolved. Say "unknown" rather than guessing a world.
-    const world = lane.onTrunk === true ? 'trunk'
-                : lane.onTrunk === false ? 'variant branch'
-                : 'branch world unknown';
+    const world = laneWorldLabel(lane);
     const ws = lane.workspace ? ' [ws:' + lane.workspace + ']' : '';
     const who = lane.userEmail ? '  ' + lane.userEmail : '';
     const ttl = lane.expiresInSeconds != null
@@ -3617,7 +3674,21 @@ function printAccountLanes(response) {
   });
   console.log('  (* = this command\'s lane)');
   console.log('  A variant-branch lane layers over that branch\'s ComponentVariant overlays, and a commit');
-  console.log('  from it writes overlays — never the trunk rows a trunk lane commits to.');
+  console.log('  from it writes overlays — never the trunk rows a trunk lane commits to. A feature-branch lane');
+  console.log('  resolves the account\'s subscription beneath its staged entries and cannot be landed.');
+}
+
+// The world a lane row resolves, from the platform's answer. null onTrunk means the owner could not be
+// resolved, and a non-trunk lane without a reported source (an older platform) is only known to be
+// non-trunk — never guessed to be a variant branch. Pure.
+function laneWorldLabel(lane) {
+  if (!lane || lane.onTrunk == null) return 'branch world unknown';
+  if (lane.onTrunk === true) return 'trunk';
+  if (lane.variantBranchSource === 'subscription-fallback') return 'feature branch';
+  if (lane.variantBranchSource === 'branch-has-variants' || lane.variantBranchSource === 'branch-has-subscribers') {
+    return 'variant branch';
+  }
+  return 'non-trunk branch';
 }
 
 function isCurrentStagingLane(lane) {
@@ -3638,10 +3709,15 @@ function printBranchContext(response) {
   console.log('');
   if (ctx.onTrunk) {
     console.log('Working tree: TRUNK (' + response.branchName + ')');
+  } else if (ctx.variantBranchSource === 'subscription-fallback') {
+    console.log('Working tree: FEATURE BRANCH "' + response.branchName + '"  (not a variant branch; trunk is "' + ctx.trunkBranch + '")');
   } else {
     console.log('Working tree: VARIANT BRANCH "' + response.branchName + '"  (trunk is "' + ctx.trunkBranch + '")');
   }
   console.log('  runs resolve:   ' + ctx.resolves);
+  if (ctx.variantBranchSource) {
+    console.log('  variant world:  ' + (ctx.variantBranch || 'none (subscription)') + '  [' + ctx.variantBranchSource + ']');
+  }
   console.log('  commit writes:  ' + ctx.commitWrites);
   if (Object.prototype.hasOwnProperty.call(ctx, 'lastSyncedSha')) {
     // null is "unknown" (never synced, expired, or the last sync had errors) — never "nothing landed".
@@ -3755,6 +3831,9 @@ async function statusComponentsCommand(flags) {
     workspace,
     dataMode,
     mode: 'status',
+    // So "runs resolve" describes the run these flags would launch, by the same server-side rule.
+    variantBranch: flags['variant-branch'],
+    asAccountId: flags['as-account'] || flags['as-account-id'],
     componentType: flags['component-type'] || flags.type,
     componentId: flags['component-id'] || flags.id
   }).then((r) => r.data);
@@ -3983,6 +4062,9 @@ async function syncComponentsCommand(rawFlags) {
     ...runContextPayload(flags),
     agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
     acknowledge: flags.acknowledge || undefined,
+    // The platform refuses to sync a branch that is not a variant branch (see featureBranchLandingRefusal);
+    // this is the explicit statement that a NEW variant branch is being created on purpose.
+    createVariantBranch: flagEnabled(flags['create-variant-branch']) || undefined,
     components: []
   };
 
@@ -4005,7 +4087,7 @@ async function syncComponentsCommand(rawFlags) {
     // --safe is fail-closed: a sync that would reconcile a repository other than this checkout's is refused.
     const preflightRepoCheck = repositoryCheck(cwd, branchContext);
     if (preflightRepoCheck.matches === false) {
-      const mismatch = repositoryMismatchMessage(preflightRepoCheck, 'components sync');
+      const mismatch = repositoryMismatchMessage(preflightRepoCheck, 'components sync', branchContext);
       if (flagEnabled(flags.json)) {
         const refusal = {
           success: false,
@@ -4132,7 +4214,7 @@ async function syncComponentsCommand(rawFlags) {
   response.repositoryCheck = repositoryCheck(cwd, { repository: response.sync && response.sync.repository });
   if (response.repositoryCheck.matches === false) {
     (flagEnabled(flags.json) ? console.error : console.log)('WARNING: ' +
-      repositoryMismatchMessage(response.repositoryCheck, 'components sync'));
+      repositoryMismatchMessage(response.repositoryCheck, 'components sync', response.branchContext));
   }
   const summary = buildSyncSummary(response);
   summary.gates = gate.checks;
@@ -4550,11 +4632,66 @@ function repositoryCheck(cwd, branchContext) {
   return { platformRepository, checkoutOrigin, matches: repositoryNamesMatch(platformRepository, checkoutOrigin) };
 }
 
-function repositoryMismatchMessage(check, commandName) {
+function repositoryMismatchMessage(check, commandName, branchContext) {
   return commandName + ': this checkout\'s origin is ' + check.checkoutOrigin + ', but the platform syncs repository "' +
     check.platformRepository + '" for this account. A push from here would never be synced, and the sync would ' +
-    'reconcile a repository you are not editing. Run it from that repository\'s checkout, or check which account ' +
-    'this command resolved (account-info.json, --account-id).';
+    'reconcile a repository you are not editing. ' + (featureBranchLandingHint(branchContext) ||
+    ('Run it from that repository\'s checkout, or check which account this command resolved ' +
+    '(account-info.json, --account-id).'));
+}
+
+// A git branch that is not a variant world (no committed variants, no subscribers) resolves the account's
+// SUBSCRIBED branch beneath its staged entries — the platform reports that as
+// `variantBranchSource: 'subscription-fallback'`. Syncing such a branch would write overlays nobody resolves,
+// so the way to land it is through the branch it resolves. Pure; null when the context says nothing of the kind.
+function featureBranchLandingHint(branchContext) {
+  if (!branchContext || branchContext.variantBranchSource !== 'subscription-fallback') return null;
+  const subscribed = branchContext.subscribedComponentBranch;
+  const trunk = branchContext.trunkBranch || 'trunk';
+  // Without a subscription the platform cannot know which branch this was cut from; naming trunk would send a
+  // branch cut from a variant branch into trunk.
+  return 'This git branch is not a variant branch: runs from it resolve ' +
+    (subscribed ? 'the \'' + subscribed + '\' variant branch this account subscribes to' : 'trunk') +
+    ' plus what you staged. To land the work, ' +
+    (subscribed
+      ? 'merge this branch into \'' + subscribed + '\' and commit/sync \'' + subscribed + '\' from that checkout.'
+      : 'merge this branch into the branch you cut it from (trunk \'' + trunk + '\', or the variant branch it came ' +
+        'from) and commit/sync that branch from its checkout.');
+}
+
+// Refuse a commit from a branch the platform reports as NOT a variant branch, unless the caller says it is
+// creating one. Mirrors the server-side refusal so nothing is pushed that cannot be synced. Pure.
+function featureBranchCommitRefusal(branchContext, branchName, flags) {
+  if (!branchContext || branchContext.variantBranchSource !== 'subscription-fallback') return null;
+  if (flags && (flags['create-variant-branch'] === true || flags['create-variant-branch'] === 'true')) return null;
+  return 'components commit refused: \'' + branchName + '\' is not a variant branch (no committed variants, no ' +
+    'subscribers). ' + featureBranchLandingHint(branchContext) + ' Committing here would write overlays for \'' +
+    branchName + '\' that nobody subscribes to, and flip every other lane on that branch to them. If you are ' +
+    'deliberately creating a NEW variant branch, re-run with --create-variant-branch.';
+}
+
+// What a verification envelope records as the world it verified. Taken from the platform's answer
+// (`variantWorld`, the same rule every run uses), never inferred from `onTrunk`: a feature branch cut from a
+// variant branch is not on trunk, yet resolves the SUBSCRIBED branch, and labelling it by its own name recorded
+// a world no run executed in. Pure.
+function verificationWorldFromStatus(statusResponse, branchName) {
+  if (!statusResponse) return {};
+  const ctx = statusResponse.branchContext || {};
+  const world = statusResponse.variantWorld || null;
+  const staged = !!(statusResponse.laneSummary && statusResponse.laneSummary.stagedCount > 0);
+  let componentBranch;
+  if (world) {
+    componentBranch = world.componentBranch || 'trunk';
+  } else {
+    // An older platform that does not report the world: the previous inference, kept for compatibility.
+    componentBranch = ctx.onTrunk ? 'trunk' : branchName;
+  }
+  const sourceLayer = staged ? 'staged' : (componentBranch && componentBranch !== 'trunk' ? 'variant' : 'trunk');
+  return {
+    componentBranch,
+    sourceLayer,
+    variantBranchSource: world ? world.variantBranchSource : undefined
+  };
 }
 
 function printRepositoryCheck(check) {
@@ -4850,6 +4987,10 @@ function buildSyncSummary(response) {
   };
 }
 
+/*
+## Branches, Promotion, Commit, And Test Runs
+*/
+
 // Inspect committed branch variants: durable, branch-scoped overlays of this account's components.
 // Unlike `components status` (which shows the ephemeral Redis staging cache), these are what
 // subscribing accounts actually resolve in production.
@@ -5457,7 +5598,7 @@ async function refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, sk
   // `--skip-git` pushes nothing, so there is nothing to mis-deliver.
   const repoCheck = skipGit ? null : repositoryCheck(cwd, branchContext);
   if (repoCheck && repoCheck.matches === false) {
-    const mismatch = repositoryMismatchMessage(repoCheck, 'components commit');
+    const mismatch = repositoryMismatchMessage(repoCheck, 'components commit', branchContext);
     if (flagEnabled(flags.json)) {
       console.log(JSON.stringify({
         success: false,
@@ -5478,6 +5619,30 @@ async function refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, sk
     }
     throw new Error(mismatch + ' No git commit or push was attempted.');
   }
+  // Before ANY git write: is this a feature branch (not a variant branch)? The platform refuses its sync, and
+  // a commit pushed first would leave a pushed-but-unsyncable branch. Same decision, taken before the push.
+  const featureRefusal = featureBranchCommitRefusal(branchContext, branchName, flags);
+  if (featureRefusal) {
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({
+        success: false,
+        mode: 'commit',
+        dataMode,
+        accountId,
+        branchName,
+        workspace,
+        branchContext,
+        refusal: 'feature_branch_landing',
+        phase: 'pre-git',
+        gitWritten: false,
+        gateViolations: [featureRefusal],
+        message: featureRefusal
+      }, null, 2));
+      process.exitCode = 1;
+      return true;
+    }
+    throw new Error(featureRefusal + ' No git commit or push was attempted.');
+  }
   if (!flagEnabled(flags.yes) && branchContextIsTrunk(branchContext)) {
     printTrunkSyncWarning(branchContext ? branchContext.trunkBranch || branchName : branchName, {
       stderr: flagEnabled(flags.json)
@@ -5819,6 +5984,10 @@ async function testCommand(flags) {
   }, { quiet: jsonOutput });
 }
 
+/*
+## Tokens, Tools, Verification, And Config
+*/
+
 async function tokenCommand(flags) {
   const subcommand = flags._ && flags._[1];
   if (subcommand === 'inspect' || subcommand === 'details' || subcommand === 'decode') {
@@ -5876,6 +6045,9 @@ async function tokenCommand(flags) {
     accountId: data.accountId,
     branchName: data.branchName,
     variantBranch: data.variantBranch,
+    // Why the variant branch is (or is not) set — the platform's one rule, so a null is explainable.
+    variantBranchSource: data.variantBranchSource,
+    variantWorld: data.variantWorld,
     workspace: data.workspace !== undefined ? data.workspace : workspace,
     stagingLane: data.stagingLane,
     accountLanes: data.accountLanes,
@@ -6346,9 +6518,10 @@ async function verifyCommand(flags, subcommand) {
 
     const source = collectVerificationSource(cwd, flags);
     if (statusResponse) {
-      source.componentBranch = statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : branchName;
-      source.sourceLayer = statusResponse.laneSummary && statusResponse.laneSummary.stagedCount > 0
-        ? 'staged' : (statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : 'variant');
+      const verifiedWorld = verificationWorldFromStatus(statusResponse, branchName);
+      source.componentBranch = verifiedWorld.componentBranch;
+      source.sourceLayer = verifiedWorld.sourceLayer;
+      if (verifiedWorld.variantBranchSource) source.variantBranchSource = verifiedWorld.variantBranchSource;
       source.stagedOverlayHash = statusResponse.laneSummary ? sha256(stableStringify(statusResponse.laneSummary)) : null;
     }
 
@@ -6712,6 +6885,10 @@ async function sessionsCommand(flags, subcommand) {
   throw new Error('Unknown sessions subcommand: ' + subcommand + '. Use: list, remove');
 }
 
+/*
+## Service Dashboard And WebSocket Listener
+*/
+
 // --- Listener PID management ---
 function isListenerRunning() {
   if (!fs.existsSync(LISTENER_PID_FILE)) {
@@ -8803,6 +8980,10 @@ async function runManagedWebsocketWatchdog() {
 
 // --- Persistent WebSocket listener ---
 // ---------------------------------------------------------------------------------------------
+/*
+## Agent And Ticket Workflows
+*/
+
 // Local agent sessions
 //
 // A "CLI agent" is ONE terminal session — one tab running Claude, Codex, or a person — that has
@@ -11857,6 +12038,10 @@ async function listenStatusCommand(flags = {}) {
   printSessionIdentity(identity);
 }
 
+/*
+## Help, Auto Update, And Command Dispatch
+*/
+
 async function whoamiCommand(flags = {}) {
   const identity = resolveSessionIdentity(process.cwd(), flags);
   printSessionResolutionWarning(identity);
@@ -12024,7 +12209,7 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'sync') {
-    console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--json]');
+    console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--create-variant-branch] [--summary] [--json]');
     console.log('');
     console.log('On trunk this reconciles the pushed repository into live component rows.');
     console.log('On a variant branch this writes ComponentVariant overlays only.');
@@ -12110,7 +12295,7 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'commit') {
-    console.log('Usage: remits-cli components commit [--yes] [--safe] [--message|-m "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]');
+    console.log('Usage: remits-cli components commit [--yes] [--safe] [--create-variant-branch] [--message|-m "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]');
     console.log('');
     console.log('Runs staged compile validation, local git add/commit/push, server sync, then fast-forward pull.');
     console.log('Prefer explicit stage + git + components sync when you need inspectable phases.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.125",
+  "version": "0.1.126",
   "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]
@@ -341,6 +341,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/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. |