severally-mcp 2.4.0 → 2.5.0

package/src/jobs.mjs

@@ -12,9 +12,10 @@ import {
   detectCaller,
   configProblem,
   consultantByName,
+  consultantNamed,
   consultantAvailable,
 } from './policy.mjs';
-import { vendorOf, sameModel, CLI_VENDORS } from './consultants.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';
@@ -29,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
@@ -55,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]));
@@ -64,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',
@@ -76,6 +191,11 @@ 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;
@@ -85,7 +205,7 @@ function ownerState(jobId, owner) {
       process.kill(owner.pid, 0);
       pidAlive = true;
     } catch (err) {
-      pidAlive = err.code === 'EPERM';
+      pidAlive = err instanceof Error && 'code' in err && err.code === 'EPERM';
     }
   if (!pidAlive) return 'dead';
   return Date.now() > Date.parse(owner.deadline_at) ? 'overdue' : 'alive';
@@ -93,9 +213,13 @@ function ownerState(jobId, owner) {
 
 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();
   }
@@ -103,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;
@@ -117,6 +245,12 @@ 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) {
@@ -151,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),
     };
   }
@@ -175,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,
@@ -218,13 +360,27 @@ 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}} [opts] */
+  /**
+   * @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
@@ -259,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()) {
@@ -272,21 +436,24 @@ 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 });
+        candidates.push({ at: row.created_at ?? '', load: () => store.loadRoundAt(row) });
       }
-    const at = (x) => x.created_at ?? x.rec?.created_at ?? x.row?.created_at ?? '';
+    /** @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) => {
@@ -321,10 +488,12 @@ 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());
@@ -338,12 +507,15 @@ export class JobManager {
           }
       }
     }
+    /** @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(
@@ -359,7 +531,9 @@ export class JobManager {
     // 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;
+    /** @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
@@ -375,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',
         );
       }
@@ -387,23 +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),
@@ -439,19 +614,22 @@ 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;
@@ -472,6 +650,7 @@ export class JobManager {
     // 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) {
@@ -484,10 +663,16 @@ 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);
@@ -501,20 +686,27 @@ export class JobManager {
       }
       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'
+      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) {
@@ -526,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',
       );
     }
@@ -564,7 +765,10 @@ 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) {
@@ -573,7 +777,7 @@ export class JobManager {
           if (diff) {
             req.context.artifacts = [
               ...req.context.artifacts,
-              { name: `git diff ${exposeManifest.entries.at(-1).base}`, kind: 'diff', language: 'diff', excerpt: diff },
+              { name: `git diff ${exposeManifest.entries.at(-1)?.base}`, kind: 'diff', language: 'diff', excerpt: diff },
             ];
           }
         }
@@ -587,21 +791,27 @@ export class JobManager {
           !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,
@@ -638,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,
@@ -657,18 +867,21 @@ 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 {
@@ -694,13 +907,13 @@ 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
@@ -718,7 +931,7 @@ export class JobManager {
     };
 
     if (!req.fanout) {
-      const job = members[0];
+      const job = firstMember;
       return {
         ...common,
         job_id: job.job_id,
@@ -732,7 +945,7 @@ export class JobManager {
     return {
       ...common,
       question: group.question, // the redacted text every member was actually sent
-      jobs: members.map((m) => ({
+      jobs: members.map((/** @type {Job} */ m) => ({
         job_id: m.job_id,
         chain_id: m.chain_id,
         target: m.target,
@@ -749,20 +962,34 @@ 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.
+        /**
+         * @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,
@@ -770,7 +997,7 @@ export class JobManager {
             verdict: verdicts.get(x.id)?.verdict ?? null,
             effect: verdicts.get(x.id)?.effect ?? null,
           }));
-        const checked = (x) => x.verdict !== 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,
@@ -788,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
@@ -802,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;
@@ -809,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);
@@ -822,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
@@ -830,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 {
@@ -886,28 +1123,37 @@ export class JobManager {
       // its latency is part of this job's duration and budget, not free time
       // before the meter starts.
       if (adapter.prepare) await adapter.prepare();
-      const invocation = adapter.buildInvocation({
-        workdir,
-        schemaPath,
-        guardrails: renderGuardrails(Boolean(req._snapshot), req.network),
-        sandbox,
-        consultant,
-        hasExposedPaths: Boolean(req._snapshot),
-        network: req.network,
-      });
+      // Built again for the fallback model, so the operator's extra args and
+      // the forbidden-flag check apply to that run exactly as to the first.
+      // Returns the invocation, or the problem with the operator's args.
+      /** @param {import('./consultants.mjs').Consultant} c @returns {import('./run.mjs').Invocation | string} */
+      const launch = (c) => {
+        const invocation = adapter.buildInvocation({
+          workdir,
+          schemaPath,
+          guardrails: renderGuardrails(Boolean(req._snapshot), req.network),
+          sandbox,
+          consultant: c,
+          hasExposedPaths: Boolean(req._snapshot),
+          network: req.network,
+        });
+        const problem = extraArgsProblem(cli, invocation.args, t.extraArgs);
+        if (problem) return problem;
+        invocation.args = withExtraArgs(invocation.args, t.extraArgs);
+        assertNoForbiddenFlags(cli, invocation.args);
+        // 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;
+        return invocation;
+      };
+      const first = launch(consultant);
+      if (typeof first === 'string') return this.#fail(job, 'spawn_error', `config clis.${cli}.args: ${first}`);
+      let invocation = first;
 
-      const argsProblem = extraArgsProblem(cli, invocation.args, t.extraArgs);
-      if (argsProblem) return this.#fail(job, 'spawn_error', `config clis.${cli}.args: ${argsProblem}`);
-      invocation.args = withExtraArgs(invocation.args, t.extraArgs);
-      assertNoForbiddenFlags(cli, invocation.args);
-      // 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;
-
-      const attempt = (timeout) => {
+      const attempt = (/** @type {number} */ timeout) => {
         const { handle, done } = runChild({
           command: invocation.command,
           args: invocation.args,
@@ -915,7 +1161,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,
@@ -933,9 +1181,11 @@ 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;
+      let fallenBack = false;
       for (;;) {
         // Read off the consultant's own event stream, last attempt only; null
         // where the CLI does not stream its tool calls (Claude Code).
@@ -976,7 +1226,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 };
         }
@@ -1007,6 +1257,25 @@ export class JobManager {
             continue;
           }
         }
+        // The operator's fallback for a model whose account quota is used up
+        // (a re-run on the same model would fail the same way). It is a
+        // different mind from the one asked, so the answer says so below.
+        if (interpreted.failureKind === 'usage_limit' && consultant.fallbackModel && !fallenBack && remaining >= MIN_RETRY_MS) {
+          fallenBack = true;
+          const fallback = consultant.fallbackModel;
+          const next = launch({ ...consultant, model: fallback });
+          if (typeof next === 'string') return this.#fail(job, 'spawn_error', `config clis.${cli}.args: ${next}`);
+          invocation = next;
+          job.retries.push({
+            failure_kind: interpreted.failureKind,
+            reason: `${job.model} quota used up; re-run on ${fallback}`,
+            at: new Date().toISOString(),
+            usage: adapter.usageRecord(interpreted.usageRaw),
+          });
+          job.model = fallback;
+          run = await attempt(remaining);
+          continue;
+        }
         const wait = POLICY.retryBackoffMs * 3 ** autoRetries;
         if (
           AUTO_RETRY_KINDS.includes(interpreted.failureKind) &&
@@ -1020,7 +1289,7 @@ export class JobManager {
             at: new Date().toISOString(),
             usage: adapter.usageRecord(interpreted.usageRaw),
           });
-          await new Promise((resolve) => {
+          await new Promise((/** @type {(value?: unknown) => void} */ resolve) => {
             const timer = setTimeout(resolve, wait);
             job._cancelFns.push(() => {
               clearTimeout(timer);
@@ -1079,6 +1348,9 @@ export class JobManager {
           `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)',
+        fallenBack && `answered by ${job.model}: ${consultant.model}'s quota was used up`,
+        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
@@ -1101,6 +1373,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';
@@ -1117,6 +1396,7 @@ 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 });
@@ -1125,6 +1405,7 @@ export class JobManager {
     }
   }
 
+  /** @param {Job} job */
   #finish(job) {
     try {
       store.persistRound(this.#record(job));
@@ -1145,7 +1426,7 @@ 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 {Record<string, any>} [input] */
+  /** @param {RawRecord} [input] */
   record(input = {}) {
     if (input.records !== undefined) return this.#recordMany(input);
     const allowed = ['job_id', 'entries', 'reflection'];
@@ -1169,6 +1450,7 @@ 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) {
@@ -1181,10 +1463,12 @@ export class JobManager {
     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');
@@ -1212,7 +1496,10 @@ 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 {{job_id?: string, entries?: any[], reflection?: any}} rec */
+  /**
+   * @param {RawRecord} rec
+   * @returns {RecordChange}
+   */
   #checkRecord({ job_id: jobId, entries, reflection }) {
     if (entries === undefined && reflection === undefined) {
       throw new RequestError(
@@ -1240,7 +1527,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() : '';
@@ -1257,7 +1545,7 @@ export class JobManager {
           'invalid_verdict',
         );
       }
-      merged.set(id, {
+      written.set(id, {
         id,
         verdict,
         effect: text(entry?.effect),
@@ -1271,6 +1559,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);
@@ -1289,30 +1578,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
@@ -1327,6 +1626,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);
@@ -1340,6 +1645,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();
@@ -1364,6 +1676,7 @@ export class JobManager {
     }, CANCEL_POLL_MS).unref();
   }
 
+  /** @param {string} jobId */
   cancel(jobId) {
     const job = this.jobs.get(jobId);
     if (!job) {
@@ -1379,18 +1692,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 {any} group @param {any[]} members @param {{detail?: string}} [opts] */
+  /**
+   * @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');
@@ -1470,16 +1787,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
@@ -1493,6 +1823,7 @@ export class JobManager {
     return this.groupView(groupId, opts);
   }
 
+  /** @param {string} groupId */
   cancelGroup(groupId) {
     const group = this.groups.get(groupId);
     if (!group) {
@@ -1519,7 +1850,7 @@ 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),
@@ -1577,8 +1908,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);
@@ -1589,6 +1925,7 @@ 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 {
@@ -1604,6 +1941,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;
@@ -1621,10 +1962,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();
@@ -1634,10 +1981,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);
@@ -1648,6 +1996,10 @@ function parses(text) {
   }
 }
 
+/**
+ * @param {ConsultResult} result
+ * @returns {string[]}
+ */
 function recordableIds(result) {
   return [
     ...result.findings.map((f) => f.id),
@@ -1658,7 +2010,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;
@@ -1667,17 +2024,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();
@@ -1690,23 +2057,29 @@ 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.
@@ -1723,6 +2096,7 @@ function inherit(raw, round) {
   return out;
 }
 
+/** @param {ReturnType<typeof normalizeResult>} normalized */
 function adviceCaveat(normalized) {
   const { result, quality } = normalized;
   const notes = [];
@@ -1745,6 +2119,44 @@ function adviceCaveat(normalized) {
   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 that looks like a file
+// reader is most often the CLI's read tool renamed in a new release; naming
+// it lets one consultation show the cause. The tools severally refuses on
+// purpose (agy tries run_command even for a trivial question) are left out:
+// reporting them would be noise, and they are not renamed readers.
+// ponytail: a name heuristic; a reader named otherwise goes unreported until the unread note shows it.
+/**
+ * @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) && /read|view|open/i.test(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 its file-reading 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
@@ -1752,10 +2164,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.
@@ -1785,15 +2204,20 @@ 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,
@@ -1812,17 +2236,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;
@@ -1851,6 +2290,7 @@ function byTarget(m, budget) {
   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
@@ -1880,6 +2320,7 @@ function byTarget(m, budget) {
     (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,
@@ -1949,6 +2390,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');
@@ -1965,10 +2410,13 @@ export function pointsOf(view, ids) {
   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,
@@ -1997,6 +2445,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;
@@ -2004,10 +2453,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.
@@ -2021,6 +2475,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);
@@ -2032,12 +2491,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') {
@@ -2072,9 +2537,9 @@ function nextStep(job) {
 // 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}`];
 };
 
@@ -2085,6 +2550,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];
@@ -2098,11 +2569,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));