severally-mcp 2.3.1 → 2.4.2

package/src/jobs.mjs

@@ -4,8 +4,18 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { POLICY, VERDICTS, limitsSummary, timeoutMs, detectCaller, configProblem, consultantByName, consultantAvailable } from './policy.mjs';
-import { vendorOf, sameModel, CLI_VENDORS } from './consultants.mjs';
+import {
+  POLICY,
+  VERDICTS,
+  limitsSummary,
+  timeoutMs,
+  detectCaller,
+  configProblem,
+  consultantByName,
+  consultantNamed,
+  consultantAvailable,
+} from './policy.mjs';
+import { vendorOf, sameModel, CLI_VENDORS, CLI_IDS } from './consultants.mjs';
 import { parseRequest, RequestError, charCount } from './schema.mjs';
 import { renderBrief, renderGuardrails, briefRecord } from './brief.mjs';
 import { CONSULT_RESULT_SCHEMA } from './result-schema.mjs';
@@ -20,6 +30,118 @@ import * as claudeCode from './adapters/claude-code.mjs';
 import * as antigravity from './adapters/antigravity.mjs';
 import * as opencode from './adapters/opencode.mjs';
 
+/** @typedef {import('./run.mjs').Adapter} Adapter */
+/** @typedef {import('./run.mjs').ProcHandle} ProcHandle */
+/** @typedef {import('./consultants.mjs').Consultant} Consultant */
+/** @typedef {import('./consultants.mjs').CliId} CliId */
+/** @typedef {import('./store.mjs').Group} Group */
+/** @typedef {import('./store.mjs').Seat} Seat */
+/** @typedef {NonNullable<Seat['owner']>} JobOwner Who runs a consultation: the severally process, and when it counts as overdue. */
+/** @typedef {import('./brief.mjs').PriorRound} PriorRound */
+/** @typedef {import('./schema.mjs').ParsedRequest & {_snapshot?: string}} ParsedRequest A validated request (see parseRequest), with the copy of the exposed files the job manager adds. */
+
+/**
+ * The tool arguments, not yet validated; only the keys inherit() and start() look at are named.
+ * @typedef {{target?: unknown, targets?: unknown[] | null | undefined, network?: unknown, context?: Record<string, unknown> | null | undefined, [key: string]: unknown}} RawRequest
+ */
+
+/** @typedef {import('./store.mjs').JobFailure} JobFailure */
+/** @typedef {import('./store.mjs').RecordEntry} RecordEntry */
+/** @typedef {import('./store.mjs').JobRecord} JobRecord */
+/** @typedef {import('./store.mjs').Reflection} Reflection */
+/** @typedef {import('./store.mjs').Prediction} Prediction */
+/** @typedef {import('./store.mjs').ResultItem} ResultItem */
+/** @typedef {import('./store.mjs').ConsultResult} ConsultResult */
+/** @typedef {import('./store.mjs').Round} Round */
+/** @typedef {import('./store.mjs').BriefRecord} BriefRecord */
+/** @typedef {import('./store.mjs').RetryRecord} RetryRecord */
+/** @typedef {import('./store.mjs').IndexRow} IndexRow */
+/** @typedef {import('./store.mjs').BriefExposeEntry} BriefExposeEntry */
+
+/** @typedef {import('./store.mjs').RunningRecord} StoredRound A round, or the marker of one still running elsewhere. */
+
+/**
+ * A consultation this process runs: the round, plus what only a live process has.
+ * @typedef {Round & {group_id: string, caller: string | null, retries: RetryRecord[], cancelRequested: boolean, _cancelFns: Array<() => void>, _request: ParsedRequest, _owner?: JobOwner | undefined, _handle?: ProcHandle | undefined, promise?: Promise<unknown>}} Job
+ */
+
+/**
+ * What a view adds to a round.
+ * @typedef {object} ViewExtras
+ * @property {boolean} [cancellable]
+ * @property {string | null} [progress]
+ * @property {string} [brief_note]
+ * @property {ReturnType<typeof limitsSummary> | null} [limits]
+ * @property {string} [next_step]
+ * @property {string} [cancel_effect]
+ */
+
+/**
+ * The brief as consult_get names it by default: its size and sha256, where it is kept, what was copied.
+ * @typedef {object} BriefSummary
+ * @property {number} chars
+ * @property {string} sha256
+ * @property {string} history_file
+ * @property {({skipped: Record<string, number>} & import('./expose-paths.mjs').ExposeTotals) | null} exposed
+ * @property {string} full_with
+ */
+
+/** @typedef {Round & ViewExtras} FullView A round as consult_get shows it with `detail: "full"`. */
+
+/** @typedef {Omit<Round, 'brief'> & ViewExtras & {brief: BriefRecord | BriefSummary | null}} JobView A round as consult_get shows it. */
+
+/**
+ * A consult_record call, or one of its `records`, as sent: not yet validated. The job_id is only ever looked up, so it is not narrowed.
+ * @typedef {{job_id?: any, entries?: Array<{id?: unknown, verdict?: unknown, effect?: unknown, note?: unknown} | null>, reflection?: {delta?: unknown, related_item_ids?: unknown} | null, [key: string]: unknown}} RawRecord
+ */
+
+/** @typedef {{job: Round, live: Job | undefined, entries?: RecordEntry[] | undefined, reflection?: Reflection | undefined}} RecordChange What a record call would write, checked and not yet written: only the entries this call names. */
+
+/** @typedef {import('./expose-paths.mjs').ExposeManifest} ExposeManifest */
+
+/**
+ * @typedef {object} GroupLink
+ * @property {Round & {nextRound: number}} parent
+ * @property {number} round
+ * @property {Round} [groupMember]
+ */
+
+/**
+ * A follow-up to a fan-out: the group, where each member goes on from, and
+ * the members that cannot take one.
+ * @typedef {object} GroupParents
+ * @property {Group} group
+ * @property {GroupLink[]} links
+ * @property {Array<{job_id: string, target: string | null, reason: string}>} skipped
+ */
+
+/**
+ * One consultant's column of a comparison.
+ * @typedef {object} ComparisonColumn
+ * @property {string} job_id
+ * @property {string} target
+ * @property {string} [cli]
+ * @property {string} [status]
+ * @property {string | null} [failure_kind]
+ * @property {string | null} stance
+ * @property {string | null} confidence
+ * @property {string | null} evidence_basis
+ * @property {string | null | undefined} summary
+ * @property {unknown[]} finding_points
+ * @property {Record<string, number>} severity_counts
+ * @property {unknown[]} decision_changers
+ * @property {unknown[]} alternative_options
+ * @property {unknown[]} unknowns
+ * @property {unknown[]} next_checks
+ * @property {unknown[]} remaining_disagreements
+ * @property {string | null | undefined} caveat
+ * @property {number | null} points_without_verdict
+ * @property {Record<string, number>} [omitted]
+ * @property {boolean} [truncated]
+ * @property {string} [full_with]
+ */
+
+/** @type {Record<CliId, Adapter> & Record<string, Adapter | undefined>} */
 const ADAPTERS = { codex, 'claude-code': claudeCode, antigravity, opencode };
 
 // The recovery respawn runs only while this much of the original budget is
@@ -46,6 +168,7 @@ const API_KEY_VARS = ['GEMINI_API_KEY', 'GOOGLE_API_KEY'];
 const CREDENTIAL_FILE_VARS = ['GOOGLE_APPLICATION_CREDENTIALS'];
 const ALL_API_CREDENTIAL_VARS = [...API_KEY_VARS, ...CREDENTIAL_FILE_VARS];
 
+/** @param {Record<string, string | undefined>} env */
 function hasApiCredential(env) {
   if (API_KEY_VARS.some((name) => env[name])) return true;
   return CREDENTIAL_FILE_VARS.some((name) => env[name] && fs.existsSync(env[name]));
@@ -55,11 +178,12 @@ function hasApiCredential(env) {
 // listed as not reported rather than silently missing from the totals.
 const USAGE_FIGURES = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'total_tokens', 'cost_usd'];
 
-const id = (prefix) => `${prefix}_${crypto.randomBytes(6).toString('hex')}`;
+const id = (/** @type {string} */ prefix) => `${prefix}_${crypto.randomBytes(6).toString('hex')}`;
 
 // Jobs this process is running, across every JobManager in it. A marker owned
 // by this pid but missing here was left by an earlier process that had the
 // same pid, so it is as dead as one whose pid no longer exists.
+/** @type {Set<string>} */
 const LIVE_HERE = new Set();
 
 // What became of the process that started a consultation: 'alive', 'dead',
@@ -67,19 +191,35 @@ const LIVE_HERE = new Set();
 // (budget, retries included, plus the kill grace), so either that process is
 // stuck or the pid now belongs to something else. Nothing is killed on the
 // strength of this.
+/**
+ * @param {string} jobId
+ * @param {JobOwner | null | undefined} owner
+ * @returns {'alive' | 'dead' | 'overdue'}
+ */
 function ownerState(jobId, owner) {
   if (!owner) return 'dead';
   let pidAlive;
   if (owner.pid === process.pid) pidAlive = LIVE_HERE.has(jobId);
-  else try { process.kill(owner.pid, 0); pidAlive = true; } catch (err) { pidAlive = err.code === 'EPERM'; }
+  else
+    try {
+      process.kill(owner.pid, 0);
+      pidAlive = true;
+    } catch (err) {
+      pidAlive = err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
   if (!pidAlive) return 'dead';
   return Date.now() > Date.parse(owner.deadline_at) ? 'overdue' : 'alive';
 }
 
 export class JobManager {
   constructor() {
+    /** @type {NodeJS.Timeout | null} */
+    this._cancelWatch = null;
+    /** @type {Map<string, Job>} */
     this.jobs = new Map();
+    /** @type {Map<string, Group>} */
     this.groups = new Map();
+    /** @type {string[]} */
     this.order = [];
     store.ensureDirs();
   }
@@ -87,6 +227,10 @@ export class JobManager {
   // A consultation this process does not hold: finished (its round file), or
   // still in progress (its marker). A marker whose owner is gone becomes a
   // failed round, `interrupted`, written once by whichever process claims it.
+  /**
+   * @param {string} jobId
+   * @returns {StoredRound | null}
+   */
   #fromDisk(jobId) {
     const done = store.loadRound(jobId);
     if (done) return done;
@@ -101,9 +245,18 @@ export class JobManager {
   // something the next reader finishes: the round is written (the index
   // takes it once), then the marker goes. A round already on disk wins -- its
   // owner finished and died before removing the marker.
+  /**
+   * @param {string} jobId
+   * @param {StoredRound} rec
+   * @param {'alive' | 'dead' | 'overdue'} state
+   * @returns {Round}
+   */
   #interrupt(jobId, rec, state) {
     const done = store.loadRound(jobId);
-    if (done) { store.removeRunning(jobId); return done; }
+    if (done) {
+      store.removeRunning(jobId);
+      return done;
+    }
     const { owner, ...round } = rec;
     round.status = 'failed';
     round.finished_at = new Date().toISOString();
@@ -114,7 +267,11 @@ export class JobManager {
       retriable: true,
       delivered_advice: false,
     };
-    try { store.persistRound(round); } catch { return round; }
+    try {
+      store.persistRound(round);
+    } catch {
+      return round;
+    }
     store.removeRunning(jobId);
     // An overdue owner may still be running its consultant: leave its working
     // directory to it. ponytail: if the pid was reused instead, that
@@ -128,22 +285,26 @@ export class JobManager {
     for (const jobId of store.listRunning()) {
       const rec = store.loadRunning(jobId);
       const state = rec && ownerState(jobId, rec.owner);
-      if (rec && state !== 'alive') this.#interrupt(jobId, rec, state);
+      if (rec && state && state !== 'alive') this.#interrupt(jobId, rec, state);
     }
   }
 
+  /**
+   * @param {StoredRound} rec
+   * @returns {FullView}
+   */
   #diskView(rec) {
-    const elsewhere = Boolean(rec.owner);
     const { owner, ...view } = rec;
     return {
       ...view,
-      cancellable: false,
+      // consult_cancel asks the process that owns it to stop it.
+      cancellable: Boolean(owner) && (view.status === 'running' || view.status === 'queued'),
       progress: null,
       record: view.record ? recordSummary(view) : null,
-      brief: elsewhere ? null : view.brief,
-      limits: elsewhere ? null : limitsSummary(),
-      next_step: elsewhere
-        ? `running in another severally process (pid ${owner.pid}); poll again later -- it can only be cancelled from that process`
+      brief: owner ? null : view.brief,
+      limits: owner ? null : limitsSummary(),
+      next_step: owner
+        ? `running in another severally process (pid ${owner.pid}); poll again later, or stop it with consult_cancel`
         : nextStep(view),
     };
   }
@@ -152,6 +313,10 @@ export class JobManager {
     return [...this.jobs.values()].filter((j) => j.status === 'running');
   }
 
+  /**
+   * @param {Job} job
+   * @returns {Round}
+   */
   #record(job) {
     return {
       job_id: job.job_id,
@@ -195,20 +360,36 @@ export class JobManager {
 
   // `detail: "full"` returns the brief as stored; by default a finished
   // consultation names it (size, sha256, round file) instead of repeating it.
+  /**
+   * @param {string} jobId
+   * @param {{detail?: string | undefined}} [opts]
+   * @returns {JobView | null}
+   */
   view(jobId, { detail } = {}) {
     const job = this.jobs.get(jobId);
     if (!job) {
       const rec = this.#fromDisk(jobId);
       return rec ? compactBrief(this.#diskView(rec), detail) : null;
     }
+    return this.#jobView(job, detail);
+  }
+
+  /**
+   * @param {Job} job
+   * @param {string | undefined} detail
+   * @returns {JobView}
+   */
+  #jobView(job, detail) {
+    /** @type {FullView} */
     const rec = this.#record(job);
     rec.cancellable = job.status === 'running' || job.status === 'queued';
     // While it runs, say what it is doing. "running" for twenty minutes tells
     // the lead nothing; a consultation visibly grinding through tool calls is
     // one it can cancel now rather than wait out.
-    rec.progress = job.status === 'running' && job._handle
-      ? (ADAPTERS[job.cli]?.progress?.({ stdout: job._handle.stdoutSoFar() }) ?? null)
-      : null;
+    rec.progress =
+      job.status === 'running' && job._handle
+        ? (ADAPTERS[job.cli]?.progress?.({ stdout: job._handle.stdoutSoFar() }) ?? null)
+        : null;
     rec.record = job.record ? recordSummary(job) : null;
     rec.prediction = job.prediction ?? null;
     rec.reflection = job.reflection ?? null;
@@ -222,7 +403,8 @@ export class JobManager {
     const live = job.status === 'running' || job.status === 'queued' || job.status === 'cancelling';
     if (live) {
       rec.brief = null;
-      rec.brief_note = 'omitted while the consultation is running; returned once it finishes, and kept in ~/.severally/history either way';
+      rec.brief_note =
+        'omitted while the consultation is running; returned once it finishes, and kept in ~/.severally/history either way';
     }
     rec.limits = live ? null : limitsSummary();
     rec.next_step = nextStep(job);
@@ -233,10 +415,18 @@ export class JobManager {
   // job_id and group_id can still be followed up and recorded against. The
   // index only picks and orders; each row shown is read from its round, which
   // holds the verdicts written since. Memory wins over disk for the same job.
+  /** @param {{limit?: number}} [opts] */
   list({ limit = 20 } = {}) {
-    const here = this.order.map((jid) => this.jobs.get(jid));
-    const seen = new Set(here.map((j) => j.job_id));
-    const elsewhere = [];
+    // Sorted by when each was created; a round file is read only for the rows shown.
+    /** @type {Array<{at: string, load: () => Round | null}>} */
+    const candidates = [];
+    const seen = new Set();
+    for (const jid of this.order) {
+      const job = this.jobs.get(jid);
+      if (!job) continue;
+      seen.add(job.job_id);
+      candidates.push({ at: job.created_at ?? '', load: () => job });
+    }
     // Read only: a marker whose owner is gone is shown as interrupted, and
     // left for consult_get or the startup sweep to close out.
     for (const jobId of store.listRunning()) {
@@ -246,41 +436,49 @@ export class JobManager {
       const state = ownerState(jobId, live.owner);
       // A round saved just before its owner died is the answer, whatever the marker says.
       const saved = state === 'alive' ? null : store.loadRoundAt(live);
-      elsewhere.push({ rec: state === 'alive' ? live : saved ?? { ...live, status: 'failed', failure: { kind: 'interrupted' } } });
+      // The marker of a round whose owner is gone: shown as interrupted, with no failure detail to give.
+      const rec =
+        state === 'alive'
+          ? live
+          : (saved ?? /** @type {Round} */ ({ ...live, status: 'failed', failure: { kind: 'interrupted' } }));
+      candidates.push({ at: rec.created_at ?? '', load: () => rec });
     }
-    for (const row of store.indexRows()) if (!seen.has(row.job_id)) { seen.add(row.job_id); elsewhere.push({ row }); }
-    const at = (x) => x.created_at ?? x.rec?.created_at ?? x.row?.created_at ?? '';
+    for (const row of store.indexRows())
+      if (!seen.has(row.job_id)) {
+        seen.add(row.job_id);
+        candidates.push({ at: row.created_at ?? '', load: () => store.loadRoundAt(row) });
+      }
+    /** @type {Round[]} */
     const picked = [];
-    // Round files are read only for the rows shown; one that cannot be read is passed over.
-    for (const x of [...here, ...elsewhere].sort((p, q) => (at(q) < at(p) ? -1 : at(q) > at(p) ? 1 : 0))) {
+    // One that cannot be read is passed over.
+    for (const x of candidates.sort((p, q) => (q.at < p.at ? -1 : q.at > p.at ? 1 : 0))) {
       if (picked.length >= limit) break;
-      const j = x.row ? store.loadRoundAt(x.row) : x.rec ?? x;
+      const j = x.load();
       if (j) picked.push(j);
     }
-    return picked
-      .map((j) => {
-        return {
-          job_id: j.job_id,
-          group_id: j.group_id ?? null,
-          chain_id: j.chain_id,
-          round: j.round,
-          target: j.target,
-          cli: j.cli,
-          model: j.model,
-          mode: j.mode,
-          status: j.status,
-          failure_kind: j.failure?.kind ?? null,
-          created_at: j.created_at,
-          duration_ms: j.duration_ms,
-          summary: j.result ? j.result.summary.slice(0, 200) : null,
-          recorded: Boolean(j.record),
-          verdicts: j.record?.entries ? tally(j.record.entries.map((e) => e.verdict)) : null,
-          this_session: this.jobs.has(j.job_id),
-          predicted: Boolean(j.prediction),
-          reflected: Boolean(j.reflection),
-          initiator: j.initiator ?? null,
-        };
-      });
+    return picked.map((j) => {
+      return {
+        job_id: j.job_id,
+        group_id: j.group_id ?? null,
+        chain_id: j.chain_id,
+        round: j.round,
+        target: j.target,
+        cli: j.cli,
+        model: j.model,
+        mode: j.mode,
+        status: j.status,
+        failure_kind: j.failure?.kind ?? null,
+        created_at: j.created_at,
+        duration_ms: j.duration_ms,
+        summary: j.result ? j.result.summary.slice(0, 200) : null,
+        recorded: Boolean(j.record),
+        verdicts: j.record?.entries ? tally(j.record.entries.map((e) => e.verdict)) : null,
+        this_session: this.jobs.has(j.job_id),
+        predicted: Boolean(j.prediction),
+        reflected: Boolean(j.reflection),
+        initiator: j.initiator ?? null,
+      };
+    });
   }
 
   /**
@@ -290,25 +488,34 @@ export class JobManager {
    * but named under `not_reported`. Nothing is estimated.
    */
   usageTotals() {
+    /** @type {Record<string, Record<string, number> & {consultations: number, attempts: number}>} */
     const by = {};
+    /** @type {Record<string, Set<string>>} */
     const reported = {};
     for (const j of this.jobs.values()) {
-      const attempts = [...(j.retries ?? []).map((r) => r.usage), j.usage].filter(Boolean);
+      const attempts = [...(j.retries ?? []).map((r) => r.usage), j.usage].filter((u) => u != null);
       if (!attempts.length) continue;
       const t = (by[j.target] ??= { consultations: 0, attempts: 0 });
       const seen = (reported[j.target] ??= new Set());
       t.consultations += 1;
       t.attempts += attempts.length;
       for (const u of attempts) {
-        for (const [k, v] of Object.entries(u)) if (typeof v === 'number') { t[k] = (t[k] ?? 0) + v; seen.add(k); }
+        for (const [k, v] of Object.entries(u))
+          if (typeof v === 'number') {
+            t[k] = (t[k] ?? 0) + v;
+            seen.add(k);
+          }
       }
     }
+    /** @type {Record<string, Record<string, number | string[]>>} */
+    const out = {};
     for (const [target, t] of Object.entries(by)) {
-      t.not_reported = USAGE_FIGURES.filter((k) => !reported[target].has(k));
+      out[target] = { ...t, not_reported: USAGE_FIGURES.filter((k) => !reported[target]?.has(k)) };
     }
-    return by;
+    return out;
   }
 
+  /** @param {RawRequest} rawRequest the tool arguments, not yet validated */
   start(rawRequest) {
     if (process.env.SEVERALLY_ACTIVE === '1') {
       throw new RequestError(
@@ -318,13 +525,15 @@ export class JobManager {
     }
     // A config the operator got wrong is not run on defaults: that could
     // re-enable a CLI they turned off. Reading the history still works.
-    if (configProblem()) throw new RequestError(`the severally config file needs fixing first: ${configProblem()}`, 'config_invalid');
+    if (configProblem())
+      throw new RequestError(`the severally config file needs fixing first: ${configProblem()}`, 'config_invalid');
 
     // Resolve the chain before validating, so follow-up rules can be applied.
-    const followupTo = typeof rawRequest?.followup_to === 'string' && rawRequest.followup_to.trim()
-      ? rawRequest.followup_to.trim()
-      : null;
+    const followupTo =
+      typeof rawRequest?.followup_to === 'string' && rawRequest.followup_to.trim() ? rawRequest.followup_to.trim() : null;
+    /** @type {(Round & {nextRound: number}) | null} */
     let parent = null;
+    /** @type {GroupParents | null} */
     let fromGroup = null;
     if (followupTo?.startsWith('group_')) {
       // A follow-up to a fan-out goes to every member that can take one; the
@@ -340,11 +549,11 @@ export class JobManager {
     } else if (followupTo) {
       // A job from an earlier server session is read back from the history,
       // so a restart does not end a consultation the lead is still checking.
-      parent = this.jobs.get(followupTo) ?? store.loadRound(followupTo);
-      if (!parent) throw new RequestError(`followup_to references unknown job "${followupTo}"`, 'unknown_job');
-      if (parent.status !== 'completed') {
+      const found = this.jobs.get(followupTo) ?? store.loadRound(followupTo);
+      if (!found) throw new RequestError(`followup_to references unknown job "${followupTo}"`, 'unknown_job');
+      if (found.status !== 'completed') {
         throw new RequestError(
-          `followup_to job "${followupTo}" is ${parent.status}; only a completed consultation can be followed up`,
+          `followup_to job "${followupTo}" is ${found.status}; only a completed consultation can be followed up`,
           'followup_not_completed',
         );
       }
@@ -352,22 +561,24 @@ export class JobManager {
       // round goes after every round already there: numbering it parent + 1
       // would overwrite a later round's history file. A later round that
       // failed or was cancelled does not block a retry from the parent.
-      const rounds = this.#chainRounds(parent.chain_id);
-      const later = rounds.find((j) => j.round > parent.round && !['failed', 'cancelled'].includes(j.status));
+      const rounds = this.#chainRounds(found.chain_id);
+      const later = rounds.find((j) => j.round > found.round && !['failed', 'cancelled'].includes(j.status));
       if (later) {
         throw new RequestError(
-          `job "${followupTo}" is round ${parent.round}, and this consultation already has round ${later.round} (job "${later.job_id}", ${later.status}); follow up the latest round`,
+          `job "${followupTo}" is round ${found.round}, and this consultation already has round ${later.round} (job "${later.job_id}", ${later.status}); follow up the latest round`,
           'followup_not_latest',
         );
       }
-      parent = { ...parent, nextRound: Math.max(...rounds.map((j) => j.round)) + 1 };
+      parent = { ...found, nextRound: Math.max(...rounds.map((j) => j.round)) + 1 };
     }
 
     if (parent && (rawRequest.target ?? null) === null && !rawRequest.targets?.length) {
       rawRequest = { ...rawRequest, target: parent.target };
     }
     // A fan-out's members were all handed the same brief, so any one of them holds it.
-    if (parent || fromGroup) rawRequest = inherit(rawRequest, fromGroup ? fromGroup.links[0].groupMember ?? fromGroup.links[0].parent : parent);
+    const first = fromGroup?.links[0];
+    const inheritFrom = first ? (first.groupMember ?? first.parent) : parent;
+    if (inheritFrom) rawRequest = inherit(rawRequest, inheritFrom);
 
     const req = parseRequest(rawRequest, {
       isFollowup: Boolean(parent || fromGroup),
@@ -403,37 +614,43 @@ export class JobManager {
     // A follow-up's seat also names the chain and round it opens, so that two
     // servers continuing one consultation at once cannot both take a round
     // number: neither sees the other's round in its history until it ends.
-    const chainOf = (i) => (fromGroup ? fromGroup.links[i] : parent ? { parent, round } : null);
-    const seats = req.targets.map((target, i) => ({
-      job_id: id('job'),
-      ...(chainOf(i) ? { chain_id: chainOf(i).parent.chain_id, round: chainOf(i).round } : {}),
-      // Twice the budget plus an hour: the deadline is wall-clock, the budget is
-      // not, so a suspended laptop must not make a live owner look overdue.
-      owner: {
-        pid: process.pid,
-        deadline_at: new Date(Date.now() + 2 * timeoutMs(consultantByName(target)) + POLICY.killGraceMs + 3_600_000).toISOString(),
-      },
-    }));
+    const chainOf = (/** @type {number} */ i) => (fromGroup ? fromGroup.links[i] : parent ? { parent, round } : null);
+    const seats = req.targets.map((/** @type {string} */ target, /** @type {number} */ i) => {
+      const link = chainOf(i);
+      return {
+        job_id: id('job'),
+        ...(link ? { chain_id: link.parent.chain_id, round: link.round } : {}),
+        // Twice the budget plus an hour: the deadline is wall-clock, the budget is
+        // not, so a suspended laptop must not make a live owner look overdue.
+        owner: {
+          pid: process.pid,
+          deadline_at: new Date(
+            Date.now() + 2 * timeoutMs(consultantByName(target)) + POLICY.killGraceMs + 3_600_000,
+          ).toISOString(),
+        },
+      };
+    });
     const taken = store.takeSeats(seats, POLICY.maxConcurrent, (seat) => ownerState(seat.job_id, seat.owner) === 'alive');
     if (taken.chainBusy) {
       const { live, mine } = taken.chainBusy;
       throw new RequestError(
-        `another severally process has already continued this consultation: job "${live.job_id}" is round ${live.round ?? mine.round}`
-        + '; wait for it (consult_get) and follow up the latest round',
+        `another severally process has already continued this consultation: job "${live.job_id}" is round ${live.round ?? mine.round}` +
+          '; wait for it (consult_get) and follow up the latest round',
         'followup_not_latest',
       );
     }
     if (!taken.ok) {
       throw new RequestError(
-        `this would run ${taken.live + seats.length} consultations at once; the cap is ${POLICY.maxConcurrent}`
-        + (taken.elsewhere ? `, and ${taken.elsewhere} of the ${taken.live} running are in other severally processes` : '')
-        + '. Wait for one to finish (consult_get) or cancel it',
+        `this would run ${taken.live + seats.length} consultations at once; the cap is ${POLICY.maxConcurrent}` +
+          (taken.elsewhere ? `, and ${taken.elsewhere} of the ${taken.live} running are in other severally processes` : '') +
+          '. Wait for one to finish (consult_get) or cancel it',
         'concurrency_limit',
       );
     }
     // A request refused from here on gives its seats back.
     try {
       // Each target's parent round and the round it opens, in req.targets order.
+      /** @type {Array<{parent: Round | null, round: number, groupMember?: Round}>} */
       const links = fromGroup?.links ?? req.targets.map(() => ({ parent, round }));
       return this.#admitted(req, links, seats, fromGroup);
     } catch (err) {
@@ -446,29 +663,50 @@ export class JobManager {
   // round of its own chain. A member that is still running, never answered or
   // has used its rounds is skipped and named; if that is every member, the
   // request is refused.
+  /**
+   * @param {string} groupId
+   * @returns {GroupParents}
+   */
   #groupParents(groupId) {
     const group = this.groups.get(groupId) ?? store.loadGroup(groupId);
     if (!group) throw new RequestError(`followup_to references unknown group "${groupId}"`, 'unknown_group');
+    /** @type {GroupLink[]} */
     const links = [];
+    /** @type {GroupParents['skipped']} */
     const skipped = [];
     for (const jid of group.job_ids) {
       const member = this.jobs.get(jid) ?? store.loadRound(jid);
       if (!member) {
-        skipped.push({ job_id: jid, target: null, reason: 'not found: aged out of the history, or still running in another severally process' });
+        skipped.push({
+          job_id: jid,
+          target: null,
+          reason: 'not found: aged out of the history, or still running in another severally process',
+        });
         continue;
       }
       const rounds = this.#chainRounds(member.chain_id);
       const latest = rounds.filter((j) => !['failed', 'cancelled'].includes(j.status)).sort((a, b) => b.round - a.round)[0];
+      if (!latest) {
+        skipped.push({
+          job_id: member.job_id,
+          target: member.target,
+          reason: `${member.status}, so there is no answer to follow up`,
+        });
+        continue;
+      }
       const nextRound = Math.max(...rounds.map((j) => j.round)) + 1;
       // The name is kept, not re-resolved: a consultant renamed or turned off
       // since is skipped, never continued by whichever one answers to it now.
       const consultant = consultantByName(member.target);
-      const reason = !latest ? `${member.status}, so there is no answer to follow up`
-        : latest.status !== 'completed' ? `round ${latest.round} is still ${latest.status}`
-          : nextRound > POLICY.maxRounds ? `has used its ${POLICY.maxRounds} rounds`
-            : !consultant || !consultantAvailable(consultant) ? 'this consultant is no longer configured or available here'
+      const reason =
+        latest.status !== 'completed'
+          ? `round ${latest.round} is still ${latest.status}`
+          : nextRound > POLICY.maxRounds
+            ? `has used its ${POLICY.maxRounds} rounds`
+            : !consultant || !consultantAvailable(consultant)
+              ? 'this consultant is no longer configured or available here'
               : null;
-      if (reason) skipped.push({ job_id: (latest ?? member).job_id, target: member.target, reason });
+      if (reason) skipped.push({ job_id: latest.job_id, target: member.target, reason });
       else links.push({ parent: { ...latest, nextRound }, round: nextRound, groupMember: member });
     }
     if (!links.length) {
@@ -480,21 +718,30 @@ export class JobManager {
     return { group, links, skipped };
   }
 
+  /**
+   * @param {ParsedRequest} req
+   * @param {Array<{parent: Round | null, round: number, groupMember?: Round}>} links
+   * @param {Seat[]} seats
+   * @param {GroupParents | null} [fromGroup]
+   */
   #admitted(req, links, seats, fromGroup = null) {
     // What expose_from_parent copies again: for a group, what that fan-out
     // exposed (one manifest, shared by its members); otherwise the parent's.
-    const parent = links[0].groupMember ?? links[0].parent;
+    const first = links[0];
+    const parent = first?.groupMember ?? first?.parent;
     const groupId = id('group');
     // Copied once for the whole request, before a round is counted or a job
     // exists, into the group's own directory: every member is then handed the
     // same bytes (the manifest carries their sha256), and a path that is
     // missing or a tree that blows the cap is the lead's to fix now rather
     // than a job that fails having already spent a round of this chain.
+    /** @type {ExposeManifest | null} */
     let exposeManifest = null;
-    const parentEntries = req.context.expose_from_parent ? parent.brief?.expose_paths?.entries ?? [] : [];
+    /** @type {BriefExposeEntry[]} */
+    const parentEntries = req.context.expose_from_parent ? (parent?.brief?.expose_paths?.entries ?? []) : [];
     if (req.context.expose_from_parent && parentEntries.length === 0) {
       throw new RequestError(
-        `context.expose_from_parent: job "${parent.job_id}" exposed no files, so there is nothing to copy again; name them in context.expose_paths`,
+        `context.expose_from_parent: job "${parent?.job_id}" exposed no files, so there is nothing to copy again; name them in context.expose_paths`,
         'nothing_to_inherit',
       );
     }
@@ -503,8 +750,11 @@ export class JobManager {
       try {
         fs.mkdirSync(path.join(snapshot, 'workspace'), { recursive: true, mode: 0o700 });
         const plan = planInheritance(parentEntries, req.context.expose_paths);
-        exposeManifest = materializeExposedPaths(snapshot, plan.paths)
-          ?? { entries: [], totals: { files: 0, bytes: 0 }, skipped: [] };
+        exposeManifest = materializeExposedPaths(snapshot, plan.paths) ?? {
+          entries: [],
+          totals: { files: 0, bytes: 0 },
+          skipped: [],
+        };
         exposeManifest.skipped.push(...plan.skipped);
         const parentSources = new Set(parentEntries.map((e) => e.source));
         for (const e of exposeManifest.entries) if (parentSources.has(e.source)) e.inherited = true;
@@ -515,37 +765,53 @@ export class JobManager {
           if (req.context.expose_diff) {
             exposeManifest.skipped.push({ source: d.source, reason: 'replaced', exposed_as: d.exposed_as });
           } else {
-            if (reexposeChange(snapshot, d, exposeManifest)) exposeManifest.entries.at(-1).inherited = true;
+            if (reexposeChange(snapshot, d, exposeManifest)) {
+              const added = exposeManifest.entries.at(-1);
+              if (added) added.inherited = true;
+            }
           }
         }
         if (req.context.expose_diff) {
           const room = Math.min(POLICY.input.artifactExcerptMax, POLICY.input.totalCharsMax - charCount(req));
           const diff = exposeDiff(snapshot, req.context.expose_diff, exposeManifest, room);
           if (diff) {
-            req.context.artifacts = [...req.context.artifacts,
-              { name: `git diff ${exposeManifest.entries.at(-1).base}`, kind: 'diff', language: 'diff', excerpt: diff }];
+            req.context.artifacts = [
+              ...req.context.artifacts,
+              { name: `git diff ${exposeManifest.entries.at(-1)?.base}`, kind: 'diff', language: 'diff', excerpt: diff },
+            ];
           }
         }
         markSinceParent(exposeManifest, parentEntries);
         // Every earlier path gone, and nothing else to go on: refused, as a
         // first round with no context is.
-        if (parentEntries.length && !exposeManifest.entries.length && !req.context.facts.length && !req.context.artifacts.length) {
+        if (
+          parentEntries.length &&
+          !exposeManifest.entries.length &&
+          !req.context.facts.length &&
+          !req.context.artifacts.length
+        ) {
           throw new RequestError(
-            `context.expose_from_parent: nothing job "${parent.job_id}" exposed is there any more, and this request has no facts or artifacts`,
+            `context.expose_from_parent: nothing job "${parent?.job_id}" exposed is there any more, and this request has no facts or artifacts`,
             'nothing_to_inherit',
           );
         }
       } catch (err) {
         store.cleanupJobDir(groupId);
-        if (err instanceof RequestError || !err.code) throw err;
+        if (err instanceof RequestError || !(err instanceof Error) || !('code' in err) || !err.code) throw err;
         throw new RequestError(err.message, err.code === 'too_large' ? 'expose_paths_too_large' : 'expose_path_invalid');
       }
       req._snapshot = path.join(snapshot, 'workspace');
     }
-    const members = req.targets.map((target, i) => {
-      const { parent: from, round } = links[i];
+    const members = req.targets.map((/** @type {string} */ target, /** @type {number} */ i) => {
+      // One link and one seat per target: start() builds them from req.targets.
+      const link = links[i];
+      const seat = seats[i];
+      if (!link || !seat) throw new Error(`no follow-up link or seat for target "${target}"`);
+      const { parent: from, round } = link;
       const chainId = from ? from.chain_id : id('chain');
-      const jobId = seats[i].job_id;
+      const jobId = seat.job_id;
+      const consultant = consultantNamed(target);
+      /** @type {Job} */
       const job = {
         job_id: jobId,
         chain_id: chainId,
@@ -582,9 +848,9 @@ export class JobManager {
         status: 'queued',
         // What this consultant is: the CLI it runs on, the model and its
         // lineage, as the operator defined it.
-        cli: consultantByName(target).cli,
-        model: consultantByName(target).model,
-        vendor: consultantByName(target).vendor,
+        cli: consultant.cli,
+        model: consultant.model,
+        vendor: consultant.vendor,
         created_at: new Date().toISOString(),
         started_at: null,
         finished_at: null,
@@ -601,21 +867,28 @@ export class JobManager {
       this.order.push(jobId);
       LIVE_HERE.add(jobId);
       this.#watchCancels();
-      job._owner = seats[i].owner;
+      job._owner = seat.owner;
       this.#mark(job);
       return job;
     });
     this.#evict();
 
+    const [firstMember] = members;
+    if (!firstMember) throw new Error('a consultation needs a target');
+    /** @type {Group} */
     const group = {
       group_id: groupId,
       created_at: new Date().toISOString(),
       mode: req.mode,
-      question: members[0].question, // already redacted, and byte-identical across the group
-      job_ids: members.map((m) => m.job_id),
+      question: firstMember.question, // already redacted, and byte-identical across the group
+      job_ids: members.map((/** @type {Job} */ m) => m.job_id),
     };
     this.groups.set(groupId, group);
-    try { store.persistGroup(group); } catch { /* history is best effort */ }
+    try {
+      store.persistGroup(group);
+    } catch {
+      /* history is best effort */
+    }
 
     // A fan-out is only comparable if every consultant answered the same
     // question in the same words: every member's brief is the same request,
@@ -634,28 +907,31 @@ export class JobManager {
     if (req._snapshot) store.cleanupJobDir(groupId);
 
     // The members of a follow-up to a group can be at different rounds.
-    const { round } = members[0];
-    const sameRound = members.every((m) => m.round === round);
+    const { round } = firstMember;
+    const sameRound = members.every((/** @type {Job} */ m) => m.round === round);
     const common = {
       group_id: groupId,
       ...(sameRound ? { round, rounds_remaining: POLICY.maxRounds - round } : {}),
       ...(fromGroup ? { followup_to_group: fromGroup.group.group_id, skipped: fromGroup.skipped } : {}),
-      ...(parentEntries.length ? { exposed_from_parent: inheritedSummary(exposeManifest) } : {}),
+      ...(parentEntries.length && exposeManifest ? { exposed_from_parent: inheritedSummary(exposeManifest) } : {}),
       mode: req.mode,
       // Counted, not refused: a brief of facts alone is a legitimate
       // consultation, but one about code that hands over no file is one the
       // consultant answers without having seen the repository.
       files_exposed: exposeManifest?.totals.files ?? 0,
-      ...(exposeManifest?.totals.files ? {} : {
-        files_note: 'no file was handed over, so the consultant answers from the brief alone; if this is about code in a repository, consult_cancel and start again with context.expose_paths',
-      }),
+      ...(exposeManifest?.totals.files
+        ? {}
+        : {
+            files_note:
+              'no file was handed over, so the consultant answers from the brief alone; if this is about code in a repository, consult_cancel and start again with context.expose_paths',
+          }),
       status: 'running',
       accepted_at: group.created_at,
       limits: limitsSummary(),
     };
 
     if (!req.fanout) {
-      const job = members[0];
+      const job = firstMember;
       return {
         ...common,
         job_id: job.job_id,
@@ -669,8 +945,12 @@ export class JobManager {
     return {
       ...common,
       question: group.question, // the redacted text every member was actually sent
-      jobs: members.map((m) => ({
-        job_id: m.job_id, chain_id: m.chain_id, target: m.target, cli: m.cli, model: m.model,
+      jobs: members.map((/** @type {Job} */ m) => ({
+        job_id: m.job_id,
+        chain_id: m.chain_id,
+        target: m.target,
+        cli: m.cli,
+        model: m.model,
         ...(sameRound ? {} : { round: m.round, rounds_remaining: POLICY.maxRounds - m.round }),
       })),
       poll_with: `consult_get({ group_id: "${groupId}" })`,
@@ -682,25 +962,42 @@ export class JobManager {
   // (memory wins: it can hold a verdict written since the round was saved).
   // Each point goes with the lead's verdict on it, so the consultant answers
   // knowing which of its points were checked and how they came out.
+  /**
+   * @param {string} chainId
+   * @returns {Round[]}
+   */
   #chainRounds(chainId) {
+    /** @type {Map<number, Round>} */
     const byRound = new Map(store.loadChain(chainId).map((j) => [j.round, j]));
     for (const j of this.jobs.values()) if (j.chain_id === chainId) byRound.set(j.round, j);
     return [...byRound.values()];
   }
 
+  /**
+   * @param {string} chainId
+   * @returns {PriorRound[]}
+   */
   #chainHistory(chainId) {
     return this.#chainRounds(chainId)
-      .filter((j) => j.status === 'completed' && j.result)
+      .filter(/** @returns {j is Round & {result: ConsultResult}} */ (j) => j.status === 'completed' && Boolean(j.result))
       .sort((a, b) => a.round - b.round)
       .map((j) => {
         const verdicts = new Map((j.record?.entries ?? []).map((e) => [e.id, e]));
         // The checked points first, then the unchecked ones, each with the
         // lead's verdict and effect when there is one.
-        const ordered = (items, shape) => [
-          ...items.filter((x) => verdicts.has(x.id)),
-          ...items.filter((x) => !verdicts.has(x.id)),
-        ].map((x) => ({ id: x.id, ...shape(x), verdict: verdicts.get(x.id)?.verdict ?? null, effect: verdicts.get(x.id)?.effect ?? null }));
-        const checked = (x) => x.verdict !== null;
+        /**
+         * @template {ResultItem} T
+         * @param {T[]} items
+         * @param {(x: T) => {point: string, grounds?: string | null}} shape
+         */
+        const ordered = (items, shape) =>
+          [...items.filter((x) => verdicts.has(x.id)), ...items.filter((x) => !verdicts.has(x.id))].map((x) => ({
+            id: x.id,
+            ...shape(x),
+            verdict: verdicts.get(x.id)?.verdict ?? null,
+            effect: verdicts.get(x.id)?.effect ?? null,
+          }));
+        const checked = (/** @type {{verdict: unknown}} */ x) => x.verdict !== null;
         const findings = ordered(j.result.findings, (f) => ({ point: f.point, grounds: f.grounds ?? null }));
         return {
           round: j.round,
@@ -718,6 +1015,7 @@ export class JobManager {
   #evict() {
     while (this.order.length > POLICY.maxJobsRetained) {
       const oldest = this.order.shift();
+      if (oldest === undefined) break;
       const j = this.jobs.get(oldest);
       if (j && (j.status === 'running' || j.status === 'queued')) {
         this.order.push(oldest); // never evict live work
@@ -732,6 +1030,7 @@ export class JobManager {
   // last member there is nothing left to compare, so drop the group rather than
   // keep answering as a complete fan-out with no answers in it (and keep the
   // Map, which holds the question text, from growing without bound).
+  /** @param {string} groupId */
   #dropGroupIfEmpty(groupId) {
     const group = this.groups.get(groupId);
     if (!group) return;
@@ -739,8 +1038,15 @@ export class JobManager {
     this.groups.delete(groupId);
   }
 
+  /**
+   * @param {Job} job
+   * @param {ParsedRequest} req
+   * @param {import('./brief.mjs').BriefChain} chain
+   * @param {string} [brief]
+   * @returns {Promise<Job>}
+   */
   async #execute(job, req, chain, brief) {
-    const consultant = consultantByName(job.target);
+    const consultant = consultantNamed(job.target);
     const cli = consultant.cli;
     const adapter = ADAPTERS[cli];
     const workdir = store.makeWorkdir(job.job_id);
@@ -752,7 +1058,7 @@ export class JobManager {
       try {
         fs.cpSync(req._snapshot, path.join(workdir, 'workspace'), { recursive: true });
       } catch (err) {
-        return this.#fail(job, 'spawn_error', `could not copy the exposed files: ${err.message}`);
+        return this.#fail(job, 'spawn_error', `could not copy the exposed files: ${err instanceof Error ? err.message : err}`);
       }
     }
     // start() renders the brief and hands it in: every member of a fan-out is
@@ -760,6 +1066,7 @@ export class JobManager {
     // added on a follow-up to the group.
     const text = brief ?? renderBrief(req, chain);
     const schemaPath = store.writeJobArtifact(job.job_id, 'response-schema.json', JSON.stringify(CONSULT_RESULT_SCHEMA, null, 2));
+    // Left out, not undefined, when the request names none.
     const sandbox = adapter.prepareSandbox ? adapter.prepareSandbox({ workdir, network: req.network }) : null;
 
     try {
@@ -797,11 +1104,11 @@ export class JobManager {
         return this.#fail(
           job,
           'auth',
-          `no ${t.label} credential to hand the consultant: nothing at `
-          + `${sandbox.credentialsSource}, and none of ${ALL_API_CREDENTIAL_VARS.join(' / ')} names a `
-          + 'usable credential. Log in with that CLI, point SEVERALLY_AGY_CRED_HOME at the home '
-          + 'directory that holds the token, or set one of those variables to authenticate with an API key '
-          + 'instead.',
+          `no ${t.label} credential to hand the consultant: nothing at ` +
+            `${sandbox.credentialsSource}, and none of ${ALL_API_CREDENTIAL_VARS.join(' / ')} names a ` +
+            'usable credential. Log in with that CLI, point SEVERALLY_AGY_CRED_HOME at the home ' +
+            'directory that holds the token, or set one of those variables to authenticate with an API key ' +
+            'instead.',
         );
       }
 
@@ -833,10 +1140,11 @@ export class JobManager {
       // What this consultant was actually launched with, read off the
       // invocation and the sandbox rather than restated from intent, so the
       // record says what held for this run.
-      job.boundary = adapter.boundary?.({ args: invocation.args, sandbox, network: req.network,
-        hasExposedPaths: Boolean(req._snapshot) }) ?? null;
+      job.boundary =
+        adapter.boundary?.({ args: invocation.args, sandbox, network: req.network, hasExposedPaths: Boolean(req._snapshot) }) ??
+        null;
 
-      const attempt = (timeout) => {
+      const attempt = (/** @type {number} */ timeout) => {
         const { handle, done } = runChild({
           command: invocation.command,
           args: invocation.args,
@@ -844,7 +1152,9 @@ export class JobManager {
           env,
           input: text,
           timeoutMs: timeout,
-          onCancelSignal: (fn) => job._cancelFns.push(fn),
+          onCancelSignal: (fn) => {
+            job._cancelFns.push(fn);
+          },
           compactLine: adapter.compactLine,
           settleAfter: adapter.settleAfter,
           stopSignal: adapter.stopSignal,
@@ -862,6 +1172,7 @@ export class JobManager {
       // Same consultant, same model, same brief: a re-run never picks another
       // mind. Every earlier failure is kept in job.retries.
       let run = await attempt(budgetMs);
+      /** @type {import('./run.mjs').Interpreted} */
       let interpreted;
       let authTried = false;
       let autoRetries = 0;
@@ -876,7 +1187,9 @@ export class JobManager {
         if ((run.stalled || run.timedOut || run.cancelled) && adapter.diagnostics && sandbox) {
           try {
             job.diagnostics = store.writeDiagnostics(job.chain_id, job.round, redact(adapter.diagnostics({ run, sandbox })));
-          } catch { /* history is best effort */ }
+          } catch {
+            /* history is best effort */
+          }
         }
         if (run.spawnError) {
           return this.#fail(job, 'spawn_error', `could not start ${invocation.command}: ${run.spawnError}`);
@@ -903,7 +1216,7 @@ export class JobManager {
         interpreted = adapter.interpret({ ...run, lastMessageText });
         // An answer after an error the CLI reported is kept only if it parses;
         // otherwise it is that error, re-run like any other.
-        const { recoveredError } = interpreted;
+        const recoveredError = interpreted.ok ? interpreted.recoveredError : null;
         if (interpreted.ok && recoveredError && !parses(interpreted.text)) {
           interpreted = { ok: false, ...recoveredError, usageRaw: interpreted.usageRaw };
         }
@@ -911,9 +1224,12 @@ export class JobManager {
         // No envelope at all: what stderr holds is the dump from stopping it,
         // not a message to classify. Not re-run, as it may have spent its quota.
         if (run.stalled && !interpreted.usageRaw) {
-          return this.#fail(job, 'cli_error',
+          return this.#fail(
+            job,
+            'cli_error',
             `${invocation.command} wrote its finish step but neither returned a result nor exited, and was stopped`,
-            adapter.progress?.(run) ?? null);
+            adapter.progress?.(run) ?? null,
+          );
         }
 
         const remaining = budgetMs - (Date.now() - t0);
@@ -921,19 +1237,35 @@ export class JobManager {
           authTried = true;
           const seeded = adapter.recoverAuthFailure({ interpreted, sandbox, model: job.model });
           if (seeded && remaining >= MIN_RETRY_MS) {
-            job.retries.push({ failure_kind: interpreted.failureKind, reason: 'credentials re-seeded', at: new Date().toISOString(), usage: adapter.usageRecord(interpreted.usageRaw) });
+            job.retries.push({
+              failure_kind: interpreted.failureKind,
+              reason: 'credentials re-seeded',
+              at: new Date().toISOString(),
+              usage: adapter.usageRecord(interpreted.usageRaw),
+            });
             run = await attempt(remaining);
             continue;
           }
         }
         const wait = POLICY.retryBackoffMs * 3 ** autoRetries;
-        if (AUTO_RETRY_KINDS.includes(interpreted.failureKind) && autoRetries < POLICY.maxAutoRetries
-          && remaining - wait >= MIN_RETRY_MS) {
+        if (
+          AUTO_RETRY_KINDS.includes(interpreted.failureKind) &&
+          autoRetries < POLICY.maxAutoRetries &&
+          remaining - wait >= MIN_RETRY_MS
+        ) {
           autoRetries += 1;
-          job.retries.push({ failure_kind: interpreted.failureKind, reason: `transient; re-run after ${wait} ms`, at: new Date().toISOString(), usage: adapter.usageRecord(interpreted.usageRaw) });
-          await new Promise((resolve) => {
+          job.retries.push({
+            failure_kind: interpreted.failureKind,
+            reason: `transient; re-run after ${wait} ms`,
+            at: new Date().toISOString(),
+            usage: adapter.usageRecord(interpreted.usageRaw),
+          });
+          await new Promise((/** @type {(value?: unknown) => void} */ resolve) => {
             const timer = setTimeout(resolve, wait);
-            job._cancelFns.push(() => { clearTimeout(timer); resolve(); });
+            job._cancelFns.push(() => {
+              clearTimeout(timer);
+              resolve();
+            });
           });
           if (job.cancelRequested) return this.#fail(job, 'cancelled', 'consultation cancelled by the lead');
           run = await attempt(budgetMs - (Date.now() - t0));
@@ -943,8 +1275,8 @@ export class JobManager {
       }
 
       // Without an answer, a process left holding the pipes is the failure to report.
-      const leftover = run.pipesForced
-        && `${invocation.command} exited, but a process it started kept its output open and was stopped`;
+      const leftover =
+        run.pipesForced && `${invocation.command} exited, but a process it started kept its output open and was stopped`;
       if (!interpreted.ok) {
         job.usage = adapter.usageRecord(interpreted.usageRaw);
         if (leftover) return this.#fail(job, 'cli_error', leftover, interpreted.message);
@@ -983,8 +1315,12 @@ export class JobManager {
       const notes = [
         adviceCaveat(normalized),
         sameVendorCaveat(job.caller, job.caller_model, consultant),
-        interpreted.recoveredError && `the consultant's CLI reported an error mid-run and then finished its answer: ${redact(interpreted.recoveredError.message).slice(0, 300)}`,
-        leftover && 'the answer parsed, but a process the consultant started kept its output open after it exited and was stopped (one that left its process group may still be running)',
+        interpreted.recoveredError &&
+          `the consultant's CLI reported an error mid-run and then finished its answer: ${redact(interpreted.recoveredError.message).slice(0, 300)}`,
+        leftover &&
+          'the answer parsed, but a process the consultant started kept its output open after it exited and was stopped (one that left its process group may still be running)',
+        req._snapshot && unreadCaveat(job.tool_calls, adapter.FILE_READ_TOOLS),
+        refusedToolCaveat(job.tool_calls, adapter.ALLOWED_TOOLS),
       ].filter(Boolean);
       // No `advice_usable` verdict here. It was always true, so it carried no
       // information -- and worse, it read as the server vouching for advice it
@@ -1007,6 +1343,13 @@ export class JobManager {
     }
   }
 
+  /**
+   * @param {Job} job
+   * @param {string} kind
+   * @param {unknown} message
+   * @param {string | null} [detail]
+   * @returns {Job}
+   */
   #fail(job, kind, message, detail) {
     if (job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') return job;
     job.status = kind === 'cancelled' ? 'cancelled' : 'failed';
@@ -1023,12 +1366,22 @@ export class JobManager {
   }
 
   // The in-progress marker other processes read (see store.writeRunning).
+  /** @param {Job} job */
   #mark(job) {
-    try { store.writeRunning({ ...this.#record(job), owner: job._owner }); } catch { /* history is best effort */ }
+    try {
+      store.writeRunning({ ...this.#record(job), owner: job._owner });
+    } catch {
+      /* history is best effort */
+    }
   }
 
+  /** @param {Job} job */
   #finish(job) {
-    try { store.persistRound(this.#record(job)); } catch { /* history is best effort */ }
+    try {
+      store.persistRound(this.#record(job));
+    } catch {
+      /* history is best effort */
+    }
     store.removeRunning(job.job_id);
     store.releaseSeat(job.job_id);
     LIVE_HERE.delete(job.job_id);
@@ -1043,16 +1396,17 @@ export class JobManager {
   // consultant did not produce and a word outside VERDICTS, then stores what
   // was written. It never decides that a finding was adopted, and it never
   // fills in a verdict the lead did not write.
+  /** @param {RawRecord} [input] */
   record(input = {}) {
     if (input.records !== undefined) return this.#recordMany(input);
     const allowed = ['job_id', 'entries', 'reflection'];
     const unknown = Object.keys(input).filter((k) => !allowed.includes(k));
     if (unknown.length) {
       throw new RequestError(
-        `${unknown.map((k) => `"${k}"`).join(', ')} cannot be written here; this call takes ${allowed.join(', ')}, or records`
-        + (unknown.includes('prediction')
-          ? '. A prediction is written when the consultation starts (consult_start\'s `prediction`) and cannot be added or changed afterwards -- that is what makes it a prediction'
-          : ''),
+        `${unknown.map((k) => `"${k}"`).join(', ')} cannot be written here; this call takes ${allowed.join(', ')}, or records` +
+          (unknown.includes('prediction')
+            ? ". A prediction is written when the consultation starts (consult_start's `prediction`) and cannot be added or changed afterwards -- that is what makes it a prediction"
+            : ''),
         'unknown_field',
       );
     }
@@ -1066,24 +1420,32 @@ export class JobManager {
   // record is checked before anything is written, so a bad id leaves the
   // history as it was; then each job is written on its own, and a write that
   // fails is named in the answer rather than reported as saved.
+  /** @param {RawRecord} input */
   #recordMany(input) {
     const extra = Object.keys(input).filter((k) => k !== 'records');
     if (extra.length) {
-      throw new RequestError(`records cannot be combined with ${extra.map((k) => `"${k}"`).join(', ')}; put each job's verdicts inside records`, 'unknown_field');
+      throw new RequestError(
+        `records cannot be combined with ${extra.map((k) => `"${k}"`).join(', ')}; put each job's verdicts inside records`,
+        'unknown_field',
+      );
     }
     const { records } = input;
     if (!Array.isArray(records) || records.length === 0) {
       throw new RequestError('records must be a non-empty array of { job_id, entries?, reflection? }', 'records_required');
     }
+    /** @type {Array<{index: number, job_id: string | null, error: string, message: string}>} */
     const problems = [];
+    /** @type {RecordChange[]} */
     const changes = [];
     const seen = new Set();
-    records.forEach((r, i) => {
+    records.forEach((/** @type {RawRecord} */ r, i) => {
       try {
-        if (seen.has(r?.job_id)) throw new RequestError(`job "${r.job_id}" appears twice; give each job one record`, 'duplicate_job');
+        if (seen.has(r?.job_id))
+          throw new RequestError(`job "${r.job_id}" appears twice; give each job one record`, 'duplicate_job');
         seen.add(r?.job_id);
         const unknown = Object.keys(r ?? {}).filter((k) => !['job_id', 'entries', 'reflection'].includes(k));
-        if (unknown.length) throw new RequestError(`${unknown.map((k) => `"${k}"`).join(', ')} cannot be written here`, 'unknown_field');
+        if (unknown.length)
+          throw new RequestError(`${unknown.map((k) => `"${k}"`).join(', ')} cannot be written here`, 'unknown_field');
         changes.push(this.#checkRecord(r ?? {}));
       } catch (err) {
         if (!(err instanceof RequestError)) throw err;
@@ -1104,9 +1466,16 @@ export class JobManager {
 
   // Everything that can be wrong with a record, found before anything is
   // written: what the job's record and reflection become, or a RequestError.
+  /**
+   * @param {RawRecord} rec
+   * @returns {RecordChange}
+   */
   #checkRecord({ job_id: jobId, entries, reflection }) {
     if (entries === undefined && reflection === undefined) {
-      throw new RequestError('pass entries (verdicts on specific points), reflection (what the answer added), or both', 'nothing_to_record');
+      throw new RequestError(
+        'pass entries (verdicts on specific points), reflection (what the answer added), or both',
+        'nothing_to_record',
+      );
     }
     // A job this process ran is in memory; one from an earlier session is read
     // back from its round file, so a verdict can still be written once the
@@ -1114,10 +1483,7 @@ export class JobManager {
     const live = this.jobs.get(jobId);
     const job = live ?? store.loadRound(jobId);
     if (!job) {
-      throw new RequestError(
-        `no consultation with job_id "${jobId}" in this session or in ~/.severally/history`,
-        'unknown_job',
-      );
+      throw new RequestError(`no consultation with job_id "${jobId}" in this session or in ~/.severally/history`, 'unknown_job');
     }
     if (!job.result) {
       throw new RequestError(
@@ -1131,7 +1497,8 @@ export class JobManager {
 
     const ids = recordableIds(job.result);
     const now = new Date().toISOString();
-    const merged = new Map((job.record?.entries ?? []).map((e) => [e.id, e]));
+    /** @type {Map<string, RecordEntry>} */
+    const written = new Map();
 
     for (const entry of entries ?? []) {
       const id = typeof entry?.id === 'string' ? entry.id.trim() : '';
@@ -1148,7 +1515,7 @@ export class JobManager {
           'invalid_verdict',
         );
       }
-      merged.set(id, {
+      written.set(id, {
         id,
         verdict,
         effect: text(entry?.effect),
@@ -1162,6 +1529,7 @@ export class JobManager {
     // lead predicted can still arrive with the evidence that settles it, and a
     // surprise can still be wrong, so a match/miss verdict would rate the
     // consultation on the wrong axis.
+    /** @type {Reflection | undefined} */
     let newReflection;
     if (reflection !== undefined) {
       const delta = text(reflection?.delta);
@@ -1180,29 +1548,40 @@ export class JobManager {
       newReflection = { delta, related_item_ids: related, recorded_at: now };
     }
 
-    const newRecord = entries === undefined
-      ? undefined
-      : { updated_at: now, entries: ids.filter((id) => merged.has(id)).map((id) => merged.get(id)) };
-    return { job, live, record: newRecord, reflection: newReflection };
+    return { job, live, entries: entries === undefined ? undefined : [...written.values()], reflection: newReflection };
   }
 
-  #saveRecord({ job, live, record, reflection }) {
+  /** @param {RecordChange} change */
+  #saveRecord({ job, live, entries, reflection }) {
     const was = { record: job.record, reflection: job.reflection };
-    if (reflection !== undefined) job.reflection = reflection;
-    if (record !== undefined) job.record = record;
+    // Another server may have written verdicts or a reflection to this round
+    // since this one loaded it. Start from the file, so this call replaces
+    // only the ids it names (and the reflection, if it passes one) and keeps
+    // the rest; the merge goes back into memory too, so consult_get and a
+    // follow-up's brief show the same record.
+    // ponytail: read-then-write, not locked; two writes in the same instant can still lose one.
+    const disk = store.loadRoundAt(job);
+    const base = disk?.result ? disk : job;
+    job.reflection = reflection ?? base.reflection;
+    if (entries !== undefined) {
+      const merged = new Map((base.record?.entries ?? []).map((e) => [e.id, e]));
+      for (const e of entries) merged.set(e.id, e);
+      const ids = job.result ? recordableIds(job.result) : [];
+      job.record = { updated_at: new Date().toISOString(), entries: ids.flatMap((id) => merged.get(id) ?? []) };
+    } else if (base.record) job.record = base.record;
     // An update to a round that already happened, so the index line stays as it
     // was: the history has one line per consultation, not one per edit.
     // Unlike the round itself, a verdict exists nowhere else once this server
     // exits, so a failed write is the lead's to know about, not best effort.
     try {
-      store.persistRound(live ? this.#record(job) : job, { appendIndex: false });
+      store.persistRound(live ? this.#record(live) : job, { appendIndex: false });
     } catch (e) {
       // Not saved, so not shown as recorded either.
       Object.assign(job, was);
       return {
         job_id: job.job_id,
         error: 'record_not_saved',
-        message: `the verdict for "${job.job_id}" could not be written to the history (${e.message}); record it again`,
+        message: `the verdict for "${job.job_id}" could not be written to the history (${e instanceof Error ? e.message : e}); record it again`,
       };
     }
     // Counts only: the entries are what the lead just wrote, and
@@ -1217,6 +1596,12 @@ export class JobManager {
     };
   }
 
+  /**
+   * @param {string} jobId
+   * @param {number | undefined} waitMs
+   * @param {{detail?: string | undefined}} [opts]
+   * @param {AbortSignal} [signal]
+   */
   async wait(jobId, waitMs, opts, signal) {
     const job = this.jobs.get(jobId);
     if (!job) return this.#waitOnDisk(() => this.view(jobId, opts), waitMs, signal);
@@ -1230,6 +1615,13 @@ export class JobManager {
 
   // A consultation another process runs has no promise here, so its history
   // is re-read once a second until it is no longer running or the wait is up.
+  /**
+   * @template {{status: string}} T
+   * @param {() => T | null} read
+   * @param {number | undefined} waitMs
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<T | null>}
+   */
   async #waitOnDisk(read, waitMs, signal) {
     const until = Date.now() + Math.min(Math.max(0, waitMs ?? 0), POLICY.maxWaitMs);
     let view = read();
@@ -1254,12 +1646,14 @@ export class JobManager {
     }, CANCEL_POLL_MS).unref();
   }
 
+  /** @param {string} jobId */
   cancel(jobId) {
     const job = this.jobs.get(jobId);
     if (!job) {
       const view = this.view(jobId);
       if (!view) return null;
-      if (view.status !== 'running' && view.status !== 'queued') return { ...view, cancel_effect: `job was already ${view.status}` };
+      if (view.status !== 'running' && view.status !== 'queued')
+        return { ...view, cancel_effect: `job was already ${view.status}` };
       return {
         ...view,
         cancel_effect: store.requestCancel(jobId)
@@ -1268,17 +1662,22 @@ export class JobManager {
       };
     }
     if (job.status !== 'running' && job.status !== 'queued') {
-      return { ...this.view(jobId), cancel_effect: `job was already ${job.status}` };
+      return { ...this.#jobView(job, undefined), cancel_effect: `job was already ${job.status}` };
     }
     job.cancelRequested = true;
     for (const fn of job._cancelFns) fn();
     if (job._handle) job._handle.stop();
-    return { ...this.view(jobId), status: 'cancelling', cancel_effect: 'consultant process group signalled' };
+    return { ...this.#jobView(job, undefined), status: 'cancelling', cancel_effect: 'consultant process group signalled' };
   }
 
   // Every field here is derived from the one `members` array it is handed, so a
   // group view can never report one status in `members` and another in
   // `comparison` or `status` for the same job.
+  /**
+   * @param {Group} group
+   * @param {JobView[]} members
+   * @param {{detail?: string | undefined}} [opts]
+   */
   #shapeGroup(group, members, { detail } = {}) {
     const full = detail === 'full';
     const cancelling = members.some((m) => m.status === 'cancelling');
@@ -1295,9 +1694,10 @@ export class JobManager {
     // same thing three times. Hoist one copy to the group and strip it from
     // the members, which keeps the payload readable without losing anything.
     const firstBrief = members.find((m) => m.brief)?.brief ?? null;
-    const groupBrief = firstBrief && !full
-      ? { ...firstBrief, full_with: `consult_get({ group_id: "${group.group_id}", detail: "full" }) or consult_export` }
-      : firstBrief;
+    const groupBrief =
+      firstBrief && !full
+        ? { ...firstBrief, full_with: `consult_get({ group_id: "${group.group_id}", detail: "full" }) or consult_export` }
+        : firstBrief;
     // The limits are the server's, not a member's: one copy, on the group.
     // By default a member is only its state: what there is to compare is in
     // `comparison`, once, and the full answer is one consult_get({ job_id }) away.
@@ -1305,7 +1705,8 @@ export class JobManager {
       if (full) return rest;
       const message = rest.failure && cut(rest.failure.message, FAILURE_MESSAGE_CHARS);
       const progress = cut(rest.progress, FAILURE_MESSAGE_CHARS);
-      const cutShort = progress !== rest.progress || Boolean(rest.failure && (message !== rest.failure.message || rest.failure.detail));
+      const cutShort =
+        progress !== rest.progress || Boolean(rest.failure && (message !== rest.failure.message || rest.failure.detail));
       return {
         job_id: rest.job_id,
         target: rest.target,
@@ -1321,19 +1722,22 @@ export class JobManager {
     const question = full ? group.question : cut(group.question, QUESTION_CHARS);
     const view = {
       group_id: group.group_id,
-      status: cancelling ? 'cancelling' : (live ? 'running' : 'done'),
+      status: cancelling ? 'cancelling' : live ? 'running' : 'done',
       mode: group.mode,
       question,
-      ...(question !== group.question ? { question_full_with: `consult_get({ group_id: "${group.group_id}", detail: "full" })` } : {}),
+      ...(question !== group.question
+        ? { question_full_with: `consult_get({ group_id: "${group.group_id}", detail: "full" })` }
+        : {}),
       brief: groupBrief,
       members_expected: group.job_ids.length,
       members_available: members.length,
       // History is capped, so an older member can already be gone. Say so:
       // a fan-out that quietly reports fewer answers than it asked for is
       // worse than one that admits the comparison is partial.
-      incomplete_note: missing > 0
-        ? `${missing} of ${group.job_ids.length} member consultation(s) have aged out of this session's history; the comparison below is partial`
-        : null,
+      incomplete_note:
+        missing > 0
+          ? `${missing} of ${group.job_ids.length} member consultation(s) have aged out of this session's history; the comparison below is partial`
+          : null,
       members: trimmed,
       comparison: null,
       cancellable: live,
@@ -1353,16 +1757,29 @@ export class JobManager {
     // While no one has finished there is nothing to set side by side, and an
     // empty column per consultant is only context spent on every poll.
     const anyFinished = members.some((m) => ['completed', 'failed', 'cancelled'].includes(m.status));
-    if (anyFinished) view.comparison = comparison(members, full ? Infinity : GROUP_CHARS - printed(view));
-    return view;
+    return anyFinished ? { ...view, comparison: comparison(members, full ? Infinity : GROUP_CHARS - printed(view)) } : view;
   }
 
+  /**
+   * @param {string} groupId
+   * @param {{detail?: string | undefined}} [opts]
+   */
   groupView(groupId, opts) {
     const group = this.groups.get(groupId) ?? store.loadGroup(groupId);
     if (!group) return null;
-    return this.#shapeGroup(group, group.job_ids.map((jid) => this.view(jid, opts)).filter(Boolean), opts);
+    return this.#shapeGroup(
+      group,
+      group.job_ids.map((jid) => this.view(jid, opts)).filter((v) => v != null),
+      opts,
+    );
   }
 
+  /**
+   * @param {string} groupId
+   * @param {number | undefined} waitMs
+   * @param {{detail?: string | undefined}} [opts]
+   * @param {AbortSignal} [signal]
+   */
   async waitGroup(groupId, waitMs, opts, signal) {
     const group = this.groups.get(groupId);
     // A fan-out from another process or an earlier session: nothing here to
@@ -1376,6 +1793,7 @@ export class JobManager {
     return this.groupView(groupId, opts);
   }
 
+  /** @param {string} groupId */
   cancelGroup(groupId) {
     const group = this.groups.get(groupId);
     if (!group) {
@@ -1383,10 +1801,14 @@ export class JobManager {
       if (!view) return null;
       // Started by another server: each member still running there is asked to stop.
       const asked = (store.loadGroup(groupId)?.job_ids ?? [])
-        .map((jid) => this.cancel(jid)).filter((r) => /^asked/.test(r?.cancel_effect ?? '')).length;
-      return { ...view, cancel_effect: asked
-        ? `asked the severally process running it to stop ${asked} consultation(s); that takes up to ${CANCEL_POLL_MS / 1000} s, and consult_get shows when it has`
-        : 'nothing to signal: no consultant in this fan-out is still running' };
+        .map((jid) => this.cancel(jid))
+        .filter((r) => /^asked/.test(r?.cancel_effect ?? '')).length;
+      return {
+        ...view,
+        cancel_effect: asked
+          ? `asked the severally process running it to stop ${asked} consultation(s); that takes up to ${CANCEL_POLL_MS / 1000} s, and consult_get shows when it has`
+          : 'nothing to signal: no consultant in this fan-out is still running',
+      };
     }
     // Count what is actually about to be signalled before signalling it:
     // cancel() short-circuits on a member that has already finished, so a
@@ -1398,15 +1820,16 @@ export class JobManager {
     // Shape the view from the cancel() results, not from a fresh read: the
     // children exit asynchronously, so a signalled member reads as
     // "cancelling" until it is reaped, and the whole payload must say so.
-    const members = group.job_ids.map((jid) => this.cancel(jid)).filter(Boolean);
+    const members = group.job_ids.map((jid) => this.cancel(jid)).filter((v) => v != null);
     const total = group.job_ids.length;
     return {
       ...this.#shapeGroup(group, members),
-      cancel_effect: signalled === 0
-        ? 'nothing to signal: every consultant in this fan-out had already finished'
-        : signalled === total
-          ? 'every consultant process group in this fan-out was signalled'
-          : `${signalled} of ${total} consultant process groups in this fan-out were signalled; the rest had already finished`,
+      cancel_effect:
+        signalled === 0
+          ? 'nothing to signal: every consultant in this fan-out had already finished'
+          : signalled === total
+            ? 'every consultant process group in this fan-out was signalled'
+            : `${signalled} of ${total} consultant process groups in this fan-out were signalled; the rest had already finished`,
     };
   }
 
@@ -1422,7 +1845,10 @@ export class JobManager {
     for (const job of live) {
       job.cancelRequested = true;
       for (const fn of job._cancelFns) fn();
-      if (job._handle) { handles.push(job._handle); job._handle.stop(); }
+      if (job._handle) {
+        handles.push(job._handle);
+        job._handle.stop();
+      }
     }
     const settled = Promise.all(live.map((j) => j.promise).filter(Boolean));
     await Promise.race([settled, new Promise((r) => setTimeout(r, graceMs).unref?.())]);
@@ -1452,8 +1878,13 @@ export class JobManager {
 // files of that diff are the same entry for this purpose.
 // ponytail: a diff recorded before 1.11 hashed its files in git's order, not
 // path order, so its re-copy can read as changed when it is not.
+/**
+ * @param {ExposeManifest} manifest
+ * @param {BriefExposeEntry[]} parentEntries
+ */
 function markSinceParent(manifest, parentEntries) {
-  const key = (source, kind) => `${kind === 'change_files' ? 'diff' : kind}\0${source}`;
+  const key = (/** @type {string} */ source, /** @type {string} */ kind) =>
+    `${kind === 'change_files' ? 'diff' : kind}\0${source}`;
   const before = new Map(parentEntries.map((e) => [key(e.source, e.kind), e.sha256]));
   for (const e of manifest.entries) {
     const k = key(e.source, e.kind);
@@ -1464,13 +1895,13 @@ function markSinceParent(manifest, parentEntries) {
 // What consult_start says a follow-up copied again: the entries it shares
 // with the parent round, the ones left out and why, and how many files that
 // added to this round.
+/** @param {ExposeManifest} manifest */
 function inheritedSummary(manifest) {
   const carried = manifest.entries.filter((e) => e.inherited);
   return {
     entries: carried.map((e) => ({ exposed_as: e.exposedAs, kind: e.kind, files: e.files, changed: e.changed ?? null })),
     // Only what an earlier round showed carries the name it had there.
-    left_out: manifest.skipped.filter((x) => x.exposed_as)
-      .map((x) => ({ exposed_as: x.exposed_as, reason: x.reason })),
+    left_out: manifest.skipped.filter((x) => x.exposed_as).map((x) => ({ exposed_as: x.exposed_as, reason: x.reason })),
     files: carried.reduce((n, e) => n + e.files, 0),
   };
 }
@@ -1480,6 +1911,10 @@ function inheritedSummary(manifest) {
 // is the raw output stream, unparsed: material the lead may read, never an
 // answer, which is why it sits beside the failure and not in `result`.
 const PARTIAL_TAIL_CHARS = 8_000;
+/**
+ * @param {import('./run.mjs').ChildResult} run
+ * @returns {import('./store.mjs').PartialOutput | null}
+ */
 function partialOutput(run) {
   const out = String(run.stdout ?? '');
   if (!out.trim()) return null;
@@ -1497,10 +1932,16 @@ function partialOutput(run) {
 // Waits for `promise` (null: for nothing), at most `ms`, and no longer than
 // `signal` stays unaborted. The timer goes with the wait: a ten-minute wait
 // cut short leaves nothing behind.
+/**
+ * @param {Promise<unknown> | null | undefined} promise
+ * @param {number} ms
+ * @param {AbortSignal} [signal]
+ */
 async function settled(promise, ms, signal) {
   let timer;
+  /** @type {(() => void) | undefined} */
   let stop;
-  const until = new Promise((resolve) => {
+  const until = new Promise((/** @type {(value?: unknown) => void} */ resolve) => {
     stop = resolve;
     timer = setTimeout(resolve, ms);
     if (signal?.aborted) resolve();
@@ -1510,10 +1951,11 @@ async function settled(promise, ms, signal) {
     await (promise ? Promise.race([promise, until]) : until);
   } finally {
     clearTimeout(timer);
-    signal?.removeEventListener('abort', stop);
+    if (stop) signal?.removeEventListener('abort', stop);
   }
 }
 
+/** @param {string | Record<string, unknown>} text */
 function parses(text) {
   try {
     normalizeResult(text);
@@ -1524,6 +1966,10 @@ function parses(text) {
   }
 }
 
+/**
+ * @param {ConsultResult} result
+ * @returns {string[]}
+ */
 function recordableIds(result) {
   return [
     ...result.findings.map((f) => f.id),
@@ -1534,7 +1980,12 @@ function recordableIds(result) {
 
 // How many of each word, in the order they first appear. The only arithmetic
 // this server does on anyone's judgement.
+/**
+ * @param {Iterable<string>} values
+ * @returns {Record<string, number>}
+ */
 function tally(values) {
+  /** @type {Record<string, number>} */
   const out = {};
   for (const v of values) out[v] = (out[v] ?? 0) + 1;
   return out;
@@ -1543,17 +1994,27 @@ function tally(values) {
 // Counting is mechanical and stays that way: how many points the answer has,
 // how many carry a verdict, which ones do not. No judgement about whether the
 // consultation was worth it -- that is the lead's to draw from the entries.
+/**
+ * @param {Round} job
+ * @returns {JobRecord}
+ */
 function recordSummary(job) {
-  const ids = recordableIds(job.result);
-  const written = new Set(job.record.entries.map((e) => e.id));
+  // Callers pass a round that has a record, and a record is only written against an answer (#checkRecord).
+  const record = /** @type {JobRecord} */ (job.record);
+  const ids = recordableIds(/** @type {ConsultResult} */ (job.result));
+  const written = new Set(record.entries.map((e) => e.id));
   return {
-    ...job.record,
-    verdicts: tally(job.record.entries.map((e) => e.verdict)),
+    ...record,
+    verdicts: tally(record.entries.map((e) => e.verdict)),
     coverage: { recordable: ids.length, recorded: written.size },
     unrecorded: ids.filter((id) => !written.has(id)),
   };
 }
 
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
 function text(value) {
   if (typeof value !== 'string') return null;
   const t = redact(value).trim();
@@ -1566,24 +2027,37 @@ function text(value) {
 // a key left out is inherited -- one passed, even as an empty list, replaces
 // it -- and the validation that follows sees the result. Files are not:
 // copying them again stays expose_from_parent, named in the call (schema.mjs).
+/**
+ * @param {RawRequest} raw
+ * @param {Round} round
+ * @returns {RawRequest}
+ */
 function inherit(raw, round) {
   const { brief } = round;
   // A round kept off the web stays off: the material it carries over is the same.
+  /** @type {RawRequest} */
   const out = raw.network === undefined && round.network ? { ...raw, network: round.network } : { ...raw };
   if (!brief) return out;
-  for (const k of ['objective', 'success_criteria', 'constraints']) {
-    if (out[k] === undefined && raw.context?.[k] === undefined && brief[k] != null && !(Array.isArray(brief[k]) && !brief[k].length)) out[k] = brief[k];
+  /** @type {Array<'objective' | 'success_criteria' | 'constraints'>} */
+  const topKeys = ['objective', 'success_criteria', 'constraints'];
+  for (const k of topKeys) {
+    const v = brief[k];
+    if (out[k] === undefined && raw.context?.[k] === undefined && v != null && !(Array.isArray(v) && !v.length)) out[k] = v;
   }
   const ctx = { ...(raw.context ?? {}) };
-  for (const k of ['facts', 'proposal', 'counterpoints']) {
-    if (ctx[k] === undefined && brief[k] != null && !(Array.isArray(brief[k]) && !brief[k].length)) ctx[k] = brief[k];
+  /** @type {Array<'facts' | 'proposal' | 'counterpoints'>} */
+  const contextKeys = ['facts', 'proposal', 'counterpoints'];
+  for (const k of contextKeys) {
+    const v = brief[k];
+    if (ctx[k] === undefined && v != null && !(Array.isArray(v) && !v.length)) ctx[k] = v;
   }
   // The diff expose_diff added is not the lead's material: it is taken again
   // (or replaced) through expose_from_parent, against the files as they are now.
   // It is the last artifact (appended after the lead's own), so only that one is dropped.
   const artifacts = [...(brief.artifacts ?? [])];
   const last = artifacts.at(-1);
-  if (brief.expose_paths?.entries?.some((e) => e.kind === 'diff') && last?.kind === 'diff' && last.name.startsWith('git diff ')) artifacts.pop();
+  if (brief.expose_paths?.entries?.some((e) => e.kind === 'diff') && last?.kind === 'diff' && last.name.startsWith('git diff '))
+    artifacts.pop();
   if (ctx.artifacts === undefined && artifacts.length) {
     // Stored with null for an absent language or source; the request schema takes them as optional strings.
     ctx.artifacts = artifacts.map((a) => Object.fromEntries(Object.entries(a).filter(([, v]) => v != null)));
@@ -1592,6 +2066,7 @@ function inherit(raw, round) {
   return out;
 }
 
+/** @param {ReturnType<typeof normalizeResult>} normalized */
 function adviceCaveat(normalized) {
   const { result, quality } = normalized;
   const notes = [];
@@ -1603,16 +2078,51 @@ function adviceCaveat(normalized) {
     notes.push('the consultant did not say how well its evidence supports the answer (evidence_basis)');
   }
   // Read first in a comparison; a missing one is shown as null there, and named here.
-  if (!result.stance) notes.push('the answer gives no bottom line (stance): read the summary and findings for one before relying on it');
+  if (!result.stance)
+    notes.push('the answer gives no bottom line (stance): read the summary and findings for one before relying on it');
   if (quality.findings_without_grounds > 0) {
     notes.push(`${quality.findings_without_grounds} finding(s) arrived without grounds: do not adopt them without checking`);
   }
   if (quality.unsourced && result.findings.length > 0) {
-    notes.push('no sources were cited; the findings rest on the consultant\'s own reasoning over the brief');
+    notes.push("no sources were cited; the findings rest on the consultant's own reasoning over the brief");
   }
   return notes.length ? notes.join('; ') : null;
 }
 
+// Files were handed over, but no call to a file-reading tool succeeded. On
+// 2026-10-20 an agy release renamed its read tool, every read was refused,
+// and the answer still cited line numbers. Only for a CLI that reports its
+// tool calls and names its reading tools; the others say nothing here.
+/**
+ * @param {Record<string, number> | null | undefined} calls
+ * @param {readonly string[] | undefined} readTools
+ * @returns {string | null}
+ */
+function unreadCaveat(calls, readTools) {
+  if (!calls || !readTools) return null;
+  if (readTools.some((t) => calls[t])) return null;
+  const failed = readTools.reduce((n, t) => n + (calls[`${t}:error`] ?? 0), 0);
+  const how = failed ? `${failed} failed or were refused` : 'none was made';
+  return `files were exposed, but no call to read one succeeded (${how})`;
+}
+
+// A refused call to a tool outside the allowlist is most often a tool the CLI
+// renamed in a new release; naming it lets one consultation show the cause.
+/**
+ * @param {Record<string, number> | null | undefined} calls
+ * @param {readonly string[] | undefined} allowed
+ * @returns {string | null}
+ */
+function refusedToolCaveat(calls, allowed) {
+  if (!calls || !allowed) return null;
+  const names = Object.keys(calls)
+    .filter((k) => k.endsWith(':error'))
+    .map((k) => k.slice(0, -':error'.length))
+    .filter((t) => !allowed.includes(t));
+  if (!names.length) return null;
+  return `the consultant's CLI called ${names.join(', ')}, which severally does not allow, and was refused; a new CLI release may have renamed a tool`;
+}
+
 // A lead may legitimately name its own CLI as the consultant: a fresh child
 // session with no shared context is still a useful clean-context re-read.
 // But it is not an independent opinion -- the answer comes from the same
@@ -1620,10 +2130,17 @@ function adviceCaveat(normalized) {
 // lineage is the consultant's model's, not its CLI's: OpenCode can run GLM
 // for a GLM lead and DeepSeek for anyone.
 
+/**
+ * @param {string | null | undefined} caller
+ * @param {string | null | undefined} callerModel
+ * @param {Consultant} consultant
+ * @returns {string | null}
+ */
 function sameVendorCaveat(caller, callerModel, consultant) {
   // The lead's lineage: its declared model if that names one, else its CLI's
   // own. An unknown lineage on either side is no caveat -- not a guess.
-  const callerVendor = (callerModel ? vendorOf(callerModel) : null) ?? (caller ? CLI_VENDORS[caller] ?? null : null);
+  const callerCli = CLI_IDS.find((c) => c === caller);
+  const callerVendor = (callerModel ? vendorOf(callerModel) : null) ?? (callerCli ? (CLI_VENDORS[callerCli] ?? null) : null);
   const vendor = consultant.vendor;
   if (!callerVendor || !vendor || callerVendor !== vendor) return null;
   // Say what a fresh session of the same lineage removes and what it keeps.
@@ -1653,21 +2170,26 @@ function sameVendorCaveat(caller, callerModel, consultant) {
 // A mechanical side-by-side. The server deliberately does not decide whether
 // the consultants agree: inventing agreement that is not there is exactly the
 // failure a second opinion is supposed to prevent.
+/**
+ * @param {JobView[]} members
+ * @param {number} budget
+ */
 function comparison(members, budget) {
   // Each column first pays for its fixed fields; the rest is its budget.
   const each = (budget - COMPARISON_NOTE_CHARS) / Math.max(1, members.length) - COLUMN_FIXED_CHARS;
-  let columns = members.map((m) => byTarget(m, each));
+  const firstPass = members.map((m) => ({ m, column: byTarget(m, each) }));
+  let columns = firstPass.map((x) => x.column);
   // What the short answers did not spend goes to the ones that were cut.
   const cutShort = columns.filter((c) => c.truncated).length;
   if (each !== Infinity && cutShort) {
     const spare = columns.reduce((n, c) => n + (c.truncated ? 0 : Math.max(0, each + COLUMN_FIXED_CHARS - printed(c))), 0);
-    columns = members.map((m, i) => (columns[i].truncated ? byTarget(m, each + spare / cutShort) : columns[i]));
+    columns = firstPass.map(({ m, column }) => (column.truncated ? byTarget(m, each + spare / cutShort) : column));
   }
   return {
     by_target: columns,
     note:
       'This server does not judge whether the consultants agree: similar summaries are not evidence of agreement. ' +
-      'Each stance is the consultant\'s own declaration, relayed as given -- consultants that share a finding can still ' +
+      "Each stance is the consultant's own declaration, relayed as given -- consultants that share a finding can still " +
       'declare opposite stances, and that is a divergence. Compare the grounds behind each point yourself, and spend a ' +
       'follow-up only where a divergence would change your decision.',
   };
@@ -1680,17 +2202,32 @@ function comparison(members, budget) {
 // shortened to fit the share before any is left out. A cut is flagged, never hidden: `truncated` says so,
 // `omitted` counts the items a list could not hold, and `full_with` names the
 // call that has everything.
+/**
+ * @param {JobView} m
+ * @param {number} budget
+ * @returns {ComparisonColumn}
+ */
 function byTarget(m, budget) {
   const full = budget === Infinity;
   let left = budget;
   let truncated = false;
+  /** @type {Record<string, number>} */
   const omitted = {};
-  const clip = (s, max) => {
+  const clip = (/** @type {string | null | undefined} */ s, /** @type {number} */ max) => {
     const out = full ? s : cut(s, max);
     if (out !== s) truncated = true;
     return out;
   };
   const item = Math.min(ITEM_CHARS, budget / 10);
+  /**
+   * @template T
+   * @param {string} name
+   * @param {T[] | undefined} items
+   * @param {number} fields
+   * @param {(x: T, n: number) => unknown} build
+   * @param {number} part
+   * @param {number} [floor]
+   */
   const list = (name, items = [], fields, build, part, floor = MIN_TEXT_CHARS) => {
     if (full) return items.map((x) => build(x, Infinity));
     let share = left * part;
@@ -1710,25 +2247,46 @@ function byTarget(m, budget) {
       left -= n;
       out.push(v);
     }
-    if (out.length < items.length) { omitted[name] = items.length - out.length; truncated = true; }
+    if (out.length < items.length) {
+      omitted[name] = items.length - out.length;
+      truncated = true;
+    }
     return out;
   };
   const summary = clip(m.result?.summary ?? null, Math.min(SUMMARY_CHARS, budget / 3));
   const caveat = clip(m.quality?.caveat ?? null, Math.min(CAVEAT_CHARS, budget / 3));
   if (!full) left -= printed(summary) + printed(caveat);
+  /** @type {Partial<ConsultResult>} */
   const r = m.result ?? {};
   // The findings first, with up to 60% of what is left and their points cut
   // as short as it takes: they are what gets recorded against, so their ids
   // matter most. The other lists then share the rest evenly.
-  const findingPoints = list('finding_points', r.findings, 1,
-    (f, n) => ({ id: f.id, severity: f.severity ?? null, point: clip(f.point, n) }), 0.6, 20);
-  const decisionChangers = list('decision_changers', r.decision_changers, 2,
-    (d, n) => ({ condition: clip(d.condition, n), changes_to: clip(d.changes_to, n) }), 1 / 4);
+  const findingPoints = list(
+    'finding_points',
+    r.findings,
+    1,
+    (f, n) => ({ id: f.id, severity: f.severity ?? null, point: clip(f.point, n) }),
+    0.6,
+    20,
+  );
+  const decisionChangers = list(
+    'decision_changers',
+    r.decision_changers,
+    2,
+    (d, n) => ({ condition: clip(d.condition, n), changes_to: clip(d.changes_to, n) }),
+    1 / 4,
+  );
   const alternatives = list('alternative_options', r.alternatives, 1, (a, n) => clip(a.option, n), 1 / 3);
   const unknowns = list('unknowns', r.unknowns, 1, (u, n) => ({ id: u.id, item: clip(u.item, n) }), 1 / 2);
   const nextChecks = list('next_checks', r.next_checks, 1, (c, n) => ({ id: c.id, check: clip(c.check, n) }), 1 / 2);
-  const disagreements = list('remaining_disagreements', r.remaining_disagreements, 3,
-    (d, n) => Object.fromEntries(Object.entries(d).map(([k, v]) => [k, clip(v, n)])), 1);
+  const disagreements = list(
+    'remaining_disagreements',
+    r.remaining_disagreements,
+    3,
+    (d, n) => Object.fromEntries(Object.entries(d).map(([k, v]) => [k, clip(v, n)])),
+    1,
+  );
+  /** @type {ComparisonColumn} */
   const entry = {
     job_id: m.job_id,
     target: m.target,
@@ -1763,7 +2321,11 @@ function byTarget(m, budget) {
     points_without_verdict: m.result ? (m.record?.unrecorded ?? recordableIds(m.result)).length : null,
   };
   // A member's status and failure are in `members`; say them once.
-  if (!full) { delete entry.cli; delete entry.status; delete entry.failure_kind; }
+  if (!full) {
+    delete entry.cli;
+    delete entry.status;
+    delete entry.failure_kind;
+  }
   if (Object.keys(omitted).length) entry.omitted = omitted;
   if (truncated) {
     entry.truncated = true;
@@ -1794,6 +2356,10 @@ const MIN_TEXT_CHARS = 40;
  * points being checked, without the rest of the answer. A projection, not a
  * summary. An id the answer does not have is refused with the ones it has.
  */
+/**
+ * @param {JobView} view
+ * @param {string[]} ids
+ */
 export function pointsOf(view, ids) {
   if (!view.result) {
     throw new RequestError(`consultation "${view.job_id}" is ${view.status} and has no answer to take points from`, 'no_result');
@@ -1802,13 +2368,21 @@ export function pointsOf(view, ids) {
   const known = recordableIds(r);
   const unknown = ids.filter((id) => !known.includes(id));
   if (unknown.length) {
-    throw new RequestError(`${unknown.map((id) => `"${id}"`).join(', ')} not in this answer; it has: ${known.join(', ')}`, 'unknown_entry_id');
+    throw new RequestError(
+      `${unknown.map((id) => `"${id}"`).join(', ')} not in this answer; it has: ${known.join(', ')}`,
+      'unknown_entry_id',
+    );
   }
   const verdicts = new Map((view.record?.entries ?? []).map((e) => [e.id, e]));
   const lists = { finding: r.findings, unknown: r.unknowns, next_check: r.next_checks };
   const points = [...new Set(ids)].map((id) => {
-    const [kind, item] = Object.entries(lists).map(([k, l]) => [k, l.find((x) => x.id === id)]).find(([, x]) => x);
-    return { kind, ...item, recorded: verdicts.get(id) ?? null };
+    // Every id was checked against recordableIds above, so one list has it.
+    const [point] = Object.entries(lists).flatMap(([kind, l]) => {
+      const item = l.find((x) => x.id === id);
+      return item ? [{ kind, ...item }] : [];
+    });
+    if (!point) throw new RequestError(`"${id}" is not a point in this answer`, 'unknown_entry_id');
+    return { ...point, recorded: verdicts.get(id) ?? null };
   });
   return {
     job_id: view.job_id,
@@ -1837,6 +2411,7 @@ export function pointsOf(view, ids) {
 
 // What a value takes as the server prints it, nested four levels into the
 // response: two-space JSON, every line indented eight more.
+/** @param {unknown} v */
 function printed(v) {
   const j = JSON.stringify(v, null, 2) ?? '';
   return j.length + 8 * j.split('\n').length;
@@ -1844,10 +2419,15 @@ function printed(v) {
 
 // A text cut to `max` characters as printed in JSON, so a run of characters
 // that JSON escapes (a control character takes six) cannot outgrow the cut.
+/**
+ * @param {string | null | undefined} s
+ * @param {number} max
+ * @returns {string | null | undefined}
+ */
 function cut(s, max) {
   if (typeof s !== 'string') return s;
   const room = Math.max(0, Math.floor(max));
-  const width = (t) => JSON.stringify(t).length - 2;
+  const width = (/** @type {string} */ t) => JSON.stringify(t).length - 2;
   if (width(s) <= room) return s;
   // One character of the room goes to the ellipsis, and a surrogate pair is
   // never split.
@@ -1861,6 +2441,11 @@ function cut(s, max) {
 // is named rather than repeated: its size and sha256 (of the JSON stored in
 // the round file, so both can be checked against it), where it is kept, and
 // what was copied -- skipped files counted by reason, not listed.
+/**
+ * @param {FullView} view
+ * @param {string} [detail]
+ * @returns {JobView}
+ */
 function compactBrief(view, detail) {
   if (detail === 'full' || !view.brief) return view;
   const json = JSON.stringify(view.brief);
@@ -1872,12 +2457,18 @@ function compactBrief(view, detail) {
       sha256: crypto.createHash('sha256').update(json).digest('hex'),
       // Under the severally home (~/.severally unless the operator moved it).
       history_file: path.relative(POLICY.home, store.roundPath(view.chain_id, view.round)),
-      exposed: ex ? { ...ex.totals, skipped: tally((ex.skipped ?? []).map((x) => x.reason)) } : null,
+      exposed: ex
+        ? { ...ex.totals, skipped: tally((ex.skipped ?? []).map((/** @type {{reason: string}} */ x) => x.reason)) }
+        : null,
       full_with: `consult_get({ job_id: "${view.job_id}", detail: "full" }) or consult_export`,
     },
   };
 }
 
+/**
+ * @param {Round} job
+ * @returns {string}
+ */
 function nextStep(job) {
   if (job.status === 'running' || job.status === 'queued') return 'poll consult_get again, or consult_cancel to stop it';
   if (job.status === 'completed') {
@@ -1886,27 +2477,35 @@ function nextStep(job) {
     // point showed, not when the answer arrives. Name the open ones until then.
     const written = new Set((job.record?.entries ?? []).map((e) => e.id));
     const open = job.result ? recordableIds(job.result).filter((id) => !written.has(id)).length : 0;
-    const close = open > 0
-      ? ` Then write what checking showed: consult_record({ job_id: "${job.job_id}", entries: [{ id, verdict, effect }] }) -- ${open} point(s) still carry no verdict.`
-      : '';
-    return (left > 0
-      ? `check the grounds behind the points that matter, run the one check that would change the decision, then either decide, or spend one of your ${left} remaining round(s) on the specific divergences (followup_to: "${job.job_id}").`
-      : 'rounds exhausted: decide with what you have.') + close;
+    const close =
+      open > 0
+        ? ` Then write what checking showed: consult_record({ job_id: "${job.job_id}", entries: [{ id, verdict, effect }] }) -- ${open} point(s) still carry no verdict.`
+        : '';
+    return (
+      (left > 0
+        ? `check the grounds behind the points that matter, run the one check that would change the decision, then either decide, or spend one of your ${left} remaining round(s) on the specific divergences (followup_to: "${job.job_id}").`
+        : 'rounds exhausted: decide with what you have.') + close
+    );
   }
-  if (job.failure?.kind === 'timeout' || job.failure?.kind === 'cli_error') return 'retriable: narrow the brief and start a new consultation';
-  if (job.failure?.kind === 'interrupted') return 'the severally process running it exited before the consultant answered; start the consultation again if you still need it';
-  if (job.failure?.kind === 'rate_limited') return 'the consultant was rate-limited and the server already re-ran it (see retries); try again in a few minutes, or proceed on your own judgement';
-  if (job.failure?.kind === 'usage_limit' || job.failure?.kind === 'auth') return 'not a consultation outcome: the consultant never answered. Proceed on your own judgement, or fix the credentials/quota first';
-  if (job.failure?.kind === 'invalid_output') return 'the consultant answered but not in the required shape; retry once with a shorter brief before giving up';
+  if (job.failure?.kind === 'timeout' || job.failure?.kind === 'cli_error')
+    return 'retriable: narrow the brief and start a new consultation';
+  if (job.failure?.kind === 'interrupted')
+    return 'the severally process running it exited before the consultant answered; start the consultation again if you still need it';
+  if (job.failure?.kind === 'rate_limited')
+    return 'the consultant was rate-limited and the server already re-ran it (see retries); try again in a few minutes, or proceed on your own judgement';
+  if (job.failure?.kind === 'usage_limit' || job.failure?.kind === 'auth')
+    return 'not a consultation outcome: the consultant never answered. Proceed on your own judgement, or fix the credentials/quota first';
+  if (job.failure?.kind === 'invalid_output')
+    return 'the consultant answered but not in the required shape; retry once with a shorter brief before giving up';
   return 'proceed on your own judgement and note that no peer input was obtained';
 }
 
 // Every spelling a token could name a flag by: `--name[=v]` as written, and for
 // a single dash both a short flag with its value attached (`-sdanger-full-access`
 // in clap) and a Go-style long flag (`-dangerously-skip-permissions`).
-const flagNames = (a) => {
+const flagNames = (/** @type {string} */ a) => {
   if (!a.startsWith('-') || a === '-') return [];
-  const name = a.split('=')[0];
+  const [name = ''] = a.split('=');
   return a.startsWith('--') ? [name] : [name, a.slice(0, 2), `-${name}`];
 };
 
@@ -1917,6 +2516,12 @@ const flagNames = (a) => {
  * adapter's FORBIDDEN_FLAGS and RESERVED_FLAGS (aliases and other flags that
  * undo it). Values (tokens without a leading dash) are not inspected.
  */
+/**
+ * @param {CliId} target
+ * @param {readonly string[]} adapterArgs
+ * @param {unknown} extra
+ * @returns {string | null}
+ */
 export function extraArgsProblem(target, adapterArgs, extra) {
   if (!Array.isArray(extra) || !extra.every((a) => typeof a === 'string')) return 'must be an array of strings';
   const adapter = ADAPTERS[target];
@@ -1930,11 +2535,20 @@ export function extraArgsProblem(target, adapterArgs, extra) {
 }
 
 /** Extra args go before a trailing `-` (Codex's read-the-prompt-from-stdin marker), else at the end. */
+/**
+ * @param {string[]} args
+ * @param {readonly string[]} extra
+ * @returns {string[]}
+ */
 export function withExtraArgs(args, extra) {
   if (extra.length === 0) return args;
   return args.at(-1) === '-' ? [...args.slice(0, -1), ...extra, '-'] : [...args, ...extra];
 }
 
+/**
+ * @param {CliId} target
+ * @param {readonly string[]} args
+ */
 export function assertNoForbiddenFlags(target, args) {
   const forbidden = ADAPTERS[target].FORBIDDEN_FLAGS;
   const hit = args.find((a) => forbidden.includes(a));