severally-mcp 2.4.0 → 2.5.0

package/src/run.mjs

@@ -46,6 +46,7 @@ const DROP_PREFIX = ['CLAUDE_CODE_', 'SEVERALLY_', 'MCP_'];
 // The names came out of the binary with `strings`; only XDG_CONFIG_HOME was
 // probed behaviourally, so read the AGY_* line as "no evidence of a
 // config-dir override under that prefix", not as proof that none exists.
+/** @type {Record<string, string[]>} */
 const TARGET_DROP_PREFIX = {
   codex: ['ANTHROPIC_', 'GEMINI_', 'GOOGLE_', 'AGY_', 'ANTIGRAVITY_', 'ZAI_'],
   'claude-code': ['OPENAI_', 'CODEX_', 'GEMINI_', 'GOOGLE_', 'AGY_', 'ANTIGRAVITY_', 'ZAI_'],
@@ -62,6 +63,7 @@ const TARGET_DROP_PREFIX = {
 // Exact names dropped for one target only (see the note above). Kept separate
 // from DROP_EXACT so the two other consultants, whose isolation has been
 // verified with these variables present, are not changed.
+/** @type {Record<string, string[]>} */
 const TARGET_DROP_EXACT = {
   antigravity: ['XDG_CONFIG_HOME'],
 };
@@ -71,10 +73,15 @@ const TARGET_DROP_EXACT = {
  * sockets, session ids, entrypoint markers) is removed, as are the other two
  * vendors' credentials -- each consultant keeps only its own; and a recursion
  * marker is added.
+ * @param {string} target
+ * @param {Record<string, string>} [extra]
+ * @param {Record<string, string>} [operator]
+ * @returns {Record<string, string>}
  */
 export function childEnv(target, extra = {}, operator = {}) {
   const { dropPrefixes, dropExact } = dropRules(target);
   const keep = providerEnvNames(target);
+  /** @type {Record<string, string>} */
   const env = {};
   for (const [k, v] of Object.entries(process.env)) {
     if (v === undefined) continue;
@@ -101,6 +108,7 @@ export function childEnv(target, extra = {}, operator = {}) {
 const SECRET_PREFIX = ['AWS_', 'AZURE_', 'GITHUB_', 'GH_', 'GITLAB_', 'NPM_', 'DOCKER_', 'HF_', 'SLACK_', 'STRIPE_', 'OP_'];
 const SECRET_SUFFIX = /(TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIALS?)$/i;
 const SECRET_EXACT = new Set(['SSH_AUTH_SOCK', 'KUBECONFIG', 'DATABASE_URL']);
+/** @type {Record<string, string[]>} */
 const OWN_PREFIX = {
   codex: ['OPENAI_', 'CODEX_'],
   'claude-code': ['ANTHROPIC_'],
@@ -110,17 +118,25 @@ const OWN_PREFIX = {
 
 // Names the operator's OpenCode provider definitions read as "{env:NAME}":
 // the consultant needs them, wherever they were exported.
+/** @param {string} target */
 function providerEnvNames(target) {
-  const provider = JSON.stringify(POLICY.clis?.[target]?.provider ?? {});
-  return new Set([...provider.matchAll(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]));
+  // Only OpenCode's section carries provider definitions.
+  const provider = JSON.stringify(target === 'opencode' ? POLICY.clis.opencode.provider : {});
+  return new Set([...provider.matchAll(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g)].flatMap(([, name]) => name ?? []));
 }
 
+/**
+ * @param {string} target
+ * @param {string} key
+ * @param {Set<string>} keep
+ */
 function foreignSecret(target, key, keep) {
   if (keep.has(key) || (OWN_PREFIX[target] ?? []).some((p) => key.startsWith(p))) return false;
   const upper = key.toUpperCase();
   return SECRET_EXACT.has(upper) || SECRET_PREFIX.some((p) => upper.startsWith(p)) || SECRET_SUFFIX.test(key);
 }
 
+/** @param {string} target */
 function dropRules(target) {
   return {
     dropPrefixes: [...DROP_PREFIX, ...(TARGET_DROP_PREFIX[target] ?? [])],
@@ -136,11 +152,15 @@ function dropRules(target) {
  * by config is refused rather than honoured; so is any name the per-job
  * sandbox sets (HOME and friends), which would otherwise be silently
  * overwritten.
+ * @param {string} target
+ * @param {unknown} env
+ * @param {string[]} [sandboxKeys]
+ * @returns {string | null}
  */
 export function operatorEnvProblem(target, env, sandboxKeys = []) {
   if (env === null || typeof env !== 'object' || Array.isArray(env)) return 'must be an object of string values';
   const { dropPrefixes, dropExact } = dropRules(target);
-  const fold = (k) => (process.platform === 'win32' ? k.toUpperCase() : k);
+  const fold = (/** @type {string} */ k) => (process.platform === 'win32' ? k.toUpperCase() : k);
   const reserved = new Set(sandboxKeys.map(fold));
   for (const [k, v] of Object.entries(env)) {
     if (typeof v !== 'string') return `${k} must be a string`;
@@ -153,6 +173,10 @@ export function operatorEnvProblem(target, env, sandboxKeys = []) {
 }
 
 export class ProcHandle {
+  /**
+   * @param {import('node:child_process').ChildProcess} child
+   * @param {() => string} [readStdout]
+   */
   constructor(child, readStdout = () => '') {
     this.child = child;
     this.killed = false;
@@ -165,6 +189,7 @@ export class ProcHandle {
    * Kill the child and every descendant it spawned -- also after the child
    * itself has exited: a descendant still holding its pipes keeps the
    * consultation from closing, and on POSIX it is still in the group.
+   * @param {NodeJS.Signals} [signal]
    */
   stop(signal = 'SIGTERM') {
     if (this.killed || !this.child) return;
@@ -225,13 +250,131 @@ export class ProcHandle {
 }
 
 /**
- * @returns {{handle: ProcHandle, done: Promise<{code, signal, stdout, stderr, timedOut, cancelled, truncated}>}}
+ * @typedef {object} ChildResult
+ * @property {number | null} code
+ * @property {NodeJS.Signals | null} signal
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {boolean} truncated
+ * @property {boolean} timedOut
+ * @property {boolean} cancelled
+ * @property {boolean} stalled
+ * @property {boolean} pipesForced
+ * @property {string} [spawnError]
+ */
+
+/**
+ * What an adapter's buildInvocation returns.
+ * @typedef {object} Invocation
+ * @property {string} command
+ * @property {string[]} args
+ * @property {string} model
+ * @property {string} [workdir]
+ * @property {string} [lastMessagePath]
+ */
+
+/**
+ * The synthesised HOME of one consultation, as an adapter's prepareSandbox
+ * returns it; what the adapters share of it.
+ * @typedef {object} Sandbox
+ * @property {string} root
+ * @property {string} credentials 'symlink', 'copy' or 'missing'
+ * @property {string} credentialsSource
+ * @property {readonly string[]} tools
+ * @property {Record<string, string>} env
+ * @property {() => void} cleanup
+ * @property {(provider: string) => boolean} [seed] insert the provider's credential into the session database (OpenCode only)
+ */
+
+/**
+ * What a consultant was launched with, read off the invocation: the boundary
+ * record kept beside each answer. Facts about the launch, not a claim about
+ * what the consultant did.
+ * @typedef {object} Boundary
+ * @property {string} reads
+ * @property {string} shell
+ * @property {boolean} web
+ * @property {boolean} writes
+ * @property {boolean} mcp
+ * @property {string} protected_paths
+ * @property {string[] | null} tools
  */
+
+/**
+ * What a consultation used, as far as its CLI says; null where it does not say.
+ * @typedef {object} UsageRecord
+ * @property {number | null} input_tokens
+ * @property {number | null} cached_input_tokens
+ * @property {number | null} output_tokens
+ * @property {number | null} total_tokens
+ * @property {number | null} cost_usd
+ * @property {number | null} web_search_requests
+ * @property {number | null} [turns]
+ * @property {number | null} [thinking_tokens]
+ * @property {number | null} [reasoning_tokens]
+ * @property {string[] | null} [denied_actions]
+ */
+
+/**
+ * What jobs.mjs hands buildInvocation; each adapter reads the fields it needs.
+ * @typedef {object} BuildRequest
+ * @property {string} workdir
+ * @property {string} schemaPath
+ * @property {string} guardrails
+ * @property {Sandbox | null} sandbox the adapter's own prepareSandbox result, if it has one
+ * @property {import('./consultants.mjs').Consultant} consultant
+ * @property {boolean} [hasExposedPaths]
+ * @property {'on' | 'off' | undefined} [network]
+ */
+
+/**
+ * What an adapter's interpret makes of a finished child: an answer (text is a
+ * JSON object or the raw text to mine one out of), or a classified failure.
+ * @typedef {{ ok: true, text: string | Record<string, unknown>, usageRaw: unknown, payload?: unknown, events?: number, denials?: unknown[], recoveredError?: { failureKind: string, message: string } | null, earlierTextParts?: string[] }} InterpretedOk
+ * @typedef {{ ok: false, failureKind: string, message: string, usageRaw: unknown, payload?: unknown, events?: number }} InterpretedFail
+ * @typedef {InterpretedOk | InterpretedFail} Interpreted
+ */
+
+/**
+ * The shape every adapter module (codex, claude-code, antigravity, opencode)
+ * exports; the optional members are the ones only some CLIs have.
+ * @typedef {object} Adapter
+ * @property {readonly string[]} FORBIDDEN_FLAGS
+ * @property {readonly string[]} RESERVED_FLAGS
+ * @property {(req: BuildRequest) => Invocation} buildInvocation
+ * @property {(run: Partial<ChildResult> & { lastMessageText?: string }) => Interpreted} interpret
+ * @property {(raw: unknown) => UsageRecord | null} usageRecord
+ * @property {(args: { args: string[], sandbox: Sandbox | null, network?: 'on' | 'off' | undefined, hasExposedPaths?: boolean }) => Boundary} [boundary]
+ * @property {(run: { stdout: string }) => string | null} [progress]
+ * @property {(run: { stdout: string }) => Record<string, number> | null} [toolCalls]
+ * @property {readonly string[]} [FILE_READ_TOOLS] the names toolCalls reports for reading a file
+ * @property {readonly string[]} [ALLOWED_TOOLS] the only tools the consultant may call; any other is refused
+ * @property {() => Promise<void>} [prepare]
+ * @property {(args: { workdir: string, network?: 'on' | 'off' | undefined }) => Sandbox} [prepareSandbox]
+ * @property {(args: { run: ChildResult, sandbox: Sandbox }) => string} [diagnostics]
+ * @property {(args: { interpreted: Interpreted, sandbox: Sandbox, model: string }) => boolean} [recoverAuthFailure]
+ * @property {(line: string) => string} [compactLine]
+ * @property {(line: string) => number | null | undefined} [settleAfter]
+ * @property {NodeJS.Signals} [stopSignal]
+ */
+
 /**
  * `pipesForced` in the result: the child exited but something it started kept
  * stdout or stderr open past the kill grace, so the group was stopped and the
  * pipes closed from this side. A descendant outside the group (setsid, or on
  * Windows once the parent is gone) may still be running.
+ * @param {object} options
+ * @param {string} options.command
+ * @param {readonly string[]} options.args
+ * @param {string} [options.cwd]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string | null} [options.input]
+ * @param {number} options.timeoutMs
+ * @param {(cancel: () => void) => void} [options.onCancelSignal]
+ * @param {((line: string) => string) | null} [options.compactLine]
+ * @param {((line: string) => number | null | undefined) | null} [options.settleAfter]
+ * @param {NodeJS.Signals} [options.stopSignal]
+ * @returns {{handle: ProcHandle, done: Promise<ChildResult>, pid: number | undefined}}
  */
 export function runChild({
   command,
@@ -267,10 +410,11 @@ export function runChild({
   // says it is done; past that it is stopped and `stalled` set. A later line
   // can shorten the wait, never lengthen it.
   let stalled = false;
-  let settleTimer = null;
+  /** @type {NodeJS.Timeout | undefined} */
+  let settleTimer;
   let settleAt = Infinity;
-  const watch = (line) => {
-    const ms = settleAfter(line);
+  const watch = (/** @type {string} */ line) => {
+    const ms = settleAfter?.(line);
     if (ms == null || Date.now() + ms >= settleAt) return;
     settleAt = Date.now() + ms;
     clearTimeout(settleTimer);
@@ -280,7 +424,7 @@ export function runChild({
     }, ms);
   };
 
-  const append = (which, chunk) => {
+  const append = (/** @type {'out' | 'err'} */ which, /** @type {string | Buffer} */ chunk) => {
     const text = chunk.toString('utf8');
     if (which === 'out') {
       if (stdout.length >= cap) {
@@ -304,10 +448,10 @@ export function runChild({
   // partial line is bounded by the cap too; past it, the line is kept as is.
   let pending = '';
   const byLine = Boolean(compactLine || settleAfter);
-  const compact = compactLine ?? ((l) => l);
+  const compact = compactLine ?? ((/** @type {string} */ l) => l);
   const flushLines = () => {
     const lines = pending.split('\n');
-    pending = lines.pop();
+    pending = lines.pop() ?? '';
     for (const l of lines) {
       if (settleAfter) watch(l);
       append('out', `${compact(l)}\n`);
@@ -340,11 +484,13 @@ export function runChild({
     });
   }
 
+  /** @type {Promise<ChildResult>} */
   const done = new Promise((resolve) => {
     let settled = false;
     let pipesForced = false;
-    let orphanTimer = null;
-    const finish = (payload) => {
+    /** @type {NodeJS.Timeout | undefined} */
+    let orphanTimer;
+    const finish = (/** @type {{ code: number | null, signal: NodeJS.Signals | null, spawnError?: string }} */ payload) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);

package/src/schema.mjs

@@ -18,7 +18,14 @@ import {
 } from './policy.mjs';
 import { normalizeName, resolveConsultant } from './consultants.mjs';
 
+/** @typedef {import('./consultants.mjs').Consultant} Consultant */
+/** @typedef {import('./consultants.mjs').CliId} CliId */
+
 const L = POLICY.input;
+/**
+ * @param {number} max
+ * @param {string} label
+ */
 const trimmed = (max, label) =>
   z.string().trim().min(1, `${label} must not be empty`).max(max, `${label} exceeds ${max} characters`);
 
@@ -144,10 +151,59 @@ export const requestSchema = z
   })
   .strict();
 
+/**
+ * What charCount reads of a request, once parseRequest has filled in its defaults.
+ * @typedef {{
+ *   question: string,
+ *   objective?: string | null | undefined,
+ *   constraints?: string[] | undefined,
+ *   success_criteria?: string[] | undefined,
+ *   context: { facts: string[], counterpoints: string[], proposal?: string | null | undefined, artifacts: { name: string, excerpt: string }[] },
+ * }} CountedRequest
+ */
+
+/** @typedef {'explore' | 'review' | 'debate'} Mode */
+/** @typedef {z.output<typeof requestSchema>} ValidRequest */
+/** @typedef {z.output<typeof contextSchema>} ValidContext */
+
+/**
+ * A request as parseRequest returns it: validated, defaults filled in, the
+ * consultant(s) resolved. `target` is the first of `targets`.
+ * @typedef {Omit<
+ *   ValidRequest,
+ *   'target' | 'targets' | 'caller' | 'caller_model' | 'initiator' | 'followup_to' | 'mode' | 'network' | 'success_criteria' | 'constraints' | 'context'
+ * > & {
+ *   target: string,
+ *   targets: string[],
+ *   fanout: boolean,
+ *   caller: CliId | null,
+ *   caller_model: string | null,
+ *   initiator: string | null,
+ *   followup_to: string | null,
+ *   mode: Mode,
+ *   network: 'on' | 'off',
+ *   success_criteria: string[],
+ *   constraints: string[],
+ *   context: Omit<ValidContext, 'constraints' | 'success_criteria' | 'facts' | 'counterpoints' | 'artifacts' | 'proposal'> & {
+ *     facts: string[],
+ *     counterpoints: string[],
+ *     artifacts: ValidContext['artifacts'] & {},
+ *     proposal: string | null,
+ *   },
+ * }} ParsedRequest
+ */
+
+/**
+ * parseRequest's working copy: the request as it is until the defaults are filled in.
+ * `constraints` and `success_criteria` may still sit inside the context at first.
+ * @typedef {ParsedRequest & { context: { constraints?: string[] | undefined, success_criteria?: string[] | undefined } }} DraftRequest
+ */
+
+/** @param {CountedRequest} req */
 export function charCount(req) {
   let n = req.question.length + (req.objective?.length ?? 0);
-  for (const c of req.constraints) n += c.length;
-  for (const c of req.success_criteria) n += c.length;
+  for (const c of req.constraints ?? []) n += c.length;
+  for (const c of req.success_criteria ?? []) n += c.length;
   for (const f of req.context.facts) n += f.length;
   for (const c of req.context.counterpoints) n += c.length;
   if (req.context.proposal) n += req.context.proposal.length;
@@ -156,6 +212,11 @@ export function charCount(req) {
 }
 
 export class RequestError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code]
+   * @param {unknown[]} [details]
+   */
   constructor(message, code = 'invalid_request', details = undefined) {
     super(message);
     this.name = 'RequestError';
@@ -168,6 +229,9 @@ export class RequestError extends Error {
  * Validate + normalise a consult request.
  * `isFollowup` is decided by the caller (the job store resolves followup_to first);
  * `groupFollowup` when followup_to named a fan-out, whose members are the targets.
+ * @param {unknown} raw
+ * @param {{ isFollowup?: boolean, parentMode?: Mode | null, groupFollowup?: boolean }} [options]
+ * @returns {ParsedRequest}
  */
 export function parseRequest(raw, { isFollowup = false, parentMode = null, groupFollowup = false } = {}) {
   const parsed = requestSchema.safeParse(raw);
@@ -175,24 +239,31 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
     throw new RequestError(`request failed validation: ${issues.join('; ')}`, 'invalid_request', issues);
   }
-  // Filled in below with what the request resolves to (targets, caller, ...).
-  /** @type {Record<string, any>} */
-  const req = parsed.data;
+  // Filled in below with what the request resolves to (targets, caller, ...), so
+  // until it returns it is only partly a ParsedRequest: the validated data is
+  // typed as the finished shape and every field the shape adds is set before the return.
+  const req = /** @type {DraftRequest} */ (parsed.data);
   // Left without a default in the schema, so that a follow-up can tell a list
   // it left out (inherited from the round before, jobs.mjs) from one it
   // emptied on purpose: the tool layer applies the schema's defaults first.
-  for (const k of ['constraints', 'success_criteria']) {
-    if (req.context[k] === undefined) continue;
+  /** @param {'constraints' | 'success_criteria'} k */
+  const hoist = (k) => {
+    const inner = req.context[k];
+    if (inner === undefined) return;
     if (req[k] !== undefined) {
       throw new RequestError(`pass ${k} once: at the top of the request or inside context, not both`, 'invalid_request');
     }
-    req[k] = req.context[k];
+    req[k] = inner;
     delete req.context[k];
-  }
+  };
+  hoist('constraints');
+  hoist('success_criteria');
   req.network ??= 'on';
   req.success_criteria ??= [];
   req.constraints ??= [];
-  for (const k of ['facts', 'counterpoints', 'artifacts']) req.context[k] ??= [];
+  req.context.facts ??= [];
+  req.context.counterpoints ??= [];
+  req.context.artifacts ??= [];
   const hasSingle = req.target !== undefined && req.target !== null;
   const hasMany = Array.isArray(req.targets) && req.targets.length > 0;
   if (hasSingle && hasMany) {
@@ -208,12 +279,14 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
       'target_required',
     );
   }
+  /** @type {string[]} */
   const named = hasSingle ? [req.target] : req.targets;
   const isAll = named.map((n) => normalizeName(n) === 'all');
   if (isAll.some(Boolean) && named.length > 1) {
     throw new RequestError('"all" already means every available consultant; pass it alone', 'all_mixed');
   }
 
+  /** @type {Consultant[]} */
   let chosen;
   if (isAll[0]) {
     chosen = availableConsultants();
@@ -275,7 +348,7 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     );
   }
   req.targets = unique;
-  req.target = unique[0]; // single-target consumers (brief, history, adapters) keep working
+  req.target = /** @type {string} */ (unique[0]); // non-empty: every name in `named` resolved to a consultant; single-target consumers (brief, history, adapters) keep working
   req.fanout = unique.length > 1;
   req.caller = resolveCaller(req.caller ?? '') ?? null;
   req.caller_model = req.caller_model ?? null;

package/src/server.mjs

@@ -9,7 +9,9 @@ import { requestSchema, RequestError } from './schema.mjs';
 import { JobManager, pointsOf } from './jobs.mjs';
 import { exportChain, ExportError } from './export.mjs';
 
-export const SEVERALLY_VERSION = '2.4.0';
+/** @typedef {import('@modelcontextprotocol/server').CallToolResult} CallToolResult */
+
+export const SEVERALLY_VERSION = '2.5.0';
 
 // consult_get waits this long when no wait_ms is given: a call that forgot it
 // would otherwise return at once and be repeated. Up to 45 s, under the 60 s
@@ -21,10 +23,19 @@ const DEFAULT_WAIT_MS = process.env.SEVERALLY_MAX_WAIT_MS ? POLICY.maxWaitMs : M
 // counts silence against the call keeps it open.
 const PROGRESS_EVERY_MS = 15_000;
 
+/** @param {string} v */
 const semver = (v) => String(v).split('.').map(Number);
+/**
+ * @param {string} a
+ * @param {string} b
+ */
 const older = (a, b) => {
   const [x, y] = [semver(a), semver(b)];
-  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i];
+  for (let i = 0; i < 3; i++) {
+    const [p, q] = [x[i], y[i]];
+    if (p === undefined || q === undefined) return false;
+    if (p !== q) return p < q;
+  }
   return false;
 };
 
@@ -33,8 +44,11 @@ const older = (a, b) => {
  * from this server: a fix reaches a client only through the copy it runs, and
  * an operator who updated one copy cannot see that another is behind. Only
  * version strings are compared. A copy that is missing is not reported.
+ * @param {string} [home]
+ * @param {string} [severallyHome]
  */
 export function staleInstall(home = os.homedir(), severallyHome = POLICY.home) {
+  /** @param {string} file */
   const read = (file) => {
     try {
       return fs.readFileSync(file, 'utf8');
@@ -50,6 +64,7 @@ export function staleInstall(home = os.homedir(), severallyHome = POLICY.home) {
     // This release names it SEVERALLY_VERSION; older ones only had it in the server info.
     runtime: bundle?.match(/(?:SEVERALLY_VERSION = |name: ["']severally["'], version: )["'](\d+\.\d+\.\d+)["']/)?.[1],
     claude_skills_dir: (() => {
+      if (plugin === null) return undefined;
       try {
         return JSON.parse(plugin).version;
       } catch {
@@ -57,15 +72,18 @@ export function staleInstall(home = os.homedir(), severallyHome = POLICY.home) {
       }
     })(),
   };
+  /** @type {Record<string, string>} */
   const copies = { this_server: SEVERALLY_VERSION };
   // Only plain x.y.z is compared; anything else is left out rather than guessed at.
-  for (const [name, v] of Object.entries(found)) if (/^\d+\.\d+\.\d+$/.test(v ?? '')) copies[name] = v;
+  for (const [name, v] of Object.entries(found)) if (v !== undefined && /^\d+\.\d+\.\d+$/.test(v)) copies[name] = v;
   const versions = Object.values(copies);
   if (versions.every((v) => v === SEVERALLY_VERSION)) return null;
   const newest = versions.reduce((a, b) => (older(a, b) ? b : a));
   return {
     copies,
-    behind: Object.keys(copies).filter((k) => older(copies[k], newest)),
+    behind: Object.entries(copies)
+      .filter(([, v]) => older(v, newest))
+      .map(([k]) => k),
     fix:
       `bring every copy to ${newest}: run \`npx -y severally-mcp@${newest} install\` (or \`node scripts/install.mjs\` from a checkout of that version) ` +
       '(it updates the runtime and the ~/.claude/skills copy), run `/plugin marketplace update severally` for a ' +
@@ -149,15 +167,27 @@ const recordShape = {
     .describe('written after reading the answer'),
 };
 
+/** @param {unknown} err */
+const errorMessage = (err) =>
+  String((typeof err === 'object' && err !== null && 'message' in err ? err.message : undefined) ?? err);
+
 export function createServer(manager = new JobManager()) {
   // Read once: the copies on disk change only when someone reinstalls, and then
   // this server is the one to restart.
   const stale = staleInstall();
   const server = new McpServer({ name: 'severally', version: SEVERALLY_VERSION }, { instructions: SERVER_INSTRUCTIONS });
 
-  const ok = (payload) => ({ content: [{ type: /** @type {const} */ ('text'), text: JSON.stringify(payload, null, 2) }] });
+  /**
+   * @param {unknown} payload
+   * @returns {CallToolResult}
+   */
+  const ok = (payload) => ({ content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] });
+  /**
+   * @param {unknown} payload
+   * @returns {CallToolResult}
+   */
   const fail = (payload) => ({
-    content: [{ type: /** @type {const} */ ('text'), text: JSON.stringify(payload, null, 2) }],
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
     isError: true,
   });
 
@@ -177,7 +207,7 @@ export function createServer(manager = new JobManager()) {
         if (err instanceof RequestError) {
           return fail({ error: err.code, message: err.message, details: err.details ?? null, limits: limitsSummary() });
         }
-        return fail({ error: 'internal_error', message: String(err?.message ?? err) });
+        return fail({ error: 'internal_error', message: errorMessage(err) });
       }
     },
   );
@@ -241,12 +271,13 @@ export function createServer(manager = new JobManager()) {
             }, PROGRESS_EVERY_MS);
       let view;
       try {
-        // A request the client cancels stops the wait with it.
+        // A request the client cancels stops the wait with it. Without group_id,
+        // job_id is set: exactly one of the two was checked above.
         view = group_id
           ? await manager.waitGroup(group_id, wait_ms ?? DEFAULT_WAIT_MS, { detail }, req?.signal)
-          : await manager.wait(job_id, wait_ms ?? DEFAULT_WAIT_MS, { detail }, req?.signal);
+          : await manager.wait(/** @type {string} */ (job_id), wait_ms ?? DEFAULT_WAIT_MS, { detail }, req?.signal);
       } finally {
-        clearInterval(timer);
+        clearInterval(timer ?? undefined);
       }
       if (!view) {
         return fail({
@@ -257,7 +288,8 @@ export function createServer(manager = new JobManager()) {
       // Still running: the poll answer as it is; ids applies once there is an answer.
       if (!ids || ['running', 'queued', 'cancelling'].includes(view.status)) return ok(view);
       try {
-        return ok(pointsOf(view, ids));
+        // ids comes with job_id alone (checked above), so this is one job's view.
+        return ok(pointsOf(/** @type {import('./jobs.mjs').JobView} */ (view), ids));
       } catch (err) {
         if (err instanceof RequestError) return fail({ error: err.code, message: err.message });
         throw err;
@@ -283,7 +315,8 @@ export function createServer(manager = new JobManager()) {
       if (Boolean(job_id) === Boolean(group_id)) {
         return fail({ error: 'invalid_request', message: 'pass exactly one of job_id or group_id' });
       }
-      const view = group_id ? manager.cancelGroup(group_id) : manager.cancel(job_id);
+      // Without group_id, job_id is set: exactly one of the two was checked above.
+      const view = group_id ? manager.cancelGroup(group_id) : manager.cancel(/** @type {string} */ (job_id));
       if (!view) {
         return fail({
           error: 'unknown_job',
@@ -324,6 +357,7 @@ export function createServer(manager = new JobManager()) {
     async ({ job_id, entries, reflection, records }) => {
       try {
         if (records !== undefined) {
+          /** @type {Record<string, unknown>} */
           const out = manager.record(
             Object.fromEntries(Object.entries({ job_id, entries, reflection, records }).filter(([, v]) => v !== undefined)),
           );
@@ -342,7 +376,7 @@ export function createServer(manager = new JobManager()) {
         if (err instanceof RequestError) {
           return fail({ error: err.code, message: err.message, details: err.details ?? null });
         }
-        return fail({ error: 'internal_error', message: String(err?.message ?? err) });
+        return fail({ error: 'internal_error', message: errorMessage(err) });
       }
     },
   );
@@ -367,7 +401,7 @@ export function createServer(manager = new JobManager()) {
         return ok(exportChain({ chain_id, group_id }));
       } catch (err) {
         if (err instanceof ExportError) return fail({ error: err.code, message: err.message });
-        return fail({ error: 'internal_error', message: String(err?.message ?? err) });
+        return fail({ error: 'internal_error', message: errorMessage(err) });
       }
     },
   );
@@ -420,6 +454,7 @@ export async function main() {
   manager.sweepInterrupted();
 
   let closing = false;
+  /** @param {string} signal */
   const bye = async (signal) => {
     if (closing) return;
     closing = true;