@remits/remits-cli 0.1.112 → 0.1.113

package/README.md

@@ -21,6 +21,7 @@ remits-cli stop
 remits-cli install --skills
 remits-cli tools
 remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
+remits-cli tool --name mcp_firestore_search --input '{"collection":"statements","documentId":"1234"}' --scope children
 remits-cli components stage
 remits-cli components status
 remits-cli components clear
@@ -70,7 +71,8 @@ remits-cli install --skills --overwrite true
 - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
 - `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
 - `components push` is deprecated and currently behaves the same as `components stage`.
-- `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json` (`resolution.accountId`, then the short-lived `repoContext.accountInfoAccountId`, then the legacy top-level id — legacy files are rooted at the hierarchy ROOT, so their top-level `id` may be an ancestor), then the active session. For `remits-cli tool` calls the server applies a further precedence — explicit `--account-id` > `input.accountId` > session/repo default — so a tool can execute against a different account than the surrounding repo.
+- `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json` (`resolution.accountId`, then the short-lived `repoContext.accountInfoAccountId`, then the legacy top-level id — legacy files are rooted at the hierarchy ROOT, so their top-level `id` may be an ancestor), then the active session.
+- For `remits-cli tool`, read/discovery tools treat that resolved account as the **scope root**. You do not need the owning child account id for an exact document/record lookup: pass `--scope children`, or put `scope:"children"` in `--input`, and use the returned `resolvedTargetAccountId` for follow-up writes/runs. Use `--target-account-id` when you already know the exact owner, `--account-ids` for an explicit bounded owner list, and `--anchor-account-id` only to disambiguate multi-parent paths. Mutating tools still require an exact target.
 - 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.
 - `--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.

package/index.js

@@ -1248,13 +1248,45 @@ function countAccountRepos(index) {
   return listAccountRepoEntries(index).length;
 }
 
+/**
+ * Fold discovered checkouts into the index, one entry per account.
+ *
+ * <p><b>Two checkouts can claim one account, and the naive merge picked a silent winner.</b> The index is
+ * keyed by accountId, so a plain last-write-wins loop resolved a fork, a worktree or a dated backup copy
+ * by scan order — which is alphabetical, which is meaningless. Measured on this machine: account 33 had
+ * both `remits-invoice-automation` and `remits-invoice-automation copy-EOD-09302025`, and the index held
+ * the dated copy. Four open tickets would have been worked in a month-old snapshot.</p>
+ *
+ * <p>So: a real checkout always beats a non-checkout (an unpacked export cannot win merely by sorting
+ * later); an explicit `cwd` entry — the operator standing in the directory — always beats a scan; and
+ * when two genuine checkouts remain, the incumbent is KEPT and the loser is recorded in `ambiguousWith`
+ * rather than discarded. Ambiguity a person can see is recoverable; a silent winner is not.</p>
+ */
 function mergeAccountRepoEntries(entries, options = {}) {
   const nextIndex = options.existingIndex ? { ...options.existingIndex } : {};
+  const rank = (entry) => (isAccountCheckout(entry.directory) ? 2 : 0) + (entry.source === 'cwd' ? 1 : 0);
+
   for (const entry of entries) {
     if (!entry || !entry.accountId || !entry.directory) {
       continue;
     }
-    nextIndex[String(entry.accountId)] = entry;
+    const key = String(entry.accountId);
+    const current = nextIndex[key];
+    if (!current || !current.directory || current.directory === entry.directory) {
+      nextIndex[key] = { ...entry, ambiguousWith: (current && current.ambiguousWith) || [] };
+      continue;
+    }
+
+    const winner = rank(entry) > rank(current) ? entry : current;
+    const loser = winner === entry ? current : entry;
+    const seen = new Set([...((current.ambiguousWith) || []), ...((entry.ambiguousWith) || [])]);
+    // Only a genuine rival is worth reporting. A non-checkout losing to a checkout is the system
+    // working, not a decision the operator needs to review.
+    if (isAccountCheckout(loser.directory) && isAccountCheckout(winner.directory)) {
+      seen.add(loser.directory);
+    }
+    seen.delete(winner.directory);
+    nextIndex[key] = { ...winner, ambiguousWith: [...seen] };
   }
   writeAccountRepoIndex(nextIndex);
   return nextIndex;
@@ -3756,6 +3788,51 @@ function parseToolInput(flags) {
   return {};
 }
 
+const TOOL_SCOPES = ['self', 'children', 'hierarchy', 'parents'];
+
+// Hierarchy-scoped discovery flags, folded into the tool's own input.
+//
+// They are CONVENIENCE only: every one of them can be written inside --input, and a value already there
+// wins, because the explicit JSON is what the caller typed for this specific tool. The flags exist so the
+// overwhelmingly common shape — "search my repo account's children for this id" — does not require
+// hand-writing JSON.
+function applyScopeFlags(input, flags) {
+  const merged = input && typeof input === 'object' ? input : {};
+
+  const scope = flags && (flags.scope || flags['tool-scope']);
+  if (scope && merged.scope === undefined) {
+    const normalized = String(scope).trim().toLowerCase();
+    if (!TOOL_SCOPES.includes(normalized)) {
+      throw new Error('Invalid --scope "' + scope + '". Valid values: ' + TOOL_SCOPES.join(', '));
+    }
+    merged.scope = normalized;
+  }
+
+  const targetAccountId = flags && (flags['target-account-id'] || flags.targetAccountId);
+  if (targetAccountId && merged.targetAccountId === undefined) {
+    merged.targetAccountId = String(targetAccountId).trim();
+  }
+
+  const anchorAccountId = flags && (flags['anchor-account-id'] || flags.anchorAccountId);
+  if (anchorAccountId && merged.anchorAccountId === undefined) {
+    merged.anchorAccountId = String(anchorAccountId).trim();
+  }
+
+  const accountIds = flags && (flags['account-ids'] || flags.accountIds);
+  if (accountIds && merged.accountIds === undefined) {
+    const parsed = String(accountIds)
+      .split(',')
+      .map((part) => Number(String(part).trim()))
+      .filter((value) => Number.isFinite(value) && value > 0);
+    if (!parsed.length) {
+      throw new Error('--account-ids expects a comma-separated list of numeric account ids');
+    }
+    merged.accountIds = parsed;
+  }
+
+  return merged;
+}
+
 async function toolCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -3774,7 +3851,7 @@ async function toolCommand(flags) {
   const explicitFlagAccountId = Number(flags && flags['account-id']);
   const accountIdExplicit = Number.isFinite(explicitFlagAccountId) && explicitFlagAccountId > 0;
 
-  const input = parseToolInput(flags);
+  const input = applyScopeFlags(parseToolInput(flags), flags);
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
@@ -3840,6 +3917,10 @@ async function toolCommand(flags) {
     token: session.token,
     accountId,
     accountIdExplicit,
+    // The repo/session account, sent as a FIRST-CLASS value rather than left to be inferred from
+    // `accountId`: a read tool may reinterpret its own `input.accountId`, and the scope root — what bounds
+    // what the call may discover — has to survive that. The server validates it; it is never authorization.
+    scopeRootAccountId: accountId,
     branchName,
     workspace: resolveWorkspace(cwd, flags),
     dataMode,
@@ -6074,28 +6155,55 @@ const AGENT_WORKER_MAX_LOG_BYTES = 8 * 1024 * 1024;
 const AGENT_LAUNCHERS = {
   codex: {
     binary: 'codex',
+    // A ticket worker's whole job runs THROUGH the platform: `remits-cli ticket read/accept/progress/
+    // complete`, and every investigation tool. So the sandbox has to let it reach the platform, and by
+    // default it does not — `workspace-write` disables network, and a worker launched without this flag
+    // fails its FIRST command with exit 6 / HTTP 000 while looking, from the outside, like an agent that
+    // simply did not do much. Passed on the command line rather than documented as a config edit so the
+    // supervisor works on a machine nobody has prepared.
+    //
+    // `read-only` is deliberately NOT used for investigate mode, even though it is the tighter sandbox.
+    // It has no network AND no setting that restores it, so a read-only worker cannot read the ticket it
+    // was given, cannot run a diagnostic, and cannot record a finding — the three things investigating
+    // IS. It would then exit 0 having written nothing, which the supervisor reads as a delivered
+    // judgement and un-routes, so the next sweep hands the same ticket to another worker that learns the
+    // same nothing. A loop that reports success is worse than a refusal.
+    //
+    // What enforces the read-only phase instead: the brief's Boundaries section, which names the lease
+    // holder, says which commands not to run, and explains that the shared CHECKOUT is the thing at
+    // risk. Enforcement moved from the sandbox to the instructions deliberately — the sandbox could not
+    // express "may talk to the platform, may not write this directory".
     build: ({ cwd, mode, lastMessageFile }) => ({
       args: [
         'exec',
         '--cd', cwd,
         '--skip-git-repo-check',
-        '--sandbox', mode === 'investigate' ? 'read-only' : 'workspace-write',
+        '--sandbox', 'workspace-write',
+        '-c', 'sandbox_workspace_write.network_access=true',
         '--json',
         ...(lastMessageFile ? ['--output-last-message', lastMessageFile] : []),
         '-'
-      ]
+      ],
+      // Reported on the worker record so an operator can tell a phase the platform derived from a
+      // sandbox the launcher applied — they are no longer the same thing for codex.
+      sandbox: 'workspace-write' + (mode === 'investigate' ? ' (investigate: boundary is the brief)' : '')
     })
   },
   claude: {
     binary: 'claude',
+    // Same requirement, different mechanism: in `-p` there is no one to answer a permission prompt, so
+    // an un-allowlisted Bash call is DENIED rather than queued. Without this the worker cannot run
+    // remits-cli at all. `plan` mode is avoided for the same reason `read-only` is avoided above.
     build: ({ cwd, mode }) => ({
       args: [
         '-p',
         '--add-dir', cwd,
         '--output-format', 'stream-json',
         '--verbose',
-        '--permission-mode', mode === 'investigate' ? 'plan' : 'acceptEdits'
-      ]
+        '--permission-mode', 'acceptEdits',
+        '--allowedTools', 'Bash,Read,Grep,Glob,WebFetch' + (mode === 'investigate' ? '' : ',Edit,Write')
+      ],
+      sandbox: 'acceptEdits' + (mode === 'investigate' ? ' (investigate: no Edit/Write tool)' : '')
     })
   },
   gemini: {
@@ -6107,7 +6215,8 @@ const AGENT_LAUNCHERS = {
         '-p', 'Work the support ticket described above, following its instructions exactly.',
         '--approval-mode', mode === 'investigate' ? 'plan' : 'auto_edit',
         '--output-format', 'stream-json'
-      ]
+      ],
+      sandbox: mode === 'investigate' ? 'plan' : 'auto_edit'
     })
   }
 };
@@ -6179,7 +6288,31 @@ function resolveWorkerAgent(value, anchor = null) {
   };
 }
 
-/** Where the repository for an account is checked out on THIS machine, or null. */
+/**
+ * Is this directory a real checkout, rather than something that merely contains an account-info.json?
+ *
+ * <p>The index is built by scanning for `account-info.json`, and that file is also in every zip export
+ * of an account. An unpacked export in `~/Downloads` therefore looks exactly like a checkout, and it
+ * exists — which was the whole of the previous validation.</p>
+ */
+function isAccountCheckout(directory) {
+  try {
+    return !!directory && fs.existsSync(path.join(directory, '.git'));
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Where the repository for an account is checked out on THIS machine, or null.
+ *
+ * <p>Null when the entry is not a git checkout, and that is the load-bearing part. The caller's next
+ * step on null is the brief telling the worker "no local checkout was resolved — do not guess", which
+ * is the correct outcome; the previous `fs.existsSync` test let an unpacked zip export in `~/Downloads`
+ * satisfy it instead, so the guard never fired and a worker edited, staged and reported success against
+ * a directory with no remote and no history. Nothing about that run looked wrong. Measured on this
+ * machine: account 11 (11 open tickets) and account 2 both resolved that way.</p>
+ */
 function repoDirectoryForAccount(accountId) {
   const wanted = Number(accountId);
   if (!Number.isFinite(wanted) || wanted <= 0) {
@@ -6187,12 +6320,48 @@ function repoDirectoryForAccount(accountId) {
   }
   const entry = listAccountRepoEntries(readAccountRepoIndex())
     .find((candidate) => Number(candidate.accountId) === wanted);
-  if (!entry || !entry.directory || !fs.existsSync(entry.directory)) {
+  if (!entry || !entry.directory || !isAccountCheckout(entry.directory)) {
     return null;
   }
   return entry.directory;
 }
 
+/**
+ * Everything wrong with the local account-repo index, as sentences an operator can act on.
+ *
+ * <p>Reported at `agent serve` rather than discovered one ticket at a time: a supervisor about to work a
+ * production queue should be told up front which accounts it cannot work, because the alternative is
+ * finding out per ticket, hours apart, from a brief that says only "no checkout resolved".</p>
+ */
+function accountRepoIndexProblems(ownCwd = null) {
+  const problems = [];
+  // The account this session is standing in resolves from its OWN directory, not from the shared index,
+  // so an ambiguity there is not a problem for this supervisor — it is two worktrees working as intended.
+  // Reporting it anyway trains an operator to ignore the warning, and the warning is load-bearing for
+  // every OTHER account, where a silent wrong winner is unrecoverable.
+  const own = ownCwd ? accountCheckoutIdentity(ownCwd) : null;
+  for (const entry of listAccountRepoEntries(readAccountRepoIndex())) {
+    const label = 'account ' + entry.accountId + ' (' + (entry.name || 'unnamed') + ')';
+    if (!fs.existsSync(entry.directory)) {
+      problems.push({ accountId: Number(entry.accountId), severity: 'unusable',
+        message: label + ': the recorded directory no longer exists — ' + entry.directory });
+    } else if (!isAccountCheckout(entry.directory)) {
+      problems.push({ accountId: Number(entry.accountId), severity: 'unusable',
+        message: label + ': ' + entry.directory + ' is not a git checkout (an unpacked export?). ' +
+          'Tickets for this account will park instead of being worked.' });
+    }
+    if (Array.isArray(entry.ambiguousWith) && entry.ambiguousWith.length &&
+        !(own && own.accountId === Number(entry.accountId))) {
+      problems.push({ accountId: Number(entry.accountId), severity: 'ambiguous',
+        message: label + ': more than one checkout claims this account. Using ' + entry.directory +
+          '; also found ' + entry.ambiguousWith.join(', ') +
+          '. Set the right one with `remits-cli agent repos --account-id ' + entry.accountId +
+          ' --directory <path>`.' });
+    }
+  }
+  return problems;
+}
+
 /**
  * The working directory a ticket should be worked in.
  *
@@ -6201,13 +6370,27 @@ function repoDirectoryForAccount(accountId) {
  * neither is checked out here the answer is null, and the brief says so explicitly instead of
  * letting the worker start in whatever directory the supervisor happened to inherit.
  */
-function resolveTicketWorkingDirectory(ticket) {
+function resolveTicketWorkingDirectory(ticket, ownCwd = null) {
   const facts = (ticket && ticket.briefFacts) || {};
   const candidates = [
     facts.repoAccountId,
     ticket && ticket.implementationAccountId,
     ticket && ticket.accountId
-  ];
+  ].map((value) => Number(value)).filter((value) => Number.isFinite(value) && value > 0);
+
+  // THIS supervisor's own checkout wins, when it is a checkout of one of the candidate accounts.
+  //
+  // The account-repo index is a single global map keyed by accountId, and `agent serve` writes its own
+  // cwd into it — so two supervisors serving two git WORKTREES of one account fight over one entry, and
+  // the second to start silently repoints the first's future workers into its own tree. That is the
+  // shape worktrees exist to prevent: a supervisor must launch its workers where IT is, not where the
+  // machine's last-registered session happened to be. The index stays the answer for every account this
+  // session is not standing in, which is the normal case.
+  const own = ownCwd ? accountCheckoutIdentity(ownCwd) : null;
+  if (own && candidates.includes(own.accountId)) {
+    return own.directory;
+  }
+
   for (const candidate of candidates) {
     const dir = repoDirectoryForAccount(candidate);
     if (dir) {
@@ -6217,6 +6400,30 @@ function resolveTicketWorkingDirectory(ticket) {
   return null;
 }
 
+/**
+ * Which account this directory is a checkout OF, read from the directory itself.
+ *
+ * Deliberately not a lookup in the shared index: the whole point is to answer for one process without
+ * consulting a map another process can overwrite. Null when the directory is not a real checkout — an
+ * unpacked zip export carries `account-info.json` too, which is exactly the trap `isAccountCheckout`
+ * exists to close.
+ */
+function accountCheckoutIdentity(directory) {
+  try {
+    if (!directory || !isAccountCheckout(directory)) {
+      return null;
+    }
+    const info = loadAccountInfo(directory);
+    const accountId = Number(info && accountIdFromAccountInfo(info));
+    if (!Number.isFinite(accountId) || accountId <= 0) {
+      return null;
+    }
+    return { accountId, directory: path.resolve(directory) };
+  } catch (_) {
+    return null;
+  }
+}
+
 /**
  * Turn a worker's streamed output into something an operator can read in one line.
  *
@@ -6665,6 +6872,35 @@ async function agentServeCommand(flags) {
   const mode = String(flags.mode || (flagEnabled(flags['investigate-only']) ? 'investigate' : 'edit'))
     .toLowerCase() === 'investigate' ? 'investigate' : 'edit';
 
+  // Say what this supervisor CANNOT work, before it starts rather than one ticket at a time. A worker
+  // pointed at an account with no usable checkout parks correctly, but the operator only learns that
+  // from a brief they may never read, hours later, on one ticket. `--strict-repos` turns it into a
+  // refusal for anyone who would rather not start a production run with known holes.
+  try {
+    updateAccountRepoIndex(process.cwd());
+    discoverAccountRepos();
+  } catch (_) { /* best-effort; the checks below still report what the index does say */ }
+  const problems = accountRepoIndexProblems(process.cwd());
+  if (problems.length) {
+    console.log('');
+    console.log('Account repository index — ' + problems.length + ' issue(s) to know about before serving:');
+    for (const problem of problems) {
+      console.log('  [' + problem.severity + '] ' + problem.message);
+    }
+    console.log('  Tickets for an "unusable" account are parked with an explanation, never worked in the');
+    console.log('  wrong directory. Fix with: remits-cli agent repos --account-id <id> --directory <path>');
+    const ownHere = accountCheckoutIdentity(process.cwd());
+    if (ownHere) {
+      console.log('  Account ' + ownHere.accountId + ' is exempt: this session serves it from its own directory');
+      console.log('  (' + ownHere.directory + '), so a second worktree elsewhere cannot redirect these workers.');
+    }
+    console.log('');
+    if (flagEnabled(flags['strict-repos'])) {
+      throw new Error('Refusing to serve with ' + problems.length +
+        ' account-repository issue(s). Resolve them, or drop --strict-repos to serve anyway.');
+    }
+  }
+
   return agentRegisterCommand(flags, {
     serve: {
       workerAgent,
@@ -6876,6 +7112,54 @@ function clearWorkerAttempts(agentId, ticketId) {
   }
 }
 
+/**
+ * The worker's closing summary, recorded on the ticket by the SUPERVISOR.
+ *
+ * <p>A worker is supposed to record what it established itself, with `remits-cli ticket progress`. Most
+ * do. The ones that do not are exactly the runs worth hearing from: a worker that hit its context limit,
+ * that crashed after investigating, or that could not reach the platform at all. Their conclusion was
+ * captured to disk the whole time (`codex exec --output-last-message`) and thrown away, so a ticket came
+ * back to the queue with nothing on it and the next worker rediscovered the same thing.</p>
+ *
+ * <p>Posted only when the run added no worklog entry of its own, so a worker that reported properly is
+ * not duplicated. Marked `worker_summary` rather than `investigation` so a reader can tell a finding the
+ * worker chose to record from a transcript tail the supervisor salvaged.</p>
+ */
+async function postWorkerSummary(context, agentId, ticket, summaryFile, options = {}) {
+  let text = '';
+  try {
+    text = fs.readFileSync(summaryFile, 'utf8').trim();
+  } catch (_) {
+    return false;   // codex only writes it on a clean finish, and the other launchers never do.
+  }
+  if (!text) {
+    return false;
+  }
+  // The worklog is read by people and by the next worker's brief; a whole transcript would bury both.
+  const MAX = 4000;
+  const body = text.length > MAX ? (text.slice(0, MAX) + '\n\n…truncated; full run: ' + options.logFile) : text;
+  try {
+    await buildAxios(context.baseUrl, context.session.token, 20000)
+      .post('/cli/ticket', {
+        action: 'progress',
+        ticketId: ticket.ticketId || ticket.id,
+        accountId: Number(ticket.accountId) || undefined,
+        dataMode: context.dataMode,
+        agentId,
+        category: 'worker_summary',
+        summary: 'Autonomous worker exited without recording a finding; this is its closing summary.',
+        details: body,
+        nextStep: options.nextStep || null
+      });
+    return true;
+  } catch (err) {
+    appendGlobalActivityLog('agent', 'worker.summary_post_failed', {
+      agentId, ticketId: ticket.ticketId || ticket.id, error: describeError(err)
+    }, 'error');
+    return false;
+  }
+}
+
 /** Drop a claim on the platform. Best-effort: the claim expires on its own if this never lands. */
 async function releaseTicketClaim(context, agentId, ticket, options = {}) {
   try {
@@ -6928,7 +7212,7 @@ function spawnTicketWorker(context, ctx, ticket) {
     return { pid: null, done: Promise.resolve({ ticketId, ok: false, reason: 'unsupported_agent' }) };
   }
 
-  const workingDirectory = resolveTicketWorkingDirectory(ticket);
+  const workingDirectory = resolveTicketWorkingDirectory(ticket, ctx && ctx.cwd);
   // The brief is rendered server-side without the local path (the platform cannot know it), so the
   // resolved directory is appended here. When nothing resolved, the server-rendered brief already
   // tells the worker to find it rather than guess — do not paper over that with a default.
@@ -6999,6 +7283,11 @@ function spawnTicketWorker(context, ctx, ticket) {
     workspace: workerWorkspace,
     attempt,
     agentType,
+    // The sandbox the launcher actually applied. Kept beside the phase because for codex they are no
+    // longer the same fact: an investigating worker still runs workspace-write (it needs the network to
+    // report at all), and its boundary is the brief. An operator reading "investigating" must be able to
+    // see that.
+    sandbox: built.sandbox || null,
     startedAt: new Date().toISOString(),
     workingDirectory: workingDirectory || null,
     accountId: ticket.accountId || null,
@@ -7081,6 +7370,22 @@ function spawnTicketWorker(context, ctx, ticket) {
       });
 
       const row = (result && result.ticket) || {};
+
+      // Did this run leave anything on the record? If not, salvage its closing summary before the ticket
+      // goes back to the queue — otherwise the next worker starts from exactly where this one did.
+      // Compared against the count we were HANDED at spawn, so a worker that reported properly (or that
+      // asked a question, or completed) is never duplicated.
+      const worklogBefore = Number(ticket.worklogCount || 0);
+      const worklogAfter = Number(row.worklogCount != null ? row.worklogCount : worklogBefore);
+      if (worklogAfter <= worklogBefore && !['resolved', 'closed'].includes(String(row.status || ''))) {
+        await postWorkerSummary(context, agentId, { ticketId, accountId: ticket.accountId }, lastMessageFile, {
+          logFile,
+          nextStep: giveUp
+            ? 'This worker failed ' + attempt + ' time(s) and the ticket was returned to the queue.'
+            : null
+        });
+      }
+
       const terminal = ['resolved', 'closed'].includes(String(row.status || ''));
       if (terminal || giveUp) {
         clearWorkerAttempts(agentId, ticketId);
@@ -7397,6 +7702,21 @@ async function agentWorkCommand(flags) {
  */
 async function ticketCommand(flags, subcommand) {
   const action = String(subcommand || 'read').toLowerCase();
+
+  // `queue` and `create` are the two verbs with no ticket to act on, so they are dispatched before the
+  // id requirement rather than being forced to invent one.
+  if (action === 'queue' || action === 'list' || action === 'ls') {
+    return ticketQueueCommand(flags);
+  }
+  if (action === 'create' || action === 'new' || action === 'raise') {
+    return ticketCreateCommand(flags);
+  }
+  // Bulk reclaim scans a queue rather than acting on one id, so it is dispatched here too. With
+  // --ticket it falls through to the single-ticket path below like any other verb.
+  if (action === 'reclaim' && !flags.ticket && !flags['ticket-id']) {
+    return ticketReclaimSweepCommand(flags);
+  }
+
   const ticketId = String(flags.ticket || flags['ticket-id'] || flags._?.[2] || process.env.REMITS_SUPPORT_TICKET_ID || '').trim();
   if (!ticketId) {
     printTicketHelp();
@@ -7441,7 +7761,9 @@ async function ticketCommand(flags, subcommand) {
     summary: flags.summary || flags.note,
     question: flags.question,
     context: flags.context,
-    to: flags.to,
+    // Recipients are a list on the platform side (message.to / deliver.to). A single value still works,
+    // so `--to a@x.test` and `--to a@x.test,b@x.test` both do what they look like they do.
+    to: flags.to ? String(flags.to).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
     message: flags.message || flags.answer,
     route: flags.route === 'false' ? false : undefined,
     details: flags.details,
@@ -7457,6 +7779,26 @@ async function ticketCommand(flags, subcommand) {
     size: planningFlagValue(flags.size),
     blockedBy: planningFlagValue(firstDefined(flags['blocked-by'], flags.blockedBy)),
     workstream: planningFlagValue(flags.workstream),
+    tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
+    label: flags.label,
+    url: flags.url,
+    body: flags.body,
+    role: flags.role,
+    email: flags.email,
+    key: flags.key,
+    value: flags.value,
+    // Conversation and outbox. `--message` is shared with `answer`/`note`, which is deliberate: it is
+    // always "the text", and the ACTION decides who ends up reading it.
+    channel: flags.channel,
+    subject: flags.subject,
+    visibility: flags.visibility,
+    direction: flags.direction,
+    template: flags.template,
+    cc: flags.cc ? String(flags.cc).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
+    deliveryId: flags['delivery-id'] || flags.deliveryId || undefined,
+    idempotencyKey: flags['idempotency-key'] || flags.idempotencyKey || undefined,
+    providerMessageId: flags['provider-message-id'] || undefined,
+    reason: flags.reason,
     // Lease operations act as the AGENT, not the user: the lease is held by a worker session, and a
     // human's email is not a thing that can hold one. Inside a worker these come from the environment
     // the supervisor set, so the commands need no flags.
@@ -7495,7 +7837,7 @@ async function ticketCommand(flags, subcommand) {
     return;
   }
 
-  if (flagEnabled(flags.json) || action === 'read') {
+  if (flagEnabled(flags.json) || action === 'read' || action === 'deliveries') {
     console.log(JSON.stringify(response, null, 2));
     return;
   }
@@ -7537,6 +7879,19 @@ async function ticketCommand(flags, subcommand) {
   const ticket = (response && response.ticket) || {};
   console.log(action + ' ok — ticket ' + ticketId + ' is now [' + (ticket.status || '?') + ']' +
     (ticket.assignedTo ? ', owned by ' + ticket.assignedTo : ', unassigned'));
+  // Say what was actually written. Without this, `message`, `note`, `deliver` and `participant` all
+  // printed the same status line, so the only feedback distinguishing "told the customer" from "left an
+  // internal note" was the word the caller had just typed.
+  if (action === 'message') {
+    console.log('  public message added (' + (ticket.messageCount || '?') + ' on the ticket) — visible to the requester.');
+    console.log('  This did NOT send anything. To have it delivered: remits-cli ticket deliver --channel email --to <who>');
+  }
+  if (action === 'note') console.log('  internal note added — the requester does not see it.');
+  if (action === 'participant') console.log('  participants: ' + (ticket.participantCount || '?'));
+  if (action === 'deliver') {
+    console.log('  delivery queued (' + (ticket.deliveryCount || '?') + ' on the ticket). An account-owned rule or');
+    console.log('  scheduled Action sends it. Check with: remits-cli ticket deliveries --ticket ' + ticketId);
+  }
   if (action === 'planning' || action === 'plan') {
     const planning = [
       ticket.workstream ? 'workstream=' + ticket.workstream : '',
@@ -7557,6 +7912,229 @@ async function ticketCommand(flags, subcommand) {
   }
 }
 
+/**
+ * The ticket queue — what else is open, and what it looks like as a whole.
+ *
+ * <p><b>Why this had to exist.</b> The worker brief is emphatic that `remits-cli ticket` is the surface to
+ * use, and that an account's own ticket tooling must not be reached for: it belongs to one account, may not
+ * exist on this platform, and refuses tickets other accounts own. That advice was right and the surface was
+ * incomplete — it could act on ONE ticket whose id it was handed, and could not see anything else. So a
+ * worker could not tell that the ticket it was given is one of eleven instances of the same fix, could not
+ * check whether the defect it just found is already filed, and could not triage at all. The server side
+ * already existed in full (`/cli/tickets`, the same `queue(...)` the operator UI reads); its only consumer
+ * was the local dashboard.</p>
+ */
+async function ticketQueueCommand(flags) {
+  const local = listLocalAgents()[0] || null;
+  const context = agentSessionFor(flags, local);
+  const accountId = Number(flags['account-id'] || flags.accountId || context.accountId);
+  if (!Number.isFinite(accountId) || accountId <= 0) {
+    throw new Error('ticket queue needs --account-id (or run it from an account repo).');
+  }
+
+  const csv = (value) => (value ? String(value).split(',').map((v) => v.trim()).filter(Boolean) : undefined);
+  const response = await buildAxios(context.baseUrl, context.session.token, 30000)
+    .post('/cli/tickets', {
+      accountId,
+      dataMode: context.dataMode,
+      statuses: csv(flags.status || flags.statuses),
+      priorities: csv(flags.priority || flags.priorities),
+      types: csv(flags.type || flags.types),
+      sources: csv(flags.source || flags.sources),
+      workstream: flags.workstream,
+      assignedTo: flags['assigned-to'] || flags.assignedTo,
+      routedAgentId: flags['routed-to'] || flags.routedAgentId,
+      unrouted: flagEnabled(flags.unrouted) || undefined,
+      unassigned: flagEnabled(flags.unassigned) || undefined,
+      // "Parked on a human" cannot be asked for with a status filter: `ask` parks a ticket in
+      // pending_review, which also means "done, review me".
+      awaitingResponse: flagEnabled(flags['awaiting-response'] || flags.awaitingResponse) || undefined,
+      plannedIn: flags['planned-in'] || flags.plannedIn,
+      boardStage: flags['board-stage'] || flags.boardStage,
+      blockedBy: flags['blocked-by'] || flags.blockedBy,
+      search: flags.search || flags.q,
+      sortBy: flags['sort-by'] || flags.sortBy,
+      sortDirection: flags['sort-direction'] || flags.sortDirection,
+      includeChildren: flags['include-children'] === 'false' ? false : undefined,
+      limit: parsePositiveInt(flags.limit, 25)
+    }).then((r) => r.data);
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+
+  const tickets = (response && response.tickets) || [];
+  const counts = (response && response.counts) || {};
+  if (!tickets.length) {
+    console.log('No tickets match. (' + (response && response.dataMode) + ' lane, account ' + accountId + ')');
+    return;
+  }
+  console.log(String(response.totalCount != null ? response.totalCount : tickets.length) +
+    ' ticket(s) — ' + (counts.unrouted || 0) + ' unrouted, ' + (counts.unassigned || 0) + ' unassigned' +
+    ', ' + (counts.awaitingResponse || 0) + ' waiting on a human' +
+    '   [' + (response.dataMode || '?') + ' lane]');
+  console.log('');
+  // Board position is printed only when some ticket in this queue actually has one. An always-on column
+  // would be blank for every account that does not run a board, and a blank column reads as missing data.
+  const showsBoard = tickets.some((t) => t.boardStage || t.plannedIn || t.blockedBy);
+  for (const t of tickets) {
+    // The repo account, not just the owning account: it is what the edit lease excludes on, so it is
+    // what tells a reader which of these can be worked at the same time.
+    const repo = t.implementationAccountId || t.accountId;
+    const who = t.routedAgentLabel || t.routedAgentId || t.assignedTo || '—';
+    console.log('  ' + String(t.ticketId || t.id).padStart(6) + '  ' +
+      String(t.status || '').padEnd(14) + String(t.priority || '').padEnd(9) +
+      'repo ' + String(repo || '?').padEnd(6) +
+      String(who).slice(0, 18).padEnd(20) + String(t.subject || '').slice(0, 58));
+    // A second line rather than more columns: these are the account's own labels, of unbounded length,
+    // and truncating `awaiting_customer_confirmation` to fit a column makes it unrecognisable.
+    const marks = [
+      t.awaitingResponseSince ? 'WAITING ON A HUMAN' : '',
+      showsBoard && t.boardStage ? 'stage ' + t.boardStage : '',
+      showsBoard && t.plannedIn ? 'in ' + t.plannedIn : '',
+      showsBoard && t.blockedBy ? 'BLOCKED BY ' + t.blockedBy : ''
+    ].filter(Boolean);
+    if (marks.length) console.log(' '.repeat(10) + marks.join('   '));
+  }
+  if (response.totalCount > tickets.length) {
+    console.log('');
+    console.log('  showing ' + tickets.length + ' of ' + response.totalCount + ' — raise --limit to see more');
+  }
+}
+
+/**
+ * Find tickets an agent took and abandoned, and hand them back to the queue.
+ *
+ * <p><b>Dry by default.</b> This takes work away from a holder on a judgement about staleness, across a
+ * whole account tree, in one command — so the default is to show what it WOULD do. `--apply` is the
+ * operator saying yes. The platform re-checks every row against the document before acting, so a stale
+ * listing cannot cause a wrong reclaim even if this list is minutes old.</p>
+ */
+async function ticketReclaimSweepCommand(flags) {
+  const local = listLocalAgents()[0] || null;
+  const context = agentSessionFor(flags, local);
+  const accountId = Number(flags['account-id'] || flags.accountId || context.accountId);
+  if (!Number.isFinite(accountId) || accountId <= 0) {
+    throw new Error('ticket reclaim needs --account-id (or --ticket ID for a single ticket).');
+  }
+  const staleHours = parsePositiveInt(flags['stale-hours'] || flags.staleHours, 24);
+  const apply = flagEnabled(flags.apply);
+
+  const queue = await buildAxios(context.baseUrl, context.session.token, 30000)
+    .post('/cli/tickets', {
+      accountId, dataMode: context.dataMode,
+      statuses: ['accepted', 'in_progress'], limit: parsePositiveInt(flags.limit, 200)
+    }).then((r) => r.data);
+
+  const cutoff = Date.now() - staleHours * 3600000;
+  // A local pre-filter only, to keep the output short and avoid asking about obviously-live rows. The
+  // platform owns the actual decision and will refuse anything that does not qualify.
+  const candidates = ((queue && queue.tickets) || []).filter((t) => {
+    const holder = t.assignedTo || t.routedAgentId;
+    if (!holder || String(holder).includes('@')) return false;
+    if (t.awaitingResponseSince) return false;
+    const touched = Date.parse(t.updatedAt || t.claimedAt || t.assignedAt || '');
+    return Number.isFinite(touched) && touched < cutoff;
+  });
+
+  if (!candidates.length) {
+    console.log('No abandoned tickets under account ' + accountId + ' (agent-held, untouched for ' +
+      staleHours + 'h). ' + (((queue && queue.tickets) || []).length) + ' accepted/in_progress ticket(s) checked.');
+    return;
+  }
+
+  console.log((apply ? 'Reclaiming ' : 'Would reclaim ') + candidates.length + ' abandoned ticket(s) — ' +
+    'agent-held, no live session, untouched for ' + staleHours + 'h:');
+  console.log('');
+  let done = 0;
+  for (const t of candidates) {
+    const id = String(t.ticketId || t.id);
+    const line = '  ' + id.padStart(6) + '  ' + String(t.status || '').padEnd(13) +
+      String(t.assignedTo || t.routedAgentId || '').slice(0, 16).padEnd(18) +
+      String(t.subject || '').slice(0, 52);
+    if (!apply) {
+      console.log(line);
+      continue;
+    }
+    try {
+      await buildAxios(context.baseUrl, context.session.token, 30000)
+        .post('/cli/ticket', {
+          action: 'reclaim', ticketId: id, accountId: Number(t.accountId) || undefined,
+          dataMode: context.dataMode, staleHours, reason: flags.reason || undefined
+        });
+      done += 1;
+      console.log(line + '   -> open');
+    } catch (err) {
+      const body = err && err.response && err.response.data;
+      // A refusal is the platform re-checking against the document and disagreeing with this listing.
+      // That is the guard working, so it is reported per ticket rather than failing the run.
+      console.log(line + '   -> refused: ' + ((body && body.message) || describeError(err)).slice(0, 90));
+    }
+  }
+  console.log('');
+  console.log(apply
+    ? (done + ' reclaimed and back in the queue; an idle supervisor will sweep them.')
+    : 'Dry run. Re-run with --apply to reclaim these.');
+}
+
+/**
+ * Raise a ticket.
+ *
+ * <p>The verb a worker needs when it finds a SECOND problem. Without it the only options were to widen the
+ * ticket it was given until the record no longer described one piece of work, or to drop the finding.</p>
+ */
+async function ticketCreateCommand(flags) {
+  const local = listLocalAgents()[0] || null;
+  const context = agentSessionFor(flags, local);
+  const accountId = Number(flags['account-id'] || flags.accountId || context.accountId);
+  if (!Number.isFinite(accountId) || accountId <= 0) {
+    throw new Error('ticket create needs --account-id (or run it from an account repo).');
+  }
+  if (!flags.subject) {
+    throw new Error('ticket create needs --subject "..." and --type defect|question|task|incident|enhancement.');
+  }
+
+  let response;
+  try {
+    response = await buildAxios(context.baseUrl, context.session.token, 30000)
+      .post('/cli/ticketCreate', {
+        accountId,
+        dataMode: context.dataMode,
+        subject: flags.subject,
+        description: flags.description || flags.body,
+        type: flags.type || 'defect',
+        priority: flags.priority,
+        source: flags.source,
+        workstream: flags.workstream,
+        affectedComponent: flags['affected-component'] || flags.affectedComponent,
+        implementationAccountId: flags['implementation-account-id'] || flags.implementationAccountId,
+        // A deterministic key makes this get-or-create, which is what stops a swept fleet raising the
+        // same follow-up once per worker.
+        referenceId: flags['reference-id'] || flags.referenceId,
+        tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
+        agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined
+      }).then((r) => r.data);
+  } catch (err) {
+    const body = err && err.response && err.response.data;
+    if (body && body.message) {
+      console.error('Refused: ' + body.message);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+  const t = (response && response.ticket) || {};
+  console.log('created ticket ' + response.ticketId + ' on account ' + response.accountId +
+    ' [' + (t.status || 'open') + ']');
+  console.log('  ' + (t.subject || flags.subject));
+}
+
 /** The account a ticket belongs to, so routing does not make the caller look it up by hand. */
 async function resolveTicketAccountId(context, ticketId) {
   const read = await buildAxios(context.baseUrl, context.session.token, 20000)
@@ -7573,6 +8151,20 @@ async function resolveTicketAccountId(context, ticketId) {
 function printTicketHelp() {
   console.log('Usage: remits-cli ticket <action> --ticket ID');
   console.log('');
+  console.log('  queue [--account-id ID] [--status open,accepted] [--unrouted] [--search "..."]');
+  console.log('      What else is open. Read it BEFORE deciding your ticket is unique — the same fix often');
+  console.log('      appears a dozen times, and the "repo" column is the account the edit lease excludes');
+  console.log('      on, so it also tells you which of these can be worked at the same time.');
+  console.log('      Also: --priority --type --workstream --assigned-to --unassigned --board-stage');
+  console.log('            --planned-in --blocked-by --sort-by --sort-direction --limit --json');
+  console.log('      --awaiting-response lists only tickets parked on a human. A status filter cannot');
+  console.log('      ask that: `ask` parks a ticket in pending_review, which also means "done, review me".');
+  console.log('  create --subject "..." --type defect|question|task|incident|enhancement');
+  console.log('      Raise a ticket. Use it when you find a SECOND problem while working one — file it');
+  console.log('      rather than widening the ticket you were given. [--priority --description --tags');
+  console.log('      --workstream --affected-component --implementation-account-id --reference-id]');
+  console.log('      --reference-id makes it get-or-create, so a re-run does not duplicate it.');
+  console.log('');
   console.log('  read                                  The full ticket record, as JSON.');
   console.log('  where                                 WHERE this work is happening: repository account,');
   console.log('      checkout, branch, staging workspace lane, the live edit lease and who holds it, the');
@@ -7584,13 +8176,39 @@ function printTicketHelp() {
   console.log('  complete --resolution "what you found and did"');
   console.log('  ask --question "..." [--context "..."] [--to WHO]');
   console.log('      Put a decision to a human and park. Use it when the CHOICE is not yours.');
-  console.log('  reply --message "..." [--route false]');
-  console.log('      Answer the open question. By default this re-routes the ticket, so a fresh worker');
-  console.log('      resumes with your answer already in its brief.');
+  console.log('  answer --message "..." [--route false]   (alias: reply)');
+  console.log('      Answer the open question a previous run asked. By default this re-routes the ticket,');
+  console.log('      so a fresh worker resumes with your answer already in its brief. This is NOT how you');
+  console.log('      talk to the requester — that is `message`. (`reply` means the conversational one in');
+  console.log('      some account tools, so this surface teaches `answer` and keeps `reply` as an alias.)');
+  console.log('  message --message "..." [--to a@x,b@y] [--subject "..."] [--channel email]');
+  console.log('      A PUBLIC conversation entry the requester reads. Writing it does not send it:');
+  console.log('      the record is vendor-agnostic and the account\'s own rule chooses the transport.');
+  console.log('  deliver --channel email --to a@x [--template T] [--subject "..."] [--idempotency-key K]');
+  console.log('      Ask for that entry to actually be SENT. It records an outbox request; an account-owned');
+  console.log('      rule or scheduled Action delivers it and marks the result. Use it when a ticket is');
+  console.log('      waiting on somebody who is not watching the queue.');
+  console.log('  deliveries [--channel email]          What is queued to go out, and what already went.');
+  console.log('  delivered --delivery-id ID  |  delivery-failed --delivery-id ID --reason "..."');
   console.log('  release [--notes "..."]               Hand it back to the queue.');
+  console.log('  reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]');
+  console.log('      OPERATOR: take a ticket back from an agent that accepted it and vanished. Such a');
+  console.log('      ticket is invisible to the sweep (it is assigned, so nothing offers it to anyone).');
+  console.log('      Never touches a ticket owned by a person, holding a live claim, or awaiting a reply.');
+  console.log('      Without --ticket it scans the account tree and is a DRY RUN until --apply.');
   console.log('  reopen | assign --assignee EMAIL');
   console.log('  route --agent AGENT_ID                 Hand it to a registered agent session.');
   console.log('  unroute                               Clear its routing, e.g. when that session is gone.');
+  console.log('  tag --tags a,b                        Mark it. The cheapest way to make a cluster of');
+  console.log('      near-identical tickets visible as one cluster to whoever looks next.');
+  console.log('  artifact --type TYPE --label "..." [--url U | --content "..."]');
+  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');
+  console.log('      see it; the requester does not. Use `message` for anything they should read.');
+  console.log('  participant --email E [--role watcher|requester|agent]');
+  console.log('  field --key K --value V               Write the ORGANIZATION\'s own field on the ticket,');
+  console.log('      outside the platform\'s bounded planning slots. Whatever your account models.');
   console.log('  planning [--workstream V] [--planned-in V] [--board-stage V] [--rank N] [--size V] [--blocked-by V]');
   console.log('      Update organization-owned planning fields without changing platform lifecycle status.');
   console.log('      Pass a flag with no value to CLEAR that slot, e.g. --blocked-by');
@@ -7773,6 +8391,104 @@ async function agentListCommand(flags) {
   }
 }
 
+/**
+ * Inspect and correct the local account-repository index — which checkout a ticket for an account is
+ * worked in.
+ *
+ * <p>This index is the one fact the platform cannot supply: it knows the ticket and the account, and
+ * only this machine knows where that account is checked out. It is built by scanning for
+ * `account-info.json`, which is also present in every unpacked zip export, so it can and does acquire
+ * entries that are not checkouts at all. There was no way to see it, and no way to correct it.</p>
+ */
+async function agentReposCommand(flags) {
+  const accountId = Number(flags['account-id'] || flags.accountId);
+  const directory = flags.directory || flags.dir;
+
+  if (Number.isFinite(accountId) && accountId > 0 && directory) {
+    const resolved = path.resolve(String(directory));
+    if (!fs.existsSync(resolved)) {
+      throw new Error('No such directory: ' + resolved);
+    }
+    if (!isAccountCheckout(resolved)) {
+      throw new Error(resolved + ' is not a git checkout. A ticket worker edits, stages and reports ' +
+        'against this directory, so an unpacked export would silently lose the work.');
+    }
+    const info = loadAccountInfo(resolved);
+    const declared = info ? Number(accountIdFromAccountInfo(info)) : null;
+    if (declared && declared !== accountId) {
+      throw new Error(resolved + ' declares account ' + declared + ', not ' + accountId +
+        '. Point account ' + declared + ' at it instead, or pass the directory that belongs to ' + accountId + '.');
+    }
+    const index = readAccountRepoIndex();
+    const previous = index[String(accountId)];
+    index[String(accountId)] = {
+      ...(previous || {}),
+      ...(info ? buildAccountRepoEntryFromInfo(info, resolved, 'manual') : {}),
+      accountId,
+      directory: resolved,
+      source: 'manual',
+      // The operator has just answered the question, so the rival is no longer ambiguity.
+      ambiguousWith: [],
+      updatedAt: new Date().toISOString()
+    };
+    writeAccountRepoIndex(index);
+    console.log('account ' + accountId + ' -> ' + resolved);
+    if (previous && previous.directory && previous.directory !== resolved) {
+      console.log('  (was ' + previous.directory + ')');
+    }
+    return;
+  }
+
+  if (Number.isFinite(accountId) && accountId > 0 && flagEnabled(flags.forget)) {
+    const index = readAccountRepoIndex();
+    const previous = index[String(accountId)];
+    delete index[String(accountId)];
+    writeAccountRepoIndex(index);
+    console.log(previous
+      ? 'account ' + accountId + ' removed (was ' + previous.directory + '). Its tickets will now park ' +
+        'with an explanation rather than being worked in that directory.'
+      : 'account ' + accountId + ' was not in the index.');
+    return;
+  }
+
+  if (flagEnabled(flags.rescan)) {
+    try { discoverAccountRepos(); } catch (err) { console.error('scan failed: ' + describeError(err)); }
+  }
+
+  const entries = listAccountRepoEntries(readAccountRepoIndex())
+    .sort((a, b) => Number(a.accountId) - Number(b.accountId));
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify({ repos: entries, problems: accountRepoIndexProblems() }, null, 2));
+    return;
+  }
+
+  console.log('Account repositories on this machine (' + entries.length + '):');
+  console.log('');
+  for (const entry of entries) {
+    const ok = isAccountCheckout(entry.directory);
+    const missing = !fs.existsSync(entry.directory);
+    const state = missing ? 'MISSING ' : (ok ? 'ok      ' : 'NOT-GIT ');
+    console.log('  ' + state + String(entry.accountId).padStart(5) + '  ' +
+      String(entry.name || '').slice(0, 26).padEnd(26) + '  ' + entry.directory);
+    for (const rival of entry.ambiguousWith || []) {
+      console.log('           also claims this account: ' + rival);
+    }
+  }
+
+  const problems = accountRepoIndexProblems();
+  if (problems.length) {
+    console.log('');
+    console.log(problems.length + ' issue(s):');
+    for (const problem of problems) {
+      console.log('  [' + problem.severity + '] ' + problem.message);
+    }
+  }
+  console.log('');
+  console.log('  Set one:    remits-cli agent repos --account-id <id> --directory <path>');
+  console.log('  Remove one: remits-cli agent repos --account-id <id> --forget');
+  console.log('  Rescan:     remits-cli agent repos --rescan');
+}
+
 async function agentReleaseCommand(flags) {
   const agentId = resolveAgentId(flags, { optional: true });
   if (!agentId) {
@@ -7813,6 +8529,7 @@ async function agentCommand(flags, subcommand) {
     case 'work': return agentWorkCommand(flags);
     case 'list': case 'ls': return agentListCommand(flags);
     case 'map': case 'work-map': case 'workmap': return agentWorkMapCommand(flags);
+    case 'repos': case 'repo': return agentReposCommand(flags);
     case 'release': case 'deregister': case 'stop': return agentReleaseCommand(flags);
     case 'heartbeat-daemon': return agentHeartbeatDaemonCommand(flags);
     default:
@@ -7858,6 +8575,12 @@ function printAgentHelp() {
   console.log('  map  [--account-ids 1,4] [--json]    Who is EDITING which repository right now.');
   console.log('      One agent at a time may edit an account\'s repo (the edit lease); everyone else');
   console.log('      investigates read-only. Check this before starting work that changes files.');
+  console.log('  repos [--rescan] [--json]            WHERE each account is checked out on this machine —');
+  console.log('      the one fact the platform cannot supply, and what decides the directory a ticket');
+  console.log('      worker is launched into. Flags anything that is not a git checkout (an unpacked');
+  console.log('      export looks identical to the scanner) and any account claimed by two checkouts.');
+  console.log('      Correct it with --account-id <id> --directory <path>, or --account-id <id> --forget');
+  console.log('      to make that account\'s tickets park instead of being worked somewhere wrong.');
   console.log('  release                              Deregister this session immediately.');
   console.log('');
   console.log('  After `register`, the other subcommands need no flags: they reuse the platform, lane');
@@ -8366,8 +9089,16 @@ function printToolHelp() {
   console.log('Usage: remits-cli tool --name <toolName> [--base-url URL] [--account-id ID] [--branch BRANCH] [--input "{...}"|--input-file file.json] [--data-mode test|prod] [--variant-branch NAME|none] [--timeout-ms 60000] [--async true --wait true]');
   console.log('       remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
   console.log('');
+  console.log('Hierarchy scope (read/discovery tools) — you do NOT need the owning child account id:');
+  console.log('  --scope self|children|hierarchy   expand from the repo account when searching');
+  console.log('  --target-account-id ID            the exact account to act on (required by writes)');
+  console.log('  --account-ids 1,2,3               an explicit bounded list of owner accounts');
+  console.log('  --anchor-account-id ID            disambiguate the path for a multi-parent account');
+  console.log('  These are merged into --input; a value already in --input wins.');
+  console.log('');
   console.log('Examples:');
   console.log('  remits-cli tool --name mcp_firestore_search --input-file query.json --data-mode prod');
+  console.log('  remits-cli tool --name mcp_firestore_search --input \'{"collection":"statements","documentId":"1234"}\' --scope children');
   console.log('  remits-cli tool --name mcp_run_action --input \'{"accountId":49,"actionId":200,"executionMode":"async"}\' --data-mode prod');
   console.log('');
   console.log('For mcp_run_action and mcp_run_agent, prefer the tool\'s own executionMode:"async" and poll with that tool\'s controlAction:"status".');
@@ -8454,7 +9185,7 @@ async function main() {
     console.log('  remits-cli data-mode [set test|prod]');
     console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
     console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--variant-branch NAME|none]');
-    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--branch BRANCH] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--variant-branch NAME|none] [--timeout-ms 60000] [--async true --wait true]');
+    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--branch BRANCH] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--scope self|children|hierarchy] [--target-account-id ID] [--account-ids 1,2,3] [--variant-branch NAME|none] [--timeout-ms 60000] [--async true --wait true]');
     console.log('  remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
     console.log('  remits-cli workspace [show|use <name>|use --auto|clear]        # isolate staging when several agents share a repo');
     console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--changed-only] [--data-mode test|prod] [--json|--verbose]');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -23,6 +23,10 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
   - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
   - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
   - [If you are the worker](#if-you-are-the-worker)
+  - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
+  - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
+  - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
+  - [Agent components are workers too](#agent-components-are-workers-too)
   - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
   - [When a worker needs a decision from a human](#when-a-worker-needs-a-decision-from-a-human)
   - [The manual loop](#the-manual-loop)
@@ -587,6 +591,64 @@ headless run is invisible otherwise), and **end in a terminal state** — `compl
 resolution, or `update_status` with what you established and what the next agent should try. Exiting
 quietly leaves a ticket that looks in-flight forever.
 
+### Before you edit anything: where you are, and whether you may
+
+Presence answers *who*. Two more facts answer *whether you may edit*, and with git worktrees and
+workspace lanes an account id no longer identifies a working tree — so an agent that does not ask these
+is assuming, and the assumption it makes when it guesses wrong is "this is my repository to edit".
+
+```bash
+remits-cli ticket where --ticket 22454     # repo account, checkout, branch, staging lane, lease, claim, YOUR phase
+remits-cli agent map                       # every repository, who holds each lease, and where each agent is working
+```
+
+**Reading, reproducing and investigating are parallel-safe and unrestricted. Editing one account's
+repository is exclusive**, enforced by a lease held per repository account per data lane:
+
+```bash
+remits-cli ticket lease   --ticket 22454   # take it when you started read-only and reached an actual edit
+remits-cli ticket unlease --ticket 22454   # complete / ask / release already do this for you
+```
+
+Four things are worth knowing and are not obvious:
+
+- **A refusal is not an error.** The run continues read-only, and the message names who holds the lease
+  **and where they are working**, so you can tell a real conflict from a holder in a different worktree.
+  **Do not wait for a lease and do not poll for one** — investigation is most of the work on most
+  tickets, and a ticket that turns out to need an edit hands off with `ticket progress --next-step`
+  saying exactly what change is needed. A lock people queue on turns one stuck worker into a stalled
+  fleet.
+- **A staging workspace does not replace the lease.** Separate lanes stop two runs *resolving* each
+  other's staged code; they do nothing about two processes writing the same files or pushing the same
+  branch, which is what actually destroys work.
+- **One editing worker per repository account per lane — worktrees do not change this.** Two worktrees
+  of one repo push to the same branch on the same remote, so per-directory leases would trade file
+  conflicts for non-fast-forward push conflicts, which surface later and are worse.
+- **A spawned ticket worker already has its own staging lane** (`REMITS_WORKSPACE=ticket-<id>`). You do
+  not set it, and your brief states it. Say which lane you staged into when you report what you verified
+  — somebody looking at the shared lane will not see your changes.
+
+`unlease` returns **your own** lease and deliberately cannot touch anybody else's. Breaking a stale one
+is a separate, human verb: `remits-cli ticket force-unlease --ticket ID --reason "..."`.
+
+### Your account's process is binding, and it is already in your brief
+
+An account declares how its work is done as Prompts with purpose `OPERATIONS`, selected per the ticket's
+`workstream` (`support`, `sdlc`, `incident`, `release`, or whatever that organization calls its
+processes) via `Prompt.category`, with an uncategorised one as the catch-all. The matching text is
+**inlined verbatim into the brief** of every agent that works one of that account's tickets and is
+binding on it — follow it even where it differs from how you would normally proceed, and if it conflicts
+with the brief, follow the process and say so on the ticket.
+
+You do not fetch it: if the brief has a "The process that governs this ticket" section, that is it. If
+it says the account documents no process, the likely cause is that the prompt is **staged but not
+committed** — an autonomous worker resolves the committed one, so it is never bound by a procedure
+nobody has reviewed. The repo root also carries a generated `OPERATIONS.md`; that file is generated
+from the prompt, so **edit the prompt, not the file**.
+
+`workstream` is not `type`: a type classifies the request, a workstream names the procedure, and they
+cross — a `defect` handled by incident response out of hours goes through the SDLC in the morning.
+
 ### Seeing the queue as a human does
 
 `remits-cli start` opens a browser control center showing the same facts you are acting on: which
@@ -632,10 +694,76 @@ remits-cli ticket progress --ticket 22454 --summary "Traced it to the posting Ac
 remits-cli ticket status   --ticket 22454 --status in_progress
 remits-cli ticket complete --ticket 22454 --resolution "What you found and did"
 remits-cli ticket ask      --ticket 22454 --question "Re-issue or skip?" --context "412 affected"
-remits-cli ticket reply    --ticket 22454 --message "Skip them."
+remits-cli ticket answer   --ticket 22454 --message "Skip them."   # alias: reply
+remits-cli ticket message  --ticket 22454 --message "We reproduced it; a fix is staged."
+remits-cli ticket planning --ticket 22454 --board-stage ready_for_qa --blocked-by CAB-112
 remits-cli ticket release  --ticket 22454        # hand it back to the queue
 ```
 
+**See the whole queue before deciding your ticket is unique.** Alert-raised tickets arrive in
+clusters, and the same root cause routinely appears under several different account names — so the
+first useful question is usually "how many of these are one fix?", and you cannot ask it from a single
+ticket.
+
+```bash
+remits-cli ticket queue --account-id 49                       # triage order, most urgent first
+remits-cli ticket queue --account-id 49 --unrouted --status open
+remits-cli ticket queue --account-id 49 --search "firestore index"
+```
+
+The `repo` column is the account the **edit lease** excludes on, so it also tells you which of these
+could be worked at the same time and which will serialize behind one another.
+
+Found a second, unrelated problem while working yours? **File it rather than widening the ticket you
+were given** — a ticket that describes two things cannot be closed by either fix.
+
+```bash
+remits-cli ticket create --account-id 49 --subject "Vendor name lost on re-normalization" \
+    --type defect --priority medium --reference-id vendor-name-lost
+```
+
+`--reference-id` makes it get-or-create, so a re-run — or another worker reaching the same conclusion
+— reconciles onto the same ticket instead of filing a duplicate.
+
+Marking and evidence, so the next reader does not repeat your work:
+
+```bash
+remits-cli ticket tag      --ticket 22454 --tags firestore-index,cluster-aug
+remits-cli ticket artifact --ticket 22454 --type log --label "Failing query" --content "..."
+remits-cli ticket note     --ticket 22454 --message "Internal: same cause as 23465"
+remits-cli ticket field    --ticket 22454 --key customerReference --value CR-9182
+```
+
+`note` is internal — the next worker and a reviewer see it, the requester does not. Use `message` for
+anything the requester should read. `field` writes your **organization's own** field, outside the
+platform's bounded planning slots.
+
+**`message`, `answer` and `note` are separated by who reads the result, not by tone.** They are easy to
+confuse and they do different things to the ticket:
+
+| Command | Who reads it | What it does to the ticket |
+|---|---|---|
+| `ticket message --message "..."` | the requester | appends a public entry. **Does not send anything** |
+| `ticket note --message "..."` | the next worker, a reviewer | appends an internal entry |
+| `ticket answer --message "..."` | whoever asked | answers the open question and **re-routes**, so a fresh worker resumes |
+
+`ticket reply` is an **alias of `answer`** — kept because every existing brief says it. Do not read it as
+"reply to the customer"; that is `message`. (Some account tools spell the conversational verb `reply`,
+which is exactly why this surface teaches `answer`.)
+
+**Appending a message is not emailing anyone.** The record is deliberately vendor-agnostic; the account
+owns the transport. To ask for something to actually go out:
+
+```bash
+remits-cli ticket deliver --ticket 22454 --channel email --to ops@acme.test \
+    --subject "Waiting on you" --idempotency-key waiting-22454
+remits-cli ticket deliveries --ticket 22454          # what is queued, and what already went
+```
+
+That records an outbox request. An account-owned Rule or scheduled Action sends it and marks the result
+(`ticket delivered --delivery-id ...` / `ticket delivery-failed --delivery-id ... --reason "..."`). Use
+this when a ticket is waiting on somebody who is not watching the queue.
+
 ### When a worker needs a decision from a human
 
 There are **three** ways a run can end, not two, and the third is what stops an agent guessing:
@@ -644,12 +772,14 @@ There are **three** ways a run can end, not two, and the third is what stops an
 |---|---|---|
 | Done | `ticket complete --resolution` | finished, here is what I did |
 | **Blocked on a choice** | `ticket ask --question` | I understand the work; the DECISION is not mine |
+
 | Could not finish | `ticket status --status pending_review` + `ticket progress` | stuck, here is the hand-off |
 
 `ask` puts the question on the ticket as an outbound message and parks it. The queue then shows it as
 **awaiting a response** — distinct from "done, review me", which `pending_review` alone cannot express.
 
-Someone answers with `remits-cli ticket reply --message "..."` (or through an operator Embeddable).
+Someone answers with `remits-cli ticket answer --message "..."` (`reply` is an alias), or through an
+operator Embeddable.
 That **re-routes the ticket by default**, so the supervisor's next poll starts a **fresh worker whose
 brief already contains the exchange**. Resumption costs nothing because a worker is one process per
 ticket — there is no session to restore.
@@ -684,8 +814,9 @@ Ticket-routing context:
 - For defect investigations, start from the owning ticket account, then move to the platform/product context if the root cause is in shared components.
 
 Sandbox note:
-- `remits-cli` commands that call the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`) require outbound network access.
-- In Codex or similar sandboxed agent environments, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar network errors usually mean the command must be retried with escalated permissions or outside the sandbox.
+- Every `remits-cli` command that reaches the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`, and all of `ticket` / `agent`) needs outbound network access.
+- **Inside an autonomous ticket worker this is already arranged** — the supervisor launches the worker with network enabled, in both the editing and the investigating phase. An investigating worker is restricted from *writing the repository*, never from *talking to the platform*: reading its ticket, running a diagnostic and recording a finding are the whole of what investigating means.
+- Elsewhere, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM` or a bare exit 6 / `HTTP:000` from a sandboxed session means the command needs escalated permissions or must run outside the sandbox. Do not read it as "the platform is down" — check a second command before concluding anything about the service.
 
 Use the same repo/context rules as other tools:
 - If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
@@ -975,6 +1106,43 @@ remits-cli tool --name "mcp_run_action" --input '{"accountId":49,"actionId":200,
 
 Every tool response is saved to `./.remits-cli/tool-responses/<callId>.json`.
 
+### Hierarchy-scoped tool reads
+
+For read/discovery tools, the account resolved from the checkout/session is the **scope root**, not proof
+that the business record is owned by that account. This closes the common support loop where you know a
+precise document, object, event, or indexed source id but do not yet know which child account owns it.
+
+Use the tool flags rather than editing JSON by hand:
+
+```bash
+remits-cli tool --name mcp_firestore_search \
+  --input '{"collection":"statements","documentId":"1234"}' \
+  --scope children --data-mode prod
+```
+
+Available flags:
+
+| Flag | Meaning |
+|---|---|
+| `--scope self|children|hierarchy` | Expand from the repo/session account for read/discovery. Exact-id lookups usually default to `children`; broad searches default to `self` unless widened. |
+| `--target-account-id ID` | Exact owner/execution account when already known. Required by mutating tools. |
+| `--account-ids 1,2,3` | Explicit bounded owner list. The platform verifies every id against the scope root. |
+| `--anchor-account-id ID` | Path-disambiguation anchor for multi-parent account relationships. |
+
+The CLI merges these into `--input`; a value already present in `--input` wins. Tool responses echo
+`scopeRootAccountId`, `scope`, `accountIds`, and, when an exact owner is discovered,
+`resolvedTargetAccountId`. Feed that returned owner to `mcp_firestore_patch`, action/test runs, and browser
+tokens. Mutating tools do not infer or fan out writes.
+
+The implicit account ceiling is intentionally different by shape: broad searches stay capped at 100 accounts
+unless the tool says otherwise, while exact-id discovery may span up to 1000 accounts by default. If a broad
+tool returns `scopeTooBroad`, narrow with `--target-account-id`, `--account-ids`, or a smaller `--scope`.
+
+`mcp_firestore_search` handles exact Firestore document ids. `mcp_index_search` handles fuzzy/semantic
+lookup through Vertex. `mcp_bigquery_query` handles warehouse lookup/query with server-resolved
+`{table_current}`/`{table}` placeholders and the scoped `{account_filter}` predicate. BigQuery is a prod
+analytics surface, so use `--data-mode prod` when you intend to query it.
+
 Poll a CLI-transport async call (mechanism 2) by call id:
 
 ```bash
@@ -3181,6 +3349,20 @@ remits-cli agent release
 remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
 remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
 remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
+remits-cli ticket ask --ticket ID --question "..." [--context "..."] [--to WHO]   # park on a human decision
+remits-cli ticket answer --ticket ID --message "..." [--route false]             # answer it (alias: reply); re-routes by default
+remits-cli ticket message --ticket ID --message "..." [--to a@x,b@y] [--subject "..."] [--channel email]  # PUBLIC — the requester reads it
+remits-cli ticket note --ticket ID --message "..."     # INTERNAL — the next worker and a reviewer read it
+remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [--subject "..."] [--idempotency-key K]   # ask for it to be SENT
+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 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
+remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
+remits-cli ticket create --account-id ID --subject "..." --type defect|question|task|incident|enhancement [--priority P] [--description "..."] [--tags a,b] [--workstream W] [--affected-component C] [--implementation-account-id ID] [--reference-id KEY]
 remits-cli start [--foreground true] [--port 8787]
 remits-cli stop
 remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]