@remits/remits-cli 0.1.112 → 0.1.114

package/index.js

@@ -24,7 +24,10 @@ const SESSIONS_FILE = path.join(SESSION_DIR, 'sessions.json');
 const CONFIG_FILE = path.join(SESSION_DIR, 'config.json');
 const LISTENER_PID_FILE = path.join(SESSION_DIR, 'listener.pid');
 const ACTIVITY_LOG_FILE = path.join(SESSION_DIR, 'activity.log');
-const SKILL_SOURCE_FILE = path.join(__dirname, 'skills', 'remits-cli', 'SKILL.md');
+const SKILL_SOURCE_DIR = path.join(__dirname, 'skills', 'remits-cli');
+const SKILL_SOURCE_FILE = path.join(SKILL_SOURCE_DIR, 'SKILL.md');
+const SKILL_REFERENCES_DIRNAME = 'references';
+const SKILL_REFERENCES_SOURCE_DIR = path.join(SKILL_SOURCE_DIR, SKILL_REFERENCES_DIRNAME);
 const ACCOUNT_REPO_INDEX_FILE = path.join(SESSION_DIR, 'account-repos.json');
 const SERVICE_STATE_FILE = path.join(SESSION_DIR, 'service-state.json');
 const ISSUES_DIR = path.join(SESSION_DIR, 'issues');
@@ -1248,13 +1251,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;
@@ -1265,7 +1300,6 @@ function updateAccountRepoIndex(cwd) {
   if (!info) {
     return;
   }
-  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
   const entry = buildAccountRepoEntryFromInfo(info, cwd, 'cwd');
   if (!entry) {
     return;
@@ -1339,7 +1373,6 @@ function discoverAccountRepos() {
   for (const root of roots) {
     walkForAccountInfo(root, 0, matches, visited, platformMatches);
   }
-  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
 
   const entries = [];
   for (const file of matches) {
@@ -1892,13 +1925,166 @@ async function loggedGet(api, cwd, endpoint, params = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Skill delivery
+//
+// The skill is SKILL.md (the index and the rules) plus the reference files in
+// skills/remits-cli/references/. Both ship inside the npm package, so the whole
+// skill is available before the CLI has ever authenticated.
+//
+// Every delivered markdown file goes through deliverSkillMarkdown(), which is
+// the ONE delivery path: it substitutes the machine-specific placeholders and
+// resolves each file's table of contents to real line numbers. Writing a file
+// out with fs.writeFileSync + readFileSync instead would ship the same skill
+// with a different table of contents depending on which door it came out of.
+// ---------------------------------------------------------------------------
+
+// GitHub-style heading anchor: lowercase, punctuation dropped, spaces to hyphens.
+function headingSlug(headingText) {
+  return String(headingText || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9 _-]/g, '')
+    .trim()
+    .replace(/\s/g, '-');
+}
+
+function formatTocEntry(indent, target) {
+  if (!target) return null;
+  return indent + '- L' + target.line + '  ' + target.title;
+}
+
+// Rewrites a document's "## Table of Contents" entries to carry the line number of
+// the heading they point at, turning the TOC into a jump table:
+//
+//   - [Component Structure](#component-structure)   ->   - L59  Component Structure
+//   - Line 31: Component Structure                  ->   - L59  Component Structure
+//
+// Numbers are computed HERE, at delivery, never written into the repo file.
+// Hand-maintained line numbers rot on the first edit above them, and a WRONG
+// number is worse than none: it sends the reader to the wrong section, where it
+// may conclude the content is missing. Resolving at delivery means the numbers
+// cannot be stale, while the repo file keeps anchor links that survive edits and
+// produce clean diffs.
+//
+// INVARIANT: every rewrite is one line in, one line out. The line count must not
+// change, or the numbers computed against the input would no longer describe the
+// output. Locked down by test/skill-references.test.js.
+//
+// An entry whose target heading cannot be resolved is left exactly as written —
+// it degrades to the original text, never to a guessed number.
+function resolveTableOfContentsLineNumbers(markdown) {
+  if (!markdown || !markdown.trim()) {
+    return markdown;
+  }
+
+  const lines = markdown.split('\n');
+  const tocStart = lines.findIndex((line) => /^##\s+table of contents\s*$/i.test(line));
+  if (tocStart < 0) {
+    return markdown;
+  }
+
+  let tocEnd = lines.length;
+  for (let i = tocStart + 1; i < lines.length; i += 1) {
+    if (/^##(?!#)\s+.*$/.test(lines[i])) {
+      tocEnd = i;
+      break;
+    }
+  }
+
+  // A `#`-prefixed line inside a fenced code block is CONTENT, not a heading. The
+  // references routinely show markdown and shell samples that contain one. Indexing
+  // those shifts GitHub's duplicate-slug disambiguation (-1, -2 ...) out of step with
+  // the real headings, so a legitimate repeated heading resolves to the wrong line.
+  const byAnchor = new Map();
+  const byTitle = new Map();
+  const slugCounts = new Map();
+  let inFence = false;
+
+  lines.forEach((line, index) => {
+    if (/^\s{0,3}(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (inFence) return;
+
+    const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!heading) return;
+
+    const title = heading[2].trim();
+    const target = { line: index + 1, title };
+
+    const baseSlug = headingSlug(title);
+    const seen = slugCounts.get(baseSlug) || 0;
+    slugCounts.set(baseSlug, seen + 1);
+    const slug = seen === 0 ? baseSlug : baseSlug + '-' + seen;
+
+    if (!byAnchor.has(slug)) byAnchor.set(slug, target);
+    if (!byTitle.has(title)) byTitle.set(title, target);
+  });
+
+  let changed = false;
+  for (let i = tocStart + 1; i < tocEnd; i += 1) {
+    const rewritten = resolveTocEntry(lines[i], byAnchor, byTitle);
+    if (rewritten !== null) {
+      lines[i] = rewritten;
+      changed = true;
+    }
+  }
+
+  return changed ? lines.join('\n') : markdown;
+}
+
+// The rewritten entry carries the ACTUAL heading text, not the TOC's own link text.
+// The two drift (a heading gets reworded and the TOC entry does not), and emitting
+// the heading text both self-heals that drift and guarantees the entry is a literal
+// match for the heading — so an agent can grep it as-is rather than trusting the number.
+//
+// Returns null when the line is not a resolvable TOC entry and must be left untouched.
+function resolveTocEntry(line, byAnchor, byTitle) {
+  const anchorEntry = /^(\s*)[-*]\s+\[(.+)\]\(#([^)\s]+)\)\s*$/.exec(line);
+  if (anchorEntry) {
+    return formatTocEntry(anchorEntry[1], byAnchor.get(anchorEntry[3]));
+  }
+
+  // Legacy hand-written form. Re-resolving it corrects files that have not been
+  // audited yet, instead of shipping their stale numbers.
+  const legacyEntry = /^(\s*)[-*]\s+Line\s+\d+:\s*(.+?)\s*$/.exec(line);
+  if (legacyEntry) {
+    const title = legacyEntry[2];
+    return formatTocEntry(legacyEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
+  }
+
+  return null;
+}
+
+// THE single delivery path for a skill markdown file. Substitutes the placeholders
+// that only the installing machine can fill in, then resolves the table of contents.
+function deliverSkillMarkdown(sourceText, referencesDir) {
+  let body = String(sourceText);
+  body = body.split('{{ACCOUNT_REPO_INDEX_PATH}}').join(ACCOUNT_REPO_INDEX_FILE);
+  body = body.split('{{SKILL_REFERENCES_DIR}}').join(referencesDir);
+  return resolveTableOfContentsLineNumbers(body);
+}
+
 function resolveSkillTargets(target) {
   const value = String(target || 'all').toLowerCase();
   const home = os.homedir();
+  // Gemini reads a FLAT skill file, so its references cannot sit beside it as
+  // `references/`. That is why SKILL.md states the reference directory as an
+  // absolute path substituted per target rather than a relative one.
   const targets = {
-    codex: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
-    claude: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
-    gemini: path.join(home, '.gemini', 'skills', 'remits-cli.md')
+    codex: {
+      skillPath: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
+      referencesDir: path.join(home, '.codex', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    },
+    claude: {
+      skillPath: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
+      referencesDir: path.join(home, '.claude', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    },
+    gemini: {
+      skillPath: path.join(home, '.gemini', 'skills', 'remits-cli.md'),
+      referencesDir: path.join(home, '.gemini', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    }
   };
 
   if (value === 'all') {
@@ -1910,34 +2096,83 @@ function resolveSkillTargets(target) {
   return [[value, targets[value]]];
 }
 
-function buildSkillSourceBody() {
+function listSkillReferenceSources() {
+  if (!fs.existsSync(SKILL_REFERENCES_SOURCE_DIR)) {
+    return [];
+  }
+  return fs.readdirSync(SKILL_REFERENCES_SOURCE_DIR)
+    .filter((name) => name.endsWith('.md'))
+    .sort();
+}
+
+function buildSkillSourceBody(referencesDir) {
   if (!fs.existsSync(SKILL_SOURCE_FILE)) {
     throw new Error('Skill source file not found: ' + SKILL_SOURCE_FILE);
   }
+  return deliverSkillMarkdown(fs.readFileSync(SKILL_SOURCE_FILE, 'utf8'), referencesDir);
+}
+
+// Install the reference set beside (or, for gemini, alongside) the skill file, and
+// prune any reference this CLI version no longer ships. A stale reference is worse
+// than a missing one: SKILL.md would not name it, but an agent listing the directory
+// would still find and trust it.
+function writeSkillReferences(referencesDir, options = {}) {
+  const names = listSkillReferenceSources();
+  const written = [];
+  if (!names.length) {
+    return written;
+  }
 
-  let sourceBody = fs.readFileSync(SKILL_SOURCE_FILE, 'utf8');
-  sourceBody = sourceBody.replace('{{ACCOUNT_REPO_INDEX_PATH}}', ACCOUNT_REPO_INDEX_FILE);
-  return sourceBody;
+  ensureDir(referencesDir);
+  const expected = new Set(names);
+
+  for (const name of names) {
+    const body = deliverSkillMarkdown(
+      fs.readFileSync(path.join(SKILL_REFERENCES_SOURCE_DIR, name), 'utf8'),
+      referencesDir
+    );
+    const targetPath = path.join(referencesDir, name);
+    if (options.overwrite === false && fs.existsSync(targetPath)) {
+      continue;
+    }
+    if (writeFileIfChanged(targetPath, body)) {
+      written.push(targetPath);
+    }
+  }
+
+  try {
+    for (const existing of fs.readdirSync(referencesDir)) {
+      if (existing.endsWith('.md') && !expected.has(existing)) {
+        fs.unlinkSync(path.join(referencesDir, existing));
+      }
+    }
+  } catch (_) {
+    // Best-effort pruning; a stale file never blocks delivery of the current set.
+  }
+
+  return written;
 }
 
 function syncInstalledSkills(target = 'all') {
   const targets = resolveSkillTargets(target);
-  const sourceBody = buildSkillSourceBody();
   const summary = {
     updated: [],
     failed: []
   };
 
-  for (const [agent, targetPath] of targets) {
+  for (const [agent, spec] of targets) {
     try {
-      ensureDir(path.dirname(targetPath));
-      if (writeFileIfChanged(targetPath, sourceBody)) {
-        summary.updated.push({ agent, path: targetPath });
+      ensureDir(path.dirname(spec.skillPath));
+      if (writeFileIfChanged(spec.skillPath, buildSkillSourceBody(spec.referencesDir))) {
+        summary.updated.push({ agent, path: spec.skillPath });
+      }
+      for (const referencePath of writeSkillReferences(spec.referencesDir)) {
+        summary.updated.push({ agent, path: referencePath });
       }
     } catch (error) {
       summary.failed.push({
         agent,
-        path: targetPath,
+        path: spec.skillPath,
         reason: error && error.message ? error.message : String(error)
       });
     }
@@ -1953,19 +2188,24 @@ async function installSkillsCommand(flags) {
 
   const overwrite = flags.overwrite === true || flags.overwrite === 'true';
   const targets = resolveSkillTargets(flags.target || 'all');
-  const sourceBody = buildSkillSourceBody();
 
   const installed = [];
   const skipped = [];
 
-  for (const [agent, targetPath] of targets) {
-    ensureDir(path.dirname(targetPath));
-    if (fs.existsSync(targetPath) && !overwrite) {
-      skipped.push({ agent, path: targetPath, reason: 'already exists (use --overwrite true)' });
-      continue;
+  for (const [agent, spec] of targets) {
+    ensureDir(path.dirname(spec.skillPath));
+    if (fs.existsSync(spec.skillPath) && !overwrite) {
+      skipped.push({ agent, path: spec.skillPath, reason: 'already exists (use --overwrite true)' });
+    } else {
+      atomicWriteFile(spec.skillPath, buildSkillSourceBody(spec.referencesDir));
+      installed.push({ agent, path: spec.skillPath });
+    }
+    // References are refreshed even when the skill file itself was left alone: an
+    // agent reading a customized SKILL.md still needs the reference set it points at.
+    const references = writeSkillReferences(spec.referencesDir);
+    if (references.length) {
+      installed.push({ agent, path: spec.referencesDir + ' (' + references.length + ' reference file(s))' });
     }
-    atomicWriteFile(targetPath, sourceBody);
-    installed.push({ agent, path: targetPath });
   }
 
   console.log('Skill installation complete.');
@@ -3756,6 +3996,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 +4059,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 +4125,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 +6363,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 +6423,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 +6496,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 +6528,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 +6578,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 +6608,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 +7080,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 +7320,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 +7420,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 +7491,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 +7578,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 +7910,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 +7969,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 +7987,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 +8045,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 +8087,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 +8120,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 +8359,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 +8384,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 +8599,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 +8737,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 +8783,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 +9297,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".');
@@ -8409,6 +9348,15 @@ async function main() {
     if (autoUpdateIfNeeded(originalArgv, { requireSuccess: requireSuccessfulAutoUpdate })) return;
   }
 
+  // Refresh the installed skill on EVERY command, not just from inside an account repo. This runs
+  // after the auto-update re-exec, so it is the new version writing the new skill. It was previously
+  // hung off updateAccountRepoIndex(), which returns early outside a repo — so a user who upgraded and
+  // then ran `remits-cli agent serve` from a plain tab (the documented way to work tickets, explicitly
+  // "no need to be in an account repo") kept the PREVIOUS skill on disk indefinitely: a stale index
+  // pointing at reference files that the upgrade had just renamed or removed. Reading and comparing the
+  // whole corpus across all three agent targets measures ~3ms, so there is nothing to save by guarding it.
+  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
+
   // Best-effort: update account-repo index whenever running from inside a remits repo
   try { updateAccountRepoIndex(process.cwd()); } catch (_) { /* not in account repo */ }
   // Auto-start the background service if not already running.
@@ -8454,7 +9402,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]');