severally-mcp 2.4.0 → 2.5.0

package/plugins/severally/skills/_template/SKILL.md.tmpl

@@ -50,7 +50,8 @@ actually reach. When the user names one, pass **the word the user used** as `tar
 
 **Do not pick a model yourself.** When the user named no one, ask everyone; overriding the operator's
 consultants on your own judgement — including after a `usage_limit` failure — substitutes a different mind
-for the one the user asked for.
+for the one the user asked for. The operator may have set a fallback model for that case; a caveat reading
+"answered by X: Y's quota was used up" means it answered, and your report names X as the one who answered.
 
 Consult your own CLI (`target: "{{SELF_TARGET}}"`) freely, alone or alongside the peers, and the same goes
 for a **different model of your own lineage** when the user wants one (an Opus lead asking Fable). Either is a

package/plugins/severally/skills/_template/reference.md.tmpl

@@ -29,8 +29,8 @@ gets a vague answer.
    already in the question.
 2. **Write down what a useful answer looks like** (`success_criteria`) — e.g. "a concrete failure scenario with
    numbers, or a clear all-clear with its conditions".
-3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`, and then
-   the only part of your repository the consultant has), `context.facts` for the load-bearing facts,
+3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`; not a read
+   boundary -- apart from the protected credential paths, most consultants can still read other files on the disk), `context.facts` for the load-bearing facts,
    `context.artifacts` for what is not a file here. For a change you are making,
    `context.expose_diff: { repo, base? }` puts the diff in the brief and copies every file it touches, untracked
    ones included, under `./workspace/repo/` at their repository paths; add `expose_paths` for a caller or the

package/plugins/severally/skills/antigravity/severally/SKILL.md

@@ -61,7 +61,8 @@ actually reach. When the user names one, pass **the word the user used** as `tar
 
 **Do not pick a model yourself.** When the user named no one, ask everyone; overriding the operator's
 consultants on your own judgement — including after a `usage_limit` failure — substitutes a different mind
-for the one the user asked for.
+for the one the user asked for. The operator may have set a fallback model for that case; a caveat reading
+"answered by X: Y's quota was used up" means it answered, and your report names X as the one who answered.
 
 Consult your own CLI (`target: "antigravity"`) freely, alone or alongside the peers, and the same goes
 for a **different model of your own lineage** when the user wants one (an Opus lead asking Fable). Either is a

package/plugins/severally/skills/antigravity/severally/reference.md

@@ -29,8 +29,8 @@ gets a vague answer.
    already in the question.
 2. **Write down what a useful answer looks like** (`success_criteria`) — e.g. "a concrete failure scenario with
    numbers, or a clear all-clear with its conditions".
-3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`, and then
-   the only part of your repository the consultant has), `context.facts` for the load-bearing facts,
+3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`; not a read
+   boundary -- apart from the protected credential paths, most consultants can still read other files on the disk), `context.facts` for the load-bearing facts,
    `context.artifacts` for what is not a file here. For a change you are making,
    `context.expose_diff: { repo, base? }` puts the diff in the brief and copies every file it touches, untracked
    ones included, under `./workspace/repo/` at their repository paths; add `expose_paths` for a caller or the

package/plugins/severally/skills/claude/severally/SKILL.md

@@ -62,7 +62,8 @@ actually reach. When the user names one, pass **the word the user used** as `tar
 
 **Do not pick a model yourself.** When the user named no one, ask everyone; overriding the operator's
 consultants on your own judgement — including after a `usage_limit` failure — substitutes a different mind
-for the one the user asked for.
+for the one the user asked for. The operator may have set a fallback model for that case; a caveat reading
+"answered by X: Y's quota was used up" means it answered, and your report names X as the one who answered.
 
 Consult your own CLI (`target: "claude-code"`) freely, alone or alongside the peers, and the same goes
 for a **different model of your own lineage** when the user wants one (an Opus lead asking Fable). Either is a

package/plugins/severally/skills/claude/severally/reference.md

@@ -29,8 +29,8 @@ gets a vague answer.
    already in the question.
 2. **Write down what a useful answer looks like** (`success_criteria`) — e.g. "a concrete failure scenario with
    numbers, or a clear all-clear with its conditions".
-3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`, and then
-   the only part of your repository the consultant has), `context.facts` for the load-bearing facts,
+3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`; not a read
+   boundary -- apart from the protected credential paths, most consultants can still read other files on the disk), `context.facts` for the load-bearing facts,
    `context.artifacts` for what is not a file here. For a change you are making,
    `context.expose_diff: { repo, base? }` puts the diff in the brief and copies every file it touches, untracked
    ones included, under `./workspace/repo/` at their repository paths; add `expose_paths` for a caller or the

package/plugins/severally/skills/codex/severally/SKILL.md

@@ -61,7 +61,8 @@ actually reach. When the user names one, pass **the word the user used** as `tar
 
 **Do not pick a model yourself.** When the user named no one, ask everyone; overriding the operator's
 consultants on your own judgement — including after a `usage_limit` failure — substitutes a different mind
-for the one the user asked for.
+for the one the user asked for. The operator may have set a fallback model for that case; a caveat reading
+"answered by X: Y's quota was used up" means it answered, and your report names X as the one who answered.
 
 Consult your own CLI (`target: "codex"`) freely, alone or alongside the peers, and the same goes
 for a **different model of your own lineage** when the user wants one (an Opus lead asking Fable). Either is a

package/plugins/severally/skills/codex/severally/reference.md

@@ -29,8 +29,8 @@ gets a vague answer.
    already in the question.
 2. **Write down what a useful answer looks like** (`success_criteria`) — e.g. "a concrete failure scenario with
    numbers, or a clear all-clear with its conditions".
-3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`, and then
-   the only part of your repository the consultant has), `context.facts` for the load-bearing facts,
+3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`; not a read
+   boundary -- apart from the protected credential paths, most consultants can still read other files on the disk), `context.facts` for the load-bearing facts,
    `context.artifacts` for what is not a file here. For a change you are making,
    `context.expose_diff: { repo, base? }` puts the diff in the brief and copies every file it touches, untracked
    ones included, under `./workspace/repo/` at their repository paths; add `expose_paths` for a caller or the

package/plugins/severally/skills/opencode/severally/SKILL.md

@@ -61,7 +61,8 @@ actually reach. When the user names one, pass **the word the user used** as `tar
 
 **Do not pick a model yourself.** When the user named no one, ask everyone; overriding the operator's
 consultants on your own judgement — including after a `usage_limit` failure — substitutes a different mind
-for the one the user asked for.
+for the one the user asked for. The operator may have set a fallback model for that case; a caveat reading
+"answered by X: Y's quota was used up" means it answered, and your report names X as the one who answered.
 
 Consult your own CLI (`target: "opencode"`) freely, alone or alongside the peers, and the same goes
 for a **different model of your own lineage** when the user wants one (an Opus lead asking Fable). Either is a

package/plugins/severally/skills/opencode/severally/reference.md

@@ -29,8 +29,8 @@ gets a vague answer.
    already in the question.
 2. **Write down what a useful answer looks like** (`success_criteria`) — e.g. "a concrete failure scenario with
    numbers, or a clear all-clear with its conditions".
-3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`, and then
-   the only part of your repository the consultant has), `context.facts` for the load-bearing facts,
+3. **Supply the evidence**: `context.expose_paths` for the files (copied read-only under `./workspace`; not a read
+   boundary -- apart from the protected credential paths, most consultants can still read other files on the disk), `context.facts` for the load-bearing facts,
    `context.artifacts` for what is not a file here. For a change you are making,
    `context.expose_diff: { repo, base? }` puts the diff in the brief and copies every file it touches, untracked
    ones included, under `./workspace/repo/` at their repository paths; add `expose_paths` for a caller or the

package/scripts/build.mjs

@@ -13,6 +13,7 @@ const skillsDir = path.join(root, 'plugins', 'severally', 'skills');
 // `en`/`jp` are the everyday name a user would actually type when asking for
 // this peer by alias ("ask GPT", "gptと相談して") -- English keeps the
 // acronym capitalised, casual Japanese usually doesn't.
+/** @type {Record<string, { label: string, short: string, reach: string, en: string, jp: string, jpVerb: string }>} */
 const PEERS = {
   codex: {
     label: 'Codex CLI',
@@ -70,8 +71,8 @@ const EVERYONE_TRIGGERS = [
 
 // All four everyday-alias shapes for one peer: "ask X", "get X to review
 // this", the natural Japanese "XにVERBして" form, and "Xにレビューしてもらって".
-function triggersFor(peerId) {
-  const p = PEERS[peerId];
+/** @param {{ en: string, jp: string, jpVerb: string }} p */
+function triggersFor(p) {
   return [`"ask ${p.en}"`, `"get ${p.en} to review this"`, `"${p.jp}${p.jpVerb}"`, `"${p.jp}にレビューしてもらって"`];
 }
 
@@ -83,6 +84,7 @@ function triggersFor(peerId) {
 // one turn and the Skill itself then needs approving once (checked
 // 2026-10-18 with `claude -p --permission-mode default`).
 const QUIET_TOOLS = ['consult_get', 'consult_list', 'consult_record', 'consult_export', 'consult_cancel'];
+/** @param {string} text */
 function withAllowedTools(text) {
   const names = QUIET_TOOLS.flatMap((t) => [`mcp__plugin_severally_severally__${t}`, `mcp__severally__${t}`]);
   // A one-line description is assumed; a folded one would swallow the new key.
@@ -96,65 +98,63 @@ function withAllowedTools(text) {
 // then file name. Writes nothing, so it is safe to call from a test without
 // mutating the working tree.
 export function renderSkills() {
-  const rendered = {};
-  for (const host of HOSTS) rendered[host.dir] = {};
-  for (const name of SKILL_FILES) {
-    const texts = renderTemplate(`${name}.tmpl`);
-    for (const host of HOSTS) rendered[host.dir][name] = texts[host.dir];
-  }
-  return rendered;
+  return Object.fromEntries(
+    HOSTS.map((host) => [host.dir, Object.fromEntries(SKILL_FILES.map((name) => [name, renderTemplate(`${name}.tmpl`, host)]))]),
+  );
 }
 
 const SKILL_FILES = ['SKILL.md', 'reference.md'];
 
-function renderTemplate(file) {
+/**
+ * @param {string} file
+ * @param {{ dir: string, self: string }} host
+ */
+function renderTemplate(file, host) {
   const tmpl = fs.readFileSync(path.join(skillsDir, '_template', file), 'utf8');
-  const rendered = {};
-  for (const host of HOSTS) {
-    const peers = Object.keys(PEERS).filter((id) => id !== host.self);
-    const table = [
-      '| target | Consultant | Reach for it when |',
-      '|---|---|---|',
-      ...peers.map((id) => `| \`${id}\` | ${PEERS[id].label} | ${PEERS[id].reach} |`),
-    ].join('\n');
-    // Every consultant can read files; what keeps the answer brief-only is
-    // that the child starts in an empty working directory and is never told
-    // where the repository is. Codex additionally keeps a read-only shell, so
-    // "they cannot run commands" would be false about it.
-    const codexCaveat = peers.includes('codex')
-      ? ' The Codex consultant additionally has a read-only shell, so it can run commands that only read.'
-      : '';
-    const executionCaveat =
-      '\n\nOne caveat on that list: a consultant can read local files. Its writes are blocked,' +
-      '\nits network reaches only web search and browsing (none with `network: "off"`), credential and history' +
-      '\npaths are refused where its CLI allows, and by default it starts in an empty working directory without being' +
-      '\ntold where your repository is, so it answers from the brief and from the files you hand it:' +
-      '\n`context.expose_paths` (absolute paths) or `context.expose_diff` (a change in progress), which are' +
-      '\ncopied read-only into its working directory.' +
-      codexCaveat;
-    const text = tmpl
-      .replaceAll('{{EXECUTION_CAVEAT}}', executionCaveat)
-      .replaceAll('{{DESCRIPTION_PEERS}}', peers.map((id) => PEERS[id].short).join(' or '))
-      .replaceAll('{{TRIGGERS}}', [...peers.flatMap(triggersFor), ...EVERYONE_TRIGGERS].join(', '))
-      .replaceAll('{{PEER_TABLE}}', table)
-      .replaceAll('{{DEFAULT_TARGET}}', peers[0])
-      // The second peer, for the fan-out example of two named consultants.
-      .replaceAll('{{SECOND_TARGET}}', peers[1])
-      .replaceAll('{{SELF_TARGET}}', host.self);
-    rendered[host.dir] = host.self === 'claude-code' && file === 'SKILL.md.tmpl' ? withAllowedTools(text) : text;
-  }
-  return rendered;
+  const peers = Object.entries(PEERS).filter(([id]) => id !== host.self);
+  const [first, second] = peers;
+  // Every host has three peers, so both exist.
+  if (!first || !second) throw new Error(`${host.self}: expected at least two peers to consult`);
+  const table = [
+    '| target | Consultant | Reach for it when |',
+    '|---|---|---|',
+    ...peers.map(([id, p]) => `| \`${id}\` | ${p.label} | ${p.reach} |`),
+  ].join('\n');
+  // Every consultant can read files; what keeps the answer brief-only is
+  // that the child starts in an empty working directory and is never told
+  // where the repository is. Codex additionally keeps a read-only shell, so
+  // "they cannot run commands" would be false about it.
+  const codexCaveat = peers.some(([id]) => id === 'codex')
+    ? ' The Codex consultant additionally has a read-only shell, so it can run commands that only read.'
+    : '';
+  const executionCaveat =
+    '\n\nOne caveat on that list: a consultant can read local files. Its writes are blocked,' +
+    '\nits network reaches only web search and browsing (none with `network: "off"`), credential and history' +
+    '\npaths are refused where its CLI allows, and by default it starts in an empty working directory without being' +
+    '\ntold where your repository is, so it answers from the brief and from the files you hand it:' +
+    '\n`context.expose_paths` (absolute paths) or `context.expose_diff` (a change in progress), which are' +
+    '\ncopied read-only into its working directory.' +
+    codexCaveat;
+  const text = tmpl
+    .replaceAll('{{EXECUTION_CAVEAT}}', executionCaveat)
+    .replaceAll('{{DESCRIPTION_PEERS}}', peers.map(([, p]) => p.short).join(' or '))
+    .replaceAll('{{TRIGGERS}}', [...peers.flatMap(([, p]) => triggersFor(p)), ...EVERYONE_TRIGGERS].join(', '))
+    .replaceAll('{{PEER_TABLE}}', table)
+    .replaceAll('{{DEFAULT_TARGET}}', first[0])
+    // The second peer, for the fan-out example of two named consultants.
+    .replaceAll('{{SECOND_TARGET}}', second[0])
+    .replaceAll('{{SELF_TARGET}}', host.self);
+  return host.self === 'claude-code' && file === 'SKILL.md.tmpl' ? withAllowedTools(text) : text;
 }
 
 // Thin writer: renders and writes each host's SKILL.md. Stays silent --
 // logging belongs to the CLI entry point below, not to code that may be
 // imported (e.g. by a test).
 export function generateSkills() {
-  const rendered = renderSkills();
-  for (const host of HOSTS) {
-    const out = path.join(skillsDir, host.dir, 'severally');
+  for (const [dir, files] of Object.entries(renderSkills())) {
+    const out = path.join(skillsDir, dir, 'severally');
     fs.mkdirSync(out, { recursive: true });
-    for (const name of SKILL_FILES) fs.writeFileSync(path.join(out, name), rendered[host.dir][name]);
+    for (const [name, text] of Object.entries(files)) fs.writeFileSync(path.join(out, name), text);
   }
 }
 
@@ -184,15 +184,18 @@ export async function bundle() {
  * THIRD_PARTY_NOTICES beside the bundle: each package the bundle actually
  * contains, with its LICENSE file verbatim. esbuild's legalComments cannot do
  * this -- these packages state their licence only in the LICENSE file.
+ * @param {string[]} inputs
+ * @param {string} outDir
  */
 function writeNotices(inputs, outDir) {
   const pkgDirs = new Set();
   for (const input of inputs) {
-    const m = input
-      .split('/')
-      .join(path.sep)
-      .match(/^(.*node_modules[\\/](?:@[^\\/]+[\\/])?[^\\/]+)/);
-    if (m) pkgDirs.add(path.resolve(process.cwd(), m[1]));
+    const [, pkgPath] =
+      input
+        .split('/')
+        .join(path.sep)
+        .match(/^(.*node_modules[\\/](?:@[^\\/]+[\\/])?[^\\/]+)/) ?? [];
+    if (pkgPath) pkgDirs.add(path.resolve(process.cwd(), pkgPath));
   }
   const sections = [...pkgDirs]
     .map((dir) => {

package/scripts/doctor.mjs

@@ -27,6 +27,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { JobManager } from '../src/jobs.mjs';
+/** @typedef {import('../src/jobs.mjs').JobView} JobView */
 import { spawnSync } from 'node:child_process';
 import { availableConsultants, POLICY } from '../src/policy.mjs';
 import { checkTargets } from '../src/consultants.mjs';
@@ -40,6 +41,11 @@ if (!consultants) {
   process.exit(2);
 }
 
+/**
+ * @param {string} dir
+ * @param {string} secret
+ * @param {string} rootCanary
+ */
 function probe(dir, secret, rootCanary) {
   const written = path.join(dir, 'written-by-consultant.txt');
   const touched = path.join(dir, 'touched-by-command.txt');
@@ -63,6 +69,10 @@ function probe(dir, secret, rootCanary) {
 // A consultant that was told a path is denied may simply not try it, so an
 // unreturned canary does not show the sandbox stopped anything. For Codex the
 // sandbox can be asked directly, with no model and no quota.
+/**
+ * @param {string} file
+ * @param {string} word
+ */
 function codexSandboxRead(file, word) {
   const r = spawnSync(
     POLICY.clis.codex.cli,
@@ -87,6 +97,7 @@ function codexSandboxRead(file, word) {
 
 const SUB_AGENT_TOOL = /subagent|spawn_agent|collab_tool_call|^task(:|$)|^agent(:|$)/i;
 
+/** @param {JobView} view */
 function subAgentRow(view) {
   if (!view.tool_calls) return `not observable (no tool-call stream); tools offered: ${view.boundary?.tools ?? 'unknown'}`;
   if (Object.keys(view.tool_calls).length === 0) return 'inconclusive: the stream shows no tool calls at all';
@@ -119,17 +130,17 @@ for (const { name: target, cli } of consultants) {
   const { _secret, ...request } = probe(dir, secret, rootCanary);
 
   const mgr = new JobManager();
-  /** @type {Record<string, any>} */
   const started = mgr.start({ target, ...request });
-  if (!started.job_id) {
+  if (!('job_id' in started)) {
     rows.push({ target, error: JSON.stringify(started) });
     failed = true;
     for (const d of [dir, rootDir]) fs.rmSync(d, { recursive: true, force: true });
     continue;
   }
   process.stderr.write(`${target}: running ${started.job_id}\n`);
-  await mgr.jobs.get(started.job_id).promise;
-  const view = mgr.view(started.job_id);
+  await mgr.jobs.get(started.job_id)?.promise;
+  // The job was started above in this process, so it exists.
+  const view = /** @type {JobView} */ (mgr.view(started.job_id));
 
   if (view.status !== 'completed') {
     rows.push({ target, error: `${view.status}: ${view.failure?.kind} ${view.failure?.message ?? ''}`.trim() });

package/scripts/init-config.mjs

@@ -47,6 +47,7 @@ export function renderConfig() {
     '  //   effort           reasoning effort (default high); antigravity takes it from the model name instead',
     "  //   timeout_ms       this consultant's own budget in ms (default: server timeout_ms, max 7200000)",
     '  //   max_budget_usd   claude-code only: spending cap per consultation (default 10, 0.05-20)',
+    "  //   fallback_model   a model to run instead, once, when model's quota is used up (usage_limit)",
     '  //   vendor           the lineage, when the model name does not say (e.g. "nvidia")',
     '  //   enabled, note    as for clis, for this consultant alone',
     '  //',
@@ -117,7 +118,7 @@ function main() {
   }
   console.log('');
   console.log('clis.<cli>: enabled  note  bin  args  env');
-  console.log('consultants.<name>: cli  model  effort  timeout_ms  max_budget_usd  vendor  enabled  note');
+  console.log('consultants.<name>: cli  model  effort  timeout_ms  max_budget_usd  fallback_model  vendor  enabled  note');
   console.log('   more: CONFIG.md (what each key does), config.example.json (a working example).');
   console.log('   Restart the client after editing.');
   console.log('   comments and trailing commas are fine; name it config.jsonc if your editor prefers that');

package/scripts/install.mjs

@@ -80,9 +80,16 @@ const backupDir = path.join(home, '.severally', 'backups', stamp);
 let keptRegistrations = false;
 let lastListOutput = '';
 
+/** @param {...unknown} a */
 const log = (...a) => console.log(...a);
+/** @param {string} s */
 const step = (s) => log(`\n== ${s}`);
 
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {import('../src/platform.mjs').ExecOptions & { real?: boolean }} [opts]
+ */
 function run(cmd, args, opts = {}) {
   const { real, ...spawnOpts } = opts;
   if (dryRun && !real) {
@@ -92,16 +99,25 @@ function run(cmd, args, opts = {}) {
   return execCommandSync(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], ...spawnOpts });
 }
 
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {import('../src/platform.mjs').ExecOptions & { real?: boolean }} [opts]
+ * @returns {RunResult}
+ */
 function tryRun(cmd, args, opts) {
   try {
     return { ok: true, out: run(cmd, args, opts) };
-  } catch (err) {
+  } catch (e) {
+    // execFileSync failures carry the child's stdout and stderr.
+    const err = /** @type {{ stdout?: unknown, stderr?: unknown, message?: unknown }} */ (e);
     return { ok: false, out: `${err.stdout ?? ''}${err.stderr ?? ''}`.trim() || String(err.message) };
   }
 }
 
 // Backup names are derived from the whole path: two different clients both
 // hold a "severally" directory, and one must not overwrite the other.
+/** @param {string} target */
 function backupName(target) {
   return path
     .relative(home, target)
@@ -110,6 +126,7 @@ function backupName(target) {
     .replace(/^\./, '');
 }
 
+/** @param {string} file */
 function backup(file) {
   if (!fs.existsSync(file)) return null;
   if (dryRun) {
@@ -125,6 +142,7 @@ function backup(file) {
   return dest;
 }
 
+/** @param {string} dir */
 function backupTree(dir) {
   if (!fs.existsSync(dir)) return null;
   if (dryRun) {
@@ -138,6 +156,7 @@ function backupTree(dir) {
 }
 
 // Read-only probes run even under --dry-run, so the plan it prints is accurate.
+/** @param {string} bin */
 function which(bin) {
   return findCommand(bin);
 }
@@ -198,6 +217,7 @@ let globalRoot = null;
 if (mode === 'plugin' && !skipGlobal) {
   const npmRoot = tryRun('npm', ['root', '-g'], { real: true });
   globalRoot = npmRoot.ok ? npmRoot.out.trim() || null : null;
+  /** @param {string} dir */
   const inside = (dir) => {
     try {
       return fs.realpathSync(root).startsWith(fs.realpathSync(dir) + path.sep);
@@ -214,6 +234,7 @@ if (mode === 'plugin' && !skipGlobal) {
 }
 
 step(`Installing the standalone MCP server (mode: ${mode})`);
+/** @type {[string, string]} */
 const serverCommand = [process.execPath, installRuntime()];
 const runtimeDir = path.dirname(serverCommand[1]);
 const marketplaceRoot = path.join(home, '.severally', 'marketplace');
@@ -322,17 +343,20 @@ const agyConfig = path.join(home, '.gemini', 'config', 'mcp_config.json');
 const CODEX_TIMEOUT_SEC = 660;
 const codexConfig = path.join(codexHome, 'config.toml');
 // The user's own tool_timeout_sec, read before --force removes the table that holds it.
+/** @type {number | undefined} */
 let priorCodexTimeout;
 
 // Where [mcp_servers.severally] sits in config.toml, and what it holds.
 // A minimal text read, not a TOML parser: the table runs to the next header
 // that is not one of its own sub-tables (codex may put env in one).
+/** @returns {{ reason: string, lines?: undefined, start?: undefined, timeout?: undefined, wait?: undefined } | { reason?: undefined, lines: string[], start: number, timeout: number | undefined, wait: boolean }} */
 function codexTable() {
+  /** @type {string[]} */
   let lines;
   try {
     lines = fs.readFileSync(codexConfig, 'utf8').split('\n');
   } catch (err) {
-    return { reason: `cannot read ${codexConfig}: ${err.message}` };
+    return { reason: `cannot read ${codexConfig}: ${/** @type {Error} */ (err).message}` };
   }
   const start = lines.findIndex((l) => /^\s*\[\s*mcp_servers\.severally\s*\]/.test(l));
   if (start < 0) return { reason: `${codexConfig} has no [mcp_servers.severally] table` };
@@ -357,15 +381,16 @@ function codexPlan() {
 
 // Inserts tool_timeout_sec right after the table header. Returns why it could
 // not, or null.
+/** @param {number} sec */
 function writeCodexTimeout(sec) {
   const t = codexTable();
-  if (t.reason) return t.reason;
+  if (t.reason !== undefined) return t.reason;
   if (t.timeout !== undefined) return null; // never overwrite the user's value
   t.lines.splice(t.start + 1, 0, `tool_timeout_sec = ${sec}`);
   try {
     fs.writeFileSync(codexConfig, t.lines.join('\n'));
   } catch (err) {
-    return `cannot write ${codexConfig}: ${err.message}`;
+    return `cannot write ${codexConfig}: ${/** @type {Error} */ (err).message}`;
   }
   return null;
 }
@@ -373,12 +398,28 @@ function writeCodexTimeout(sec) {
 const claudeSkillsDir = path.join(home, '.claude', 'skills');
 
 // ---------------------------------------------------------------- clients
+/**
+ * @typedef {{ ok: boolean, out: string }} RunResult
+ * @typedef {object} Client
+ * @property {string} bin
+ * @property {string} label
+ * @property {string[]} backup
+ * @property {() => boolean} isRegistered
+ * @property {() => RunResult} remove
+ * @property {(bin: string[]) => RunResult} add
+ * @property {() => void} [keptNote]
+ * @property {boolean} [verifyAdd]
+ * @property {string[]} [registrationConfig]
+ * @property {string} skillFrom
+ * @property {string} skillTo
+ */
 // Each row fully describes how to register a client's MCP server directly
 // (through the client's own `mcp add`) and place its skill. This is the one
 // place that knows how severally is installed outside of a bundled
 // plugin: --manual mode installs every row this way, and the default plugin
 // mode falls back to the Antigravity and OpenCode rows alone, since those
 // two have no verified plugin-install path.
+/** @type {Client[]} */
 const CLIENTS = [
   {
     bin: 'claude',
@@ -509,14 +550,24 @@ const CLIENTS = [
     skillTo: path.join(xdgConfig, 'opencode', 'skills', 'severally'),
   },
 ];
-const codexClient = CLIENTS.find((c) => c.bin === 'codex');
-const antigravityClient = CLIENTS.find((c) => c.bin === 'agy');
-const opencodeClient = CLIENTS.find((c) => c.bin === 'opencode');
+/** @param {string} bin */
+function clientFor(bin) {
+  const client = CLIENTS.find((c) => c.bin === bin);
+  if (!client) throw new Error(`no client row for ${bin}`);
+  return client;
+}
+const codexClient = clientFor('codex');
+const antigravityClient = clientFor('agy');
+const opencodeClient = clientFor('opencode');
 
 // opencode re-adds in place and has no `mcp remove`, so --force over an
 // existing registration can silently keep the OLD command while the
 // name-only list check passes. The global config is where the CLI records
 // the server command; confirm it matches what this install registers.
+/**
+ * @param {Client} client
+ * @param {string[]} bin
+ */
 function registrationCommandMatches(client, bin) {
   for (const file of client.registrationConfig ?? []) {
     let cfg;
@@ -534,6 +585,7 @@ function registrationCommandMatches(client, bin) {
 
 // The list right after an add can be briefly empty, so it is asked up to
 // three times, 1.5 s apart, before the add is judged.
+/** @param {Client} client */
 function listedAfterAdd(client) {
   for (let i = 0; i < 3; i++) {
     if (i) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1500);
@@ -545,6 +597,10 @@ function listedAfterAdd(client) {
 // Registers one client's MCP server directly (through its own `mcp add`) and
 // copies its skill, backing up everything it touches first. Shared by plugin
 // mode (Antigravity only) and --manual mode (all three clients).
+/**
+ * @param {Client} client
+ * @param {string[]} bin
+ */
 function installClientDirectly(client, bin) {
   step(`Registering with ${client.label}`);
   if (!which(client.bin)) {
@@ -609,7 +665,12 @@ function claudeHasMarketplacePlugin() {
   if (!which('claude')) return false;
   const r = tryRun('claude', ['plugin', 'list', '--json'], { real: true });
   try {
-    return (r.ok && JSON.parse(r.out).find((p) => /^severally@/.test(p.id) && p.id !== 'severally@skills-dir')?.id) || false;
+    return (
+      (r.ok &&
+        JSON.parse(r.out).find((/** @type {{ id: string }} */ p) => /^severally@/.test(p.id) && p.id !== 'severally@skills-dir')
+          ?.id) ||
+      false
+    );
   } catch {
     return false;
   }
@@ -751,10 +812,13 @@ async function allowLocalTools() {
   if (!which('claude')) return;
   const prefix = mode === 'plugin' || claudeMarketplace ? 'mcp__plugin_severally_severally__' : 'mcp__severally__';
   const settingsFile = path.join(home, '.claude', 'settings.json');
+  /** @type {{ permissions?: { allow?: string[] } & Record<string, unknown> } & Record<string, unknown>} */
   let settings = {};
   try {
     settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
-  } catch (err) {
+  } catch (e) {
+    // readFileSync and JSON.parse throw Errors; only fs ones carry a code.
+    const err = /** @type {NodeJS.ErrnoException} */ (e);
     if (err.code !== 'ENOENT') {
       log(`   could not read ${settingsFile} (${err.message}); left as it is`);
       return;